secreport

package
v1.0.0-rc.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Index

Constants

View Source
const (
	SchemaVersion = "gridctl.security-report.v1"

	OutcomePass          = "pass"
	OutcomeFail          = "fail"
	OutcomeWarn          = "warn"
	OutcomeUnknown       = "unknown"
	OutcomeNotApplicable = "not-applicable"

	BasisDeclared = "declared"
	BasisObserved = "observed"
	BasisVerified = "verified"

	AvailabilityAvailable   = "available"
	AvailabilityUnavailable = "unavailable"
	AvailabilityPartial     = "partial"

	FreshnessCurrent = "current"
	FreshnessStale   = "stale"
	FreshnessUnknown = "unknown"

	SourceFile     = "file"
	SourceSnapshot = "snapshot"
	SourceGateway  = "gateway"

	SubjectGateway = "gateway"
	SubjectServer  = "server"
	SubjectSkill   = "skill"
	SubjectReplica = "replica"
	SubjectContext = "context"

	ActionViewPins        = "view_pins"
	ActionViewSkillPins   = "view_skill_pins"
	ActionViewContextPins = "view_context_pins"

	CoverageComplete = "complete"
	CoveragePartial  = "partial"
	CoverageNone     = "none"
)
View Source
const (
	PredPinStore              = "pin.schema.store"
	PredPinBaseline           = "pin.schema.baseline"
	PredPinContinuity         = "pin.schema.continuity"
	PredPinScheme             = "pin.schema.scheme"
	PredPinScanCoverage       = "pin.scan.coverage"
	PredPinScanFindings       = "pin.scan.findings"
	PredSkillPinBaseline      = "skill.pin.baseline"
	PredSkillPinContinuity    = "skill.pin.continuity"
	PredSkillPinApproval      = "skill.pin.approval"
	PredContextPinBaseline    = "context.pin.baseline"
	PredContextPinContinuity  = "context.pin.continuity"
	PredPinSchemaApproval     = "pin.schema.approval"
	PredSourceDeclared        = "source.declared"
	PredSourceBuildDigest     = "source.build_digest"
	PredSourceImageObserved   = "source.image_observed"
	PredSourceManifest        = "source.manifest"
	PredSourceSignature       = "source.signature"
	PredVarCompleteness       = "var.completeness"
	PredVarReferences         = "var.references"
	PredGatewayAuthDeclared   = "gateway.auth.declared"
	PredGatewayAuthStartup    = "gateway.auth.startup"
	PredGatewayOriginsStartup = "gateway.origins.startup"
	PredExecutionAvailability = "execution.availability"
	PredExecutionEnforcement  = "execution.enforcement"
	PredPolicyDeclared        = "policy.declared"
)

Variables

View Source
var (
	ErrSourceRequired     = errors.New("security source required")
	ErrSourceInvalid      = errors.New("invalid security source")
	ErrSourceUnsupported  = errors.New("unsupported security source")
	ErrSourceUnreadable   = errors.New("security source unreadable")
	ErrSourceInvalidFmt   = errors.New("unsupported or invalid security snapshot")
	ErrRedirectsForbidden = errors.New("redirects are not followed")
	ErrCredentialURL      = errors.New("credential-bearing URLs are rejected")
	ErrGatewayRequest     = errors.New("gateway report request failed")
)

FailPredicates are the only predicates that may produce exit-one failures. They reuse producer-recorded negatives or documented enforcement outcomes.

PredicateInventory is the finite named check catalog. Coverage "complete" refers only to this list, not to complete security knowledge.

Functions

func ExitCode

func ExitCode(report *Report) int

func QuietSummary

func QuietSummary(report *Report) string

func RedirectCheck

func RedirectCheck(_ *http.Request, _ []*http.Request) error

func SanitizeDigest

func SanitizeDigest(value string) string

func SanitizeIdentifier

func SanitizeIdentifier(value string) string

func WriteJSON

func WriteJSON(w io.Writer, report *Report) error

func WriteText

func WriteText(w io.Writer, report *Report, quiet bool) error

Types

type Action

type Action struct {
	ID    string `json:"id"`
	Label string `json:"label"`
	Path  string `json:"path"`
}

Action is an allowlisted link to an existing review surface.

type Check

type Check struct {
	ID          string       `json:"id"`
	Predicate   string       `json:"predicate"`
	Subject     Subject      `json:"subject"`
	Outcome     string       `json:"outcome"`
	ReasonCode  string       `json:"reason_code"`
	Explanation string       `json:"explanation"`
	Evidence    Evidence     `json:"evidence"`
	Facts       CheckFacts   `json:"facts,omitempty"`
	Suppression *Suppression `json:"suppression,omitempty"`
	Actions     []Action     `json:"actions,omitempty"`
	Limitations []string     `json:"limitations,omitempty"`
}

Check is one scoped predicate outcome with independent evidence facets.

type CheckFacts

