evidence

Documentation

Overview

Package evidence assembles an audit-ready folder from a set of scan findings. The output layout follows ARCHITECTURE.md section 10:

<out>/
  MANIFEST.sha256             // every file under <out> hashed
  control-mapping.csv         // (check, control, status, evidence path)
  summary.html                // auditor-readable index
  <framework>/<control-id>-<slug>/
    findings.json             // raw findings for this control
    control.md                // per-control human summary

The pack is designed to survive auditor handoff: filenames carry the period prefix, MANIFEST.sha256 detects tampering, and control-mapping.csv is the row-per-evidence-artifact format that Drata, Vanta, and AuditBoard ingest. Per ADR-006 the pack is the differentiator versus Prowler / ScoutSuite / Steampipe -- those tools emit JSON; we emit a folder an auditor can sign off on.

Layout is fixed (no plugins) at v0.4. v0.6+ may add tarballing, gpg signing, and S3 upload as separate post-generators.

Index

• func WriteManifest(dir string) (string, error)
• type ControlRef
• type FrameworkResult
• type Options
• type Result
  • func Generate(_ context.Context, findings []core.Finding, opts Options) (Result, error)

Functions

func WriteManifest

func WriteManifest(dir string) (string, error)

WriteManifest walks dir, hashes every regular file inside it (excluding the manifest itself), and writes the result to <dir>/MANIFEST.sha256 in the canonical sha256sum format:

<hex-digest>  <relative/path>

The relative path uses forward slashes and is rooted at dir so the manifest is portable across filesystems. Lines are sorted by path so a re-run over identical content produces a byte-stable manifest -- useful both for diffing packs across periods and for letting an auditor verify integrity with:

cd <pack-root> && sha256sum -c MANIFEST.sha256

Returns the absolute path of the manifest file written.

Types

type ControlRef

type ControlRef struct {
	FrameworkID   string
	FrameworkName string
	ControlID     string
	ControlName   string
	DirName       string // "<id>-<slug>" -- this control's directory under <framework>/
	Findings      []core.Finding
}

ControlRef pairs a control with the findings attributed to it. The per-control Markdown writer (Phase 3) consumes this; Phase 2 emits findings.json from the same data.

type FrameworkResult

type FrameworkResult struct {
	FrameworkID      string
	FrameworkName    string
	ControlsCovered  int
	ControlsWithFail int
}

FrameworkResult is the per-framework rollup shown in the CLI footer.

type Options

type Options struct {
	// OutDir is the directory the pack is written into. Must not
	// exist or must be empty; Generate refuses to overwrite an
	// existing pack so a stale run cannot be silently merged with a
	// fresh one. Required.
	OutDir string

	// Period is the audit period label embedded in pack metadata and
	// the per-control Markdown. Optional; defaults to the current
	// year-quarter (e.g. "2026-Q2").
	Period string

	// IncludeRaw, when true, copies the raw collector payloads
	// pointed to by Finding.Evidence into the pack without
	// redaction. Default false: redacted summaries only. v0.4 ships
	// the toggle; the collector-side raw capture lands in v0.5.
	IncludeRaw bool

	// Generated overrides the timestamp embedded in the pack header.
	// Tests use this to produce byte-stable output; production
	// callers leave it zero (Generate substitutes time.Now().UTC()).
	Generated time.Time

	// Tailoring is the operator-declared list of (framework, control)
	// pairs scoped out of audit, each with a required justification.
	// When non-nil and non-empty, the evidence pack writes a
	// tailoring.json at the root and the control-mapping.csv gains
	// `tailored` + `tailoring_justification` columns. v0.12+.
	Tailoring *frameworks.Tailoring
}

Options controls evidence pack generation. Period is a free-form label used in the pack header and the top-level directory name when the caller passes "" for OutDir; "2026-Q2", "2026-05", and "pre-audit-soak" are all valid.

type Result

type Result struct {
	OutDir              string                  // absolute path to the pack root
	FilesWritten        int                     // total files written, including MANIFEST
	FrameworkResults    []FrameworkResult       // one per framework with at least one mapped finding
	ManifestPath        string                  // <OutDir>/MANIFEST.sha256
	MappingCSVPath      string                  // <OutDir>/control-mapping.csv
	SummaryHTMLPath     string                  // <OutDir>/summary.html (empty until phase 4 lands)
	TailoringPath       string                  // <OutDir>/tailoring.json (v0.12+); empty when no rules
	TailoringCount      int                     // number of tailoring rules recorded
	OSCALARPath         string                  // <OutDir>/assessment-results.oscal.json (v0.13+)
	OSCALProfilePath    string                  // <OutDir>/profile.oscal.json (v0.13+)
	VulnerabilitiesPath string                  // <OutDir>/vulnerabilities.csv (v0.14+); empty when no CVE findings
	WaiversPath         string                  // <OutDir>/waivers.json (v0.18+); empty when no waiver-muted findings
	Generated           time.Time               // header timestamp actually used
	ControlIndex        map[string][]ControlRef // framework -> controls covered (display order)
}

Result summarizes what Generate wrote so the CLI can render a human-readable footer without re-walking the pack.

func Generate

func Generate(_ context.Context, findings []core.Finding, opts Options) (Result, error)

Generate writes a complete evidence pack to opts.OutDir. The pack includes a per-control findings.json today; per-control Markdown, control-mapping.csv, and summary.html are added by subsequent phases of v0.4.

The output directory must not exist or must be empty; Generate refuses to merge into a pre-existing pack so a stale run cannot taint a fresh one (per ARCHITECTURE.md section 10 -- every artifact is dated and the manifest must cover exactly the files of this run).