Reports
What webtrax check writes, how findings are grouped and identified, and the NDJSON record format for scripts.
Findings and ids
A finding is one problem: one rule on one URL (for example, a broken link to /old-pricing). If ten pages link to that broken URL, it is one finding seen on ten pages. Each finding has a fingerprint, a SHA-256 of the rule id, the normalised URL and a rule-specific key, so the same problem has the same id on every run and every machine. Reports show the first ten characters as the finding id.
Formats
| Format | Where | For |
|---|---|---|
| Console summary | stdout (default) | People at a terminal. Colour only on a TTY; NO_COLOR turns it off. |
| HTML | report.html |
The full report, single file, works offline. |
| Markdown | report.md, or --stdout md |
Pull request comments and pasting into an AI chat: stable headings, finding ids, fixes. |
| JSON | report.json, or --stdout json |
Scripts and dashboards: summary, findings with their fixes, pages. |
| SARIF 2.1.0 | report.sarif (--reports sarif) |
GitHub code scanning and other security tools: one result per finding, levels by severity, the fingerprint as a partial fingerprint, rule help linking to these docs. |
| JUnit XML | report.junit.xml (--reports junit) |
CI dashboards: a test suite per check suite, a failing test case per finding. |
| NDJSON | run.ndjson |
Every record of the run, one per line. |
NDJSON records
run.ndjson starts with a run record and ends with a summary; in between are page, finding, metric, snapshot and artifact records. The format is versioned (protocol_version: 1), and JSON Schemas for it (job spec, run line, rule) ship with the @webtrax/protocol package.
| Record | Main fields |
|---|---|
run |
job_id, started_at, runner, user_agent, spec (the full job spec) |
page |
url, final_url, status or error, redirect_chain, depth, title |
finding |
fingerprint, rule_id, rule_version, severity, url, source_url, title, evidence (at most 2 KB) |
summary |
status (completed, partial, failed), stop_reason, pages, links, findings by severity, suites |