# 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)
```

## Machine-readable output (`--json`)

```bash
census compare /suspect --json
```

L’output su stdout è solo JSON (ad uso pipeline). Se combini `--json` con `--output`, il file report **non** viene scritto: Census emette una nota su **stderr** che `--output` è ignorato in modalità JSON.

## 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.

## CI/CD integration

### Report-only mode (`--exit-zero`)

Always exit 0 regardless of match results. The comparison still runs and output is produced, but the pipeline does not fail. Useful for monitoring or SARIF upload workflows.

```bash
census compare /artifacts --exit-zero --json > results.json
```

### Summary mode (`--summary`)

Show only aggregate counts, no individual match lines. Keeps CI logs concise.

```bash
census compare /artifacts --summary
```

Combine both for a minimal CI step:

```bash
census compare /artifacts --summary --exit-zero
```

See also [sarif.md](sarif.md) for SARIF output and GitHub Code Scanning integration.

## Enriched comparison (`--detailed`)

With `--detailed`, Census fetches additional data per match from the API: `source` label, certification level, and timestamps. Requires an authenticated client (API key).

```bash
census compare /suspect --detailed --json
```

The `source` field appears in both JSON and CSV output, enabling attribution of matches to specific inventories.

## Parallel hashing (`--workers`)

Same as `scan --workers` — use multiple CPU cores for hashing suspect files:

```bash
census compare /suspect --workers 4
```

## 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.
