Context
During the first real pilot (groundwork, axon, jodhpur_sweets — see internal pilot report), the audit findings were manually assembled into a polished, shareable HTML report so they could go to PMs/BAs without requiring anyone to read raw JSON or terminal output. That process should become a real feature of kshield, not a one-off manual step.
Proposal
A report generator that turns an audit run's existing data into the same kind of shareable HTML document — built into the tool, usable by any developer without an AI in the loop.
Where it fits (nothing new to invent on the data side):
/api/v1/audit's JSON response and the audit_runs table already carry everything a report needs — findings, severities, counts, per-run metadata.- The new piece is purely a renderer: a template that turns that JSON into HTML.
Reuse Quiet Office instead of building new review infrastructure:
The pilot report's "reviewed, ruled out" section (a finding shown with a human's justification for why it's a false positive) maps directly onto what POST /api/v1/audit/dismiss-finding already does. The report generator should show:
- Active findings prominently
- Anything already dismissed via Quiet Office in a separate "reviewed" section, with its stored justification
No new annotation system needed — just a new consumer of what M7 already built.
Important caveat — scope this honestly
The pilot report included manual source-verification (actually reading files to confirm a finding was a true/false positive) that the tool itself cannot do. An automated report will be rawer than the pilot one: accurate to what the detection engines found, plus whatever's already been dismissed via Quiet Office — but without a "someone actually checked this" layer unless that review has happened first. Document this clearly in the report's own footer/methodology section so it isn't mistaken for a fully human-reviewed document by default.
Proposed shape
- CLI:
kshield report <name> (or a --report out.html flag on kshield agent) — pulls the latest run for that name and renders it locally
- Backend:
GET /api/v1/audit/report/{name} returning HTMLResponse, built from a template (Jinja2 — new, small, well-established dependency) using the same design tokens/severity color system as the pilot report
- Template lives in the backend so both the CLI and any future dashboard UI can reuse it
Open decision for whoever picks this up
Single-repo report only for v1, or also a fleet-wide version that aggregates multiple audit_runs entries into one document (the way org-audit.sh already aggregates data across repos)? Single-repo is the smaller first milestone; fleet-wide is more work but is the version that matters for the eventual org-wide rollout use case.
Filed by request — not yet scoped to a specific milestone.
Context
During the first real pilot (groundwork, axon, jodhpur_sweets — see internal pilot report), the audit findings were manually assembled into a polished, shareable HTML report so they could go to PMs/BAs without requiring anyone to read raw JSON or terminal output. That process should become a real feature of kshield, not a one-off manual step.
Proposal
A report generator that turns an audit run's existing data into the same kind of shareable HTML document — built into the tool, usable by any developer without an AI in the loop.
Where it fits (nothing new to invent on the data side):
/api/v1/audit's JSON response and theaudit_runstable already carry everything a report needs — findings, severities, counts, per-run metadata.Reuse Quiet Office instead of building new review infrastructure:
The pilot report's "reviewed, ruled out" section (a finding shown with a human's justification for why it's a false positive) maps directly onto what
POST /api/v1/audit/dismiss-findingalready does. The report generator should show:No new annotation system needed — just a new consumer of what M7 already built.
Important caveat — scope this honestly
The pilot report included manual source-verification (actually reading files to confirm a finding was a true/false positive) that the tool itself cannot do. An automated report will be rawer than the pilot one: accurate to what the detection engines found, plus whatever's already been dismissed via Quiet Office — but without a "someone actually checked this" layer unless that review has happened first. Document this clearly in the report's own footer/methodology section so it isn't mistaken for a fully human-reviewed document by default.
Proposed shape
kshield report <name>(or a--report out.htmlflag onkshield agent) — pulls the latest run for that name and renders it locallyGET /api/v1/audit/report/{name}returningHTMLResponse, built from a template (Jinja2 — new, small, well-established dependency) using the same design tokens/severity color system as the pilot reportOpen decision for whoever picks this up
Single-repo report only for v1, or also a fleet-wide version that aggregates multiple
audit_runsentries into one document (the wayorg-audit.shalready aggregates data across repos)? Single-repo is the smaller first milestone; fleet-wide is more work but is the version that matters for the eventual org-wide rollout use case.Filed by request — not yet scoped to a specific milestone.