# divyal27/container-supply-chain-security-compliance architecture

> Architecture diagram of the GitHub repository divyal27/container-supply-chain-security-compliance, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/divyal27/container-supply-chain-security-compliance
- Repository: https://github.com/divyal27/container-supply-chain-security-compliance

## Overview

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: [`.github/workflows/build-and-sign.yml`](https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/.github/workflows/build-and-sign.yml) (Build flow), [`policies/kyverno/check-sbom-license.yaml`](https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/policies/kyverno/check-sbom-license.yaml) (Check SBOM), [`policies/kyverno/verify-signature.yaml`](https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/policies/kyverno/verify-signature.yaml) (Verify sig), [`docs/slsa-mapping.md`](https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/docs/slsa-mapping.md) (SLSA map)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_source_ci["Source + CI"]
  node_build_workflow["Build flow<br/>gha workflow<br/>[build-and-sign.yml]"]
  node_scan_workflow["Scan flow<br/>gha workflow<br/>[scan-scheduled.yml]"]
  node_build_script["Build script<br/>shell build<br/>[build.sh]"]
  node_sign_script["Sign attest<br/>shell supply-chain<br/>[sign-and-attest.sh]"]
  node_verify_script["Verify<br/>[verify.sh]"]
  node_vex_script["VEX gen<br/>shell exception<br/>[generate-vex.sh]"]
end

subgraph group_registry["Registry + Scan"]
  node_harbor[("Harbor<br/>oci registry")]
end

subgraph group_cluster["Cluster Runtime"]
  node_namespace["Namespace<br/>[namespace.yaml]"]
  node_kyverno{{"Kyverno<br/>admission gate"}}
end

subgraph group_policy["Policy Logic"]
  node_verify_sig["Verify sig<br/>kyverno policy"]
  node_require_prov["Require prov<br/>kyverno policy"]
  node_check_sbom["Check SBOM<br/>kyverno policy"]
  node_license_rego["License rules<br/>rego rules"]
  node_sbom_rego["SBOM rules<br/>rego rules"]
end

subgraph group_infra["Infrastructure"]
  node_harbor_tf["Harbor TF<br/>terraform infra<br/>[harbor.tf]"]
  node_harbor_values["Harbor config<br/>k8s values<br/>[harbor-values.yaml]"]
end

subgraph group_metadata["Supply-chain Metadata"]
  node_vex_doc["VEX<br/>[openvex.json]"]
  node_slsa_map["SLSA map<br/>compliance mapping<br/>[slsa-mapping.md]"]
end

subgraph group_app["Sample App"]
  node_app_src["App code<br/>python app<br/>[app.py]"]
  node_app_dockerfile["Dockerfile<br/>image build"]
end

node_app_src -->|"packaged by"| node_app_dockerfile
node_app_dockerfile -->|"built in"| node_build_workflow
node_build_script -.->|"mirrors"| node_build_workflow
node_build_workflow -->|"attest via"| node_sign_script
node_build_workflow -->|"emits"| node_vex_script
node_build_workflow -->|"pushes image to"| node_harbor
node_sign_script -->|"attaches"| node_harbor
node_scan_workflow -.->|"rescans"| node_harbor
node_harbor_tf -->|"provisions"| node_harbor
node_harbor_values -->|"configures"| node_harbor
node_namespace -->|"deploys into"| node_kyverno
node_harbor -->|"supplies image"| node_kyverno
node_kyverno -->|"enforces"| node_verify_sig
node_kyverno -->|"enforces"| node_require_prov
node_kyverno -->|"enforces"| node_check_sbom
node_check_sbom -->|"delegates to"| node_license_rego
node_check_sbom -->|"delegates to"| node_sbom_rego
node_vex_script -->|"produces"| node_vex_doc
node_vex_doc -.->|"context for"| node_check_sbom
node_slsa_map -.->|"supports"| node_require_prov
node_slsa_map -.->|"supports"| node_verify_sig
node_verify_script -.->|"checks"| node_verify_sig

