How divyal27/container-supply-chain-security-compliance works
1. What this repo is
- This is not primarily an application repo; it is a container supply-chain security demo/reference architecture.
- The sample app in app/ is just the payload being built, signed, scanned, and deployed. The real product is the security pipeline around the image.
2. Main architectural boundary
- The system spans four distinct trust zones:
- Source + CI: GitHub Actions and local build scripts
- Registry + scanning: Harbor
- Cluster admission: Kubernetes + Kyverno
- Policy logic: Kyverno policies and OPA/Rego rules
- The diagram should show the image moving across these boundaries with cryptographic proof attached.
3. Build subsystem
- app/Dockerfile, app/src/, and app/requirements.txt define the containerized sample workload.
- .github/workflows/build-and-sign.yml is the main CI pipeline that builds the image in an ephemeral GitHub Actions runner.
- scripts/build.sh is the local equivalent of that build step.
4. Supply-chain metadata generation
- During build, the pipeline generates a SBOM with Syft and performs vulnerability/license inspection with Trivy.
- That metadata is not just output; it becomes part of the artifact chain through Cosign attestations.
- scripts/sign-and-attest.sh is the operational glue for signing and attaching attestations.
5. Identity, signing, and provenance
- The trust anchor is Sigstore keyless signing using GitHub OIDC.
- The repo explicitly relies on Fulcio for certificate issuance and Rekor for transparency-log verification.
- The important architecture concept is that the image is tied to:
- a repo identity,
- a build identity,
- and a specific commit/provenance record.
6. Registry and scanning layer
- The built image is pushed to Harbor as the OCI registry.
- Harbor is provisioned by infra/terraform/harbor.tf and configured with infra/kubernetes/harbor/harbor-values.yaml.
- Harbor is also the place where automated scanning and artifact storage happen, so it sits between CI and runtime deployment.
7. Cluster runtime and admission control
- infra/kubernetes/namespace.yaml defines the target deployment namespace(s).
- At deploy time, Kyverno acts as the admission gate: unsigned or noncompliant images are blocked before they run.
- The README’s example shows the intended behavior: signed images are admitted, unsigned public images are rejected.
8. Policy enforcement layer
- policies/kyverno/ contains the admission policies that enforce:
- signature verification,
- provenance requirements,
- SBOM/license checks.
- policies/opa/ contains the Rego rules that provide the license and SBOM decision logic used by the policy layer.
- This is the core “admit or deny” boundary in the architecture.
9. VEX and exception handling
- vex/openvex.json and vex/vex-template.json model Vulnerability Exploitability Exchange documents.
- scripts/generate-vex.sh creates VEX from scan results so known non-exploitable findings can be documented and later attached as attestations.
- This acts as a control to reduce false-positive noise without weakening the security gate.
10. Infrastructure provisioning
- infra/terraform/ is the infrastructure-as-code layer for standing up the registry and associated environment.
- The repo implies an AWS EKS-backed Kubernetes environment from the README, while the actual repo files focus on Harbor and cluster configuration rather than the full cluster bootstrap.
- Diagram-wise, treat Terraform as the environment provisioning plane, separate from the CI and admission planes.
11. Operational scripts
- scripts/setup-harbor.sh configures registry-side settings after Terraform brings infrastructure up.
- scripts/verify.sh is the validation path for checking signatures/attestations locally or in automation.
- scripts/sign-and-attest.sh and scripts/generate-vex.sh are the manual/automation entry points for producing trusted metadata artifacts.
12. Scheduled security re-scan
- .github/workflows/scan-scheduled.yml indicates a second CI path beyond build-and-sign.
- This is the periodic “re-evaluate what we already shipped” workflow, useful for rescanning images against new CVEs and updating VEX or policy state.
13. Docs as architecture contracts
- docs/architecture.md and docs/slsa-mapping.md describe the intended security model and its SLSA Level 3 alignment.
- policies/slsa/ holds the formal compliance mapping, so the repository is also encoding governance requirements, not just implementation.
14. End-to-end flow to show in a diagram
- Source code is built into an image in GitHub Actions.
- SBOM, vulnerability, and provenance metadata are generated.
- The image and attestations are signed with Cosign using Sigstore identity.
- The result is pushed to Harbor.
- Kubernetes admission via Kyverno verifies signature, provenance, and license/SBOM policy before allowing the pod to run.
Main entry points: build-and-sign.yml Build flow · check-sbom-license.yaml Check SBOM · verify-signature.yaml Verify sig · slsa-mapping.md SLSA map
Components 20
Source + CI
Build and re-scan workflows in GitHub Actions plus local build/sign scripts.
- Build flow · Primary CI path that builds, signs, and attests the image.
.github/workflows/build-and-sign.yml - Scan flow · Scheduled workflow for periodic re-scanning and re-evaluation.
.github/workflows/scan-scheduled.yml - Build script · Local equivalent of the CI build step.
scripts/build.sh - Sign attest · Operational glue for Cosign signing and attaching attestations.
scripts/sign-and-attest.sh - Verify · Local or automated verification of signatures and attestations.
scripts/verify.sh - VEX gen · Creates VEX documents from scan results.
scripts/generate-vex.sh
Registry + Scan
OCI registry and its provisioning/configuration boundary.
- Harbor · Registry and artifact storage, including automated scanning.
Cluster Runtime
Kubernetes namespace and admission-time enforcement.
- Namespace · Target runtime namespace for deployment.
infra/kubernetes/namespace.yaml - Kyverno · Cluster admission controller that admits or rejects images.
Policy Logic
Kyverno admission policies and OPA/Rego decision rules.
- Verify sig · Admission policy that enforces signature verification.
policies/kyverno/verify-signature.yaml - Require prov · Admission policy that requires provenance evidence.
policies/kyverno/require-provenance.yaml - Check SBOM · Admission policy that checks SBOM and license conditions.
policies/kyverno/check-sbom-license.yaml - License rules · OPA rules for banned-license decisions.
policies/opa/deny-banned-license.rego - SBOM rules · OPA rules for SBOM validation logic.
policies/opa/sbom-validation.rego
Infrastructure
Terraform and cluster configuration for the environment.
- Harbor TF · Terraform provisioning for the registry environment.
infra/terraform/harbor.tf - Harbor config · Harbor configuration values for the registry deployment.
infra/kubernetes/harbor/harbor-values.yaml
Supply-chain Metadata
VEX, SLSA, and documentation for provenance and exception handling.
Sample App
Container payload built and shipped through the security pipeline.
- App code · Sample application source packaged into the container image.
app/src/app.py - Dockerfile · Container build definition for the sample workload.
app/Dockerfile
Connections 22
- App code → Dockerfile: packaged by · Source code is assembled into the container image.
- Dockerfile → Build flow: built in · GitHub Actions builds the image from the Dockerfile.
- Build script → Build flow: mirrors · Local script mirrors the CI build behavior.
- Build flow → Sign attest: attest via · Build outputs are signed and attested.
- Build flow → VEX gen: emits · Scan findings can be turned into VEX documents.
- Build flow → Harbor: pushes image to · The trusted image artifact is published to the registry.
- Sign attest → Harbor: attaches · Cosign signatures and attestations accompany the image in the registry.
- Scan flow → Harbor: rescans · Scheduled workflow re-evaluates previously shipped images.
- Harbor TF → Harbor: provisions · Terraform stands up the registry environment.
- Harbor config → Harbor: configures · Kubernetes values define Harbor runtime settings.
- Namespace → Kyverno: deploys into · Workloads are admitted into the target namespace.
- Harbor → Kyverno: supplies image · Admission evaluates images pulled from the registry.
- Kyverno → Verify sig: enforces · Kyverno uses signature verification policy at admission.
- Kyverno → Require prov: enforces · Kyverno requires provenance before allowing execution.
- Kyverno → Check SBOM: enforces · Kyverno checks SBOM and license conditions.
- Check SBOM → License rules: delegates to · License decisions are driven by Rego rules.
- Check SBOM → SBOM rules: delegates to · SBOM validation uses Rego rules.
- VEX gen → VEX: produces · Scan exceptions are captured as VEX documents.
- VEX → Check SBOM: context for · VEX can contextualize policy decisions for findings.
- SLSA map → Require prov: supports · SLSA mapping documents the provenance requirement.
- SLSA map → Verify sig: supports · SLSA mapping documents signature verification expectations.
- Verify → Verify sig: checks · Local verification follows the same trust rules.