Documentation
¶
Index ¶
- Constants
- Variables
- func ExitCode(report *Report) int
- func QuietSummary(report *Report) string
- func RedirectCheck(_ *http.Request, _ []*http.Request) error
- func SanitizeDigest(value string) string
- func SanitizeIdentifier(value string) string
- func WriteJSON(w io.Writer, report *Report) error
- func WriteText(w io.Writer, report *Report, quiet bool) error
- type Action
- type Check
- type CheckFacts
- type ContextPinRecordView
- type ContextPinView
- type Coverage
- type Evidence
- type ExecutionView
- type FindingView
- type GatewayDeclView
- type HTTPDoer
- type Inputs
- type PinView
- type PinningDeclView
- type PolicyDeclView
- type ReferenceSite
- type Report
- func Assemble(generatedAt time.Time, in Inputs) *Report
- func FetchGatewayReport(ctx context.Context, base string, doer HTTPDoer) (*Report, error)
- func Load(ctx context.Context, ref SourceRef, gateway HTTPDoer) (*Report, error)
- func LoadSnapshot(ctx context.Context, path string) (*Report, error)
- func ParseSnapshot(data []byte) (*Report, error)
- type ScanDeclView
- type ServerPinView
- type ServerView
- type SkillPinRecordView
- type SkillPinView
- type SourceIdentity
- type SourceRef
- type StackView
- type StartupView
- type Subject
- type Suppression
Constants ¶
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" 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" )
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 ¶
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") )
var FailPredicates = []string{ PredPinContinuity, PredSkillPinContinuity, PredContextPinContinuity, PredExecutionEnforcement, }
FailPredicates are the only predicates that may produce exit-one failures. They reuse producer-recorded negatives or documented enforcement outcomes.
var PredicateInventory = []string{ PredPinStore, PredPinBaseline, PredPinContinuity, PredPinScheme, PredPinScanCoverage, PredPinScanFindings, PredSkillPinBaseline, PredSkillPinContinuity, PredSkillPinApproval, PredContextPinBaseline, PredContextPinContinuity, PredPinSchemaApproval, PredSourceDeclared, PredSourceBuildDigest, PredSourceImageObserved, PredSourceManifest, PredSourceSignature, PredVarCompleteness, PredVarReferences, PredGatewayAuthDeclared, PredGatewayAuthStartup, PredGatewayOriginsStartup, PredExecutionAvailability, PredExecutionEnforcement, PredPolicyDeclared, }
PredicateInventory is the finite named check catalog. Coverage "complete" refers only to this list, not to complete security knowledge.
Functions ¶
func QuietSummary ¶
func SanitizeDigest ¶
func SanitizeIdentifier ¶
Types ¶
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 ¶
GatewayDeclView is an auth/bind declaration, never token or header values.
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.
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 FetchGatewayReport ¶
func ParseSnapshot ¶
type ScanDeclView ¶
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 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 Suppression ¶
type Suppression struct {
Codes []string `json:"codes,omitempty"`
ReasonCode string `json:"reason_code"`
}
Suppression is independent metadata and never a pass substitute.