click node_app_src "https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/app/src/app.py"
click node_app_dockerfile "https://github.com/divyal27/container-supply-chain-security-compliance/tree/main/app/Dockerfile"
click node_build_workflow "https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/.github/workflows/build-and-sign.yml"
click node_scan_workflow "https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/.github/workflows/scan-scheduled.yml"
click node_build_script "https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/scripts/build.sh"
click node_sign_script "https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/scripts/sign-and-attest.sh"
click node_verify_script "https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/scripts/verify.sh"
click node_vex_script "https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/scripts/generate-vex.sh"
click node_harbor_tf "https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/infra/terraform/harbor.tf"
click node_harbor_values "https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/infra/kubernetes/harbor/harbor-values.yaml"
click node_namespace "https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/infra/kubernetes/namespace.yaml"
click node_verify_sig "https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/policies/kyverno/verify-signature.yaml"
click node_require_prov "https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/policies/kyverno/require-provenance.yaml"
click node_check_sbom "https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/policies/kyverno/check-sbom-license.yaml"
click node_license_rego "https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/policies/opa/deny-banned-license.rego"
click node_sbom_rego "https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/policies/opa/sbom-validation.rego"
click node_vex_doc "https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/vex/openvex.json"
click node_slsa_map "https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/docs/slsa-mapping.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_build_workflow,node_scan_workflow,node_build_script,node_sign_script,node_verify_script,node_vex_script,node_app_src,node_app_dockerfile toneBlue
class node_harbor toneAmber
class node_namespace,node_kyverno toneMint
class node_verify_sig,node_require_prov,node_check_sbom,node_license_rego,node_sbom_rego toneRose
class node_harbor_tf,node_harbor_values toneIndigo
class node_vex_doc,node_slsa_map toneTeal
```

## Components

### Source + CI

Build and re-scan workflows in GitHub Actions plus local build/sign scripts.

- [Build flow](https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/.github/workflows/build-and-sign.yml): gha workflow · Primary CI path that builds, signs, and attests the image. · `.github/workflows/build-and-sign.yml`
- [Scan flow](https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/.github/workflows/scan-scheduled.yml): gha workflow · Scheduled workflow for periodic re-scanning and re-evaluation. · `.github/workflows/scan-scheduled.yml`
- [Build script](https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/scripts/build.sh): shell build · Local equivalent of the CI build step. · `scripts/build.sh`
- [Sign attest](https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/scripts/sign-and-attest.sh): shell supply-chain · Operational glue for Cosign signing and attaching attestations. · `scripts/sign-and-attest.sh`
- [Verify](https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/scripts/verify.sh): shell verify · Local or automated verification of signatures and attestations. · `scripts/verify.sh`
- [VEX gen](https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/scripts/generate-vex.sh): shell exception · Creates VEX documents from scan results. · `scripts/generate-vex.sh`

### Registry + Scan

OCI registry and its provisioning/configuration boundary.

- **Harbor**: oci registry · Registry and artifact storage, including automated scanning.

### Cluster Runtime

Kubernetes namespace and admission-time enforcement.

- [Namespace](https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/infra/kubernetes/namespace.yaml): k8s namespace · Target runtime namespace for deployment. · `infra/kubernetes/namespace.yaml`
- **Kyverno**: admission gate · Cluster admission controller that admits or rejects images.

### Policy Logic

Kyverno admission policies and OPA/Rego decision rules.

- [Verify sig](https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/policies/kyverno/verify-signature.yaml): kyverno policy · Admission policy that enforces signature verification. · `policies/kyverno/verify-signature.yaml`
- [Require prov](https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/policies/kyverno/require-provenance.yaml): kyverno policy · Admission policy that requires provenance evidence. · `policies/kyverno/require-provenance.yaml`
- [Check SBOM](https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/policies/kyverno/check-sbom-license.yaml): kyverno policy · Admission policy that checks SBOM and license conditions. · `policies/kyverno/check-sbom-license.yaml`
- [License rules](https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/policies/opa/deny-banned-license.rego): rego rules · OPA rules for banned-license decisions. · `policies/opa/deny-banned-license.rego`
- [SBOM rules](https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/policies/opa/sbom-validation.rego): rego rules · OPA rules for SBOM validation logic. · `policies/opa/sbom-validation.rego`

### Infrastructure

Terraform and cluster configuration for the environment.

- [Harbor TF](https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/infra/terraform/harbor.tf): terraform infra · Terraform provisioning for the registry environment. · `infra/terraform/harbor.tf`
- [Harbor config](https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/infra/kubernetes/harbor/harbor-values.yaml): k8s values · 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.

- [VEX](https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/vex/openvex.json): vex document · OpenVEX document describing exploitability exceptions. · `vex/openvex.json`
- [SLSA map](https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/docs/slsa-mapping.md): compliance mapping · Repository mapping to SLSA Level 3 expectations. · `docs/slsa-mapping.md`

### Sample App

Container payload built and shipped through the security pipeline.

- [App code](https://github.com/divyal27/container-supply-chain-security-compliance/blob/main/app/src/app.py): python app · Sample application source packaged into the container image. · `app/src/app.py`
- [Dockerfile](https://github.com/divyal27/container-supply-chain-security-compliance/tree/main/app/Dockerfile): image build · Container build definition for the sample workload. · `app/Dockerfile`

## Connections

- 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.