webhook

Documentation

Index

• func ToContext(ctx context.Context, cache ResultCache) context.Context
• func ValidatePolicyAttestationsForAuthority(ctx context.Context, ref name.Reference, authority webhookcip.Authority, ...) (map[string][]PolicyAttestation, error)
• type AuthorityMatch
• type CacheResult
• type GithubExtensions
• type NoCache
  • func (nc *NoCache) Get(ctx context.Context, image, uid, resourceVersion string) *CacheResult
  • func (nc *NoCache) Set(ctx context.Context, image, name, uid, resourceVersion string, ...)
• type PolicyAttestation
• type PolicyResult
  • func ValidatePolicy(ctx context.Context, namespace string, ref name.Reference, ...) (*PolicyResult, []error)
• type PolicySignature
  • func ValidatePolicySignaturesForAuthority(ctx context.Context, ref name.Reference, authority webhookcip.Authority, ...) ([]PolicySignature, error)
• type ResultCache
  • func FromContext(ctx context.Context) ResultCache
• type Validator
  • func NewValidator(ctx context.Context) *Validator
  • func (v *Validator) ResolveCronJob(ctx context.Context, c *duckv1.CronJob)
  • func (v *Validator) ResolvePod(ctx context.Context, p *duckv1.Pod)
  • func (v *Validator) ResolvePodScalable(ctx context.Context, ps *policyduckv1beta1.PodScalable)
  • func (v *Validator) ResolvePodSpecable(ctx context.Context, wp *duckv1.WithPod)
  • func (v *Validator) ValidateCronJob(ctx context.Context, c *duckv1.CronJob) *apis.FieldError
  • func (v *Validator) ValidatePod(ctx context.Context, p *duckv1.Pod) *apis.FieldError
  • func (v *Validator) ValidatePodScalable(ctx context.Context, ps *policyduckv1beta1.PodScalable) *apis.FieldError
  • func (v *Validator) ValidatePodSpecable(ctx context.Context, wp *duckv1.WithPod) *apis.FieldError

Functions

func ToContext

func ToContext(ctx context.Context, cache ResultCache) context.Context

func ValidatePolicyAttestationsForAuthority

func ValidatePolicyAttestationsForAuthority(ctx context.Context, ref name.Reference, authority webhookcip.Authority, remoteOpts ...ociremote.Option) (map[string][]PolicyAttestation, error)

ValidatePolicyAttestationsForAuthority takes the Authority and tries to verify attestations against it.

Types

type AuthorityMatch

type AuthorityMatch struct {
	// All of the matching signatures for this authority
	// Wonder if for consistency this should also have the matching
	// attestations name, aka, make this into a map.
	Signatures []PolicySignature `json:"signatures,omitempty"`

	// Mapping from attestation name to all of verified attestations
	Attestations map[string][]PolicyAttestation `json:"attestations,omitempty"`

	// Static indicates whether this authority matched due to static
	// e.g. static: { action: pass }
	Static bool `json:"static,omitempty"`
}

AuthorityMatch returns either Signatures (if there are no Attestations specified), or Attestations if there are Attestations specified.

type CacheResult

type CacheResult struct {
	PolicyResult *PolicyResult
	Errors       []error
}

CacheResult wraps PolicyResult and errors that are suitable for caching purposes. By doing this we can make choices that control things like, should errors be cached, and if so, for how long that's independent of the successful validations.

type GithubExtensions

type GithubExtensions struct {
	// OID: 1.3.6.1.4.1.57264.1.2
	WorkflowTrigger string `json:"githubWorkflowTrigger,omitempty"`
	// OID: 1.3.6.1.4.1.57264.1.3
	WorkflowSHA string `json:"githubWorkflowSha,omitempty"`
	// OID: 1.3.6.1.4.1.57264.1.4
	WorkflowName string `json:"githubWorkflowName,omitempty"`
	// OID: 1.3.6.1.4.1.57264.1.5
	WorkflowRepo string `json:"githubWorkflowRepo,omitempty"`
	// OID: 1.3.6.1.4.1.57264.1.6
	WorkflowRef string `json:"githubWorkflowRef,omitempty"`
}

