security

Documentation

Overview

Package security provides vulnerability scanning and SBOM generation. Orchestrates external tools (Trivy, Grype, Syft) and produces structured results that feed into release notes and forge uploads.

Package security provides the 6-layer artifact verification model. Layers: registry identity, signature validity, identity validity, provenance validity, tag-binding replay detection, shadow-write detection.

Index

• func BuildSummary(result *ScanResult, detail string) (tile, body string)
• func ConfidenceLabel(c VerifyConfidence) string
• func ExtractRegistry(ref string) string
• func InferEcosystem(pkg, installed string) string
• func NormalizePackageName(pkg, ecosystem string) string
• func ResolveDetailLevel(cfg config.SecurityConfig, cliOverride string, policies config.PoliciesConfig) string
• func WriteAdvisories(outputDir, imageRef string, vulns []Vulnerability) error
• type Advisory
  • func ReadAdvisories(rootDir string) ([]Advisory, error)
• type AdvisoryFile
• type CandidateInfo
• type RefStability
  • func ClassifyRefStability(ref string, knownDigest string) RefStability
• type ScanConfig
• type ScanResult
  • func Scan(ctx context.Context, cfg ScanConfig) (*ScanResult, error)
• type ScanTarget
• type ScannerInfo
• type TargetSource
• type VerificationResult
  • func Verify(ctx context.Context, opts VerifyOpts) *VerificationResult
• type VerifyConfidence
• type VerifyOpts
• type Vulnerability

Functions

func BuildSummary

func BuildSummary(result *ScanResult, detail string) (tile, body string)

BuildSummary generates a markdown summary at the specified detail level. Returns (tile, body):

• tile: single-line status for hero area (e.g., "🛡️ ✅ **Passed** — no critical or high vulnerabilities")
• body: full section content (status line + optional <details> block with CVE data)

Detail levels: "none", "counts", "detailed", "full".

func ConfidenceLabel

func ConfidenceLabel(c VerifyConfidence) string

ConfidenceLabel returns a human-readable description for a confidence level.

func ExtractRegistry

func ExtractRegistry(ref string) string

extractRegistry extracts the registry hostname from an image reference.

func InferEcosystem

func InferEcosystem(pkg, installed string) string

InferEcosystem guesses the StageFreight ecosystem from package metadata. Explicitly heuristic — returns "unknown" as the safe default. Dep enrichment skips "unknown" entries entirely.

func NormalizePackageName

func NormalizePackageName(pkg, ecosystem string) string

NormalizePackageName returns a deterministic key for matching. Rules: trim whitespace, lowercase.

func ResolveDetailLevel

func ResolveDetailLevel(cfg config.SecurityConfig, cliOverride string, policies config.PoliciesConfig) string

ResolveDetailLevel evaluates the security detail rules against the current tag and branch to determine which detail level to use in release notes. CLI override (if non-empty) takes precedence over all rules. Policies is available for future condition resolution but currently rules use direct regex patterns via Condition.

func WriteAdvisories

func WriteAdvisories(outputDir, imageRef string, vulns []Vulnerability) error

WriteAdvisories writes fixable vulnerabilities as a bridge artifact. Only includes vulns with non-empty FixedIn — unfixable vulns aren't actionable.

Types

type Advisory

type Advisory struct {
	ID        string `json:"id"`
	Severity  string `json:"severity"`
	Package   string `json:"package"`
	Installed string `json:"installed"`
	FixedIn   string `json:"fixed_in"`
	Ecosystem string `json:"ecosystem"`
	Source    string `json:"source"` // provenance: "trivy", "grype", or "trivy+grype" (deduped)
}

Advisory represents a fixable vulnerability for the dependency updater.

func ReadAdvisories

func ReadAdvisories(rootDir string) ([]Advisory, error)

ReadAdvisories reads the security advisory bridge file from the standard location (.stagefreight/security/advisories.json relative to rootDir). Returns empty slice + nil error if file doesn't exist (no advisories = normal).

type AdvisoryFile

type AdvisoryFile struct {
	SchemaVersion int        `json:"schema_version"`
	Generator     string     `json:"generator"`
	Image         string     `json:"image"`
	Advisories    []Advisory `json:"advisories"`
}

AdvisoryFile is the bridge artifact written by security scan for the dependency updater.

type CandidateInfo

type CandidateInfo struct {
	Ref               string       `json:"ref"`
	Digest            string       `json:"digest,omitempty"`
	ObservedDigest    string       `json:"observed_digest,omitempty"`
	ObservedDigestAlt string       `json:"observed_digest_alt,omitempty"`
	Stability         RefStability `json:"stability"`
}

CandidateInfo describes a potential scan target candidate.

type RefStability

type RefStability string

RefStability classifies how stable/immutable a reference is.

const (
	StabilityDigest        RefStability = "digest"          // @sha256: — content-addressed, immutable
	StabilityTagWithDigest RefStability = "tag_with_digest" // tag + known digest — resolved instance
	StabilityTag           RefStability = "tag"             // bare tag — always mutable, even semver
)

func ClassifyRefStability

func ClassifyRefStability(ref string, knownDigest string) RefStability

ClassifyRefStability determines the stability classification of an image reference.

type ScanConfig

type ScanConfig struct {
	Enabled        bool      // run vulnerability scan
	TrivyEnabled   bool      // run Trivy scanner
	GrypeEnabled   bool      // run Grype scanner
	SBOMEnabled    bool      // generate SBOM
	FailOnCritical bool      // fail if critical vulns found
	ImageRef       string    // image reference or tarball path to scan
	OutputDir      string    // directory for scan artifacts
	SectionWriter  io.Writer // writer for CI section markers (nil = os.Stderr)
}

