Documentation
¶
Index ¶
- Constants
- func ExtractStatement(envelope *dsse.Envelope) (*intoto.Statement, error)
- func PolicyEvaluationsFromBundle(data []byte) (map[string][]*PolicyEvaluation, error)
- type Auth
- type CASBackend
- type Maintainer
- type Metadata
- type NormalizablePredicate
- type NormalizedMaterial
- type PolicyEvaluation
- type PolicyEvaluationStatus
- type PolicyEvaluationsRef
- type PolicyStatus
- type PolicyStatusSummary
- type PolicyViolation
- type PolicyViolationBlockingStrategy
- type ProvenancePredicateCommon
- type ProvenancePredicateV02
- func (p *ProvenancePredicateV02) GetMaterials() []*NormalizedMaterial
- func (p *ProvenancePredicateV02) GetPolicyEvaluationStatus() *PolicyEvaluationStatus
- func (p *ProvenancePredicateV02) GetPolicyEvaluations() map[string][]*PolicyEvaluation
- func (p *ProvenancePredicateV02) GetPolicyEvaluationsRef() *PolicyEvaluationsRef
- type ReferencedSourceComponent
- type RendererCommon
- type RendererV02
Constants ¶
const AttPolicyEvaluation = "CHAINLOOP.ATTESTATION"
const PolicyEvaluationsBundleMediaType = "application/vnd.chainloop.policy-evaluations.v1+json"
const PredicateTypeV02 = "chainloop.dev/attestation/v0.2"
Replace custom material type with https://github.com/in-toto/attestation/blob/main/spec/v1.0/resource_descriptor.md
const (
// Subject names
SubjectGitHead = "git.head"
)
Variables ¶
This section is empty.
Functions ¶
func PolicyEvaluationsFromBundle ¶ added in v1.89.0
func PolicyEvaluationsFromBundle(data []byte) (map[string][]*PolicyEvaluation, error)
PolicyEvaluationsFromBundle deserializes a PolicyEvaluationBundle and returns evaluations grouped by material name, preserving suppressed entries and structured finding data for the CP describe API.
Types ¶
type CASBackend ¶ added in v1.67.0
type Maintainer ¶
type Metadata ¶
type Metadata struct {
Name string `json:"name"`
Project string `json:"project"`
ProjectVersion string `json:"projectVersion"`
ProjectVersionPrerelease bool `json:"projectVersionPrerelease"`
Team string `json:"team"`
InitializedAt *time.Time `json:"initializedAt"`
FinishedAt *time.Time `json:"finishedAt"`
WorkflowRunID string `json:"workflowRunID"`
WorkflowID string `json:"workflowID"`
WorkflowName string `json:"workflowName"`
Organization string `json:"organization"`
ContractName string `json:"contractName"`
ContractVersion string `json:"contractVersion"`
}
type NormalizablePredicate ¶
type NormalizablePredicate interface {
GetAnnotations() map[string]string
GetEnvVars() map[string]string
GetMaterials() []*NormalizedMaterial
GetRunLink() string
GetMetadata() *Metadata
GetPolicyEvaluations() map[string][]*PolicyEvaluation
GetPolicyEvaluationsRef() *PolicyEvaluationsRef
GetPolicyEvaluationStatus() *PolicyEvaluationStatus
}
NormalizablePredicate represents a common interface of how to extract materials and env vars
func ExtractPredicate ¶
func ExtractPredicate(envelope *dsse.Envelope) (NormalizablePredicate, error)
Extract the Chainloop attestation predicate from an encoded DSSE envelope NOTE: We return a NormalizablePredicate interface to allow for future versions of the predicate to be extracted without updating the consumer. Yes, having the producer define and return an interface is an anti-pattern. but it greatly simplifies the code since there are multiple consumers at different layers of the app and we expect predicates to evolve quickly
type NormalizedMaterial ¶
type NormalizedMaterial struct {
// Name of the Material
Name string
// Type of the Material
Type string
// filename of the artifact that was either uploaded or injected inline in "value"
Filename string
// Inline content for an artifact or string material (binary-safe)
Value []byte
// Hash of the Material
Hash *crv1.Hash
// Tag of the container image
Tag string
// Whether the Material was uploaded and available for download from CAS
UploadedToCAS bool
// Whether the Material was embedded inline in the attestation
EmbeddedInline bool
// Annotations contains all material annotations, both user-defined and
// internal chainloop.* system annotations (e.g. chainloop.material.type,
// chainloop.material.cas, chainloop.material.size, etc.)
Annotations map[string]string
// Referenced source component, for SBOMs, SARIF files, etc
ReferencedSourceComponent *ReferencedSourceComponent
}
type PolicyEvaluation ¶ added in v0.96.6
type PolicyEvaluation struct {
Name string `json:"name"`
MaterialName string `json:"materialName,omitempty"`
// Needed to read old attestations
MaterialNameFallback string `json:"material_name,omitempty"`
Body string `json:"body,omitempty"`
Sources []string `json:"sources,omitempty"`
PolicyReference *intoto.ResourceDescriptor `json:"policyReference,omitempty"`
// Support old attestations
PolicyReferenceFallback *intoto.ResourceDescriptor `json:"policy_reference,omitempty"`
Description string `json:"description,omitempty"`
Annotations map[string]string `json:"annotations,omitempty"`
Violations []*PolicyViolation `json:"violations,omitempty"`
With map[string]string `json:"with,omitempty"`
Type string `json:"type"`
Skipped bool `json:"skipped"`
SkipReasons []string `json:"skipReasons,omitempty"`
GroupReference *intoto.ResourceDescriptor `json:"groupReference,omitempty"`
Requirements []string `json:"requirements,omitempty"`
Gate bool `json:"gate,omitempty"`
}
type PolicyEvaluationStatus ¶ added in v0.157.0
type PolicyEvaluationStatus struct {
// Whether we want to block the attestation on policy violations
Strategy PolicyViolationBlockingStrategy
// Whether the policy check was bypassed
Bypassed bool
// Whether the attestation was blocked due to policy violations
Blocked bool
// Whether the attestation has policy violations
HasViolations bool
// Whether the attestation has gated policy violations
HasGatedViolations bool
// HasGates is true when a gate fired or strategy is ENFORCED, independent
// of whether gated violations were recorded.
HasGates bool
// Total number of policy evaluations
EvaluationsCount int
// Total number of policy violations across all evaluations
ViolationsCount int
// Number of evaluations that were skipped (did not run).
SkippedCount int
// Number of evaluations that passed: neither skipped nor with violations.
PassedCount int
// Number of suppressed violations across all evaluations.
SuppressedCount int
}
func (*PolicyEvaluationStatus) Enforced ¶ added in v1.133.0
func (s *PolicyEvaluationStatus) Enforced() (*PolicyEvaluationStatus, bool)
Enforced returns a copy of the status with the enforced strategy, in which every policy acts as a gate. The bool reports whether the status changed. The control plane uses it when the contract enforces policies, but the CLI that rendered the attestation did not apply the contract setting.
type PolicyEvaluationsRef ¶ added in v1.108.6
type PolicyEvaluationsRef struct {
*intoto.ResourceDescriptor
// Size in bytes of the referenced bundle. Zero when not recorded.
SizeBytes int64 `json:"size,omitempty"`
}
PolicyEvaluationsRef points at the policy-evaluation bundle held in a CAS backend. It is an in-toto resource descriptor plus the size in bytes of the bundle it points at: the descriptor spec has no field for a size, and readers need one to decide whether to fetch the bundle. Embedding keeps the size inside the reference in the rendered predicate, next to the digest it describes.
func (*PolicyEvaluationsRef) GetSizeBytes ¶ added in v1.108.6
func (r *PolicyEvaluationsRef) GetSizeBytes() int64
GetSizeBytes reports the recorded size, or zero when there is no reference or it records none. A negative size is treated as unrecorded: the value is only as trustworthy as the attestation it came from, and a reader that trusted it would size a bundle it cannot size.
type PolicyStatus ¶ added in v1.93.4
type PolicyStatus string
PolicyStatus is the canonical, categorical policy outcome for an attestation. It collapses the raw enforcement/bypass/violation signals carried by PolicyEvaluationStatus into a single flat value so that list and describe surfaces can render a consistent badge without re-deriving.
const ( PolicyStatusUnspecified PolicyStatus = "" PolicyStatusNotApplicable PolicyStatus = "NOT_APPLICABLE" PolicyStatusPassed PolicyStatus = "PASSED" PolicyStatusSkipped PolicyStatus = "SKIPPED" PolicyStatusWarning PolicyStatus = "WARNING" PolicyStatusBlocked PolicyStatus = "BLOCKED" PolicyStatusBypassed PolicyStatus = "BYPASSED" )
type PolicyStatusSummary ¶ added in v1.93.4
type PolicyStatusSummary struct {
Status PolicyStatus
Total int
Passed int
Skipped int
Violated int
// See PolicyEvaluationStatus.HasGates. Independent of Status — a PASSED
// run can still have HasGates=true.
HasGates bool
// Number of suppressed violations across all evaluations. Excluded
// from Violated.
Suppressed int
}
PolicyStatusSummary bundles the categorical status with the per-evaluation counters the UI needs to render a breakdown ("3/5 passed") without pulling the full attestation envelope.
func DerivePolicyStatusSummary ¶ added in v1.93.4
func DerivePolicyStatusSummary(s *PolicyEvaluationStatus) PolicyStatusSummary
DerivePolicyStatusSummary is the single source of truth for computing the canonical PolicyStatus from the raw signals on PolicyEvaluationStatus.
Rules (applied in order):
total == 0 -> NOT_APPLICABLE (hasGatedViolations || strategy==ENFORCED) & bypass -> BYPASSED (hasGatedViolations || strategy==ENFORCED) -> BLOCKED hasViolations -> WARNING skipped > 0 -> SKIPPED otherwise -> PASSED
The rule order matters: a bypassed gated violation resolves to BYPASSED, not BLOCKED; a warning (advisory violation) wins over a SKIPPED sibling.
type PolicyViolation ¶ added in v0.96.6
type PolicyViolation struct {
Subject string `json:"subject"`
Message string `json:"message"`
Suppress bool `json:"suppress,omitempty"`
// Mirrors the oneof on attestation.v1.PolicyEvaluation.Violation. Only
// populated on the bundle path; never on the inline predicate.
Vulnerability *v1.PolicyVulnerabilityFinding `json:"vulnerability,omitempty"`
Sast *v1.PolicySASTFinding `json:"sast,omitempty"`
LicenseViolation *v1.PolicyLicenseViolationFinding `json:"licenseViolation,omitempty"`
}
type PolicyViolationBlockingStrategy ¶ added in v0.153.0
type PolicyViolationBlockingStrategy string
const ( PolicyViolationBlockingStrategyEnforced PolicyViolationBlockingStrategy = "ENFORCED" PolicyViolationBlockingStrategyAdvisory PolicyViolationBlockingStrategy = "ADVISORY" )
type ProvenancePredicateCommon ¶
type ProvenancePredicateCommon struct {
Metadata *Metadata `json:"metadata"`
Builder *builder `json:"builder"`
BuildType string `json:"buildType"`
Env map[string]string `json:"env,omitempty"`
RunnerType string `json:"runnerType"`
RunnerURL string `json:"runnerURL,omitempty"`
// Custom annotations
Annotations map[string]string `json:"annotations,omitempty"`
// Additional properties related to runner
RunnerEnvironment string `json:"runnerEnvironment,omitempty"`
RunnerAuthenticated bool `json:"runnerAuthenticated,omitempty"`
RunnerWorkflowFilePath string `json:"runnerWorkflowFilePath,omitempty"`
Auth *Auth `json:"auth,omitempty"`
CASBackend *CASBackend `json:"casBackend,omitempty"`
}
func (*ProvenancePredicateCommon) GetAnnotations ¶
func (p *ProvenancePredicateCommon) GetAnnotations() map[string]string
func (*ProvenancePredicateCommon) GetEnvVars ¶
func (p *ProvenancePredicateCommon) GetEnvVars() map[string]string
Implement NormalizablePredicate interface
func (*ProvenancePredicateCommon) GetMetadata ¶
func (p *ProvenancePredicateCommon) GetMetadata() *Metadata
func (*ProvenancePredicateCommon) GetRunLink ¶
func (p *ProvenancePredicateCommon) GetRunLink() string
type ProvenancePredicateV02 ¶
type ProvenancePredicateV02 struct {
*ProvenancePredicateCommon
Materials []*intoto.ResourceDescriptor `json:"materials,omitempty"`
// Deprecated: use PolicyEvaluationsRef to fetch full data from CAS.
PolicyEvaluations map[string][]*PolicyEvaluation `json:"policyEvaluations,omitempty"`
// Reference to the PolicyEvaluationBundle stored in CAS, carrying its size
PolicyEvaluationsRef *PolicyEvaluationsRef `json:"policyEvaluationsRef,omitempty"`
// Used to read policy evaluations from old attestations
PolicyEvaluationsFallback map[string][]*PolicyEvaluation `json:"policy_evaluations,omitempty"`
// Whether the attestation has policy violations
PolicyHasViolations bool `json:"policyHasViolations"`
// Total number of policy evaluations
PolicyEvaluationsCount int `json:"policyEvaluationsCount"`
// Total number of policy violations across all evaluations
PolicyViolationsCount int `json:"policyViolationsCount"`
// Number of evaluations that were skipped (did not run)
PolicySkippedCount int `json:"policySkippedCount,omitempty"`
// Number of evaluations that passed (no violations and not skipped)
PolicyPassedCount int `json:"policyPassedCount,omitempty"`
// Number of suppressed violations across all evaluations. Suppressed
// entries themselves are not embedded in the predicate — they live in
// the CAS-stored PolicyEvaluationBundle.
PolicySuppressedCount int `json:"policySuppressedCount,omitempty"`
// Whether the attestation has policy violations in gated policies
PolicyHasGatedViolations bool `json:"policyHasGatedViolations,omitempty"`
PolicyHasGates bool `json:"policyHasGates,omitempty"`
// Whether we want to block the attestation on policy violations
PolicyCheckBlockingStrategy PolicyViolationBlockingStrategy `json:"policyCheckBlockingStrategy"`
// Whether the policy check was bypassed
PolicyBlockBypassEnabled bool `json:"policyBlockBypassEnabled"`
// Whether the attestation was blocked due to policy violations
PolicyAttBlocked bool `json:"policyAttBlocked"`
// Default keyless signing authority (not necessarily the one used)
SigningCA string `json:"signingCA,omitempty"`
// Default TSA used for signing (not necessarily the one used)
SigningTSA string `json:"signingTSA,omitempty"`
}
func (*ProvenancePredicateV02) GetMaterials ¶
func (p *ProvenancePredicateV02) GetMaterials() []*NormalizedMaterial
Implement NormalizablePredicate interface
func (*ProvenancePredicateV02) GetPolicyEvaluationStatus ¶ added in v0.157.0
func (p *ProvenancePredicateV02) GetPolicyEvaluationStatus() *PolicyEvaluationStatus
func (*ProvenancePredicateV02) GetPolicyEvaluations ¶
func (p *ProvenancePredicateV02) GetPolicyEvaluations() map[string][]*PolicyEvaluation
func (*ProvenancePredicateV02) GetPolicyEvaluationsRef ¶ added in v1.89.0
func (p *ProvenancePredicateV02) GetPolicyEvaluationsRef() *PolicyEvaluationsRef
type ReferencedSourceComponent ¶ added in v1.0.0
type ReferencedSourceComponent struct {
// i.e container, file
Type string `json:"type"`
// i.e ghcr.io/chainloop-dev/chainloop/cli
Name string `json:"name"`
// i.e sha256:bbfd27fcdb15c8082951dc59be2310a2a2e6b95e11002f8411e5918887faa607
// or a tag i.e v0.1.0
Version string `json:"version"`
}
Some materials such as SBOMs might have been generated from a source component For example, you might have generated an SBOM for a container image and this is the ifnormation name": "ghcr.io/chainloop-dev/chainloop/cli", type": "container", version": "sha256:bbfd27fcdb15c8082951dc59be2310a2a2e6b95e11002f8411e5918887faa607",
type RendererCommon ¶
type RendererCommon struct {
// contains filtered or unexported fields
}
type RendererV02 ¶
type RendererV02 struct {
*RendererCommon
// contains filtered or unexported fields
}
func NewChainloopRendererV02 ¶
func NewChainloopRendererV02(att *v1.Attestation, builderVersion, builderDigest string, attClient pb.AttestationServiceClient, logger *zerolog.Logger) *RendererV02
func (*RendererV02) SetPolicyEvaluationsRef ¶ added in v1.89.0
func (r *RendererV02) SetPolicyEvaluationsRef(ref *PolicyEvaluationsRef)
SetPolicyEvaluationsRef sets the CAS reference for the policy evaluations bundle.