type CheckFacts struct {
	DeclaredSource     string   `json:"declared_source,omitempty"`
	ReferenceSites     *int     `json:"reference_sites,omitempty"`
	WorkloadConsumers  *int     `json:"workload_consumers,omitempty"`
	UnscopedConsumers  *int     `json:"unscoped_consumers,omitempty"`
	FindingCodes       []string `json:"finding_codes,omitempty"`
	FindingSeverities  []string `json:"finding_severities,omitempty"`
	FindingConfidences []string `json:"finding_confidences,omitempty"`
	AuthType           string   `json:"auth_type,omitempty"`
	Bind               string   `json:"bind,omitempty"`
	EffectiveBind      string   `json:"effective_bind,omitempty"`
	OriginsMode        string   `json:"origins_mode,omitempty"`
	AllowedOriginCount *int     `json:"allowed_origin_count,omitempty"`
	DiscoveryRoutes    []string `json:"discovery_routes,omitempty"`
	Kind               string   `json:"kind,omitempty"`
	DefaultAction      string   `json:"default_action,omitempty"`
	RuleCount          *int     `json:"rule_count,omitempty"`
	BlockDestructive   *bool    `json:"block_destructive,omitempty"`
	RecordedOutcome    string   `json:"recorded_outcome,omitempty"`
	Instance           string   `json:"instance,omitempty"`
	Revision           string   `json:"revision,omitempty"`
}

CheckFacts are typed, allowlisted values used to rebuild explanations.

type ContextPinRecordView

type ContextPinRecordView struct {
	Status         string
	Source         string
	Pack           string
	PinnedAt       time.Time
	LastVerifiedAt time.Time
	FindingCodes   []string
}

ContextPinRecordView is one fragment pin without document content.

type ContextPinView

type ContextPinView struct {
	Available bool
	Fragments map[string]ContextPinRecordView
}

ContextPinView is stored context-pin evidence scoped to context subjects. It carries no document body, finding message, or path.

func ContextPinViewFromStore

func ContextPinViewFromStore(ctx context.Context, store *ctxpins.Store) *ContextPinView

ContextPinViewFromStore projects a context pin store into value-free report inputs. A nil store or a load error (corrupt or newer file) yields nil so the assembler reports availability unknown rather than an empty pass.

type Coverage

type Coverage struct {
	Status              string   `json:"status"`
	PredicatesTotal     int      `json:"predicates_total"`
	PredicatesEvaluated int      `json:"predicates_evaluated"`
	PredicatesUnknown   int      `json:"predicates_unknown"`
	IncludedScopes      []string `json:"included_scopes"`
	ExcludedScopes      []string `json:"excluded_scopes"`
	UnknownGaps         int      `json:"unknown_gaps"`
}

Coverage describes finite predicate inventory results, not assurance.

type Evidence

type Evidence struct {
	Basis              string     `json:"basis"`
	Availability       string     `json:"availability"`
	Freshness          string     `json:"freshness"`
	FreshnessCondition string     `json:"freshness_condition,omitempty"`
	ObservedAt         *time.Time `json:"observed_at,omitempty"`
	VerifiedAt         *time.Time `json:"verified_at,omitempty"`
	ScannedAt          *time.Time `json:"scanned_at,omitempty"`
	Producer           string     `json:"producer,omitempty"`
	ProducerVersion    string     `json:"producer_version,omitempty"`
	Ruleset            string     `json:"ruleset,omitempty"`
	Digest             string     `json:"digest,omitempty"`
	VerificationMethod string     `json:"verification_method,omitempty"`
	SubjectBinding     string     `json:"subject_binding,omitempty"`
	PredicateScope     string     `json:"predicate_scope,omitempty"`
}

Evidence separates basis, availability, and freshness.

type ExecutionView

type ExecutionView struct {
	Server     string
	Replica    string
	Kind       string
	Mode       string
	Outcome    string
	Eligible   bool
	ObservedAt time.Time
	Runtime    string
	Instance   string
	Revision   string
}

ExecutionView is per-replica execution evidence already collected.

type FindingView

type FindingView struct {
	Code       string
	Severity   string
	Confidence string
	Field      string
	Suppressed bool
}

FindingView is stored advisory metadata without snippets or decoded text.

type GatewayDeclView

type GatewayDeclView struct {
	AuthDeclared bool
	AuthType     string
	Bind         string
	Insecure     bool
}

GatewayDeclView is an auth/bind declaration, never token or header values.

type HTTPDoer

type HTTPDoer interface {
	Do(*http.Request) (*http.Response, error)
}

type Inputs

type Inputs struct {
	Source      SourceIdentity
	Stack       *StackView
	Pins        *PinView
	SkillPins   *SkillPinView
	ContextPins *ContextPinView
	Startup     *StartupView
	Execution   []ExecutionView
}

Inputs is the typed safe snapshot the assembler consumes. Nil optional producers yield unknown checks rather than fabricated evidence.

func InputsFromStackFile

func InputsFromStackFile(ctx context.Context, path string) (Inputs, error)

type PinView

type PinView struct {
	Available bool
	Enabled   bool
	Scan      *ScanDeclView
	Servers   map[string]ServerPinView
}

PinView is a stored pin snapshot. Presence is independent of Verify.

func PinViewFromStore

func PinViewFromStore(ps *pins.PinStore, enabled bool, scan *ScanDeclView) *PinView

