[Phase 1] Stage 5: Report generation (engineering + executive Markdown)

[varun-polpakkara]

Summary

Reads all DB data for a completed scan and generates two Markdown files via ReportGenerationAgent. This is the only stage where an LLM is always called. No DB writes — read-only against the database.

Engineering report

Aimed at developers and security engineers:

• Table of all findings sorted by severity/reachability
• Per-finding: CVE ID, CVSS score, vector, severity, component name/version, fix version, reachability status + rationale, exploit availability + details
• Triage history for any triaged finding

Executive summary

Aimed at programme managers and safety leads:

• ISO 21434 framing (cyber risk acceptance, CSMS posture)
• UNECE R155 compliance implications
• Risk heat map by severity/reachability
• Top 3-5 findings requiring management attention in plain language
• Recommended next actions

Interface

def run_report_stage(snapshot_id: UUID, *, db: Session, output_dir: Path,
                     report_agent: ReportGenerationAgent) -> ReportResult

Sets SBOMSnapshot.status = "COMPLETE". Raises ReportGenerationError if agent output is empty.

Verify

• Both .md files written to output_dir
• Engineering report contains CVE IDs + CVSS scores + fix versions
• Executive summary contains ISO 21434 / UNECE R155 language