# 21 — Reporting Standards

**Status:** Ratified
**Version:** 1.0.0
**Applies to:** Reporting Engine, renderers, templates, exports, evidence packages

---

## 1. Purpose

Reporting transforms **canonical, evidence-backed findings** into professional
artifacts for technical teams, executives, compliance reviewers, and
integrators. Reports are derived **only** from the Unified Security Schema
(`08`) — renderers never touch raw findings directly.

---

## 2. Report Views

| View | Audience | Content |
|------|----------|---------|
| **Technical** | Pentester/engineer | Full detail: every finding, evidence, reproduction, affected assets |
| **Executive** | Management | Summary, risk posture, top findings, remediation priorities |
| **Evidence Package** | Reviewer | Raw evidence: screenshots, requests/responses, logs, payloads (checksummed) |
| **Timeline** | Reviewer/auditor | Chronological mission timeline (phases, findings, approvals, tool runs) |
| **Compliance** | Compliance | Mapping to frameworks (OWASP, PCI-DSS, MITRE) |

---

## 3. Report Data Model

A report is assembled from `ReportBundle`:

- `mission` summary (scope, dates, status).
- `assets` inventory (canonical, deduplicated).
- `findings` (severity-ordered, correlated, deduplicated, with evidence refs).
- `risk` rollups (per asset, per domain, mission total).
- `timeline` entries.
- `compliance` mappings.
- `metadata` (template version, generator version, generated_at, content_hash).

Every report is **deterministic**: same mission state + same template version =
same bytes (up to embedded dynamic timestamps, which are pinned in headers).

---

## 4. Export Formats

| Format | Use | Notes |
|--------|-----|-------|
| JSON | Machine consumers, API, re-import | Canonical; includes full USS payload |
| Markdown | Docs, Git, quick review | Human-readable, portable |
| HTML | Web review, dashboards | Self-contained; no external assets |
| PDF | Client delivery | Paginated, branded, cross-platform |
| SARIF | IDE/CI integration | Findings mapped to SARIF 2.1.0 schema |
| CSV (future) | Spreadsheet consumption | Flat finding table |

- JSON is the **source of truth** for format fidelity; other formats derive from it.
- SARIF mapping: rule = finding category; level = severity; location = primary
  affected asset; `relatedLocations` = evidence endpoints; `partialFingerprints`
  = canonical finding hash; `properties` = provenance + CWE/CVE refs.

---

## 5. Evidence Package

- Bundles: screenshots, raw HTTP request/response pairs, logs, tool raw
  outputs (within retention), payloads used, verification transcripts.
- Each artifact records: object key, SHA-256, captured_at, source tool/step,
  redaction status.
- Package is a **checksummed archive** (zip with a manifest.json + per-file
  hashes) so reviewers can verify integrity.
- PII and secrets are redacted before packaging (masking at export boundary).

---

## 6. Timeline Report

Renders `TimelineEntry` sequence with:

- Phase/step boundaries.
- Finding lifecycle (new → confirmed → reported).
- Approvals and scope decisions.
- Tool runs (tool, target, duration, outcome).
- AI decisions (draft/triage provenance).
- Operator actions.

Used for auditability and client trust.

---

## 7. Compliance Mapping

| Framework | Mapping source |
|-----------|----------------|
| OWASP Top 10 | finding category → A1..A10 |
| MITRE ATT&CK | CVE/finding → technique |
| PCI-DSS | finding category → requirement |
| ISO 27001 / NIST CSF | finding class → control family |
| (extensible) | compliance mapping plugin (`05`) |

Mappings are **explicit and reviewed**; never LLM-guessed for compliance
reports (deterministic mapping files; AI drafting optional and labeled).

---

## 8. Rendering Pipeline

```
ReportService.request(mission, views, formats)
  → assemble ReportBundle (from TIDB + graph + evidence refs)
  → for each view: apply template (versioned)
  → for each format: render (deterministic)
  → compute content_hash
  → store artifacts in object store + report records
  → emit report.generated event → notify subscribers
```

- Long renders run as async jobs (`20` §6).
- Renderer pool bounded (PDF/image-heavy) per `14` §8.

---

## 9. Templates

- Templates are versioned; a report records `template_version`.
- Template changes: additive/minor = minor template bump; structural change =
  major (older reports remain reproducible).
- Report templates support: HTML/CSS (HTML+PDF), Jinja (MD/HTML), JSON schema
  (JSON), SARIF schema.

---

## 10. Branding & Internationalization

- Branding (logo, client name) injected at render; never baked into data.
- Locale/templates: report text templated; i18n supported for UI-facing
  formats (MD/HTML); JSON/SARIF always canonical English keys.

---

## 11. Versioning & Retention of Reports

- Reports are immutable artifacts: a new generation creates new report records;
  old ones retained per retention policy (`09` §8).
- `content_hash` enables deduplication and verification.
- Re-generate vs re-render: regenerate = re-run analysis (new data);
  re-render = same data, new format/template.

---

## 12. Security of Reports

- Access control: report visibility per engagement/RBAC (`13` §4).
- Redaction of secrets/PII at packaging boundary (masking + tests).
- PDF: metadata sanitized (no internal paths/emails unless intended).
- HTML: self-contained, no external fetch; CSP embedded.
- Signing (optional): report artifact signature for delivery integrity.

---

## 13. Reporting Quality Gates

- All findings in technical report reference evidence (`evidence_refs`).
- Executive report excludes raw payloads; summarizes with risk posture.
- No secrets in any format — verified by security tests (`15` §6).
- Mandatory formats per mission profile honored (`12` §7).

---

## 14. References

- `08 - Unified Security Schema.md` (report entities)
- `12 - Mission Profiles.md` (expected output contract)
- `13 - Security Standards.md` (redaction, access control)
- `15 - Testing Standards.md` (report golden tests)