type PinningDeclView

type PinningDeclView struct {
	Enabled bool
}

PinningDeclView is schema-pinning enablement as declared.

type PolicyDeclView

type PolicyDeclView struct {
	Declared          bool
	Default           string
	RuleCount         int
	BlockDestructive  bool
	ApprovalRuleCount int
}

PolicyDeclView is the authored per-tool policy block, never match patterns that could be confused with arguments. Declared is false when the key was omitted. An empty block is declared.

type ReferenceSite

type ReferenceSite struct {
	Kind       string
	Name       string
	Target     string
	TargetKind string
	Untargeted bool
}

ReferenceSite counts a variable reference without values or field paths that may contain operands.

type Report

type Report struct {
	SchemaVersion      string         `json:"schema_version"`
	GeneratedAt        time.Time      `json:"generated_at"`
	Source             SourceIdentity `json:"source"`
	Coverage           Coverage       `json:"coverage"`
	Checks             []Check        `json:"checks"`
	Limitations        []string       `json:"limitations"`
	GenerationOK       bool           `json:"-"`
	FailCount          int            `json:"fail_count"`
	WarnCount          int            `json:"warn_count"`
	UnknownCount       int            `json:"unknown_count"`
	NotApplicableCount int            `json:"not_applicable_count"`
	PassCount          int            `json:"pass_count"`
}

Report is the versioned value-free security evidence DTO.

func Assemble

func Assemble(generatedAt time.Time, in Inputs) *Report

func FetchGatewayReport

func FetchGatewayReport(ctx context.Context, base string, doer HTTPDoer) (*Report, error)

func Load

func Load(ctx context.Context, ref SourceRef, gateway HTTPDoer) (*Report, error)

func LoadSnapshot

func LoadSnapshot(ctx context.Context, path string) (*Report, error)

func ParseSnapshot

func ParseSnapshot(data []byte) (*Report, error)

type ScanDeclView

type ScanDeclView struct {
	Enabled bool
	Ignore  []string
}

ScanDeclView is advisory scanner configuration.

type ServerPinView

type ServerPinView struct {
	Status             string
	ToolCount          int
	PinnedAt           time.Time
	LastVerifiedAt     time.Time
	LegacySchemeCount  int
	CurrentSchemeCount int
	Findings           []FindingView
	// Approval fields are presence and the bound hash only. Reason text,
	// references, and the approver name stay out of the report.
	ApprovalRecorded bool
	ApprovedAt       time.Time
	ApprovedHash     string
}

ServerPinView is one server's stored pin record.

type ServerView

type ServerView struct {
	Name              string
	Kind              string
	Image             string
	SourceType        string
	SourcePackage     string
	SourceVersion     string
	SourceRef         string
	SourceHostPath    string
	BuildDigest       string
	ObservedImage     string
	ObservedImageID   string
	ManifestDigest    string
	SignatureBound    bool
	ExecutionMode     string
	ExecutionDeclared bool
}

ServerView is authored server identity without commands or credentials.

type SkillPinRecordView

type SkillPinRecordView struct {
	Status           string
	Source           string
	PinnedAt         time.Time
	LastVerifiedAt   time.Time
	FindingCodes     []string
	ApprovalRecorded bool
	ApprovedAt       time.Time
	ApprovedHash     string
}

SkillPinRecordView is one skill pin without document bodies.

type SkillPinView

type SkillPinView struct {
	Available bool
	Skills    map[string]SkillPinRecordView
}

SkillPinView is stored skill-pin evidence scoped to skill subjects.

func SkillPinViewFromStore

func SkillPinViewFromStore(ps *skillpins.Store) *SkillPinView

type SourceIdentity

type SourceIdentity struct {
	Kind       string `json:"kind"`
	Display    string `json:"display"`
	Historical bool   `json:"historical"`
	StackName  string `json:"stack_name,omitempty"`
}

SourceIdentity names the explicit selected source without credentials.

type SourceRef

type SourceRef struct {
	Kind  string
	Value string
}

SourceRef is an explicit no-fallback source selection.

func ParseSource

func ParseSource(raw string) (SourceRef, error)

type StackView

type StackView struct {
	Name             string
	Servers          []ServerView
	References       map[string][]ReferenceSite
	SetMembers       map[string][]string
	UnscopedSetCount int
	Gateway          *GatewayDeclView
	Scan             *ScanDeclView
	Pinning          *PinningDeclView
	Policy           *PolicyDeclView
}

StackView is a value-free authored configuration projection.

type StartupView

type StartupView struct {
	AuthEnabled        bool
	AuthType           string
	Bind               string
	Insecure           bool
	OriginsMode        string
	AllowedOriginCount int
	DiscoveryRoutes    []string
}

StartupView is a value-free active startup security snapshot.

type Subject

type Subject struct {
	Kind string `json:"kind"`
	Name string `json:"name"`
}

Subject is a bounded identity for the check.

type Suppression

type Suppression struct {
	Codes      []string `json:"codes,omitempty"`
	ReasonCode string   `json:"reason_code"`
}

Suppression is independent metadata and never a pass substitute.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL