# On-Match Notification Hooks

The `--on-match CMD` option executes a shell command when Census detects matches,
enabling automated alerting for incident response, SOC integration, and CI/CD workflows.

## Supported Commands

| Command | `--on-match` |
|---------|:---:|
| `compare` | Yes |
| `bulk-scan` | Yes |

## How It Works

1. Census completes the scan/comparison
2. If `matched > 0`, the command is executed with **results as JSON on stdin**
3. The JSON payload includes `matched` count, `matches` array, `census_version`, and `elapsed_seconds`
4. If the command fails or times out (30s), Census logs a warning but does **not** change its exit code

## Usage Examples

```bash
# Run a local alert script
census compare /suspects --on-match './scripts/alert.sh'

# POST to a Slack webhook
census compare /suspects --on-match 'curl -s -X POST -H "Content-Type: application/json" -d @- https://hooks.slack.com/services/...'

# Pipe to a Python notification script
census bulk-scan /data --on-match 'python3 scripts/notify.py'

# Combine with --exit-zero for CI (report + alert, never fail pipeline)
census compare /data --exit-zero --on-match './alert.sh'
```

## JSON Payload

The command receives a JSON object on stdin:

```json
{
  "matched": 3,
  "matches": [
    {
      "hash_hex": "abab...",
      "suspect_path": "/data/leak.txt",
      "attestation_id": "att-123",
      "level": "T0",
      "source": "incident-001",
      "inventory_path": "/inventory/confidential.txt"
    }
  ],
  "census_version": "1.4.0",
  "elapsed_seconds": 5.2
}
```

## Security Note

The `--on-match` command is passed to `shell=True` to enable shell features
(pipes, env vars, redirects). This is a deliberate design choice — Census is a
trusted local tool, and the user controls the command string. Do not use
`--on-match` with untrusted input.
