### Setup Local Development Cluster

Source: https://github.com/sigstore/policy-controller/blob/main/README.md

Set up a local Kind Kubernetes cluster using the local-dev CLI tool. This command defaults to using the local Kind registry.

```bash
./bin/local-dev setup
```

--------------------------------

### Install Policy Controller with AKS Workload Identity

Source: https://context7.com/sigstore/policy-controller/llms.txt

Install the policy controller using Helm, configuring AKS workload identity with the provided client and tenant IDs.

```bash
helm upgrade --install policy-controller sigstore/policy-controller --version 0.9.0 \
  --set-json webhook.serviceAccount.annotations={
    "azure.workload.identity/client-id": "${SERVICE_PRINCIPAL_CLIENT_ID}",
    "azure.workload.identity/tenant-id": "${TENANT_ID}"
  }
```

--------------------------------

### Create AWS KMS key

Source: https://github.com/sigstore/policy-controller/blob/main/examples/README.md

Example command to create an AWS KMS key for container signing. Note the ARN for subsequent steps.

```bash
$ aws kms create-key \
  --description "Container signing key" \
  --key-spec ECC_NIST_P256 \
  --key-usage SIGN_VERIFY
{
    "KeyMetadata": {
        "AWSAccountId": "...."
        "Arn": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        ....
    }
}
```

--------------------------------

### Install Policy Controller with Service Principal via Helm

Source: https://github.com/sigstore/policy-controller/blob/main/README.md

Use this command to install or upgrade the policy-controller Helm chart and configure it to use service principals for AKS clusters by setting workload identity annotations.

```bash
helm upgrade --install policy-controller sigstore/policy-controller --version 0.9.0 \
--set-json webhook.serviceAccount.annotations="{\"azure.workload.identity/client-id\": \"${SERVICE_PRINCIPAL_CLIENT_ID}\", \"azure.workload.identity/tenant-id\": \"${TENANT_ID}\"}"
```

--------------------------------

### Install Policy Controller with Managed Identity via Helm

Source: https://github.com/sigstore/policy-controller/blob/main/README.md

Use this command to install the policy-controller Helm chart and configure it to use managed identities for AKS clusters by setting environment variables.

```bash
helm install policy-controller sigstore/policy-controller --version 0.9.0 \
--set webhook.env.AZURE_CLIENT_ID=my-managed-id-client-id,webhook.env.AZURE_TENANT_ID=tenant-id
```

--------------------------------

### Set environment variables for policy validation

Source: https://github.com/sigstore/policy-controller/blob/main/examples/README.md

Set the POLICY and IMAGE environment variables to point to the example policy and the container image you want to test.

```bash
POLICY="policies/some-policy.yaml"
IMAGE="r.example.com/myapp:v0.1.0"
```

--------------------------------

### Get Git Log for Authors

Source: https://github.com/sigstore/policy-controller/blob/main/release/README.md

Use this command to get a unique list of authors who contributed since the last release. Replace YYYY-MM-DD with the date of the last release.

```shell
git log --pretty="* %an" --after="YYYY-MM-DD" | sort -u
```

--------------------------------

### policy-tester CLI Usage Examples

Source: https://context7.com/sigstore/policy-controller/llms.txt

The `policy-tester` CLI allows offline evaluation of `ClusterImagePolicy` against real images. It supports testing keyless policies, policies with `includeSpec`/`includeObjectMeta` using `--resource`, and custom trust roots via `--trustroot`. The OCI 1.1 referrers API can be enabled with `--enable-oci11`.

```bash
# Build the tool
make policy-tester

# Test keyless policy against a real image
./policy-tester \
    --policy=test/testdata/policy-controller/tester/cip-public-keyless.yaml \
    --image=ghcr.io/sigstore/cosign/cosign:v1.9.0 | jq

```

```bash
# Test with a Kubernetes resource for includeSpec/includeObjectMeta policies
./policy-tester \
    --policy=my-policy-with-include-spec.yaml \
    --image=myregistry.io/myapp@sha256:abc123... \
    --resource=my-deployment.yaml | jq

```

```bash
# Test with a custom TrustRoot (private Sigstore)
./policy-tester \
    --policy=my-keyless-policy.yaml \
    --image=private-registry.corp/myapp@sha256:abc123... \
    --trustroot=my-trustroot.yaml | jq

```

```bash
# Enable OCI 1.1 referrers API for attestation discovery
./policy-tester \
    --policy=attestation-policy.yaml \
    --image=myregistry.io/myapp@sha256:abc123... \
    --enable-oci11 | jq

```

```bash
# Log level control
./policy-tester --policy=policy.yaml --image=img:tag --log-level=debug

```

--------------------------------

### Helm Installation with Azure ACR Managed Identity

Source: https://context7.com/sigstore/policy-controller/llms.txt

Install the policy controller via Helm, passing `AZURE_CLIENT_ID` and `AZURE_TENANT_ID` as environment variables to the webhook for ACR integration using AKS managed identities.

```bash
# Install policy-controller via Helm
helm repo add sigstore https://sigstore.github.io/helm-charts
helm repo update

# Install with ACR managed identity support
helm install policy-controller sigstore/policy-controller --version 0.9.0 \
  --set webhook.env.AZURE_CLIENT_ID=<managed-identity-client-id> \
  --set webhook.env.AZURE_TENANT_ID=<azure-tenant-id>

```

--------------------------------

### Get Git Log for Pull Requests

Source: https://github.com/sigstore/policy-controller/blob/main/release/README.md

Use this command to list merged pull requests since the last release. Replace YYYY-MM-DD with the date of the last release.

```shell
git log --pretty="* %s" --after="YYYY-MM-DD"
```

--------------------------------

### Build and Deploy Webhook Locally with ko

Source: https://context7.com/sigstore/policy-controller/llms.txt

Build the webhook locally and deploy it to the configured registry using `ko apply`. Assumes `registry.local` is set up.

```bash
KO_DOCKER_REPO=registry.local make ko-apply
```

--------------------------------

### Set up Local Kind Cluster with Policy Controller

Source: https://context7.com/sigstore/policy-controller/llms.txt

Create a Kind cluster named 'policy-dev' with Kubernetes version 1.29 and configure the registry URL. Omit `--registry-url` to use the local Kind registry.

```bash
./bin/local-dev setup \
    --cluster-name=policy-dev \
    --k8s-version=1.29 \
    --registry-url=ghcr.io/myorg
```

--------------------------------

### Compile and Verify Policies Programmatically

Source: https://context7.com/sigstore/policy-controller/llms.txt

Use `policy.Compile` to build a `Verifier` from a `Verification` config and `Verifier.Verify` to check an image reference against compiled policies. This is useful for running verifications in CI pipelines.

```go
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/google/go-containerregistry/pkg/authn"
    "github.com/google/go-containerregistry/pkg/name"
    "github.com/sigstore/policy-controller/pkg/policy"
    "knative.dev/pkg/logging"
    "go.uber.org/zap"
)

func main() {
    logger, _ := zap.NewDevelopment()
    ctx := logging.WithLogger(context.Background(), logger.Sugar())

    // Define the verification config pointing at a CIP YAML file
    pols := []policy.Source{
        {Path: "./my-cluster-image-policy.yaml"},
        // Also supports: {URL: "https://..."} or {Data: "<inline yaml>"}
    }
    v := policy.Verification{
        NoMatchPolicy: "deny",   // "allow", "deny", or "warn"
        Policies:      &pols,
    }

    // Compile validates the policy and builds an executable Verifier
    warnings := []string{}
    vfy, err := policy.Compile(ctx, v, func(s string, args ...interface{}) {
        warnings = append(warnings, fmt.Sprintf(s, args...))
    })
    if err != nil {
        log.Fatalf("policy compilation failed: %v", err)
    }

    // Parse the image reference
    ref, err := name.ParseReference("ghcr.io/myorg/myapp@sha256:abc123...")
    if err != nil {
        log.Fatal(err)
    }

    // Verify the image against the compiled policies
    if err := vfy.Verify(ctx, ref, authn.DefaultKeychain); err != nil {
        log.Fatalf("verification failed: %v", err)
    }
    fmt.Println("Image verified successfully")
    // Output: Image verified successfully
}
```

--------------------------------

### Unmarshal Verification with Viper

Source: https://github.com/sigstore/policy-controller/blob/main/pkg/policy/README.md

Demonstrates how to unmarshal the policy verification configuration from a Viper configuration object.

```golang
	vfy := policy.Verification{}
	if err := v.UnmarshalKey("verification", &vfy); err != nil { ... }
```

--------------------------------

### Create GCP KMS keyring and key

Source: https://github.com/sigstore/policy-controller/blob/main/examples/README.md

Commands to create a GCP KMS keyring and key for asymmetric signing. Ensure you have the gcloud CLI configured.

```bash
gcloud kms keyrings create ${KEY_RING} \
    --location ${REGION}
gcloud kms keys create ${KEY_NAME} \
    --keyring ${KEY_RING} \
    --location ${REGION} \
    --purpose asymmetric-signing \
    --default-algorithm ec-sign-p256-sha256
```

--------------------------------

### Configure Local Registry Host Entry

Source: https://context7.com/sigstore/policy-controller/llms.txt

Add an entry to `/etc/hosts` to map `registry.local` to `127.0.0.1`, necessary when using the local Kind registry.

```bash
echo "127.0.0.1 registry.local" | sudo tee -a /etc/hosts
```

--------------------------------

### Tag and Push Repository for Release

Source: https://github.com/sigstore/policy-controller/blob/main/release/README.md

Set the release version in the RELEASE_TAG environment variable, then tag and push the repository. This action triggers the automated release workflow.

```shell
$ export RELEASE_TAG=<release version, eg "v1.4.0">
$ git tag -s ${RELEASE_TAG} -m "${RELEASE_TAG}"
$ git push origin ${RELEASE_TAG}
```

--------------------------------

### Define Verification Configuration

Source: https://github.com/sigstore/policy-controller/blob/main/pkg/policy/README.md

Defines the structure for verification configuration, including how to handle images that do not match any policies and how to specify policy sources.

```golang
type Verification struct {
	// NoMatchPolicy specifies the behavior when a base image doesn't match any
	// of the listed policies.  It allows the values: allow, deny, and warn.
	NoMatchPolicy string `yaml:"no-match-policy,omitempty"`

	// Policies specifies a collection of policies to use to cover the base
	// images used as part of evaluation.  See "policy" below for usage.
	// Policies can be nil so that we can distinguish between an explicitly
	// specified empty list and when policies is unspecified.
	Policies *[]Source `yaml:"policies,omitempty"`
}
```

--------------------------------

### Define Policy Source Options

Source: https://github.com/sigstore/policy-controller/blob/main/pkg/policy/README.md

Defines the structure for specifying policy sources, allowing policies to be provided as inline data, a file path, or a URL.

```golang
// Source contains a set of options for specifying policies.  Exactly
// one of the fields may be specified for each Source entry.
type Source struct {
	// Data is a collection of one or more ClusterImagePolicy resources.
	Data string `yaml:"data,omitempty"`

	// Path is a path to a file containing one or more ClusterImagePolicy
	// resources.
	// TODO(mattmoor): Make this support taking a directory similar to kubectl.
	// TODO(mattmoor): How do we want to handle something like -R?  Perhaps we
	// don't and encourage folks to list each directory individually?
	Path string `yaml:"path,omitempty"`

	// URL links to a file containing one or more ClusterImagePolicy resources.
	URL string `yaml:"url,omitempty"`
}
```

--------------------------------

### Build Local Development Tool

Source: https://github.com/sigstore/policy-controller/blob/main/README.md

Build the local-dev CLI tool using make. This tool is used for setting up a local Kind Kubernetes cluster for testing policy controller changes.

```bash
make local-dev
```

--------------------------------

### Build Policy Tester Tool

Source: https://github.com/sigstore/policy-controller/blob/main/README.md

Build the policy-tester tool using make. This tool is used for checking policies against various images.

```bash
make policy-tester
```

--------------------------------

### Compile Verification Configuration

Source: https://github.com/sigstore/policy-controller/blob/main/pkg/policy/README.md

Compiles the verification configuration into a Verifier, handling compilation warnings via a provided callback function.

```golang
	verifier, err := policy.Compile(ctx, verification,
		func(s string, i ...interface{}) {
			// Handle warnings your own way!
		})
	if err != nil { ... }
```

--------------------------------

### Generate key pair and sign container image using GCP KMS with cosign

Source: https://github.com/sigstore/policy-controller/blob/main/examples/README.md

Authenticate with GCP, generate a key pair using a KMS key, and then sign your container image with cosign. Ensure the policy controller has necessary IAM permissions and the GKE cluster has the cloudkms scope.

```bash
gcloud auth application-default login
cosign generate-key-pair \
    --kms gcpkms://projects/${PROJECT_ID}/locations/${REGION}/keyRings/${KEY_RING}/cryptoKeys/${KEY_NAME}
cosign sign \
    --key gcpkms://projects/${PROJECT_ID}/locations/${REGION}/keyRings/${KEY_RING}/cryptoKeys/${KEY_NAME} \
    ${IMAGE}
```

--------------------------------

### policy.Compile and policy.Verifier

Source: https://context7.com/sigstore/policy-controller/llms.txt

The `policy.Compile` function builds a `Verifier` from a `Verification` configuration. The `Verifier.Verify` method then checks an image reference against all matching policies, useful for programmatic verification outside of a webhook context, such as in CI pipelines.

```APIDOC
## `policy.Compile` and `policy.Verifier` — Programmatic policy verification

### Description
The `policy.Compile` function builds a `Verifier` from a `Verification` configuration. The `Verifier.Verify` method then checks an image reference against all matching policies, useful for programmatic verification outside of a webhook context, such as in CI pipelines.

### Function Signature
`policy.Compile(ctx context.Context, v policy.Verification, logf func(string, ...interface{})) (*policy.Verifier, error)`

### Parameters
- `ctx` (context.Context): The context for the operation.
- `v` (policy.Verification): The verification configuration.
- `logf` (func(string, ...interface{})): A callback function for logging warnings during compilation.

### Returns
- `*policy.Verifier`: A Verifier object that can be used to verify image references.
- `error`: An error if the policy compilation fails.

### Usage Example
```go
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/google/go-containerregistry/pkg/authn"
    "github.com/google/go-containerregistry/pkg/name"
    "github.com/sigstore/policy-controller/pkg/policy"
    "knative.dev/pkg/logging"
    "go.uber.org/zap"
)

func main() {
    logger, _ := zap.NewDevelopment()
    ctx := logging.WithLogger(context.Background(), logger.Sugar())

    // Define the verification config pointing at a CIP YAML file
    pols := []policy.Source{
        {Path: "./my-cluster-image-policy.yaml"},
        // Also supports: {URL: "https://..."} or {Data: "<inline yaml>"}
    }
    v := policy.Verification{
        NoMatchPolicy: "deny",   // "allow", "deny", or "warn"
        Policies:      &pols,
    }

    // Compile validates the policy and builds an executable Verifier
    warnings := []string{}
    vfy, err := policy.Compile(ctx, v, func(s string, args ...interface{}) {
        warnings = append(warnings, fmt.Sprintf(s, args...))
    })
    if err != nil {
        log.Fatalf("policy compilation failed: %v", err)
    }

    // Parse the image reference
    ref, err := name.ParseReference("ghcr.io/myorg/myapp@sha256:abc123...")
    if err != nil {
        log.Fatal(err)
    }

    // Verify the image against the compiled policies
    if err := vfy.Verify(ctx, ref, authn.DefaultKeychain); err != nil {
        log.Fatalf("verification failed: %v", err)
    }
    fmt.Println("Image verified successfully")
    // Output: Image verified successfully
}
```
```

--------------------------------

### Image Name Glob Matching with pkg/apis/glob

Source: https://context7.com/sigstore/policy-controller/llms.txt

Use `glob.Match` to test if an OCI image reference matches a glob pattern. `**` matches any characters including '/', while `*` matches within a single path segment. DockerHub images require the `index.docker.io/` prefix.

```go
package main

import (
    "fmt"
    "log"

    "github.com/sigstore/policy-controller/pkg/apis/glob"
)

func main() {
    tests := []struct{ pattern, image string }{
        {"ghcr.io/myorg/**",             "ghcr.io/myorg/myapp:v1.0"},
        {"ghcr.io/myorg/**",             "ghcr.io/myorg/nested/image:latest"},
        {"ghcr.io/myorg/*",              "ghcr.io/myorg/myapp:v1.0"},
        {"ghcr.io/myorg/*",              "ghcr.io/myorg/nested/image:latest"}, // false: * won't cross /
        {"index.docker.io/library/**",   "ubuntu"},                             // DockerHub official
        {"**",                           "gcr.io/any/registry/image:tag"},
    }

    for _, tc := range tests {
        matched, err := glob.Match(tc.pattern, tc.image)
        if err != nil {
            log.Printf("error matching %q against %q: %v", tc.image, tc.pattern, err)
            continue
        }
        fmt.Printf("glob.Match(%q, %q) = %v\n", tc.pattern, tc.image, matched)
    }
    // Output:
    // glob.Match("ghcr.io/myorg/**", "ghcr.io/myorg/myapp:v1.0") = true
    // glob.Match("ghcr.io/myorg/**", "ghcr.io/myorg/nested/image:latest") = true
    // glob.Match("ghcr.io/myorg/*", "ghcr.io/myorg/myapp:v1.0") = true
    // glob.Match("ghcr.io/myorg/*", "ghcr.io/myorg/nested/image:latest") = false
    // glob.Match("index.docker.io/library/**", "ubuntu") = true
    // glob.Match("**", "gcr.io/any/registry/image:tag") = true
}

```

--------------------------------

### Set policy for custom key attestation SBOM SPDXJSON

Source: https://github.com/sigstore/policy-controller/blob/main/examples/README.md

Set the POLICY environment variable to the path of the custom-key-attestation-sbom-spdxjson policy.

```bash
POLICY="policies/custom-key-attestation-sbom-spdxjson.yaml"
```

--------------------------------

### Attach SPDX SBOM using cosign attest keyless

Source: https://github.com/sigstore/policy-controller/blob/main/examples/README.md

Use cosign attest to attach an SPDX SBOM to your image, signing it keyless against the public Fulcio root.

```bash
cosign attest --yes --type spdxjson \
  --predicate sboms/example.spdx.json \
  "${IMAGE}"
```

--------------------------------

### Enable Enforcement on a Namespace

Source: https://context7.com/sigstore/policy-controller/llms.txt

Label a Kubernetes namespace to enable policy enforcement for it. This targets the 'my-namespace' namespace.

```bash
kubectl label namespace my-namespace policy.sigstore.dev/include=true
```

--------------------------------

### Validate image against policy using policy-tester

Source: https://github.com/sigstore/policy-controller/blob/main/examples/README.md

Execute the policy-tester CLI with the specified policy and image to validate compliance.

```bash
../policy-tester --policy "${POLICY}" --image "${IMAGE}"
```

--------------------------------

### Attach SPDX SBOM using cosign attest with custom key

Source: https://github.com/sigstore/policy-controller/blob/main/examples/README.md

Use cosign attest to attach an SPDX SBOM to your image, signing it with a custom key. Ensure COSIGN_PASSWORD is set.

```bash
export COSIGN_PASSWORD=""

cosign attest --yes --type spdxjson \
  --predicate sboms/example.spdx.json \
  --key keys/cosign.key \
  "${IMAGE}"
```

--------------------------------

### Set policy for keyless attestation SBOM SPDXJSON

Source: https://github.com/sigstore/policy-controller/blob/main/examples/README.md

Set the POLICY environment variable to the path of the keyless-attestation-sbom-spdxjson policy.

```bash
POLICY="policies/keyless-attestation-sbom-spdxjson.yaml"
```

--------------------------------

### MatchResource

Source: https://github.com/sigstore/policy-controller/blob/main/docs/api-types/index.md

MatchResource allows selecting resources based on its version, group and resource. It is also possible to select resources based on a list of matching labels.

```APIDOC
## MatchResource

MatchResource allows selecting resources based on its version, group and resource. It is also possible to select resources based on a list of matching labels.

| Field | Description | Scheme | Required |
| ----- | ----------- | ------ | -------- |
| selector |  | [metav1.LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#labelselector-v1-meta) | false |
```

--------------------------------

### Test Policy with Policy Tester

Source: https://github.com/sigstore/policy-controller/blob/main/README.md

Run the policy-tester tool to evaluate a ClusterImagePolicy against a specified image. Pipe the output to jq for formatted JSON.

```bash
(set -o pipefail && \
    ./policy-tester \
        --policy=test/testdata/policy-controller/tester/cip-public-keyless.yaml \
        --image=ghcr.io/sigstore/cosign/cosign:v1.9.0 | jq)
```

--------------------------------

### Sign container image using AWS KMS key with cosign

Source: https://github.com/sigstore/policy-controller/blob/main/examples/README.md

Sign your container image using cosign with the specified AWS KMS key. Replace the placeholder ARN with your actual KMS key ARN.

```bash
cosign sign --key "awskms:///<< arn of kms key >>" "${IMAGE}"
```

--------------------------------

### ConfigMap for Global No-Match Policy

Source: https://context7.com/sigstore/policy-controller/llms.txt

The `config-policy-controller` ConfigMap in the `cosign-system` namespace sets the global policy for images that do not match any `ClusterImagePolicy`. The `no-match-policy` can be set to `allow`, `deny`, or `warn`.

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: config-policy-controller
  namespace: cosign-system
  labels:
    policy.sigstore.dev/release: devel
data:
  # no-match-policy controls behavior for images matching no ClusterImagePolicy
  # Options: allow (default), deny, warn
  no-match-policy: deny

```

```yaml
# Warn-only variant: images without a matching policy get a warning but are admitted
apiVersion: v1
kind: ConfigMap
metadata:
  name: config-policy-controller
  namespace: cosign-system
data:
  no-match-policy: warn

```

--------------------------------

### Sign Container Image with GitHub Actions

Source: https://github.com/sigstore/policy-controller/blob/main/examples/README.md

Use this GitHub Actions workflow to sign your container images. Ensure the workflow path and branch match the policy URI. Requires 'id-token: write' permission for OIDC token signing.

```yaml
jobs:
  sign_action:
    runs-on: ubuntu-latest

    permissions:
      contents: read
      id-token: write # NB: needed for signing the images with GitHub OIDC Token

    name: Install Cosign and sign image
    steps:
      - uses: actions/checkout@master
        with:
          fetch-depth: 1

      - name: Install Cosign
        uses: sigstore/cosign-installer@main

      - name: Sign the images with GitHub OIDC Token
        run: cosign sign ${IMAGE}
```

--------------------------------

### Apply CRDs and Core Config

Source: https://context7.com/sigstore/policy-controller/llms.txt

Apply the Custom Resource Definitions (CRDs) and core configuration files for the policy controller using kubectl.

```bash
kubectl apply -f config/
```

--------------------------------

### TrustRoot CRD for custom Sigstore infrastructure

Source: https://context7.com/sigstore/policy-controller/llms.txt

`TrustRoot` enables using a private Fulcio CA, Rekor log, CT log, and Timestamp Authority instead of the public Sigstore infrastructure. Reference it in a `ClusterImagePolicy` via `trustRootRef`.

```yaml
# Define a custom trust root for a private Sigstore deployment
apiVersion: policy.sigstore.dev/v1alpha1
kind: TrustRoot
metadata:
  name: my-sigstore-keys
spec:
  sigstoreKeys:
    certificateAuthorities:
    - subject:
        organization: my-org
        commonName: my-fulcio-ca
      uri: https://fulcio.internal.corp
      certChain: |
        -----BEGIN CERTIFICATE-----
        ... (Fulcio root CA PEM) ...
        -----END CERTIFICATE-----
    tLogs:
    - baseURL: https://rekor.internal.corp
      hashAlgorithm: sha-256
      publicKey: |
        -----BEGIN PUBLIC KEY-----
        ... (Rekor public key PEM) ...
        -----END PUBLIC KEY-----
    ctLogs:
    - baseURL: https://ctfe.internal.corp
      hashAlgorithm: sha-256
      publicKey: |
        -----BEGIN PUBLIC KEY-----
        ... (CTFE public key PEM) ...
        -----END PUBLIC KEY-----
```

```yaml

---
```

```yaml
# Reference the TrustRoot in a ClusterImagePolicy
apiVersion: policy.sigstore.dev/v1alpha1
kind: ClusterImagePolicy
metadata:
  name: policy-with-custom-trustroot
spec:
  images:
  - glob: "**"
  authorities:
  - keyless:
      trustRootRef: my-sigstore-keys      # references the TrustRoot above
      identities:
      - issuer: https://accounts.internal.corp
        subject: "https://ci.internal.corp/pipelines/release"
    ctlog:
      trustRootRef: my-sigstore-keys
```

--------------------------------

### Set policy for signing by GCP KMS key

Source: https://github.com/sigstore/policy-controller/blob/main/examples/README.md

Set the POLICY environment variable to the path of the signed-by-gcp-kms.yaml policy.

```bash
POLICY="policies/signed-by-gcp-kms.yaml"
```

--------------------------------

### Set policy for signing by GitHub Actions

Source: https://github.com/sigstore/policy-controller/blob/main/examples/README.md

Set the POLICY environment variable to the path of the signed-by-github-actions.yaml policy. This policy asserts that images have been signed by a specific GitHub Actions workflow using keyless signing.

```bash
POLICY="policies/signed-by-github-actions.yaml"
```

--------------------------------

### Set policy for signing by AWS KMS key

Source: https://github.com/sigstore/policy-controller/blob/main/examples/README.md

Set the POLICY environment variable to the path of the signed-by-aws-kms.yaml policy.

```bash
POLICY="policies/signed-by-aws-kms.yaml"
```

--------------------------------

### ClusterImagePolicy with selective resource targeting

Source: https://context7.com/sigstore/policy-controller/llms.txt

The `match` field limits a policy to specific Kubernetes resource types or label selectors. Only matching resources are subject to the policy — all others bypass it.

```yaml
apiVersion: policy.sigstore.dev/v1alpha1
kind: ClusterImagePolicy
metadata:
  name: image-policy-pods-with-label
spec:
  images:
  - glob: "**"
  match:
  - resource: pods
    version: "*"
    selector:
      matchLabels:
        enforce-signing: "true"     # only pods with this label are checked
  authorities:
  - key:
      data: |
        -----BEGIN PUBLIC KEY-----
        MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEIcbqK2RAVZOfPzo+kbOhNYq8DK9f
        B2BGbU7jAXEvYthJ3vRcYq8l7g9UAXXiz9P2awFuTa4COcZU2IdEDVU0uA==
        -----END PUBLIC KEY-----
    ctlog:
      url: https://rekor.sigstore.dev
```

--------------------------------

### ClusterImagePolicy: Attestation Verification (SPDX SBOM with CUE)

Source: https://context7.com/sigstore/policy-controller/llms.txt

Validates that an image has a signed SPDX SBOM attestation using a CUE policy. The policy checks the predicate type and payload.

```yaml
# Require a signed SPDX SBOM attestation, validated with a CUE policy
apiVersion: policy.sigstore.dev/v1alpha1
kind: ClusterImagePolicy
metadata:
  name: must-have-spdx-sbom
spec:
  images:
  - glob: "**"
  authorities:
  - name: my-key
    key:
      data: |
        -----BEGIN PUBLIC KEY-----
        MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEOc6HkISHzVdUbtUsdjYtPuyPYBeg
        4FCemyVurIM4KEORQk4OAu8ZNwxvGSoY3eAabYaFIPPQ8ROAjrbdPwNdJw==
        -----END PUBLIC KEY-----
    ctlog:
      url: https://rekor.sigstore.dev
    attestations:
    - name: must-have-spdxjson
      predicateType: spdxjson
      policy:
        type: cue
        data: |
          predicateType: "https://spdx.dev/Document"
```

--------------------------------

### KeylessRef

Source: https://github.com/sigstore/policy-controller/blob/main/docs/api-types/index.md

KeylessRef contains location of the validating certificate and the identities against which to verify. KeylessRef will contain either the URL to the verifying certificate, or it will contain the certificate data inline or in a secret.

```APIDOC
## KeylessRef

