fleet-audit-reports

fleet-audit-reports — Reading What the Audits Found

Every audit run keeps what it published, on the volume, beside the agent. This skill answers questions off those files. It never runs an audit and never publishes one — the fleet-audit skill owns both ends of that lifecycle.

The store

/opt/data/fleet-audit/reports/<audit-id>/<owner>/<name>/, one directory per stream and GitOps repository. A run publishes to the role: gitops repository, or to the repository a person gave with --repo, so a stream can have more than one directory. A run with no repository to publish to uses no_forge/local:

• latest.json — the newest run's envelope.
• runs/<YYYYMMDDThhmmss.ffffffZ>.json — one envelope per run, newest 14 kept. The only run-over-run history that exists anywhere: the ledger issue rewrites itself in place.

An envelope carries audit_id, repo, finished_at, status, issue_number, issue_url, partial, coverage_gaps, declared, unaccounted, unpublished_candidates, wholly_unpublished_checks, uncorroborated_findings, prs_opened, prs_still_open, prs_closed, silent_ok, ledger_held_open, delta_known, new_ids, resolved_ids, current_ids, id_scheme, ledger_body, document, and sometimes ledger_document, silent_floor, inspect_s, publish_s and collect_s.

• document is this run's whole validated findings document — un-clipped, so it holds findings the issue body had no room to print.
• status is OPENED, UPDATED, CLEAN, HELD, or NO_FORGE. NO_FORGE means the run had no repository to publish to: it wrote no ledger issue, issue_number and issue_url are null, and the envelope is the only record of what it found. A NO_FORGE envelope in a repository's directory carries unreachable_repo (repo, reason): the run could not reach that repository. One under no_forge/local can carry no_repository_chosen (reason): several repositories are managed and none is the one role: gitops repository. For both, the new and resolved counts are unknown; say so. An envelope with neither key is from an install with no forge. ledger_held_open true means a CLEAN or HELD run left the issue open (partial, or over findings it did not account for) without rewriting it: the issue still lists the previous run's findings, current counts those, and this run's findings: 0 and critical: 0 do not mean the ledger is clear. streams, show and findings all carry it. Held open over a lost memory, the envelope's issue_number is null and current is 0: the store does not know what the issue lists, so read the issue. ledger_document is that previous document, kept for fleet-audit; do not answer from it.
• delta_known false means fleet-audit lost its memory of the previous run and withheld the delta: new_ids and resolved_ids are empty, and new/resolved 0, because nothing was claimed, not because nothing changed. Say the delta is unknown for that run. Envelopes written before the key existed lack it; read their counts as they are. streams and show carry it.
• silent_floor true means an earlier finish in the same run reported news or opened a pull request, so this run's silent_ok was kept false and its counts may be measured against that finish.
• current_ids is exactly what the body's hidden block published: the findings the body named, in full or on one line, plus the ids the collector held. Derive this run's full set from document.
• inspect_s, publish_s and collect_s are seconds: from start to finish, for finish to publish, and for the collector to run. An envelope has only the ones finish could measure. show gives them, with null for the others; streams does not carry them.
• ledger_body is the issue body the run left on GitHub — fleet-audit's memory of the previous run, not something to answer from. No subcommand returns it.