# Audit Log

Census maintains a tamper-evident audit log that records every operation
(scan, compare, verify, annotate, etc.) to an append-only JSONL file.

Each entry includes the SHA-256 hash of the previous entry, forming a
**hash chain**.  If any entry is modified or deleted, the chain breaks
and `census audit-log verify` detects the tampering.

This gives Census a lightweight compliance audit trail suitable for
SOC2, ISO 27001, and forensic chain-of-custody requirements.

## Usage

```bash
# View all audit log entries
census audit-log show

# View the last 10 entries
census audit-log show --last 10

# Machine-readable output
census audit-log show --json

# Verify hash chain integrity
census audit-log verify

# Verify with JSON output (for CI/SIEM)
census audit-log verify --json

# Delete the audit log
census audit-log clear
```

## Log Format

Each line in the JSONL file is a JSON object:

```json
{
  "timestamp": "2026-03-18T14:30:00+0100",
  "action": "scan",
  "params": {"directory": "/data/hr", "dry_run": false},
  "result": {"total": 1250, "attested": 1250},
  "prev_hash": "a1b2c3...",
  "entry_hash": "d4e5f6..."
}
```

- `prev_hash` links to the previous entry (genesis is `0` * 64)
- `entry_hash` is SHA-256 of the entry content (excluding `entry_hash` itself)

## File Location

Default: `~/.local/share/certisigma-census/audit.jsonl`

Override via:
- `--log-path` CLI flag
- `audit_log_path` in census config

## Automatic Logging

The following commands automatically log to the audit trail:
- `census scan` (records directory, dry_run flag, total files, attested count)
- `census compare` (records suspect directory, match count)

Additional commands will be added in future versions.

## Security Properties

- **Append-only**: entries are only appended, never modified in place
- **Hash chain**: each entry includes SHA-256 of the previous entry
- **Tamper detection**: `verify` checks every link in the chain
- **Local storage**: the log never leaves the client machine