ScanConfig holds security scan configuration.

type ScanResult

type ScanResult struct {
	Critical        int             // count of critical vulnerabilities
	High            int             // count of high vulnerabilities
	Medium          int             // count of medium vulnerabilities
	Low             int             // count of low vulnerabilities
	Vulnerabilities []Vulnerability // parsed vulnerability details (for detailed/full output)
	Status          string          // "passed", "warning", "critical"
	Artifacts       []string        // paths to generated files (JSON, SARIF, SBOM)
	Summary         string          // markdown summary for embedding in release notes
	EngineVersion   string          // best-effort: from `trivy --version` or empty
	OS              string          // "alpine 3.21.3" (from Trivy JSON Metadata.OS)
	Target          ScanTarget      // resolved scan target with provenance
	ScannersRun     []ScannerInfo   // scanners that completed successfully
	ScannersFailed  []ScannerInfo   // scanners that failed or were unavailable
	Partial         bool            // true if any enabled scanner failed
}

ScanResult holds the outcome of a security scan.

func Scan

func Scan(ctx context.Context, cfg ScanConfig) (*ScanResult, error)

Scan runs vulnerability scans (Trivy + Grype when available), deduplicates results, and optionally generates SBOMs.

type ScanTarget

type ScanTarget struct {
	Ref               string          `json:"ref"`
	DiscoveredTag     string          `json:"discovered_tag,omitempty"` // original tag before digest resolution
	Digest            string          `json:"digest,omitempty"`
	ObservedDigest    string          `json:"observed_digest,omitempty"`
	ObservedDigestAlt string          `json:"observed_digest_alt,omitempty"`
	DigestMatch       *bool           `json:"digest_match,omitempty"`
	Source            TargetSource    `json:"source"`
	SelectionReason   string          `json:"selection_reason"`
	Stability         RefStability    `json:"stability"`
	Candidates        []CandidateInfo `json:"candidates,omitempty"`
	ExpectedTags      []string        `json:"expected_tags,omitempty"`
	ExpectedCommit    string          `json:"expected_commit,omitempty"`
	SigningAttempted  bool            `json:"signing_attempted,omitempty"`
}

ScanTarget describes the resolved scan target with full provenance.

type ScannerInfo

type ScannerInfo struct {
	Name    string `json:"name"`
	Version string `json:"version,omitempty"`
}

ScannerInfo describes a scanner that was run or attempted.

type TargetSource

type TargetSource string

TargetSource describes how the scan target was selected.

const (
	TargetExplicit        TargetSource = "explicit"
	TargetPositionalArg   TargetSource = "positional_arg"
	TargetPublishManifest TargetSource = "publish_manifest"
)

type VerificationResult

type VerificationResult struct {
	// Layer 1 — Registry identity
	ResolvedDigest string `json:"resolved_digest"`
	ExpectedDigest string `json:"expected_digest,omitempty"`
	DigestMatch    *bool  `json:"digest_match,omitempty"`

	// Layer 2 — Signature validity
	SignatureValid   *bool `json:"signature_valid,omitempty"`
	SigningAttempted bool  `json:"signing_attempted,omitempty"`

	// Layer 3 — Identity validity
	IdentityMatched *bool `json:"identity_matched,omitempty"`

	// Layer 4 — Provenance validity
	AttestationValid  *bool `json:"attestation_valid,omitempty"`
	ProvenanceMatched *bool `json:"provenance_matched,omitempty"`

	// Layer 5 — Tag-binding replay detection
	TagBindingMatch *bool    `json:"tag_binding_match,omitempty"`
	ExpectedTags    []string `json:"expected_tags,omitempty"`
	ActualTag       string   `json:"actual_tag,omitempty"`

	// Layer 6 — Shadow write / split-view detection
	ObservedConsistent *bool `json:"observed_consistent,omitempty"`

	// Computed
	Confidence VerifyConfidence `json:"confidence"`
	Failures   []string         `json:"failures,omitempty"`
}

VerificationResult captures the outcome of multi-layer artifact verification.

func Verify

func Verify(ctx context.Context, opts VerifyOpts) *VerificationResult

Verify performs 6-layer artifact verification against a digest reference. All verification operations use digest references (repo@sha256:...), never tags.

type VerifyConfidence

type VerifyConfidence string

VerifyConfidence represents the computed trust level of artifact verification.

const (
	ConfidenceHigh     VerifyConfidence = "high"     // digest matched + signed + attested
	ConfidenceDegraded VerifyConfidence = "degraded" // digest matched, unsigned or partial attestation
	ConfidenceNone     VerifyConfidence = "none"     // mismatch, missing, or failed verification
)

type VerifyOpts

type VerifyOpts struct {
	ExpectedDigest    string
	ActualRef         string
	ActualTag         string
	ObservedDigest    string // primary observation (buildx)
	ObservedDigestAlt string // alternate observation (registry API)
	ExpectedTags      []string
	ExpectedCommit    string
	SigningAttempted  bool
	Attestation       *build.AttestationRecord
	CosignKeyPath     string
	CredResolver      func(string) (string, string)
	CredRef           string
}

VerifyOpts contains the inputs for artifact verification.

type Vulnerability

type Vulnerability struct {
	ID          string // CVE ID (e.g., "CVE-2026-1234")
	Severity    string // CRITICAL, HIGH, MEDIUM, LOW
	Package     string // affected package name
	Installed   string // installed version
	FixedIn     string // version that fixes the vuln
	Description string // one-line description
	Source      string // scanner provenance: "trivy" or "grype"
}

Vulnerability is a single parsed vulnerability from the scan.