Documentation
¶
Overview ¶
Package report implements `sigcomply report`: the read-only, auditor-facing snapshot tool. It walks a vault's {framework}/{period_id}/run_*/ tree and produces deterministic views of the data — no collection, no evaluation, no cloud calls.
Three views ship in v1-alpha (see docs/architecture/09-implementation- roadmap.md §`sigcomply report`):
- latest: per-policy roll-up using the latest run that produced a result for each policy. Answers "what was the state at period close?"
- exceptions: every waiver/NA in effect during the period, pulled from each run manifest's exceptions_applied table.
- integrity: per-run signature + file-hash verification.
Each view is independently structured and independently formattable (text, json, csv). PDF is deferred to v1.x — the formatter layer returns a clear error rather than emit a half-rendered document.
Determinism is a hard requirement: the same vault state must produce byte-identical output across invocations, modulo any "generated_at" timestamp the CLI command stamps outside the snapshot's content. Snapshot views sort every list by a stable key (policy_id, run path, etc.) before serializing.
Index ¶
- Variables
- func FormatCSV(w io.Writer, snap *Snapshot) error
- func FormatJSON(w io.Writer, snap *Snapshot) error
- func FormatText(w io.Writer, snap *Snapshot) error
- type ExceptionEntry
- type ExceptionsView
- type Input
- type IntegrityRow
- type IntegrityView
- type LatestPolicy
- type LatestView
- type Snapshot
- type View
Constants ¶
This section is empty.
Variables ¶
var ErrUnknownView = fmt.Errorf("report: unknown view")
ErrUnknownView is returned by Build when an unknown view string is passed. Sentinel so callers can distinguish "configuration error" from "vault read error".
Functions ¶
func FormatCSV ¶
FormatCSV writes a CSV rendering of snap to w. One row per policy for the latest view, one row per exception for the exceptions view, one row per run for the integrity view. Designed to play well with auditor spreadsheets.
The header row is the first record. CSV escaping is the standard encoding/csv behavior (RFC 4180): fields containing commas, quotes, or newlines are quoted.
func FormatJSON ¶
FormatJSON writes a structured JSON rendering of snap to w. The output is indented 2-space for readability and is fully deterministic — Snapshot's content is already sorted by Build, and json.Encoder emits map keys in lexicographic order for any embedded maps.
No "generated_at" field is emitted from here; the CLI command stamps run-time metadata outside the snapshot body so tests can assert byte-identical content across invocations.
func FormatText ¶
FormatText writes a human-readable text rendering of snap to w. Output is deterministic: no "generated_at" timestamp is emitted from here. The CLI command can prefix a header if it wants.
Format choices:
- latest: aligned columns via tabwriter (policy_id control status severity last_evaluated exception)
- exceptions: aligned columns (policy_id scope state approved_by approved_at expires_at reason)
- integrity: aligned columns (run_path status files_verified/total details)
Types ¶
type ExceptionEntry ¶
type ExceptionEntry struct {
PolicyID string
State string
Scope string // resource_id, resource_pattern, or "policy"
ApprovedBy string
ApprovedAt string
ExpiresAt string
Reason string
FirstSeenRunID string
LastSeenRunID string
}
ExceptionEntry is one row of the exceptions register. Fields mirror core.AppliedException — duplicated here so the report's data model is self-contained and not coupled to the manifest schema.
type ExceptionsView ¶
type ExceptionsView struct {
Exceptions []ExceptionEntry
}
ExceptionsView is the centralized register of every waiver/NA in effect during the period, deduplicated across runs by policy_id + resource_id + resource_pattern. The order of runs is preserved so readers can trace which run first/last applied a given exception.
type IntegrityRow ¶
type IntegrityRow struct {
RunPath string
RunID string
CompletedAt time.Time
SignatureValid bool
FilesVerified int
FilesTotal int
FirstMismatchPath string
Error string // populated when SignatureValid is false or a file is missing
}
IntegrityRow records the outcome of integrity verification for one run folder.
func (*IntegrityRow) Status ¶
func (r *IntegrityRow) Status() string
Status returns "pass" if the run's signature verifies and every file_hashes entry matched its recomputed SHA-256; "fail" otherwise. Centralizing the boolean → label mapping lets every formatter render the same word.
type IntegrityView ¶
type IntegrityView struct {
Runs []IntegrityRow
}
IntegrityView is the per-run signature + file-hash verification table. Rows are sorted by run path (which sorts by timestamp in ISO 8601 basic form) so the output is reproducible.
type LatestPolicy ¶
type LatestPolicy struct {
PolicyID string
ControlID string
Status string
Severity string
Category string
LastEvaluated time.Time
RunID string
// ExceptionID, when non-empty, points at the policy_id of the
// exception that suppressed this result (waived/na). The free-CLI
// design uses the policy_id as the exception's primary key — the
// exceptions view is the place to look up details.
ExceptionID string
}
LatestPolicy is one row of the latest-wins view.
type LatestView ¶
type LatestView struct {
Policies []LatestPolicy
}
LatestView is the latest-wins per-policy roll-up for the period. One row per policy that appears in any run in the period folder; for policies that appear in multiple runs, the row reflects the latest run (by manifest.completed_at) that produced a result for that policy.
type Snapshot ¶
type Snapshot struct {
View View
Framework string
PeriodID string
Latest *LatestView `json:",omitempty"`
Exceptions *ExceptionsView `json:",omitempty"`
Integrity *IntegrityView `json:",omitempty"`
}
Snapshot is the top-level result of Build. Exactly one of the per-view sub-structs is populated based on the requested view; the other fields are zero-valued.
GeneratedAt is excluded from the formatted body — it lives on the header that the CLI command stamps separately so tests can assert byte-identical content across invocations.
func Build ¶
Build walks the vault for the requested {framework}/{period_id} subtree and returns a Snapshot for the chosen view.
Build is strictly read-only: it lists run folders, parses each manifest, and (for the latest view) reads per-policy result.json files. It never writes, never opens network connections, and never requires OIDC.
Source Files