Strix (STRIX) — report module

docs / modules / report

Strix (STRIX) — report

flowchart LR IN["IN: create_vulnerability_report()\ncalls from agents"] --> ACT["ACT: validate fields,\ncompute CVSS, dedup-check"] ACT --> VAL["VAL: LLM-judged\nduplicate detection"] VAL --> OUT["OUT: strix_runs//\nreport.md, vulns/*.md,\n.csv, .json, .sarif"]

What this is

strix/report is Strix's memory of what's been found so far in one scan, and the code that turns that memory into the files a human (or a CI pipeline) actually reads at the end. Every vulnerability an agent reports passes through here before it's considered "real" and every artifact on disk is written from here.

What flows through it

flowchart TD Tool["tools/reporting/tool.py\ncreate_vulnerability_report"] --> Dedupe["dedupe.py\ncheck_duplicate()\n(LLM judge)"] Dedupe -- "not a duplicate" --> State["state.py\nReportState\n(add_vulnerability_report)"] State --> Writer["writer.py\nwrite_run_record /\nwrite_executive_report /\nwrite_vulnerabilities"] State --> Sarif["sarif.py\nbuild + write_sarif_report"] Writer --> Disk[("strix_runs//")] Sarif --> Disk

Technical details

flowchart LR IN["IN: create_vulnerability_report()\ncalls from agents"] --> ACT["ACT: validate fields,\ncompute CVSS, dedup-check"] ACT --> VAL["VAL: LLM-judged\nduplicate detection"] VAL --> OUT["OUT: strix_runs//\nreport.md, vulns/*.md,\n.csv, .json, .sarif"]

Package: strix/report/ Depends on: strix.config (dedup model settings), strix.telemetry (cost callbacks). Depended on by: strix.tools.reporting (every write goes through ReportState), strix.tools.finish (finish_scan writes final narrative fields here), strix.core.runner (reads/writes the global ReportState), strix.interface (the viewer reads written artifacts back off disk; the CLI reads ReportState for live display).

Files at a glance

File Role
state.py ReportState — the in-memory + on-disk source of truth for one run; module-global singleton via get_global_report_state().
dedupe.py check_duplicate() — LLM-judged (or fast-path, for dependency findings) duplicate detection.
writer.py write_run_record(), write_executive_report(), write_vulnerabilities() — turns ReportState into on-disk Markdown/CSV/JSON.
sarif.py Builds SARIF 2.1.0 documents for CI/CD (findings.sarif).
pricing.py resolve_litellm_model() — LiteLLM pricing table lookups.
usage.py LLMUsageLedger — cumulative token/dollar cost tracking, including OpenRouter-specific streamed cost capture.

Files & functions, explained

state.py - ReportState(run_name) — tracks vulnerability_reports (the accumulating list), final_scan_result, an LLMUsageLedger, a run_record dict mirrored to run.json, and a vulnerability_found_callback hook the CLI/TUI register for live display. - get_run_dir() — lazily resolves/creates strix_runs/<run_name>/. - hydrate_from_run_dir() — resume support: reloads run.json and vulnerabilities.json, raising loudly on corruption rather than silently starting fresh (avoiding vuln-0001 ID collisions overwriting prior files). - add_vulnerability_report() — assigns a sequential vuln-NNNN ID and stores the full structured finding.

dedupe.py - check_duplicate(candidate, existing) -> dict — builds a dedicated small-model call (optionally a distinct DedupeSettings model/key, else the main LLM) with a system prompt instructing the model to judge "same root cause on same asset," parses a structured is_duplicate/duplicate_id/confidence/reason response. - _check_dependency_duplicate() — a deterministic fast path for CVE/dependency findings, keyed on package + version + CVE id instead of LLM judgment.

writer.py - write_vulnerabilities(run_dir, vulnerability_reports, saved_vuln_ids) — writes only new reports as individual vulnerabilities/<id>.md files (idempotent — safe to call repeatedly), while fully rewriting vulnerabilities.csv and vulnerabilities.json every time. This split is what makes resume safe: previously saved Markdown files are never re-touched.

sarif.py — maps each vulnerability report to a SARIF result (rule metadata, CVSS-derived severity, CWE normalization, code-location conversion), applies repository context (git remote/branch), and computes stable per-finding fingerprints so re-runs produce comparable/diffable SARIF across CI runs. (Reviewed at the function-signature level, not verified field-by-field against the SARIF 2.1.0 schema — see ../design/LLD.md's "not independently verified" note.)

Related: STRIX — Architecture (HLD), tools.md, ../design/data-flow.md.