Skip to content

feat(reports): bounded attestation PDF cover face (B3b)#644

Merged
remyluslosius merged 1 commit into
mainfrom
feat/reports-b3b-attestation-pdf
Jun 22, 2026
Merged

feat(reports): bounded attestation PDF cover face (B3b)#644
remyluslosius merged 1 commit into
mainfrom
feat/reports-b3b-attestation-pdf

Conversation

@remyluslosius

Copy link
Copy Markdown
Contributor

Summary

Phase B3b makes the pdf export face kind-dispatched: an executive report still renders the executive summary PDF; an attestation report now renders a bounded one-page cover (renderAttestationPDF). This is the third attestation face (alongside the B1 CSV extract and the B2 OSCAL SAR) and the human-facing summary that points to the bulk machine-readable bundle.

The attestation cover (O(1) pages, regardless of fleet size)

  • Methodology note — point-in-time, latest completed scan per host; full per-(host, rule) evidence lives in the CSV/OSCAL faces.
  • Aggregate attestation coverage (hosts attested of in-scope) + a framework rollup (compliance %, checks evaluated, pass/fail/skipped/error), computed by aggregate count(*) FILTER queries over the frozen scans, framework-lensed.
  • A sampled top-failing list (rules failing on the most hosts, capped at 10) from a grouped distinct-host query.
  • A footer carrying the snapshot content hash + signing status as the pointer to the bulk faces. Never the per-(host, rule) rows.
  • A host with no completed scan is disclosed as not attested.

Rendered via the pure-Go go-pdf/fpdf core fonts (airgap-safe) and cached in report_faces (face pdf) like the other faces.

Spec / tests

  • api-reports v1.9.0: new C-15 + AC-21 (rollup correctness over a 2-host pass/fail mix → total 4 / pass 1 / fail 3 / 25% + top-failing order; the %PDF face bytes + caching + framework-lens narrowing). C-10 updated (pdf is kind-dispatched, not executive-only); AC-19 wording updated (pdf valid for both kinds).
  • gofmt silent, go vet clean, go build ./... clean; specter check 111 specs structural, specter check --test 0 errors; go test ./internal/report/ green.

Phase B sequencing note

This ships B3b ahead of the rest of B3. B3a (async generation + report.ready event) and B3c (the notification-bell frontend) remain — B3c is the product-sensitive surface (what the bell shows, unread/persistence) and is held for a direction decision rather than guessed. See docs/engineering/reports_design.md §12.

Stacked on #643 (merged); rebased onto main.

Validation

  • gofmt / go vet / go build
  • go test ./internal/report/ (AC-21 + existing faces/caching)
  • specter check (structural + annotation hygiene)

Make the pdf face KIND-DISPATCHED: an executive report still renders the
executive summary PDF; an attestation report now renders a bounded
one-page cover (renderAttestationPDF).

The attestation cover is O(1) pages regardless of fleet size:
- A methodology note (point-in-time, full evidence in the CSV/OSCAL faces).
- Aggregate attestation coverage (hosts attested of in-scope) + a
  framework rollup (compliance %, checks evaluated, pass/fail/skipped/
  error), computed by aggregate count(*) FILTER queries over the frozen
  scans, framework-lensed.
- A SAMPLED top-failing list (rules failing on the most hosts, capped at
  10) from a grouped distinct-host query.
- A footer carrying the snapshot content hash + signing status as the
  pointer to the bulk faces. Never the per-(host, rule) rows.

A host with no completed scan is disclosed as not attested. Rendered via
the pure-Go go-pdf/fpdf core fonts (airgap-safe) and cached in
report_faces (face pdf) like the other faces.

Spec api-reports v1.9.0: C-15 + AC-21 (rollup correctness over a 2-host
mix + the %PDF face + caching); C-10 updated (pdf is kind-dispatched, not
executive-only); AC-19 wording updated (pdf valid for both kinds).
@github-actions github-actions Bot added documentation Improvements or additions to documentation size/XL labels Jun 22, 2026
@remyluslosius remyluslosius merged commit b6b880d into main Jun 22, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size/XL

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant