phi-scanner/docs/deployment.md

# GreySec PHI Scanner — Multi-Location Deployment Guide

## Live Test Results

- **Date**: 2026-05-04
- **Target**: DESKTOP-1DHNF5M (192.168.68.15) — Windows 10 lab VM
- **Method**: SMB upload → atsvc DCERPC Task Scheduler → SMB download
- **Auth**: `labuser` / `LabPass123!` (local account, C$ share)
- **Findings**: 2,454 total (4 SSN, 129 DOB, 384 Phone, 4 Email, 1,933 IP)
- **Real PHI**: 4 SSNs from `C:\Users\vagrant\Desktop\Patient_Records.txt` — unauthorized PHI on Desktop

## Deployment Architecture

```
┌─────────────────────────────────────────────────────────┐
│  GreySec PHI Scanner — Multi-Location Deployment        │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐          │
│  │ Location │    │ Location │    │ Location │          │
│  │    A     │    │    B     │    │    C     │          │
│  │  (HQ)    │    │ (Branch) │    │ (Cloud)  │          │
│  │          │    │          │    │          │          │
│  │ Win/Linux│    │ Win/Linux│    │ Azure/   │          │
│  │ DBs/Host │    │ DBs/Host │    │ AWS      │          │
│  └────┬─────┘    └────┬─────┘    └────┬─────┘          │
│       │                │                │                │
│       └────────────────┴────────────────┘                │
│                          │                              │
│              ┌───────────▼───────────┐                   │
│              │  Central Reporting    │                   │
│              │  (Supabase/GreySec)  │                   │
│              └──────────────────────┘                   │
└─────────────────────────────────────────────────────────┘
```

## Per-Location Package Structure

```
greysec-phi-scanner/
├── configs/
│   ├── location_hq.yaml       # HQ — domain join, multiple hosts
│   ├── location_cloud.yaml    # AWS/Azure cloud targets
│   └── location_branch.yaml   # Workgroup, local auth
├── scripts/
│   ├── scan_files.py          # Local file system scan
│   ├── scan_db.py             # Database (MSSQL/PostgreSQL)
│   ├── scan_windows.py        # Windows remote via atsvc
│   └── aggregate.py            # Merge all location results
├── reports/                    # Output reports per location
└── credentials.env            # Secrets (not in git)
```

## Installation

### Linux/macOS

```bash
pip install greysec-phi-scanner
# or from source:
cd greysec-phi-scanner
pip install -e .
```

### Kali (Remote Deployment)

```bash
# Install dependencies
apt install python3-impacket python3-smbclient

# Run file scan
greysec-phi scan /mnt/shared/patient_data --output reports/hq_scan.json

# Run Windows remote scan
greysec-phi scan-windows --host 192.168.1.10 --user administrator --pass P@ssw0rd!
```

## Windows Remote Scanning

### Requirements
- SMB (445) access to target
- Local or domain credentials with administrative access
- Task Scheduler service running (default on all Windows)

### Authentication Options

**Option 1 — Local Account (tested, working)**
```yaml
host: 192.168.68.15
username: labuser
password: LabPass123!
domain: ""   # local account, no domain
share: C$
```

**Option 2 — Domain Account**
```yaml
host: 192.168.1.10
username: scanagent
password: ServicePass123!
domain: CONTOSO
share: C$
```

### Remote Execution Method: atsvc DCERPC

The scanner uses the Windows Task Scheduler API via the `atsvc` named pipe. This:
- Does NOT require WinRM
- Does NOT require persistent agent installation
- Works on all Windows versions (Vista through 2025)
- Runs as SYSTEM (highest privilege)

```
Flow: SMB connect → atsvc RPC bind → SchRpcRegisterTask → SchRpcRun → results file
```

### PowerShell Agent Script

The scanner deploys a lightweight PowerShell agent to the target:
- Writes to `C:\tmp\greysec_phi\`
- Scans: `%USERPROFILE%`, `%APPDATA%`, `C:\Users`, `C:\ProgramData`, `C:\inetpub`, `C:\Windows\System32\config`, `C:\tmp`
- Extensions: `*.txt, *.csv, *.log, *.json, *.xml, *.doc, *.docx, *.xls, *.xlsx, *.pdf, *.mdb, *.accdb, *.sql, *.cfg, *.ini, *.dat, *.bak`
- Max file size: 50MB
- Results written to `C:\tmp\phi_scan_results.json`
- Pulled back via SMB

### Known Limitations

- **C$ share required**: Must have write access to administrative share
- **Local accounts**: `ERROR_NONE_MAPPED` — use `S-1-5-18` (SYSTEM SID) in task XML to avoid account lookup
- **No WinRM**: Uses atsvc/Task Scheduler instead
- **Execution method**: `TASK_LOGON_SERVICE_ACCOUNT` (5) for SYSTEM tasks

## Database Scanning (MSSQL / PostgreSQL)

```bash
# MSSQL
greysec-phi scan-db \
  --engine mssql \
  --host 192.168.1.20 \
  --database PatientRecords \
  --user sa --password "DBPass123!"

# PostgreSQL
greysec-phi scan-db \
  --engine postgresql \
  --host 192.168.1.21 \
  --database health_records \
  --user postgres --password "Postgres123!"
```

### Database Patterns Detected

| PHI Type | Pattern |
|----------|---------|
| SSN | `\b\d{3}[-\s]\d{2}[-\s]\d{4}\b` |
| MRN | `\b(MRN\|Medical Record\|EHR\|ID)[:\s#]*\d{6,10}\b` |
| DOB | `\b(0[1-9]\|1[0-2])[/.-](0[1-9]\|[12]\d\|3[01])[/.-](19\|20)\d{2}\b` |
| Email | `\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z\|a-z]{2,}\b` |
| Phone | `\b(\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b` |
| IP | `\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b` |

## Multi-Location Orchestration

```python
# Example: Scan multiple locations from central server
from greysec_phi_scanner import orchestrator

locations = [
    {"name": "hq", "config": "configs/hq.yaml"},
    {"name": "branch_east", "config": "configs/branch_east.yaml"},
    {"name": "cloud_west", "config": "configs/cloud_west.yaml"},
]

results = orchestrator.scan_all(locations)
orchestrator.generate_report(results, "reports/global_phi_audit.html")
```

## CI/CD Integration

```yaml
# GitHub Actions — scan on merge to main
- name: PHI Scanner
  run: |
    pip install greysec-phi-scanner
    greysec-phi scan ./data --output scan_results.json
    greysec-phi report scan_results.json --format html --output phi_report.html
  secrets: phi_scanner_credentials
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `PHI_SCANNER_DB_HOST` | Database host for centralized inventory |
| `PHI_SCANNER_SUPABASE_URL` | Supabase project URL |
| `PHI_SCANNER_SUPABASE_KEY` | Supabase API key |
| `PHI_SCANNER_LOCATIONS` | Comma-separated list of location IDs |

## Supabase Schema (for centralized tracking)

```sql
-- See: greysec/phi-scanner/src/inventory/db.py
-- Tables: scan_runs, findings, hosts, locations
```

## Quick Start

```bash
# 1. Install
pip install greysec-phi-scanner

# 2. File scan
greysec-phi scan /path/to/patient/data --output results.json

# 3. Generate HTML report
greysec-phi report results.json --format html --output report.html

# 4. Windows remote scan
greysec-phi scan-windows --host 192.168.1.10 --user admin --pass P@ss --share C$

# 5. Database scan
greysec-phi scan-db --engine mssql --host dbserver --database EHR --user sa --pass pass
```