Appendix: Instructor Notes — Registry Signing + Admission Verification (Kyverno)

What students will do (6 steps)

  1. Start/choose a registry
  2. Build → promote → push image
  3. Sign the pushed image with cosign
  4. Install Kyverno and apply a verifyImages policy (using your cosign.pub)
  5. Prove enforcement (unsigned image rejected)
  6. Deploy signed image, collect evidence

Two variables to set (put these on a slide)

export IMAGE_REG=localhost:5000/                 # or your class registry, e.g., registry.class.tld:5000/
export VERIFY_IMAGE_PATTERN='"localhost:5000/ship-securely/*"'   # pattern Kyverno must enforce

If you’re using a shared registry, replace localhost:5000 with the class registry host and keep the trailing slash.

One-time prep (everyone)

cosign generate-key-pair            # creates cosign.key / cosign.pub
make kyverno-install                # installs Kyverno (Helm)

6-Command student runbook (copy/paste)

1) Start a local registry (skip if you provide a class registry)

make reg-up                         # starts localhost:5000 via docker compose

2) Build → promote → push to the registry

IMAGE_REG=$IMAGE_REG make build promote
docker push ${IMAGE_REG}ship-securely/app:good-$(date +%Y%m%d)-$(git rev-parse --short HEAD)

3) Sign the image in the registry (OCI signature)

IMAGE_REG=$IMAGE_REG make sign_image_registry
IMAGE_REG=$IMAGE_REG make verify_image_registry     # writes artifacts/cosign-image-verify.txt

4) Enforce at admission (Kyverno verifyImages with your public key)

VERIFY_IMAGE_PATTERN=$VERIFY_IMAGE_PATTERN make kyverno-apply-verify
# (this generates policies/verify-image-signatures.yaml from cosign.pub and applies all policies/)

5) Prove it blocks an unsigned image

# create/push an unsigned tag
docker tag ${IMAGE_REG}ship-securely/app:good-$(date +%Y%m%d)-$(git rev-parse --short HEAD) \
           ${IMAGE_REG}ship-securely/app:unsigned-$(date +%Y%m%d)-$(git rev-parse --short HEAD)
docker push ${IMAGE_REG}ship-securely/app:unsigned-$(date +%Y%m%d)-$(git rev-parse --short HEAD)

# try to deploy the unsigned tag (expect admission rejection)
kubectl -n ship set image deploy/app app=${IMAGE_REG}ship-securely/app:unsigned-$(date +%Y%m%d)-$(git rev-parse --short HEAD) || true
kubectl -n ship apply -f infra/k8s/deployment.yaml 2>&1 | tee artifacts/policy-tests.txt

6) Deploy the signed image + collect evidence

# point back to the signed GOOD tag
kubectl -n ship set image deploy/app app=${IMAGE_REG}ship-securely/app:good-$(date +%Y%m%d)-$(git rev-parse --short HEAD)

# optional: re-run ZAP and metrics, and zip the pack
make zap-k8s
make metrics
make evidence

Evidence students should see (already wired in Makefile)

  • artifacts/cosign-image-verify.txt — proof the registry signature verifies
  • policies/verify-image-signatures.yaml — the exact Kyverno verify policy used
  • artifacts/policy-tests.txt — admission rejection for the unsigned image
  • artifacts/sbom.json, artifacts/sbom-image.json, artifacts/sbom.bundle, artifacts/cosign-verify.txt
  • artifacts/trivy-image.json, artifacts/semgrep.sarif, artifacts/checkov.json, artifacts/hadolint.txt
  • (if run) artifacts/zap/report.html, artifacts/falco-last10m.log, metrics snapshot

Troubleshooting slide (quick hitters)

  • Policy didn’t enforce?

    • Confirm kyverno-admission-controller is Ready: kubectl -n kyverno get deploy/kyverno-admission-controller
    • Verify policy target pattern matches your registry: grep imageReferences policies/verify-image-signatures.yaml
    • Re-apply policies: make kyverno-apply

  • Verify fails (cosign verify …):

    • Ensure you pushed the GOOD tag to the registry before signing.
    • Make sure cosign.pub matches the key used to sign.

  • Students using Windows: run in Git Bash / WSL; ensure Docker Desktop is running.

Optional: Offline mode (no registry)

If someone can’t reach a registry, they can still produce cryptographic proof:

make cd                    # builds, scans, promotes, deploys locally
make sign_image            # signs the image digest as a blob (offline)
make verify_image          # writes artifacts/cosign-image-verify.txt (offline)
make evidence

This doesn’t enable admission enforcement (no registry signature present), but it’s valid for the evidence pack.

Instructor checklist (before class)

  • Choose and announce IMAGE_REG (e.g., registry.class.tld:5000/ or localhost:5000/)
  • Put VERIFY_IMAGE_PATTERN on a slide (e.g., "registry.class.tld:5000/ship-securely/*")
  • Validate Kyverno install on your Minikube: make kyverno-install && make kyverno-apply
  • Dry run the 6 commands end-to-end; confirm policy-tests.txt shows rejection text
  • Ensure students have Docker, Minikube, kubectl, helm, cosign available (your Part I installs)

Want me to generate a single “Student Handout” PDF page from this (markdown source) you can print or share?