Container Image Security and Software Supply Chain Protection: A Practical Guide to Trivy, Cosign, SBOM, and Sigstore

# Install Trivy (macOS)
brew install trivy

# Install Trivy (Linux)
curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin

# Verify installation
trivy version

# Basic image scan - show all severity levels
trivy image nginx:1.25

# Filter only HIGH and CRITICAL, show only fixable vulnerabilities
trivy image --severity HIGH,CRITICAL --ignore-unfixed nginx:1.25

# Output results in JSON format (for CI/CD pipeline integration)
trivy image --format json --output results.json nginx:1.25

# Use a .trivyignore file to skip specific CVEs
trivy image --ignorefile .trivyignore myapp:latest

# SBOM-based scan (use an existing SBOM as input)
trivy sbom ./sbom.cyclonedx.json

# .trivyignore - Approved exception list
# Always document expiration date and reason

# CVE-2024-1234: Feature not used, grace period until 2026-04-01
CVE-2024-1234

# CVE-2024-5678: Waiting for upstream patch
CVE-2024-5678

# Install Cosign
brew install cosign

# 1. Generate key pair (traditional approach)
cosign generate-key-pair

# 2. Sign image (key-based)
cosign sign --key cosign.key myregistry.io/myapp:v1.0.0

# 3. Keyless signing (using Sigstore Fulcio - recommended)
# Automatically issues short-lived certificate after OIDC authentication
cosign sign myregistry.io/myapp:v1.0.0

# 4. Verify signature
cosign verify --key cosign.pub myregistry.io/myapp:v1.0.0

# 5. Keyless signature verification (specify certificate issuer and identity)
cosign verify \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp "https://github.com/myorg/myrepo" \
  myregistry.io/myapp:v1.0.0

# Include build metadata in signature
cosign sign \
  -a "git.sha=$(git rev-parse HEAD)" \
  -a "build.timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  -a "build.pipeline=github-actions" \
  myregistry.io/myapp:v1.0.0

# Verify signature with annotations
cosign verify --key cosign.pub myregistry.io/myapp:v1.0.0 | jq .

# Install Syft
curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin

# Generate SBOM in CycloneDX format (container image)
syft myregistry.io/myapp:v1.0.0 -o cyclonedx-json=sbom-cyclonedx.json

# Generate SBOM in SPDX format
syft myregistry.io/myapp:v1.0.0 -o spdx-json=sbom-spdx.json

# Generate SBOM from local directory
syft dir:./my-project -o cyclonedx-json=sbom.json

# Trivy can also generate SBOMs
trivy image --format cyclonedx --output sbom-trivy.json myregistry.io/myapp:v1.0.0

# Attach SBOM to OCI registry (using Cosign)
cosign attach sbom --sbom sbom-cyclonedx.json myregistry.io/myapp:v1.0.0

# Compare runtime SBOM with build-time SBOM
# 1. Build-time SBOM (already generated)
# sbom-build.json

# 2. Extract current state from running container
docker exec running-container syft / -o cyclonedx-json > sbom-runtime.json

# 3. Compare differences
diff <(jq -r '.components[].name' sbom-build.json | sort) \
     <(jq -r '.components[].name' sbom-runtime.json | sort)

name: Container Security Pipeline

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: my-org/my-app

