Report generation and exports
Report generation turns scan findings, coverage, and model usage into durable run records and shareable reports. It keeps one per-scan state record, prevents the same issue from being filed twice, accounts for token use and cost, records what the scan did not examine, and emits SARIF for CI and code-scanning tools. See the parent page, Findings, usage, and reporting, for the wider reporting model.
Report lifecycle
The reporting flow starts with a finding, a coverage statement, or a completed model cycle and ends with files that other parts of the product or external tools can read. Report state is the link between live scan activity and those saved artifacts.
This diagram shows how accepted findings and observed scan activity become the human, machine, and structured views of one run.
flowchart LR
A[Scan finding] --> B[Report state]
B --> C{Existing finding?}
C -->|No| D[Add finding]
C -->|Yes| E[Reject duplicate]
D --> F[Write run artifacts]
B --> G[Record model usage]
B --> H[Assemble coverage]
G --> F
H --> F
F --> I[Markdown, CSV, JSON]
F --> J[SARIF]
Report state
home/…/state.py provides the per-scan report state. It holds the finding list, final scan result, run status, scan inputs, and usage summary so all report forms use the same view of a run. The state can reload an existing run before a resumed scan continues.
The state also controls the life of a finding after intake. A finding can be revised without losing its identity or withdrawn with a recorded reason. Withdrawn IDs are not reused, which keeps old files and downstream references from being assigned to a new issue.
Each saved state update refreshes the run record and the finding artifacts. It also rebuilds the coverage record and SARIF sidecar. Finding titles are normalized when they enter or reload state, and revised findings are marked for Markdown re-rendering. A corrupt finding file stops hydration instead of starting with an empty list, because an empty list could reuse an old finding ID and overwrite prior evidence.
References: strix/…/state.py• L197-238 strix/…/state.py• L260-330 strix/…/state.py• L441-637 strix/…/state.py• L790-897
Finding records
The reporting tool validates a candidate finding, applies its CVSS result, and asks report state to store it. A stored record keeps the core triage data such as title, severity, location, evidence, impact, remediation, and optional code or dependency context. It can also retain IDs for linked HTTP exchange evidence.
The record receives a stable run-local ID. New findings are saved at once and can notify the live interface, so later views and exports see the same finding that the scan accepted. A later withdrawal removes the finding from active outputs while retaining a compact deletion record for audit and ID allocation.
References: strix/…/tool.py• L220-241 strix/…/tool.py• L288-329 strix/…/state.py• L332-439 strix/…/state.py• L557-637
Finding revisions
An accepted finding can be revised without changing its run-local identity. State limits revisions to report content, removes dependent explanations when their rating or location changes without new reasoning, and records the author, reason, changed fields, and selected prior values in an update history. The writer includes that history in the finding Markdown so later changes remain visible rather than silently replacing the original record.
The persistence callback receives the complete revised record before the in-memory record changes. If persistence rejects the revision, the old evidence stays available and the update can be retried. A successful revision causes the writer to render the finding again.
References: strix/…/state.py• L459-555 strix/…/writer.py• L359-396
Coverage record
The coverage record describes the scan surface that produced no finding as well as the findings that were filed. It keeps agent-reported statements separate from machine-observed facts such as which agents ran, which risk skills they carried, how many findings were filed, and whether the run finished.
The record marks open follow-up items, silent agents, and risk classes that an assigned skill did not address as gaps. It marks a run incomplete when the run or an agent stopped early. This prevents a clean-looking finding list from being read as proof that every intended surface was checked.
References: strix/…/coverage.py• L45-66 strix/…/coverage.py• L143-215 strix/…/coverage.py• L230-352 strix/…/coverage.py• L363-443
Artifact set
The writer creates several views of the same run for different readers. Markdown gives people a detailed finding report, CSV gives index-style access, JSON preserves the full finding data, run.json keeps run status, inputs, final text, and usage together, and coverage.json records examined scope and gaps.
The writer updates the index and JSON snapshot on each save, writes each new finding as its own Markdown file, and re-renders findings that changed during a revision. A withdrawal rewrites the active indexes and removes the finding Markdown while keeping its deletion history in the run record. It also writes the coverage and SARIF sidecars on each save. Shared text paths use atomic replacement, finding titles are kept to one line, spreadsheet formula prefixes are neutralized in CSV cells, and code content is escaped or fenced as needed so attacker-controlled finding text cannot break the output format.
References: strix/…/writer.py• L35-66 strix/…/writer.py• L119-221 strix/…/writer.py• L223-396 strix/…/state.py• L557-637 strix/…/state.py• L850-897
Finding deduplication
Finding deduplication decides whether a candidate describes the same security issue as a finding already in the run. It protects the report from repeated submissions while keeping separate issues separate when their location, cause, parameter, or access conditions differ.
Duplicate decision
The dedupe check first handles dependency findings through their CVE, package, ecosystem, and manifest identity. A matching CVE and package in different manifests remains separate when both manifest paths are known. Older reports without structured dependency metadata use a limited legacy text check.
For other findings, the check compares the technical report fields with a dedicated judge or the main model when no dedicated model is set. The check returns a decision with a duplicate ID, confidence, and reason. The comparison focuses on root cause, affected location, attack method, and the likely fix. It does not treat similar titles or the same broad weakness type as enough to merge findings.
When the check has no existing findings, no model, an empty response, or an error, it allows the candidate through and reports the reason for the uncertain result. Any model use by the dedupe judge is recorded in the run usage ledger.
References: strix/…/dedupe.py• L162-285 strix/…/dedupe.py• L328-416
Usage and pricing accounting
Usage accounting records model activity as part of the run rather than as a separate report. The ledger keeps total tokens and per-agent usage, then attaches a best-effort cost so the run record can show both resource use and its estimated charge.
Usage ledger
LLMUsageLedger aggregates SDK usage for each agent and for the complete run. It ignores empty usage events, keeps model and agent labels, and can reload the aggregate from run.json when a run resumes. The report exposes total usage and also a process-only delta for telemetry.
Subscription-backed runs still record token counts. Their cost is forced to zero because the product does not treat those tokens as a metered per-token charge.
References: strix/…/usage.py• L16-96 strix/…/usage.py• L98-139 strix/…/state.py• L642-715
Cost sources
The ledger prefers observed provider cost when a model response supplies it. If observed cost is not available, it estimates cost from token use and the model price data known to LiteLLM. Per-agent cost is then allocated from the run total in proportion to each agent’s token use.
Streaming responses and provider-specific billing can expose cost in different places. The active report state accepts these observed costs separately, including upstream cost for OpenRouter BYOK responses. Model-name resolution tries provider-qualified and known bare names before giving up. A missing price entry therefore affects cost reporting but does not prevent token usage from being saved.
References: strix/…/usage.py• L51-69 strix/…/usage.py• L141-222 strix/…/pricing.py• L9-54 strix/…/state.py• L958-1021 strix/…/state.py• L1065-1221
SARIF export
SARIF is the structured output path for CI, code-scanning, and application security platforms. The exporter converts each accepted finding into a SARIF 2.1.0 result and preserves enough location, severity, identity, remediation, coverage, and run-completeness data for downstream systems to display and reconcile alerts.
Finding mapping
Each finding becomes a SARIF result under a stable rule. The rule ID prefers a normalized CWE, then a CVE, finding ID, or title slug. Strix severity maps to SARIF’s three levels, while the original severity and CVSS remain available in Strix properties. CWE data also supplies threat-model tags for consumers that group findings by STRIDE leg.
Source locations are accepted only when they are safe repository-relative paths. Findings without a usable source location remain in the export through a synthetic SECURITY.md anchor and a marker that tells consumers the location is synthetic. Endpoint findings also keep a logical endpoint location.
Fix suggestions are exported when a finding has a safe source location and a before-and-after change. The SARIF result carries the remediation text and replacement data without exporting the exploit script body.
References: strix/…/sarif.py• L201-302 strix/…/sarif.py• L429-638 strix/…/sarif.py• L771-854 strix/…/sarif.py• L862-1136
Coverage results
Coverage statements share the SARIF document with findings as non-failing results. A surface marked as having no issue is a pass, a non-applicable surface is not applicable, and a follow-up item is open. Consumers that only want alerts can filter for failing results.
Run completeness is carried in the SARIF invocation. Early termination or unfinished agents make execution unsuccessful and add warning notifications, so incomplete coverage is not mistaken for a clean completed scan.
References: strix/…/sarif.py• L645-747 strix/…/coverage.py• L314-352 strix/…/state.py• L828-848 strix/…/state.py• L878-893
Alert identity
SARIF fingerprints give code-scanning tools a stable way to match an alert across runs. The primary fingerprint uses the normalized rule, source location, and route where available, while a class fingerprint helps carry a dismissal across a file rename. This keeps cosmetic changes in model-written text from changing the identity of an underlying issue.
References: strix/…/sarif.py• L459-507 strix/…/sarif.py• L957-1081
Repository provenance
Repository scans can bind SARIF alerts to the source that produced them. When one repository target is unambiguous, the export records its URI and may include the repository name, commit, branch, and ref. URL and IP scans do not claim repository provenance.
This context lets code-scanning systems reconcile results for the same repository and revision. If the run has multiple repository targets or the source metadata is incomplete, the exporter omits ambiguous provenance instead of assigning findings to the wrong repository.
References: strix/…/state.py• L135-183 strix/…/state.py• L899-945 strix/…/sarif.py• L387-421
Export reliability
The SARIF file is written through a temporary sibling file and then replaced, so a failed write does not leave a partial export. Report state emits the file on every artifact save, including an empty result set, so a clean run can clear stale findings in systems that resolve alerts from absent results.
SARIF failure is isolated from the main report path. Markdown, CSV, JSON, coverage, and the run record can still be saved when SARIF construction or writing fails.
References: strix/…/sarif.py• L305-364 strix/…/state.py• L850-897
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the finding fields used by the reporting tool, Markdown writer, JSON snapshot, and SARIF properties aligned. A new field can be accepted in one output and silently disappear from another.
- Preserve the run-resume contract between vulnerabilities.json, finding IDs, deleted-finding history, and the saved-ID set. Changes to ID creation or hydration can cause old finding files to be overwritten or withdrawn IDs to be reused.
- Keep finding revision rules aligned with Markdown update history. A field that changes a rating or location must not leave behind reasoning that describes the old value.
- Keep revision and deletion callbacks transactional with local state. A persistence failure must leave the old finding available for retry rather than expose a half-applied update.
- Keep dependency identity rules in sync with the fields that dependency reports provide. A change to manifest identity can merge findings from separate manifests or split one finding into several.
- Keep coverage outcomes, gap rules, and SARIF non-failing result kinds aligned. A mismatch can make an unexamined surface look clean or hide it from a downstream view.
- When changing model names or provider cost data, check both token estimates and observed streaming costs. The two paths use different sources.
- When changing SARIF rule identity or fingerprints, check alert reconciliation across reruns and file moves. Small identity changes can create duplicate external alerts.
- When changing repository target data, check the single-repository condition before adding SARIF provenance. Ambiguous context must not bind a run to the wrong repository.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| No active report state when a finding is filed | The tool reports success but does not persist the finding | The tool returns a warning that persistence was not available; callers must create state before filing findings |
| Corrupt vulnerabilities.json during resume | The scan does not continue with an empty list | Hydration raises an error to prevent reused IDs and overwritten finding files |
| A revision changes confidence, severity, CVSS, or code locations without replacement reasoning | The finding could retain an explanation for a superseded value | State removes the dependent explanation and records the dropped field in update history |
| Revision persistence rejects the revised record | The finding remains unchanged and the update can be retried | The persistence callback runs before local state is replaced |
| Finding deletion or its callback fails | The finding can be restored, but indexes may need a later save if rollback also fails | State restores the active finding and records a rollback error when on-disk indexes cannot be restored |
| Deduplication model fails or returns no usable text | The candidate is allowed through and may repeat an existing issue | The result carries zero confidence and a reason so the accepted finding can be reviewed |
| No usable LiteLLM price for a model | Token counts remain available but estimated cost may be zero | Observed provider cost is recorded when present; pricing remains best effort |
| Agent graph or coverage assembly is unavailable | The run can lack its coverage record and its completeness warnings | Coverage assembly is secondary and logged as non-fatal; the findings and run record remain available |
| Unsafe or missing SARIF source location | Unsafe locations are omitted and locationless findings use a synthetic anchor | SARIF records dropped-location counts and marks synthetic locations |
| SARIF build or write error | The structured export is missing or stale for that save | The error is non-fatal to Markdown, CSV, JSON, coverage, and run-record writing |
Key files
| File | Why to read it |
|---|---|
| strix/…/state.py | Central per-scan state and the save path that connects findings, usage, coverage, run records, withdrawals, and exports |
| strix/…/writer.py | Shared human-readable and machine-readable artifact views |
| strix/…/coverage.py | Coverage record that separates agent claims from runtime facts and exposes gaps |
| strix/…/tool.py | Finding intake, validation, CVSS handling, and the handoff to deduplication and state |
| strix/…/dedupe.py | Duplicate decision rules for general findings and dependency findings |
| strix/…/usage.py | Token aggregation, per-agent summaries, and cost selection |
| strix/…/pricing.py | Model-name lookup used by cost estimates |
| strix/…/sarif.py | SARIF document creation, coverage results, location handling, provenance, and alert identity |