GithubExtensions holds the Github-related OID extensions. See also: https://github.com/sigstore/fulcio/blob/main/docs/oid-info.md NOTE: these field correlate with the names given in the cosign CertExtensionMap and must be prefixed with "github" to avoid ambiguity.

type NoCache

type NoCache struct {
}

NoCache is pretty much what it says, it caches nothing. Just meant to implement the interface that we can test with as well as if there is no caching wanted, we can do that by injecting this.

func (*NoCache) Get

func (nc *NoCache) Get(ctx context.Context, image, uid, resourceVersion string) *CacheResult

func (*NoCache) Set

func (nc *NoCache) Set(ctx context.Context, image, name, uid, resourceVersion string, cacheResult *CacheResult)

type PolicyAttestation

type PolicyAttestation struct {
	PolicySignature `json:",inline"`

	// PredicateType is the in-toto predicate type of this attestation.
	PredicateType string `json:"predicateType,omitempty"`

	// Payload is the bytes of the in-toto statement's predicate payload.
	// This is included for the benefit of the caller of ValidatePolicy, and is
	// not intended for consumption in the ClusterImagePolicy's outer policy
	// block.
	Payload []byte `json:"-"`
}

PolicyAttestation contains a normalized result of a validated attestation, which consists of the PolicySignature part, and some additional attestation specific fields.

type PolicyResult

type PolicyResult struct {
	// AuthorityMatches will have an entry for each successful Authority check
	// on it. Key in the map is the Attestation.Name
	AuthorityMatches map[string]AuthorityMatch `json:"authorityMatches,omitempty"`

	// Config contains the Config for each of the normalized os/architectures
	// where key to the map is the {OS}/{Architecture}[/{Variant}]
	//
	// Some examples are:
	// linux/arm64
	// linux/arm/v7
	// linux/arm/v6
	//
	// This field is only available for evaluation if
	// CIP.Spec.Policy.FetchConfigFile is set to true.
	Config map[string]*v1.ConfigFile `json:"config,omitempty"`

	// Spec contains the Spec for the resource that was evaluated. Note
	// that because this is resource specific, so you can use MatchResource
	// to filter to only specific resource to get only the Specs you want.
	//
	// This field is only available for evaluation if
	// CIP.Spec.Policy.IncludeSpec is set to true.
	Spec interface{} `json:"spec,omitempty"`

	// ObjectMeta contains the ObjectMeta for the resource that was evaluated.
	//
	// This field is only available for evaluation if
	// CIP.Spec.Policy.IncludeObjectMeta is set to true.
	ObjectMeta interface{} `json:"objectMeta,omitempty"`
}

PolicyResult is the result of a successful ValidatePolicy call. These are meant to be consumed by a higher level Policy engine that can reason about validated results. The 'first' level pass will verify signatures and attestations, and make the results then available for a policy that can be used to gate a passing of a ClusterImagePolicy. Some examples are, at least 'vulnerability' has to have been done and the scan must have been attested by a particular entity (sujbect/issuer) or a particular key. Other examples are N-of-M must be satisfied and so forth. We do not expose the low level details of signatures / attestations here since they have already been validated as per the Authority configuration and optionally by the Attestations which contain a particular policy that can be used to validate the Attestations (say vulnerability scanner must not have any High sev issues).

func ValidatePolicy

func ValidatePolicy(ctx context.Context, namespace string, ref name.Reference, cip webhookcip.ClusterImagePolicy, kc authn.Keychain, remoteOpts ...ociremote.Option) (*PolicyResult, []error)

