Findings, usage, and reporting
The findings and reporting system turns verified scan results into one shared record of security issues, model use, scan coverage, and run status. It prevents repeated findings, keeps cost data separate from security evidence, and delivers the same run through human-readable files, structured exports, and a protected viewer.
Reporting model
The system accepts two kinds of confirmed security result. It then combines each accepted result with run context and usage data so later readers do not need to rebuild the scan history.
This diagram shows how a scan observation becomes a saved finding and then reaches people or external tools.
flowchart LR
A[Verified scan result] --> B[Finding intake]
B --> C{Same issue already recorded?}
C -->|Yes| D[Reject repeat]
C -->|No| E[Shared run state]
E --> F[Human-readable reports]
E --> G[JSON and CSV records]
E --> H[SARIF export]
E --> I[Protected viewer and PDF delivery]
J[Model usage] --> E
K[Coverage ledger and runtime facts] --> E
Finding records
The reporting tools in home/…/tool.py define the contract for a finding before it enters the shared report state. A record describes what was found, where it was found, why it matters, how it was proved, how captured HTTP exchanges support it, and how to fix it.
The shared state also cleans finding titles into one line before it saves them. This keeps titles safe and readable in Markdown headings, CSV cells, and live lists without changing the evidence or analysis fields.
An accepted finding keeps its ID when later evidence or triage data changes. The update record notes the changed fields, the reason, the author, and selected prior ratings. When a rating or source location changes without new supporting text, the state removes the old text that described the superseded value. This keeps the current finding and its explanation aligned.
The record can include these groups of information:
- Identity and triage: title, run-local ID, severity, CVSS score, CWE, and CVE.
- Location and proof: target, endpoint, method, evidence, proof-of-concept text, captured HTTP exchange IDs, and optional code locations.
- Action: impact, remediation, fix effort, assumptions, and optional suggested changes.
- Ownership and context: the agent that filed the finding and dependency details when the result concerns a package.
The intake path validates required content and calculates the CVSS result from the supplied attack and impact facts. This keeps severity tied to the demonstrated consequence instead of to a broad vulnerability label.
References: strix/…/tool.py• L23-32 strix/…/tool.py• L128-147 strix/…/tool.py• L150-241 strix/…/state.py• L227-316 strix/…/state.py• L417-509
Finding classes
The system separates dynamically proved vulnerabilities from known dependency advisories because the two classes have different evidence and rating rules. Both classes use the same stored record and downstream report views.
| Finding class | Evidence basis | Rating basis |
|---|---|---|
dynamic | A validated proof of concept shows an unauthorized security consequence | CVSS metrics supplied for the demonstrated attack |
dependency_cve | A verified advisory matches an installed package version | The published advisory score or a code-specific contextual CVSS rating |
Dependency usage analysis records whether application code imports the package or reaches the affected symbol. This is a prioritization signal. It does not suppress the finding or prove that the package is safe.
References: strix/…/tool.py• L704-730 strix/…/tool.py• L798-867 strix/…/tool.py• L916-1090 strix/…/tool.py• L1111-1181
Coverage records
Coverage records explain what the scan examined, not only what it found. They keep agent-reported outcomes separate from facts observed by the runtime, such as assigned risk skills, agent completion, findings filed, and whether the run ended cleanly.
The record marks open items as gaps. A risk skill with no matching coverage entry is unexamined rather than clean. An agent that records no coverage is also called out, while the coordinating root agent is exempt when it delegated work. The record is saved as coverage.json and can also travel in SARIF as non-failing results and run-completeness warnings.
This diagram shows how reported coverage and runtime facts combine into a completeness view.
flowchart LR
A[Agent coverage ledger] --> C[Coverage record]
B[Runtime agent graph] --> C
D[Run status and exit reason] --> C
E[Filed findings] --> C
C --> F[coverage.json]
C --> G[SARIF coverage results]
C --> H[Completeness caveats]
References: strix/…/coverage.py• L143-215 strix/…/coverage.py• L230-352 strix/…/coverage.py• L363-443 strix/…/state.py• L520-553
Duplicate control
Duplicate control keeps one report for one underlying issue within a scan. The check runs before persistence and returns a duplicate ID, confidence, and reason when it rejects a candidate.
For normal findings, the decision centers on the root cause, affected location, attack method, and likely fix. Similar titles or the same weakness type do not merge findings when the endpoint, parameter, access condition, or cause differs. Dependency findings first use CVE, package, and ecosystem identity. Different manifest paths can remain separate findings when the same package issue appears in distinct manifests. Older dependency records can still be compared through their stored text when they do not have structured package metadata.
If there is no prior finding, or if the judge cannot give a usable answer, the system allows the candidate through with a low-confidence reason. A dedicated dedupe model can use its own endpoint and credentials, and its token use is recorded as run usage. This favors retaining possible evidence over silently losing a finding.
References: strix/…/dedupe.py• L33-63 strix/…/dedupe.py• L66-133 strix/…/dedupe.py• L162-285 strix/…/dedupe.py• L328-416 strix/…/tool.py• L255-286
Run state and persistence
Every scan has one report state that joins accepted findings, final scan text, inputs, status, coverage, and model usage. The state gives live views and saved reports the same source of truth.
Per-scan state
The per-scan state in home/…/state.py assigns run-local finding IDs and saves accepted findings as soon as they are added. It also keeps callback paths for live interfaces and persistence boundaries, so a new or revised finding can be accepted by the receiving layer before the local state moves to the new record. Each save refreshes the coverage record and SARIF sidecar as well as the core run files.
An existing finding can be revised without changing its ID. The revision is saved in the shared finding list and its detail document is rendered again, so the JSON record, Markdown view, and live update all describe the same current result. When a run resumes, the state restores its run record and prior finding list. A damaged finding snapshot is treated as a stop condition rather than as an empty run, because starting with empty state could reuse an old ID and overwrite evidence.
The run record can also retain timing for each tool call. Each timing entry links the tool and agent to its start time and duration, which helps explain scan activity alongside model request usage.
References: strix/…/state.py• L116-178 strix/…/state.py• L180-252 strix/…/state.py• L254-378 strix/…/state.py• L417-509 strix/…/state.py• L482-581 strix/…/state.py• L1048-1063
Saved artifact views
The writer in home/…/writer.py presents one run in several forms for different readers. Detailed Markdown supports human review, CSV provides a compact index, JSON preserves the finding records, and the run record carries status, inputs, final scan text, and usage. Coverage and SARIF add scan completeness and security-platform views to the same run.
The executive report is written only when final scan text exists. Finding Markdown files are created for new records and re-rendered when a finding is revised, while the index, JSON snapshot, coverage record, and SARIF document are refreshed as the run changes. CSV cells are protected from spreadsheet formula execution, and code content is placed in fences that cannot be closed by embedded backticks. The shared write paths use replacement of temporary files where a partial write could otherwise look complete.
References: strix/…/writer.py• L35-116 strix/…/writer.py• L119-198 strix/…/writer.py• L201-221 strix/…/writer.py• L223-395 strix/…/state.py• L495-510 strix/…/state.py• L542-581
Usage and pricing
Usage accounting measures model work for the run without mixing that measure with finding severity. It records token activity per agent and for the full run, then adds the best available cost view.
Usage ledger
The ledger in home/…/usage.py aggregates non-empty model usage events and keeps agent and model labels with them. The saved usage record supports both a run total and a per-agent view, which helps explain where model work went.
Subscription-backed runs still keep their token counts. Their reported cost is zero because the product does not treat subscription use as a metered per-token charge. Resumed runs reload the saved totals before adding new activity. When the active run state is cleared for a new run, pending streamed-cost entries are also discarded so one run cannot receive another run's cost.
References: strix/…/usage.py• L16-96 strix/…/usage.py• L98-139 strix/…/state.py• L166-175 strix/…/state.py• L321-365
Cost accounting
Cost reporting prefers a provider-reported charge when one is available. If it is not available, the ledger estimates cost from token counts and the model price data known to LiteLLM.
Streaming responses and provider-specific billing can expose charges through different response fields. The active run state accepts those observed charges separately and can recover a charge saved while a stream is being rebuilt. Model-name resolution tries provider-qualified and bare model names. If no price is known, token usage remains valid and the cost estimate may be zero.
References: strix/…/usage.py• L51-69 strix/…/usage.py• L160-222 strix/…/pricing.py• L9-54 strix/…/state.py• L363-407 strix/…/state.py• L643-841
Report delivery
The product delivers a run through local files, structured data, and a viewer that can package a completed assessment for sharing. Each path uses the same accepted findings but serves a different reader.
Human-readable reports
Human-readable output includes the executive Markdown report, one detailed Markdown document per finding, and a branded PDF assessment. These views retain the narrative fields that explain the issue and its proof.
The PDF includes full finding detail, including proof-of-concept scripts. It is encrypted locally with a generated password. The password is shown only to the authorized local browser, while the delivered file remains encrypted outside that browser.
References: strix/…/writer.py• L139-145 strix/…/writer.py• L148-198 strix/…/writer.py• L223-395 strix/…/report_pdf.py• L1-12 strix/…/report_pdf.py• L603-664
Machine-readable reports
Machine-readable output supports local automation and security platforms. JSON preserves the full finding data, CSV provides a simple finding index, and SARIF 2.1.0 maps findings into a format used by code-scanning and application security tools.
SARIF keeps source-linked findings when paths are safe and repository-relative. A finding without a usable source location remains visible through a marked synthetic anchor, while endpoint findings retain a logical endpoint location. Unsafe locations are omitted and counted instead of being emitted as invalid paths. The export also carries stable alert identity, severity data, threat-model tags, remediation suggestions when safe, and repository provenance when one repository target is unambiguous.
SARIF includes coverage outcomes that are not findings. A clean or ruled-out surface becomes a passing result, an inapplicable surface becomes not applicable, and an open review item becomes open. Incomplete runs set execution success to false and include warnings, so a truncated scan does not look clean. The export includes proof-of-concept descriptions and signals that a script exists, but it does not send exploit script bodies to external systems.
For the detailed lifecycle of state, deduplication, usage, pricing, and SARIF generation, see Report generation and exports.
References: strix/…/sarif.py• L201-302 strix/…/sarif.py• L305-364 strix/…/sarif.py• L429-582 strix/…/sarif.py• L585-638 strix/…/sarif.py• L645-747 strix/…/sarif.py• L771-854 strix/…/sarif.py• L862-1105 strix/…/state.py• L561-576
Viewer delivery
The viewer reads the saved run record and finding snapshot to show scan status, severity counts, the executive report, and finding details. Its report-send path accepts only a completed run and requires an authorized session plus verified account state.
After authorization, the viewer builds and sends the encrypted PDF through the report relay. It returns the password to the authorized browser only after the relay accepts the file. A live or unfinished run cannot be sent as a partial assessment.
References: strix/…/transcript.py• L19-87 strix/…/server.py• L356-394 strix/…/server.py• L480-498
Change checklist
When these files or sections are changed, remember to consider these:
- Keep finding fields aligned across intake validation, shared state, Markdown, JSON, CSV, PDF, and SARIF. A field accepted at intake can silently disappear from a downstream view.
- Preserve the link between finding IDs, the JSON snapshot, and per-finding Markdown files. ID, resume, or revision changes can overwrite old evidence or leave stale detail text.
- Keep callback ordering aligned with persistence and live-view contracts. A receiver must see a complete new or revised finding, while a failed callback must not leave local state partly changed.
- Keep revision rules aligned with dependent explanation fields. A new severity, confidence value, CVSS score, or code location must not retain reasoning that describes the old value.
- Keep dynamic and dependency finding rules distinct. A dependency advisory must not be treated as a PoC-backed result, and reachability must remain a prioritization signal.
- Keep duplicate identity rules aligned with dependency metadata, legacy report text, and manifest paths. A change can either merge separate package findings or create repeated alerts.
- When changing model or provider handling, check both observed streaming charges and token-based estimates. They use different data sources.
- When changing run-state reset or streamed-cost handling, check that pending cost data cannot cross a run boundary while resumed usage totals remain intact.
- When changing coverage outcomes or agent status rules, check both coverage.json and SARIF completeness. A missing ledger entry must remain an explicit gap rather than a clean result.
- When changing SARIF identity, source locations, threat-model tags, or repository context, check cross-run alert matching, safe-path handling, and multi-repository scans. Ambiguous provenance must stay omitted.
- When changing exported finding fields, check that proof-of-concept script bodies remain local and that CSV and Markdown rendering still treat scanned text as data.
- Preserve the completed-run and authorization boundary for PDF delivery. The relay must receive only the encrypted file and its delivery metadata.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A finding is filed without active report state | The caller receives a success response but no finding is saved | Create and register per-scan state before finding intake begins |
| A finding callback rejects a new or revised finding | Local state does not accept the new record, so the live or persistent view cannot move ahead of the saved evidence | Keep the callback before local mutation and retry from the unchanged record |
| The saved finding snapshot is corrupt during resume | The scan cannot safely continue with prior findings | Refuse to start with an empty list so old IDs and evidence cannot be overwritten |
| A revision changes a rating or location without replacing its explanation | The report can show a current value beside reasoning for the old value | Drop dependent explanation fields when their primary field changes without replacement |
| The duplicate judge fails or gives no usable result | A repeated finding can enter the report | Allow the candidate through but keep the decision reason and confidence visible for later review |
| An agent has a vulnerability skill but no matching coverage entry | The report could imply that the risk class was tested when it was not | Record the class as an unrecorded risk gap |
| A run stops early or an agent remains unfinished | A partial coverage record could be read as a clean scan | Set completeness to false and include the reason as a caveat and SARIF warning |
| A model has no known price or provider charge | Token totals remain usable but cost can be incomplete or zero | Treat pricing as best effort and retain the usage record |
| Pending streamed cost data remains when the active run changes | A later run can receive an earlier run's provider charge | Clear the pending stream-cost store when the global report state changes |
| SARIF receives unsafe source paths | Invalid source locations could break or mislead code-scanning consumers | Reject unsafe paths, count them, and retain the finding with a synthetic anchor when needed |
| A finding contains backticks or spreadsheet formula text | A human-readable or CSV report can render unsafe content as structure or a formula | Use adaptive Markdown fences and literal CSV cells |
| A report-send request targets a live run | A recipient could receive a partial assessment | Require a terminal run with an end time before building the PDF |
| A report-send request lacks session or verification state | The report or PDF password could be exposed | Require the process session and verified account before relay delivery |
Key files
| File | Why to read it |
|---|---|
| strix/…/tool.py | Finding intake, validation, CVSS rating, finding classes, and read access for scan-wide findings |
| strix/…/state.py | The shared per-scan record that connects findings, revisions, evidence links, coverage, usage, run status, persistence, exports, and tool-call timing |
| strix/…/coverage.py | Coverage claims, runtime-observed gaps, and scan completeness |
| strix/…/dedupe.py | The rules that distinguish repeated findings from separate issues |
| strix/…/usage.py | Token aggregation, per-agent usage, and cost selection |
| strix/…/pricing.py | Model-name lookup used for local cost estimates |
| strix/…/writer.py | Human-readable and local machine-readable artifact views, revision rendering, and safe file writes |
| strix/…/sarif.py | Structured security and coverage export, source locations, alert identity, threat-model tags, and repository provenance |
| strix/…/transcript.py | The saved-run data read by the viewer |
| strix/…/report_pdf.py | Full-detail PDF creation and local encryption |
| strix/…/server.py | Authorization and completed-run checks for report delivery |