KeylessRef contains location of the validating certificate and the identities against which to verify. KeylessRef will contain either the URL to the verifying certificate, or it will contain the certificate data inline or in a secret.

| Field | Description | Scheme | Required |
| ----- | ----------- | ------ | -------- |
| url | URL defines a url to the keyless instance. | apis.URL | false |
| identities | Identities sets a list of identities. | [][Identity](#identity) | true |
| ca-cert | CACert sets a reference to CA certificate | [KeyRef](#keyref) | false |
| trustRootRef | Use the Certificate Chain from the referred TrustRoot.CertificateAuthorities and TrustRoot.CTLog | string | false |
| insecureIgnoreSCT | InsecureIgnoreSCT omits verifying if a certificate contains an embedded SCT | bool | false |
```

--------------------------------

### Tear Down Local Kind Cluster

Source: https://context7.com/sigstore/policy-controller/llms.txt

Clean up and tear down the local Kind cluster named 'policy-dev'.

```bash
./bin/local-dev clean --cluster-name=policy-dev
```

--------------------------------

### ImagePattern

Source: https://github.com/sigstore/policy-controller/blob/main/docs/api-types/index.md

ImagePattern defines a pattern and its associated authorties If multiple patterns match a particular image, then ALL of those authorities must be satisfied for the image to be admitted.

```APIDOC
## ImagePattern

ImagePattern defines a pattern and its associated authorties If multiple patterns match a particular image, then ALL of those authorities must be satisfied for the image to be admitted.

| Field | Description | Scheme | Required |
| ----- | ----------- | ------ | -------- |
| glob | Glob defines a globbing pattern. | string | true |
```

--------------------------------

### Verifier Interface Definition

Source: https://github.com/sigstore/policy-controller/blob/main/pkg/policy/README.md

Defines the Verifier interface, which is used to check if a given image digest satisfies the backing policies.

```golang
// Verifier is the interface for checking that a given image digest satisfies
// the policies backing this interface.
type Verifier interface {
	// Verify checks that the provided reference satisfies the backing policies.
	Verify(context.Context, name.Reference, authn.Keychain) error
}
```

--------------------------------

### KeyRef

Source: https://github.com/sigstore/policy-controller/blob/main/docs/api-types/index.md

This references a public verification key stored in a secret in the cosign-system namespace. A KeyRef must specify only one of SecretRef, Data or KMS

```APIDOC
## KeyRef

This references a public verification key stored in a secret in the cosign-system namespace. A KeyRef must specify only one of SecretRef, Data or KMS

| Field | Description | Scheme | Required |
| ----- | ----------- | ------ | -------- |
| secretRef | SecretRef sets a reference to a secret with the key. | [v1.SecretReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#secretreference-v1-core) | false |
| data | Data contains the inline public key. | string | false |
| kms | KMS contains the KMS url of the public key Supported formats differ based on the KMS system used. | string | false |
| hashAlgorithm | HashAlgorithm always defaults to sha256 if the algorithm hasn't been explicitly set | string | false |
```

--------------------------------

### Identity

Source: https://github.com/sigstore/policy-controller/blob/main/docs/api-types/index.md

Identity may contain the issuer and/or the subject found in the transparency log. Issuer/Subject uses a strict match, while IssuerRegExp and SubjectRegExp apply a regexp for matching.

```APIDOC
## Identity

Identity may contain the issuer and/or the subject found in the transparency log. Issuer/Subject uses a strict match, while IssuerRegExp and SubjectRegExp apply a regexp for matching.

| Field | Description | Scheme | Required |
| ----- | ----------- | ------ | -------- |
| issuer | Issuer defines the issuer for this identity. | string | false |
| subject | Subject defines the subject for this identity. | string | false |
| issuerRegExp | IssuerRegExp specifies a regular expression to match the issuer for this identity. | string | false |
| subjectRegExp | SubjectRegExp specifies a regular expression to match the subject for this identity. | string | false |
```

--------------------------------

### ClusterImagePolicy with static authority (allow list)

Source: https://context7.com/sigstore/policy-controller/llms.txt

A `static` authority immediately passes or fails all matched images without any cryptographic verification — useful for allow-listing known-good images or blocking images by pattern.

```yaml
# Allow all images matching the glob without signature checks
apiVersion: policy.sigstore.dev/v1alpha1
kind: ClusterImagePolicy
metadata:
  name: allow-internal-images
spec:
  images:
  - glob: "registry.internal.corp/**"
  authorities:
  - static:
      action: pass

---
```

--------------------------------

### Validate CIP YAML Document

Source: https://context7.com/sigstore/policy-controller/llms.txt

Use `policy.Validate` to parse and validate a YAML document containing `ClusterImagePolicy` or `TrustRoot` objects. It separates warnings (e.g., deprecated fields) from hard errors.

```go
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/sigstore/policy-controller/pkg/policy"
)

func main() {
    ctx := context.Background()

    document := `
apiVersion: policy.sigstore.dev/v1beta1
kind: ClusterImagePolicy
metadata:
  name: my-policy
spec:
  images:
  - glob: "**"
  authorities:
  - keyless:
      url: https://fulcio.sigstore.dev
      identities:
      - issuer: https://token.actions.githubusercontent.com
        subject: "https://github.com/myorg/myrepo/.github/workflows/release.yml@refs/heads/main"
`
    warns, err := policy.Validate(ctx, document)
    if err != nil {
        log.Fatalf("policy is invalid: %v", err)
    }
    if warns != nil {
        fmt.Printf("policy has warnings: %v\n", warns)
    }
    fmt.Println("policy is valid")
    // Output: policy is valid
}
```

--------------------------------

### ClusterImagePolicy with static authority (deny list)

Source: https://context7.com/sigstore/policy-controller/llms.txt

A `static` authority immediately passes or fails all matched images without any cryptographic verification — useful for allow-listing known-good images or blocking images by pattern.

```yaml
# Block all images matching the glob with a custom error message
apiVersion: policy.sigstore.dev/v1alpha1
kind: ClusterImagePolicy
metadata:
  name: block-deprecated-registry
spec:
  images:
  - glob: "old-registry.corp/**"
  authorities:
  - static:
      action: fail
      message: "old-registry.corp is deprecated; use registry.internal.corp instead"
```

--------------------------------

### Clean Up Local Development Cluster

Source: https://github.com/sigstore/policy-controller/blob/main/README.md

Clean up a local Kind Kubernetes cluster managed by the local-dev CLI tool. Specify the cluster name to ensure the correct cluster is removed.

```bash
./bin/local-dev clean --cluster-name=<my cluster name>
```

--------------------------------

### ClusterImagePolicy: Keyless Signature Verification (Fulcio/Rekor)

Source: https://context7.com/sigstore/policy-controller/llms.txt

Enforces that images are signed by a specific OIDC identity verifiable through Fulcio and checked against Rekor. This policy is applied using kubectl.

```yaml
apiVersion: policy.sigstore.dev/v1alpha1
kind: ClusterImagePolicy
metadata:
  name: image-is-signed-by-github-actions
spec:
  images:
  - glob: "**"
  authorities:
  - keyless:
      url: https://fulcio.sigstore.dev
      identities:
      - issuer: https://token.actions.githubusercontent.com
        subject: "https://github.com/myorg/myrepo/.github/workflows/release.yml@refs/heads/main"
    ctlog:
      url: https://rekor.sigstore.dev

# Apply to cluster:
# kubectl apply -f policy.yaml

# Test with policy-tester CLI (built with: make policy-tester):
# ./policy-tester \
#     --policy=policy.yaml \
#     --image=ghcr.io/sigstore/cosign/cosign:v1.9.0 | jq
# Expected output on success: (empty, exit 0)
# Expected output on failure:
# {"errors":["ghcr.io/sigstore/cosign/cosign:v1.9.0 failed policy: image-is-signed-by-github-actions ..."]}
```

--------------------------------

### Attestation

Source: https://github.com/sigstore/policy-controller/blob/main/docs/api-types/index.md

Defines the type of attestation to validate and optionally apply a policy decision to it. It specifies the predicate type and an optional policy for matching signatures and attestations.

```APIDOC
## Attestation

Attestation defines the type of attestation to validate and optionally apply a policy decision to it. Authority block is used to verify the specified attestation types, and if Policy is specified, then it's applied only after the validation of the Attestation signature has been verified.

### Fields
* **name** (string) - Required - Name of the attestation. These can then be referenced at the CIP level policy.
* **predicateType** (string) - Required - PredicateType defines which predicate type to verify. Matches cosign verify-attestation options.
* **policy** ([Policy](#policy)) - Optional - Policy defines all of the matching signatures, and all of the matching attestations (whose attestations are verified).
```

--------------------------------

### ConfigMapReference

Source: https://github.com/sigstore/policy-controller/blob/main/docs/api-types/index.md

ConfigMapReference is cut&paste from SecretReference, but for the life of me couldn't find one in the public types. If there's one, use it.

```APIDOC
## ConfigMapReference

ConfigMapReference is cut&paste from SecretReference, but for the life of me couldn't find one in the public types. If there's one, use it.

| Field | Description | Scheme | Required |
| ----- | ----------- | ------ | -------- |
| name | Name is unique within a namespace to reference a configmap resource. | string | false |
| namespace | Namespace defines the space within which the configmap name must be unique. | string | false |
| key | Key defines the key to pull from the configmap. | string | false |
```

--------------------------------

### ClusterImagePolicyList

Source: https://github.com/sigstore/policy-controller/blob/main/docs/api-types/index.md

Represents a list of ClusterImagePolicy resources.

```APIDOC
## ClusterImagePolicyList

ClusterImagePolicyList is a list of ClusterImagePolicy resources

### Fields
* **metadata** ([metav1.ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#listmeta-v1-meta)) - Required - 
* **items** ([][ClusterImagePolicy](#clusterimagepolicy)) - Required - 
```

--------------------------------

### ClusterImagePolicy with warn mode

Source: https://context7.com/sigstore/policy-controller/llms.txt

Set `spec.mode: warn` to allow images that fail the policy but surface the failure as a Kubernetes admission warning rather than a hard rejection. Useful for rolling out new policies without breaking deployments.

```yaml
apiVersion: policy.sigstore.dev/v1alpha1
kind: ClusterImagePolicy
metadata:
  name: image-policy-warn-mode
spec:
  mode: warn                          # "enforce" (default) or "warn"
  images:
  - glob: "**demo**"
  authorities:
  - keyless:
      url: https://fulcio.sigstore.dev
      identities:
      - issuerRegExp: .*kubernetes.default.*
        subjectRegExp: .*kubernetes.io/namespaces/default/serviceaccounts/default
    ctlog:
      url: https://rekor.sigstore.dev

# Verification failure produces a Kubernetes admission Warning, not an Error.
# The pod is still admitted, but kubectl output shows:
# Warning: failed policy: image-policy-warn-mode ...
```

--------------------------------

### ClusterImagePolicySpec

Source: https://github.com/sigstore/policy-controller/blob/main/docs/api-types/index.md

ClusterImagePolicySpec defines a list of images that should be verified.

```APIDOC
## ClusterImagePolicySpec

ClusterImagePolicySpec defines a list of images that should be verified

| Field | Description | Scheme | Required |
| ----- | ----------- | ------ | -------- |
| images | Images defines the patterns of image names that should be subject to this policy. | [][ImagePattern](#imagepattern) | true |
| authorities | Authorities defines the rules for discovering and validating signatures. | [][Authority](#authority) | false |
| policy | Policy is an optional policy that can be applied against all the successfully validated Authorities. If no authorities pass, this does not even get evaluated, as the Policy is considered failed. | [Policy](#policy) | false |
| mode | Mode controls whether a failing policy will be rejected (not admitted), or if errors are converted to Warnings. enforce - Reject (default) warn - allow but warn | string | false |
| match | Match allows selecting resources based on their properties. | [][MatchResource](#matchresource) | false |
```

--------------------------------

### Authority

Source: https://github.com/sigstore/policy-controller/blob/main/docs/api-types/index.md

Defines the rules for discovering and validating signatures. It supports various methods for signature verification, including keys, keyless instances, static policies, and CT logs.

```APIDOC
## Authority

The authorities block defines the rules for discovering and validating signatures. Signatures are cryptographically verified using one of the "key" or "keyless" fields. When multiple authorities are specified, any of them may be used to source the valid signature we are looking for to admit an image.

### Fields
* **name** (string) - Required - Name is the name for this authority. Used by the CIP Policy validator to be able to reference matching signature or attestation verifications. If not specified, the name will be authority-<index in array>.
* **key** ([KeyRef](#keyref)) - Optional - Key defines the type of key to validate the image.
* **keyless** ([KeylessRef](#keylessref)) - Optional - Keyless sets the configuration to verify the authority against a Fulcio instance.
* **static** ([StaticRef](#staticref)) - Optional - Static specifies that signatures / attestations are not validated but instead a static policy is applied against matching images.
* **source** ([][Source](#source)) - Optional - Sources sets the configuration to specify the sources from where to consume the signatures.
* **ctlog** ([TLog](#tlog)) - Optional - CTLog sets the configuration to verify the authority against a Rekor instance.
* **attestations** ([][Attestation](#attestation)) - Optional - Attestations is a list of individual attestations for this authority, once the signature for this authority has been verified.
* **rfc3161timestamp** ([RFC3161Timestamp](#rfc3161timestamp)) - Optional - RFC3161Timestamp sets the configuration to verify the signature timestamp against a RFC3161 time-stamping instance.
* **signatureFormat** (string) - Optional - SignatureFormat specifies the format the authority expects. Supported formats are "legacy" and "bundle". If not specified, the default is "legacy" (cosign's default).
```

--------------------------------

### policy.Validate

Source: https://context7.com/sigstore/policy-controller/llms.txt

The `policy.Validate` function parses and validates a YAML document containing `ClusterImagePolicy` or `TrustRoot` objects. It separates validation warnings (e.g., deprecated fields) from hard errors.

```APIDOC
## `policy.Validate` — Validate a CIP YAML document

### Description
The `policy.Validate` function parses and validates a YAML document containing `ClusterImagePolicy` or `TrustRoot` objects. It separates validation warnings (e.g., deprecated fields) from hard errors.

### Function Signature
`policy.Validate(ctx context.Context, document string) ([]string, error)`

### Parameters
- `ctx` (context.Context): The context for the operation.
- `document` (string): The YAML document content to validate.

### Returns
- `[]string`: A slice of strings containing validation warnings.
- `error`: An error if the policy document is invalid.

### Usage Example
```go
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/sigstore/policy-controller/pkg/policy"
)

func main() {
    ctx := context.Background()

    document := `
apiVersion: policy.sigstore.dev/v1beta1
kind: ClusterImagePolicy
metadata:
  name: my-policy
spec:
  images:
  - glob: "**"
  authorities:
  - keyless:
      url: https://fulcio.sigstore.dev
      identities:
      - issuer: https://token.actions.githubusercontent.com
        subject: "https://github.com/myorg/myrepo/.github/workflows/release.yml@refs/heads/main"
`
    warns, err := policy.Validate(ctx, document)
    if err != nil {
        log.Fatalf("policy is invalid: %v", err)
    }
    if warns != nil {
        fmt.Printf("policy has warnings: %v\n", warns)
    }
    fmt.Println("policy is valid")
    // Output: policy is valid
}
```
```

--------------------------------

### ClusterImagePolicy

Source: https://github.com/sigstore/policy-controller/blob/main/docs/api-types/index.md

Defines the images that go through verification and the authorities used for verification. It includes metadata, spec, and status fields.

```APIDOC
## ClusterImagePolicy

ClusterImagePolicy defines the images that go through verification and the authorities used for verification

### Fields
* **metadata** ([metav1.ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#objectmeta-v1-meta)) - Required - 
* **spec** ([ClusterImagePolicySpec](#clusterimagepolicyspec)) - Required - Spec holds the desired state of the ClusterImagePolicy (from the client).
* **status** ([ClusterImagePolicyStatus](#clusterimagepolicystatus)) - Optional - Status represents the current state of the ClusterImagePolicy. This data may be out of date.
```

--------------------------------

### ClusterImagePolicy: Key-based Signature Verification (Inline Public Key)

Source: https://context7.com/sigstore/policy-controller/llms.txt

Requires an image to be signed by a specific inline PEM-encoded public key. The hash algorithm defaults to sha256.

```yaml
# Inline public key alternative
apiVersion: policy.sigstore.dev/v1alpha1
kind: ClusterImagePolicy
metadata:
  name: image-signed-by-inline-key
spec:
  images:
  - glob: "registry.example.com/**"
  authorities:
  - name: inline-key
    key:
      data: |
        -----BEGIN PUBLIC KEY-----
        MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEOc6HkISHzVdUbtUsdjYtPuyPYBeg
        4FCemyVurIM4KEORQk4OAu8ZNwxvGSoY3eAabYaFIPPQ8ROAjrbdPwNdJw==
        -----END PUBLIC KEY-----
    ctlog:
      url: https://rekor.sigstore.dev
```