ValidatePolicy will go through all the Authorities for a given image/policy and return validated authorities if at least one of the Authorities validated the signatures OR attestations if atttestations were specified. Returns PolicyResult if one or more authorities matched, otherwise nil. In any case returns all errors encountered if none of the authorities passed. kc is the Keychain to use for fetching ConfigFile that's independent of the signatures / attestations.

type PolicySignature

type PolicySignature struct {
	// A unique identifier describing this signature.
	// This is typically the hash of this signature's OCI layer for images.
	ID string `json:"id,omitempty"`

	// Subject that was found to match on the Cert.
	Subject string `json:"subject,omitempty"`
	// Issure that was found to match on the Cert.
	Issuer string `json:"issuer,omitempty"`

	// GithubExtensions holds the Github-related OID extensions.
	// See also: https://github.com/sigstore/fulcio/blob/main/docs/oid-info.md
	GithubExtensions `json:",inline"`
}

PolicySignature contains a normalized result of a validated signature, where signature could be a signature on the Image (.sig) or on an Attestation (.att).

func ValidatePolicySignaturesForAuthority

func ValidatePolicySignaturesForAuthority(ctx context.Context, ref name.Reference, authority webhookcip.Authority, remoteOpts ...ociremote.Option) ([]PolicySignature, error)

ValidatePolicySignaturesForAuthority takes the Authority and tries to verify a signature against it.

type ResultCache

type ResultCache interface {
	// Set caches a PolicyResult for a given CIP evaluated for a given image at
	// a particular point in time. image, uid & resourceVersion will give a
	// unique point in time, so we can make sure we're not caching things that
	// are out of date.
	Set(ctx context.Context, image, name, uid, resourceVersion string, cacheResult *CacheResult)

	// Get returns a cached result for a given image or nil if there are none.
	Get(ctx context.Context, image, uid, resourceVersion string) *CacheResult
}

func FromContext

func FromContext(ctx context.Context) ResultCache

FromContext extracts a cache from the provided context. If one has not been set, return the NoCache to fulfill the interface but it provides no caching.

type Validator

type Validator struct{}

func NewValidator

func NewValidator(ctx context.Context) *Validator

func (*Validator) ResolveCronJob

func (v *Validator) ResolveCronJob(ctx context.Context, c *duckv1.CronJob)

ResolveCronJob implements duckv1.CronJobValidator

func (*Validator) ResolvePod

func (v *Validator) ResolvePod(ctx context.Context, p *duckv1.Pod)

ResolvePod implements duckv1.PodValidator

func (*Validator) ResolvePodScalable

func (v *Validator) ResolvePodScalable(ctx context.Context, ps *policyduckv1beta1.PodScalable)

ResolvePodScalable implements policyduckv1beta1.PodScalableValidator

func (*Validator) ResolvePodSpecable

func (v *Validator) ResolvePodSpecable(ctx context.Context, wp *duckv1.WithPod)

ResolvePodSpecable implements duckv1.PodSpecValidator

func (*Validator) ValidateCronJob

func (v *Validator) ValidateCronJob(ctx context.Context, c *duckv1.CronJob) *apis.FieldError

ValidateCronJob implements duckv1.CronJobValidator

func (*Validator) ValidatePod

func (v *Validator) ValidatePod(ctx context.Context, p *duckv1.Pod) *apis.FieldError

ValidatePod implements duckv1.PodValidator

func (*Validator) ValidatePodScalable

func (v *Validator) ValidatePodScalable(ctx context.Context, ps *policyduckv1beta1.PodScalable) *apis.FieldError

ValidatePodScalable implements policyduckv1beta1.PodScalableValidator It is very similar to ValidatePodSpecable, but allows for spec.replicas to be decremented. This allows for scaling down pods with non-compliant images that would otherwise be forbidden.

func (*Validator) ValidatePodSpecable

func (v *Validator) ValidatePodSpecable(ctx context.Context, wp *duckv1.WithPod) *apis.FieldError

ValidatePodSpecable implements duckv1.PodSpecValidator