Help us shape the future of Go! Take the 2026 Go Developer Survey

chainloop

package
v1.108.3 Latest Latest
Warning

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

Go to latest
Published: Sep 4, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Index

Constants

View Source
const AttPolicyEvaluation = "CHAINLOOP.ATTESTATION"
View Source
const PolicyEvaluationsBundleMediaType = "application/vnd.chainloop.policy-evaluations.v1+json"
View Source
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

View Source
const (
	// Subject names
	SubjectGitHead = "git.head"
)

Variables

This section is empty.

Functions

func ExtractStatement

func ExtractStatement(envelope *dsse.Envelope) (*intoto.Statement, error)

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 Auth added in v1.12.0

type Auth struct {
	ID   string `json:"id"`
	Type string `json:"type"`
}

type CASBackend added in v1.67.0

type CASBackend struct {
	CASBackendID   string `json:"casBackendID"`
	CASBackendName string `json:"casBackendName"`
	Fallback       bool   `json:"fallback"`
}

type Maintainer

type Maintainer struct {
	Name  string `json:"name"`
	Email string `json:"email"`
}

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() *intoto.ResourceDescriptor
	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
}

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 (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
	PolicyEvaluationsRef *intoto.ResourceDescriptor `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() *intoto.ResourceDescriptor

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 *intoto.ResourceDescriptor)

SetPolicyEvaluationsRef sets the CAS reference for the policy evaluations bundle.

func (*RendererV02) Statement

func (r *RendererV02) Statement(_ context.Context) (*intoto.Statement, error)

Jump to

Keyboard shortcuts

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