# Forensic Reports

Census generates forensic reports suitable for legal proceedings, compliance audits, and forensic investigation handoff. Reports are generated **on demand** — never automatically during scan, compare, or watch operations.

## Output formats

Format is auto-detected from the output file extension:

| Extension | Format | Dependencies | Use case |
|-----------|--------|-------------|----------|
| `.html` | HTML | None (always available) | Browser viewing, quick sharing |
| `.pdf` | PDF | `fpdf2` via `pip install certisigma-census[report]` | Legal proceedings, compliance filings |
| `.zip` | Evidence bundle | None (PDF included if fpdf2 installed) | Complete forensic handoff package |

## Basic usage

```bash
# HTML report (always available, zero dependencies)
census report manifest.db -o report.html

# PDF report (requires fpdf2)
pip install certisigma-census[report]
census report manifest.db -o report.pdf

# Include evidence chain (fetches T0/T1/T2 from API)
census report manifest.db -o report.pdf --evidence

# Include integrity check results
census report manifest.db -o report.html --integrity

# Full report with everything
census report manifest.db -o report.pdf --evidence --integrity

# Evidence bundle (ZIP)
census report manifest.db -o bundle.zip --bundle --evidence
```

## Report sections

Both HTML and PDF reports contain the same sections:

1. **Header** — Tool version, generation timestamp, manifest root path
2. **Inventory summary** — Total files, attested count, pending count, breakdown by trust level (T0/T1/T2)
3. **File listing** — Path, SHA-256 (truncated), size, attestation status, attestation ID
4. **Evidence chain** (with `--evidence`) — Per-file T0 signature, T1 TSA details, T2 Bitcoin anchor with blockchain explorer URLs
5. **Integrity results** (with `--integrity`) — Unchanged/modified/missing/new summary and detail tables
6. **Verification instructions** — Step-by-step guide for independent verification (including `sha256sum` command)

## Evidence bundle

The `--bundle` flag (or `.zip` extension) produces a self-contained evidence package:

```
bundle.zip
├── report.html          # Always included
├── report.pdf           # Included if fpdf2 is installed
├── evidence.json        # Full T0/T1/T2 evidence chain data
├── proofs/
│   ├── att_123.ots      # OpenTimestamps proof for T2 attestations
│   └── att_456.ots
├── SHA256SUMS           # Checksums of all files in the bundle
└── README.txt           # Verification instructions
```

The bundle is designed for offline verification: an analyst can verify every file in the package without internet access using standard tools (`sha256sum`, `ots verify`).

### Verifying a bundle

```bash
# Unzip
unzip bundle.zip -d evidence/
cd evidence/

# Verify bundle integrity
sha256sum -c SHA256SUMS

# Verify individual OTS proofs
ots verify proofs/att_123.ots

# Cross-reference on Bitcoin blockchain
# (URLs are in evidence.json and the HTML/PDF report)
```

## Security considerations

- **No file content in reports**: Only hashes, paths, sizes, and attestation metadata. Content never leaves the client.
- **HTML XSS prevention**: All dynamic content in HTML reports is escaped via `html.escape()`.
- **PDF encoding**: Non-latin-1 characters are safely handled to prevent encoding errors.
- **Bundle path traversal**: OTS proof files use sanitized names (no path separators) to prevent ZIP path traversal.

## Design pattern

The on-demand report generation follows the same pattern used by industry-standard forensic tools:

| Tool | Report generation |
|------|------------------|
| **Census** | `census report manifest.db -o report.pdf` |
| **OSForensics** | Menu: Create Report → select format |
| **Magnet AXIOM** | Exhibit Builder → export |
| **Autopsy** | Generate Report → HTML/PDF |
| **Paliscope Build** | Dedicated report generation tool |

Reports are never generated automatically. The analyst decides when the investigation is complete and explicitly requests a report.