jobs:
  build-scan-sign:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
      id-token: write # Required for keyless signing

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Log in to GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and Push
        id: build
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ghcr.io/my-org/my-app:${{ github.sha }}

      # Step 1: Vulnerability Scan
      - name: Trivy Vulnerability Scan
        uses: aquasecurity/trivy-action@master
        with:
          image-ref: ghcr.io/my-org/my-app:${{ github.sha }}
          format: sarif
          output: trivy-results.sarif
          severity: HIGH,CRITICAL
          exit-code: '1'

      - name: Upload Trivy Results to GitHub Security
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: trivy-results.sarif

      # Step 2: Generate SBOM
      - name: Generate SBOM with Syft
        uses: anchore/sbom-action@v0
        with:
          image: ghcr.io/my-org/my-app:${{ github.sha }}
          format: cyclonedx-json
          output-file: sbom.cyclonedx.json

      # Step 3: Sign Image with Cosign (Keyless)
      - name: Install Cosign
        uses: sigstore/cosign-installer@v3

      - name: Sign Container Image
        run: |
          cosign sign --yes \
            -a "git.sha=${{ github.sha }}" \
            -a "build.pipeline=github-actions" \
            ghcr.io/my-org/my-app@${{ steps.build.outputs.digest }}

      # Step 4: Attach SBOM
      - name: Attach SBOM to Image
        run: |
          cosign attach sbom \
            --sbom sbom.cyclonedx.json \
            ghcr.io/my-org/my-app@${{ steps.build.outputs.digest }}

      # Step 5: Sign SBOM Attestation
      - name: Sign SBOM Attestation
        run: |
          cosign attest --yes \
            --predicate sbom.cyclonedx.json \
            --type cyclonedx \
            ghcr.io/my-org/my-app@${{ steps.build.outputs.digest }}

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: verify-image-signature
spec:
  validationFailureAction: Enforce
  background: false
  rules:
    - name: verify-cosign-signature
      match:
        any:
          - resources:
              kinds:
                - Pod
      verifyImages:
        - imageReferences:
            - 'ghcr.io/my-org/*'
          attestors:
            - entries:
                - keyless:
                    issuer: 'https://token.actions.githubusercontent.com'
                    subject: 'https://github.com/my-org/my-repo/.github/workflows/*'
                    rekor:
                      url: 'https://rekor.sigstore.dev'
          attestations:
            - type: 'https://cyclonedx.org/bom'
              conditions:
                - all:
                    - key: 'components'
                      operator: NotEquals
                      value: ''

apiVersion: templates.gatekeeper.sh/v1
kind: ConstraintTemplate
metadata:
  name: k8srequireimagedigest
spec:
  crd:
    spec:
      names:
        kind: K8sRequireImageDigest
  targets:
    - target: admission.k8s.gatekeeper.sh
      rego: |
        package k8srequireimagedigest

        violation[{"msg": msg}] {
          container := input.review.object.spec.containers[_]
          not contains(container.image, "@sha256:")
          msg := sprintf(
            "Container '%v' must use image digest (sha256) instead of tag: %v",
            [container.name, container.image]
          )
        }

        violation[{"msg": msg}] {
          container := input.review.object.spec.initContainers[_]
          not contains(container.image, "@sha256:")
          msg := sprintf(
            "Init container '%v' must use image digest (sha256) instead of tag: %v",
            [container.name, container.image]
          )
        }
---
apiVersion: constraints.gatekeeper.sh/v1beta1
kind: K8sRequireImageDigest
metadata:
  name: require-image-digest
spec:
  match:
    kinds:
      - apiGroups: ['']
        kinds: ['Pod']
    namespaces:
      - production

# Emergency isolation: apply NetworkPolicy
kubectl apply -f - <<EOF
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: emergency-isolate
  namespace: production
spec:
  podSelector:
    matchLabels:
      app: compromised-app
  policyTypes:
    - Ingress
    - Egress
EOF

# Emergency scan
trivy image --severity CRITICAL compromised-image:tag

# Search SBOMs for affected images
for sbom in sbom-*.json; do
  if jq -e '.components[] | select(.name == "libexpat")' "$sbom" > /dev/null 2>&1; then
    echo "AFFECTED: $sbom"
  fi
done

# Rebuild with patched base image
docker build --no-cache --build-arg BASE_IMAGE=nginx:1.25.4-alpine -t myapp:patched .

# Rolling update
kubectl set image deployment/myapp myapp=myregistry.io/myapp:patched
kubectl rollout status deployment/myapp

# SLSA Provenance generation workflow
name: SLSA Build Provenance

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      digest: ${{ steps.build.outputs.digest }}
    steps:
      - uses: actions/checkout@v4
      - name: Build Image
        id: build
        run: |
          docker build -t ghcr.io/my-org/my-app:${{ github.ref_name }} .
          DIGEST=$(docker inspect --format='{{index .RepoDigests 0}}' ghcr.io/my-org/my-app:${{ github.ref_name }} | cut -d@ -f2)
          echo "digest=$DIGEST" >> "$GITHUB_OUTPUT"

  provenance:
    needs: build
    permissions:
      actions: read
      id-token: write
      packages: write
    uses: slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@v2.1.0
    with:
      image: ghcr.io/my-org/my-app
      digest: ${{ needs.build.outputs.digest }}
    secrets:
      registry-username: ${{ github.actor }}
      registry-password: ${{ secrets.GITHUB_TOKEN }}