feat(reports): fleet OSCAL SAR face for attestation reports (B2) (#643)

Add a fleet OSCAL 1.0.6 assessment-results face (format=oscal_sar,
attestation-only) to the Reports export surface.

Kensa's per-scan exporter (ExportOSCALScan) inlines each scan's evidence
as base64 and is per-scan, so it cannot produce the hash-referencing
single-document fleet SAR the design requires. internal/report/oscal.go
is a light, custom assembler with its own minimal OSCAL structs mirroring
the per-scan shape:

- One assessment-results document, one result, one observation + finding
  per (host, rule) reconstructed from the attestation snapshot's frozen,
  immutable scan_results.
- Finding target state "satisfied" only on a pass (else
  "not-satisfied"); host as a deterministic-v5 inventory-item subject.
- Reviewed-controls aggregated as framework-prefixed control-id tokens
  (digit-leading native ids like CIS "1.1" stay valid OSCAL tokens),
  narrowed by the snapshot's framework lens.
- Evidence REFERENCED by sha256 in back-matter (an rlink SHA-256 hash),
  never inlined as base64; the bytes stay in scan_evidence. This is what
  keeps a 100-host x 500-rule attestation from becoming the 1000-page
  problem in OSCAL form.
- Every uuid is a deterministic v5 from the snapshot id, so the document
  is byte-deterministic and cached in report_faces (face oscal_sar) like
  the PDF/CSV faces; assembly is bounded by the same row cap as the CSV,
  with a metadata prop disclosing truncation.

OSCAL version stays 1.0.6 to match the Kensa-controlled per-scan emitter.

Spec api-reports v1.8.0: C-14 + AC-20 (DB test over the assembled
document: shape, states, control tokens, hash-referenced evidence,
determinism, framework-lens scoping, executive ErrInvalidFace).

Author: remyluslosius

api/openapi.yaml

@@ -2606,16 +2606,21 @@ paths:
   /api/v1/reports/{id}/export:
     get:
       operationId: getReportExport
-      summary: Download a rendered face of a report (PDF or JSON)
+      summary: Download a rendered face of a report (PDF, JSON, CSV, or OSCAL SAR)
       description: |
         Streams a rendered face of the report as a downloadable
-        attachment. format=pdf (default) renders the bounded one-page
-        executive PDF (a fixed posture block, the coverage caveat, and the
-        top-failing list - never the full per-host/per-rule evidence);
-        format=json returns the canonical frozen posture content. The PDF
-        is rendered on first request and cached in report_faces, so a
-        repeat download re-streams the stored bytes. RBAC: host:read. Spec
-        api-reports.
+        attachment. format=pdf (default, executive only) renders the
+        bounded one-page executive PDF (a fixed posture block, the coverage
+        caveat, and the top-failing list - never the full per-host/per-rule
+        evidence); format=json returns the canonical frozen posture
+        content (any kind). For an attestation report, format=csv returns
+        the per-(host, rule) evidence extract and format=oscal_sar returns a
+        single OSCAL 1.0.6 assessment-results document (one observation +
+        finding per (host, rule), evidence referenced by sha256 in
+        back-matter, not inlined). A face that does not apply to the
+        report's kind is a 400. Each face is rendered on first request and
+        cached in report_faces, so a repeat download re-streams the stored
+        bytes. RBAC: host:read. Spec api-reports.
       parameters:
         - name: id
           in: path
@@ -2625,7 +2630,7 @@ paths:
           in: query
           required: false
           description: The face to render. Defaults to pdf.
-          schema: {type: string, enum: [pdf, json, csv], default: pdf}
+          schema: {type: string, enum: [pdf, json, csv, oscal_sar], default: pdf}
       responses:
         '200':
           description: The rendered face, as a downloadable attachment

docs/engineering/reports_design.md

@@ -519,11 +519,26 @@ severity, framework_refs, evidence_sha256, scan_at, exception_id. The
 snapshot content is blob-stored (compressed). Spec: `api-reports`
 (kind=attestation), new `system-report-attestation`.
 
-**B2 — Fleet OSCAL SAR face.** Assemble a single OSCAL 1.0.6
-`assessment-results` from the attestation snapshot: reviewed-controls from
-the framework mapping, one observation + finding per `(host, rule)`,
-evidence referenced by `sha256` (back-matter), streamed to the `oscal_sar`
-face in `report_faces`. Spec: extend the attestation spec.
+**B2 — Fleet OSCAL SAR face.** *(SHIPPED 2026-06-21, PR #643.)* Assemble a
+single OSCAL 1.0.6 `assessment-results` from the attestation snapshot
+(`internal/report/oscal.go`): one result whose findings + observations
+carry one entry per `(host, rule)`, reviewed-controls aggregated as
+framework-prefixed control-id tokens (digit-leading native ids stay valid
+OSCAL tokens), the finding state "satisfied" only on a pass, the host as a
+deterministic-v5 inventory-item subject, narrowed by the snapshot's
+framework lens. Evidence is REFERENCED by `sha256` in back-matter (an rlink
+SHA-256 hash), never inlined as base64 — the bytes stay in `scan_evidence`.
+Since Kensa's `ExportOSCALScan` is per-scan and *inlines* evidence, the
+fleet assembler is a light hash-referencing custom builder (not Kensa's
+exporter), with its own minimal OSCAL structs mirroring the per-scan shape.
+Every uuid is a deterministic v5 from the snapshot id, so the document is
+byte-deterministic and cached in `report_faces` (face `oscal_sar`, status
+`ready`) like the other faces; the assembly is bounded by the same row cap
+as the CSV (a metadata prop discloses truncation). `format=oscal_sar` is
+attestation-only (executive is `ErrInvalidFace`). Spec: `api-reports`
+v1.8.0 (C-14 / AC-20). True streaming to a separate blob store is deferred
+(the in-memory + row-cap + `report_faces.content` pattern matches the CSV
+face).
 
 **B3 — Async generation + report.ready.** Fleet attestation generation
 (the bulk query + SAR/CSV render) moves to the job queue: a

internal/report/export.go

@@ -61,6 +61,11 @@ func (s *Service) Export(ctx context.Context, id uuid.UUID, face string) ([]byte
 			return nil, "", ErrInvalidFace
 		}
 		return s.exportAttestationCSV(ctx, rep)
+	case FaceOSCALSAR:
+		if rep.Kind != KindAttestation {
+			return nil, "", ErrInvalidFace
+		}
+		return s.exportFleetOSCALSAR(ctx, rep)
 	default:
 		return nil, "", ErrInvalidFace
 	}
@@ -150,7 +155,13 @@ func ExportFilename(rep Report, face string) string {
 	if kind == "" {
 		kind = "report"
 	}
-	return fmt.Sprintf("openwatch-%s-%s-%s.%s", kind, slugify(rep.ScopeLabel), rep.DataAsOf.Format("2006-01-02"), face)
+	// The OSCAL SAR is a JSON document; give it a readable .oscal.json
+	// extension rather than the raw face token.
+	ext := face
+	if face == FaceOSCALSAR {
+		ext = "oscal.json"
+	}
+	return fmt.Sprintf("openwatch-%s-%s-%s.%s", kind, slugify(rep.ScopeLabel), rep.DataAsOf.Format("2006-01-02"), ext)
 }
 
 // slugify lowercases and replaces non-alphanumeric runs with single