# Breach Comparison

Census compares suspect files against the CertiSigma attestation registry to detect data exfiltration. A match proves — with cryptographic certainty — that a file was previously inventoried.

## Basic usage

```bash
# Compare suspect files against the registry
census compare /path/to/suspect-files

# Cross-reference matches with the original inventory
census compare /suspect --manifest /path/to/.census-manifest.db

# Save report
census compare /suspect --output report.json
census compare /suspect --output report.csv
```

## Exit codes

| Code | Meaning |
|------|---------|
| `0` | No matches found — suspect files are not in the registry |
| `1` | Matches found — one or more suspect files match inventoried assets |

This enables scripting: `census compare /suspect && echo "clean" || echo "breach detected"`.

## Cross-referencing with manifest

When `--manifest` is provided, matched files are enriched with the **original path** from the inventory manifest. This tells you not just that a file was exfiltrated, but where it came from.

```
Suspect files:  150
Matched:        3
Not matched:    147
Errors:         0

--- Matches ---
  leaked-doc.pdf → att_abc123 [T1] (inventory: hr/quarterly-report-2026Q1.pdf)
  data-dump.csv  → att_def456 [T2] (inventory: finance/ledger-march.csv)
```

## File filters

All filter options from `scan` are available on `compare`:

```bash
census compare /suspect --include "*.pdf" --exclude "*.tmp" --min-size 1K --max-size 100M
```

See [scanning.md](scanning.md) for filter details.

## Output formats

### JSON (default for .json extension)

```bash
census compare /suspect --output report.json
```

Produces a structured JSON file with full report data:

```json
{
  "total_suspect": 150,
  "matched": 3,
  "not_matched": 147,
  "errors": 0,
  "matches": [
    {
      "hash_hex": "a1b2c3...",
      "suspect_path": "leaked-doc.pdf",
      "attestation_id": "abc123",
      "timestamp": "2026-01-15T10:00:00Z",
      "level": "T1",
      "inventory_path": "hr/quarterly-report-2026Q1.pdf"
    }
  ]
}
```

### CSV (detected by .csv extension)

```bash
census compare /suspect --output report.csv
```

CSV columns: `suspect_path`, `hash_hex`, `matched`, `attestation_id`, `level`, `timestamp`, `inventory_path`.

Suitable for import into Excel, SIEM tools, or compliance reporting systems.

## Batch verification

Hashes are verified in batches of 100 per API call. For large suspect directories, this means multiple API calls with automatic retry on transient failures.

See [retry-and-resilience.md](retry-and-resilience.md) for retry behavior.
