From 983321b519b4b1b4ce1c1a779a6ddd454253ede3 Mon Sep 17 00:00:00 2001 From: Toddy Mladenov Date: Wed, 1 Jul 2026 20:08:13 -0700 Subject: [PATCH] Docs: restructure architecture and guides around CSSC stages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reorganize docs/architecture/ and docs/guides/ around the five CSSC framework stages (Acquire, Catalog, Build, Deploy, Run). Within each stage, documents are grouped under two cross-cutting themes where they apply — Authenticity and Integrity, and Supply Chain Observability — as index subsections (stages stay the primary structure). docs/reference/ and docs/contributing/ remain cross-cutting top-level areas. Moves: - architecture/workflows/image-mirror-workflows.md -> architecture/acquire/ - architecture/workflows/promote-from-quarantine{,-override-approval}.md -> catalog/ - architecture/workflows/build-workflows.md -> architecture/build/ - architecture/workflows/ci-failure-notifications.md -> architecture/cross-cutting/ - architecture/apps/cssc-dashboard.md -> architecture/run/ - guides/mirroring-base-images.md -> guides/acquire/ - guides/configuring-override-approval.md -> guides/catalog/ - guides/{image-tagging,reading-image-annotations,verifying-image-attestations}.md -> guides/build/ Add per-stage index READMEs (architecture + guides) with theme subsections; rewrite the top docs/architecture, docs/guides, and docs README indexes around the stages. Update every internal cross-link plus external references (workflow comments, the build documentation annotation, and the app READMEs) to the new paths. Verified no dead links. Closes #127 --- .../actions/manage-failure-issue/action.yml | 2 +- .../_promote-from-quarantine-sbom.yml | 2 +- .../workflows/_promote-from-quarantine.yml | 2 +- .github/workflows/_promote-override.yml | 2 +- .github/workflows/build-cssc-dashboard.yml | 2 +- .github/workflows/promote-override.yml | 2 +- .github/workflows/report-ci-failure.yml | 2 +- apps/python-app/README.md | 2 +- apps/python-app/libs/cssc_common/README.md | 2 +- .../services/dashboard-web/README.md | 2 +- .../services/issues-service/README.md | 2 +- .../services/packages-service/README.md | 2 +- docs/README.md | 43 +++++++++++-------- docs/architecture/README.md | 33 ++++++++------ docs/architecture/acquire/README.md | 10 +++++ .../image-mirror-workflows.md | 0 docs/architecture/apps/README.md | 10 ----- docs/architecture/build/README.md | 14 ++++++ .../{workflows => build}/build-workflows.md | 2 +- docs/architecture/catalog/README.md | 15 +++++++ ...omote-from-quarantine-override-approval.md | 0 .../promote-from-quarantine-workflows.md | 4 +- docs/architecture/cross-cutting/README.md | 9 ++++ .../ci-failure-notifications.md | 4 +- docs/architecture/deploy/README.md | 7 +++ docs/architecture/run/README.md | 9 ++++ .../{apps => run}/cssc-dashboard.md | 0 docs/architecture/workflows/README.md | 31 ------------- docs/contributing/workflow-naming.md | 4 +- docs/guides/README.md | 27 +++++------- docs/guides/acquire/README.md | 9 ++++ .../{ => acquire}/mirroring-base-images.md | 16 +++---- docs/guides/build/README.md | 18 ++++++++ docs/guides/{ => build}/image-tagging.md | 8 ++-- .../{ => build}/reading-image-annotations.md | 6 +-- .../verifying-image-attestations.md | 8 ++-- docs/guides/catalog/README.md | 9 ++++ .../configuring-override-approval.md | 8 ++-- docs/guides/deploy/README.md | 5 +++ docs/guides/run/README.md | 5 +++ docs/reference/image-annotations.md | 2 +- docs/reference/workflow-actions.md | 2 +- 42 files changed, 212 insertions(+), 130 deletions(-) create mode 100644 docs/architecture/acquire/README.md rename docs/architecture/{workflows => acquire}/image-mirror-workflows.md (100%) delete mode 100644 docs/architecture/apps/README.md create mode 100644 docs/architecture/build/README.md rename docs/architecture/{workflows => build}/build-workflows.md (99%) create mode 100644 docs/architecture/catalog/README.md rename docs/architecture/{workflows => catalog}/promote-from-quarantine-override-approval.md (100%) rename docs/architecture/{workflows => catalog}/promote-from-quarantine-workflows.md (99%) create mode 100644 docs/architecture/cross-cutting/README.md rename docs/architecture/{workflows => cross-cutting}/ci-failure-notifications.md (98%) create mode 100644 docs/architecture/deploy/README.md create mode 100644 docs/architecture/run/README.md rename docs/architecture/{apps => run}/cssc-dashboard.md (100%) delete mode 100644 docs/architecture/workflows/README.md create mode 100644 docs/guides/acquire/README.md rename docs/guides/{ => acquire}/mirroring-base-images.md (91%) create mode 100644 docs/guides/build/README.md rename docs/guides/{ => build}/image-tagging.md (91%) rename docs/guides/{ => build}/reading-image-annotations.md (97%) rename docs/guides/{ => build}/verifying-image-attestations.md (97%) create mode 100644 docs/guides/catalog/README.md rename docs/guides/{ => catalog}/configuring-override-approval.md (96%) create mode 100644 docs/guides/deploy/README.md create mode 100644 docs/guides/run/README.md diff --git a/.github/actions/manage-failure-issue/action.yml b/.github/actions/manage-failure-issue/action.yml index 22acea1..99a8254 100644 --- a/.github/actions/manage-failure-issue/action.yml +++ b/.github/actions/manage-failure-issue/action.yml @@ -16,7 +16,7 @@ # This is intentionally separate from `manage-issue` (which is specific to the # promotion override flow: a different title, label set, and a required embedded # metadata block). See -# docs/architecture/workflows/ci-failure-notifications.md. +# docs/architecture/cross-cutting/ci-failure-notifications.md. # # Terminology: see docs/reference/workflow-actions.md. name: manage-failure-issue diff --git a/.github/workflows/_promote-from-quarantine-sbom.yml b/.github/workflows/_promote-from-quarantine-sbom.yml index 466c799..c459c81 100644 --- a/.github/workflows/_promote-from-quarantine-sbom.yml +++ b/.github/workflows/_promote-from-quarantine-sbom.yml @@ -18,7 +18,7 @@ # aggregates the per-tag results. # # Terminology and the action catalogue: see docs/reference/workflow-actions.md. -# See also docs/architecture/workflows/promote-from-quarantine-workflows.md. +# See also docs/architecture/catalog/promote-from-quarantine-workflows.md. name: _reusable / promote-from-quarantine-sbom on: diff --git a/.github/workflows/_promote-from-quarantine.yml b/.github/workflows/_promote-from-quarantine.yml index f6ebc0f..f77243d 100644 --- a/.github/workflows/_promote-from-quarantine.yml +++ b/.github/workflows/_promote-from-quarantine.yml @@ -19,7 +19,7 @@ # 5. deletes the promoted tag from quarantine (delete-image). # # Terminology and the action catalogue: see docs/reference/workflow-actions.md. -# See also docs/architecture/workflows/promote-from-quarantine-workflows.md. +# See also docs/architecture/catalog/promote-from-quarantine-workflows.md. name: _reusable / promote-from-quarantine on: diff --git a/.github/workflows/_promote-override.yml b/.github/workflows/_promote-override.yml index 3e18230..4cb030c 100644 --- a/.github/workflows/_promote-override.yml +++ b/.github/workflows/_promote-override.yml @@ -14,7 +14,7 @@ # 4. deny: manage-issue close (promotion-denied) -> notify-slack (denied). # # Terminology and the action catalogue: see docs/reference/workflow-actions.md. -# See also docs/architecture/workflows/promote-from-quarantine-override-approval.md. +# See also docs/architecture/catalog/promote-from-quarantine-override-approval.md. name: _reusable / promote-override on: diff --git a/.github/workflows/build-cssc-dashboard.yml b/.github/workflows/build-cssc-dashboard.yml index 50ae910..e5a6167 100644 --- a/.github/workflows/build-cssc-dashboard.yml +++ b/.github/workflows/build-cssc-dashboard.yml @@ -153,7 +153,7 @@ jobs: "org.opencontainers.image.title=CSSC Dashboard ${SERVICE}" "org.opencontainers.image.description=${desc}" "org.opencontainers.image.url=${SERVER_URL}/${REPO}" - "org.opencontainers.image.documentation=${SERVER_URL}/${REPO}/blob/main/docs/architecture/apps/cssc-dashboard.md" + "org.opencontainers.image.documentation=${SERVER_URL}/${REPO}/blob/main/docs/architecture/run/cssc-dashboard.md" "org.opencontainers.image.vendor=toddysm.com" "org.opencontainers.image.licenses=Apache-2.0" "org.opencontainers.image.base.name=${base_name}" diff --git a/.github/workflows/promote-override.yml b/.github/workflows/promote-override.yml index 1c09a27..794ce37 100644 --- a/.github/workflows/promote-override.yml +++ b/.github/workflows/promote-override.yml @@ -10,7 +10,7 @@ # the override itself is still gated by `verify-approver` inside the reusable # workflow. # -# See docs/architecture/workflows/promote-from-quarantine-override-approval.md. +# See docs/architecture/catalog/promote-from-quarantine-override-approval.md. name: promote override on: diff --git a/.github/workflows/report-ci-failure.yml b/.github/workflows/report-ci-failure.yml index 27d1620..b509691 100644 --- a/.github/workflows/report-ci-failure.yml +++ b/.github/workflows/report-ci-failure.yml @@ -13,7 +13,7 @@ # # Note: runs that fail at startup (startup_failure) may not emit `workflow_run` # and can therefore be missed; see -# docs/architecture/workflows/ci-failure-notifications.md. +# docs/architecture/cross-cutting/ci-failure-notifications.md. name: report / ci-failure on: diff --git a/apps/python-app/README.md b/apps/python-app/README.md index 89ecd76..c38291c 100644 --- a/apps/python-app/README.md +++ b/apps/python-app/README.md @@ -6,7 +6,7 @@ A scalable, Kubernetes-native demonstration app that visualizes the Container Registry (GHCR) packages and promotion tracking issues. See the full design in -[docs/architecture/apps/cssc-dashboard.md](../../docs/architecture/apps/cssc-dashboard.md). +[docs/architecture/run/cssc-dashboard.md](../../docs/architecture/run/cssc-dashboard.md). > Read-only demo. The dashboard never mutates packages or issues. diff --git a/apps/python-app/libs/cssc_common/README.md b/apps/python-app/libs/cssc_common/README.md index fef195c..2dbb46b 100644 --- a/apps/python-app/libs/cssc_common/README.md +++ b/apps/python-app/libs/cssc_common/README.md @@ -1,7 +1,7 @@ # cssc_common Shared building blocks for the CSSC Dashboard microservices. See the -[CSSC Dashboard design](../../../../docs/architecture/apps/cssc-dashboard.md). +[CSSC Dashboard design](../../../../docs/architecture/run/cssc-dashboard.md). ## What's here diff --git a/apps/python-app/services/dashboard-web/README.md b/apps/python-app/services/dashboard-web/README.md index f2c177d..77b7b81 100644 --- a/apps/python-app/services/dashboard-web/README.md +++ b/apps/python-app/services/dashboard-web/README.md @@ -4,7 +4,7 @@ CSSC Dashboard web tier: the stage registry, the Acquisition stage provider, and the Jinja2/htmx UI. It is a backend-for-frontend that aggregates the `packages-service` and `issues-service` capability services — it never calls GitHub directly. See the -[CSSC Dashboard design](../../../../docs/architecture/apps/cssc-dashboard.md). +[CSSC Dashboard design](../../../../docs/architecture/run/cssc-dashboard.md). ## Routes diff --git a/apps/python-app/services/issues-service/README.md b/apps/python-app/services/issues-service/README.md index 1639f47..fb975df 100644 --- a/apps/python-app/services/issues-service/README.md +++ b/apps/python-app/services/issues-service/README.md @@ -2,7 +2,7 @@ CSSC Dashboard capability service that reads promotion tracking issues and parses the `blocking_cves` recorded in their `cssc-metadata` block. See the -[CSSC Dashboard design](../../../../docs/architecture/apps/cssc-dashboard.md). +[CSSC Dashboard design](../../../../docs/architecture/run/cssc-dashboard.md). ## API diff --git a/apps/python-app/services/packages-service/README.md b/apps/python-app/services/packages-service/README.md index 2dc25e7..ed64637 100644 --- a/apps/python-app/services/packages-service/README.md +++ b/apps/python-app/services/packages-service/README.md @@ -2,7 +2,7 @@ CSSC Dashboard capability service that lists GHCR container packages and their tags via the GitHub Packages API. See the -[CSSC Dashboard design](../../../../docs/architecture/apps/cssc-dashboard.md). +[CSSC Dashboard design](../../../../docs/architecture/run/cssc-dashboard.md). ## API diff --git a/docs/README.md b/docs/README.md index 3959af2..f5c3f80 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,32 +1,41 @@ # Documentation -Documentation for the `cssc-framework` repository. Content is organized by -topic so each area can grow independently. +Documentation for the `cssc-framework` repository. The **architecture** and +**guides** are organized around the **CSSC framework stages** — Acquire, +Catalog, Build, Deploy, and Run — and, within each stage, grouped under two +cross-cutting themes where they apply: **Authenticity and Integrity** and +**Supply Chain Observability**. Reference material and contributing conventions +are kept as cross-cutting areas. ## Structure | Folder | Purpose | | ------ | ------- | -| [`contributing/`](contributing/) | Guides and conventions for people contributing to this repository. | -| [`architecture/`](architecture/) | Design and architecture documentation. | -| [`guides/`](guides/) | How-to and operational guides. | -| [`reference/`](reference/) | Reference material and conventions. | +| [`architecture/`](architecture/) | Design and architecture docs, organized by stage. | +| [`guides/`](guides/) | How-to and operational guides, organized by stage. | +| [`reference/`](reference/) | Reference material and conventions (cross-cutting). | +| [`contributing/`](contributing/) | Conventions for contributing to this repository. | -## Guides +## Stages -- [Mirroring base images from Docker Hub to GHCR](guides/mirroring-base-images.md) - — how the mirror actions work and how to add a new mirror for another image or - tag. +| Stage | Architecture | Guides | +| ----- | ------------ | ------ | +| **Acquire** | [architecture/acquire/](architecture/acquire/) | [guides/acquire/](guides/acquire/) | +| **Catalog** | [architecture/catalog/](architecture/catalog/) | [guides/catalog/](guides/catalog/) | +| **Build** | [architecture/build/](architecture/build/) | [guides/build/](guides/build/) | +| **Deploy** | [architecture/deploy/](architecture/deploy/) | [guides/deploy/](guides/deploy/) | +| **Run** | [architecture/run/](architecture/run/) | [guides/run/](guides/run/) | -## Architecture docs +Design docs that span stages live under +[architecture/cross-cutting/](architecture/cross-cutting/). -- [Image mirror workflows](architecture/workflows/image-mirror-workflows.md) — - how the Docker Hub → GHCR mirroring GitHub Actions are structured, the tooling - they use, and what they do and do not do. -- [CSSC Dashboard application](architecture/apps/cssc-dashboard.md) — a - microservices web app that visualizes the CSSC framework stage by stage. +## Reference -## Contributing docs +- [Workflow actions and terminology](reference/workflow-actions.md) +- [Image annotations](reference/image-annotations.md) +- [Image attestations](reference/image-attestations.md) + +## Contributing - [Workflow naming conventions](contributing/workflow-naming.md) — how GitHub Actions workflows are named and organized in this repository. diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 250b7d6..059788a 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -1,14 +1,23 @@ # Architecture -Design and architecture documentation for the `cssc-framework` repository. - -## Topics - -- [Workflow architecture](workflows/) — GitHub Actions workflows. - - [Image mirror workflows](workflows/image-mirror-workflows.md) — mirroring - upstream base images from Docker Hub into GHCR. - - [Build workflows](workflows/build-workflows.md) — building the demo apps into - versioned, multi-arch images with supply-chain metadata. -- [Application architecture](apps/) — sample applications. - - [CSSC Dashboard](apps/cssc-dashboard.md) — microservices web app that - visualizes the CSSC framework stage by stage. +Design and architecture documentation for the `cssc-framework` repository, +organized around the **CSSC framework stages**. Within each stage, documents are +grouped under two cross-cutting themes where they apply: **Authenticity and +Integrity** and **Supply Chain Observability**. + +## Stages + +- [Acquire](acquire/) — mirroring upstream base images into a controlled + namespace. +- [Catalog](catalog/) — scanning quarantined images and promoting the ones that + pass a vulnerability policy into `golden/*`. +- [Build](build/) — building the demo apps into versioned, multi-arch images + with supply-chain metadata. +- [Deploy](deploy/) — deploying the demo apps (currently the Helm charts under + `apps/*/deploy`). +- [Run](run/) — the running applications, including the CSSC Dashboard. + +## Cross-cutting + +- [Cross-cutting](cross-cutting/) — design docs that span stages, such as + CI-failure notifications. diff --git a/docs/architecture/acquire/README.md b/docs/architecture/acquire/README.md new file mode 100644 index 0000000..8e18f52 --- /dev/null +++ b/docs/architecture/acquire/README.md @@ -0,0 +1,10 @@ +# Acquire — architecture + +Design docs for the **Acquire** stage: bringing upstream artifacts into a +controlled namespace before they are used. + +## Authenticity and Integrity + +- [Image mirror workflows](image-mirror-workflows.md) — how the Docker Hub → + GHCR mirroring actions are structured, the tooling they use, and what they do + and deliberately do not do. diff --git a/docs/architecture/workflows/image-mirror-workflows.md b/docs/architecture/acquire/image-mirror-workflows.md similarity index 100% rename from docs/architecture/workflows/image-mirror-workflows.md rename to docs/architecture/acquire/image-mirror-workflows.md diff --git a/docs/architecture/apps/README.md b/docs/architecture/apps/README.md deleted file mode 100644 index b7e2a70..0000000 --- a/docs/architecture/apps/README.md +++ /dev/null @@ -1,10 +0,0 @@ -# Application architecture - -Design and architecture documentation for the sample applications in this -repository. - -## Topics - -- [CSSC Dashboard](cssc-dashboard.md) — a microservices web application that - visualizes the CSSC framework stage by stage, starting with the Acquisition - stage, sourcing data from GHCR packages and promotion tracking issues. diff --git a/docs/architecture/build/README.md b/docs/architecture/build/README.md new file mode 100644 index 0000000..90a1961 --- /dev/null +++ b/docs/architecture/build/README.md @@ -0,0 +1,14 @@ +# Build — architecture + +Design docs for the **Build** stage: building the demo apps on trusted bases and +attaching portable supply-chain metadata. + +## Authenticity and Integrity + +- [Build workflows](build-workflows.md) — how the demo applications are built + into multi-arch OCI images, tagged with the semantic-version set, pinned to a + digest-addressed base, and stamped with annotations, SBOM, and provenance. + (The SBOM, provenance, and annotations also serve **Supply Chain + Observability** — see the reference docs + [image annotations](../../reference/image-annotations.md) and + [image attestations](../../reference/image-attestations.md).) diff --git a/docs/architecture/workflows/build-workflows.md b/docs/architecture/build/build-workflows.md similarity index 99% rename from docs/architecture/workflows/build-workflows.md rename to docs/architecture/build/build-workflows.md index 3ab1a3d..8fa0efe 100644 --- a/docs/architecture/workflows/build-workflows.md +++ b/docs/architecture/build/build-workflows.md @@ -186,5 +186,5 @@ dependency resolution (for example `pip`). - [`build / cssc-dashboard` workflow](../../../.github/workflows/build-cssc-dashboard.yml) - [Image annotations (reference)](../../reference/image-annotations.md) - [Image attestations (reference)](../../reference/image-attestations.md) -- [CSSC Dashboard application architecture](../apps/cssc-dashboard.md) +- [CSSC Dashboard application architecture](../run/cssc-dashboard.md) - [Workflow naming conventions](../../contributing/workflow-naming.md) diff --git a/docs/architecture/catalog/README.md b/docs/architecture/catalog/README.md new file mode 100644 index 0000000..6b39023 --- /dev/null +++ b/docs/architecture/catalog/README.md @@ -0,0 +1,15 @@ +# Catalog — architecture + +Design docs for the **Catalog** stage: scanning quarantined images, gating them +on a vulnerability policy, and promoting the ones that pass into `golden/*`. + +## Authenticity and Integrity + +- [Promote-from-quarantine workflows](promote-from-quarantine-workflows.md) — + how quarantined images are scanned with Trivy, gated on a severity threshold + plus CVE exceptions, promoted with a scan-report referrer, and removed from + quarantine. (The scan-report referrer also serves **Supply Chain + Observability**.) +- [Promotion override approval](promote-from-quarantine-override-approval.md) — + the human-in-the-loop approve/deny path for promoting an image that a policy + would otherwise block. diff --git a/docs/architecture/workflows/promote-from-quarantine-override-approval.md b/docs/architecture/catalog/promote-from-quarantine-override-approval.md similarity index 100% rename from docs/architecture/workflows/promote-from-quarantine-override-approval.md rename to docs/architecture/catalog/promote-from-quarantine-override-approval.md diff --git a/docs/architecture/workflows/promote-from-quarantine-workflows.md b/docs/architecture/catalog/promote-from-quarantine-workflows.md similarity index 99% rename from docs/architecture/workflows/promote-from-quarantine-workflows.md rename to docs/architecture/catalog/promote-from-quarantine-workflows.md index 365678f..63b0806 100644 --- a/docs/architecture/workflows/promote-from-quarantine-workflows.md +++ b/docs/architecture/catalog/promote-from-quarantine-workflows.md @@ -12,7 +12,7 @@ scan the container images sitting in a `quarantine/` repository and For naming and file-system conventions, see [workflow naming conventions](../../contributing/workflow-naming.md). For the mirror workflows that populate quarantine in the first place, see -[image mirror workflows](image-mirror-workflows.md). +[image mirror workflows](../acquire/image-mirror-workflows.md). ## Purpose @@ -182,7 +182,7 @@ Distroless images such as [Docker Hardened Images](https://docs.docker.com/dhi/) packages. Those images instead carry their package inventory as an **SBOM attestation** — an in-toto statement attached to each platform manifest as an OCI referrer. The mirror copies these referrers into quarantine (see -[`copy_referrers`](image-mirror-workflows.md)), and a dedicated reusable +[`copy_referrers`](../acquire/image-mirror-workflows.md)), and a dedicated reusable workflow, `_promote-from-quarantine-sbom.yml`, gates on the SBOM rather than the image filesystem. diff --git a/docs/architecture/cross-cutting/README.md b/docs/architecture/cross-cutting/README.md new file mode 100644 index 0000000..bd91392 --- /dev/null +++ b/docs/architecture/cross-cutting/README.md @@ -0,0 +1,9 @@ +# Cross-cutting — architecture + +Design docs that span multiple stages rather than belonging to a single one. + +## Supply Chain Observability + +- [CI failure notifications](ci-failure-notifications.md) — how a `workflow_run` + monitor opens and closes per-workflow CI-failure tracking issues (and optional + Slack alerts) across all monitored workflows when a run fails or recovers. diff --git a/docs/architecture/workflows/ci-failure-notifications.md b/docs/architecture/cross-cutting/ci-failure-notifications.md similarity index 98% rename from docs/architecture/workflows/ci-failure-notifications.md rename to docs/architecture/cross-cutting/ci-failure-notifications.md index 6a4f196..7fa2c64 100644 --- a/docs/architecture/workflows/ci-failure-notifications.md +++ b/docs/architecture/cross-cutting/ci-failure-notifications.md @@ -27,7 +27,7 @@ issue** — opened by the `notify` job of the promote-from-quarantine reusable workflows ([`_promote-from-quarantine.yml`](../../../.github/workflows/_promote-from-quarantine.yml) and [`_promote-from-quarantine-sbom.yml`](../../../.github/workflows/_promote-from-quarantine-sbom.yml)) when an image is *policy-blocked* (and only with `enable_approval`). See the -[override-approval design](promote-from-quarantine-override-approval.md). +[override-approval design](../catalog/promote-from-quarantine-override-approval.md). A *policy-blocked image* is not a CI failure — it is an expected outcome of a **successful** run. A genuine CI failure (a crashed step, an authentication @@ -184,7 +184,7 @@ more common case of a run that starts and then fails. [workflow naming conventions](../../contributing/workflow-naming.md), document `manage-failure-issue` in the [workflow actions reference](../../reference/workflow-actions.md), and link this - document from the [workflow architecture index](README.md). + document from the [architecture index](../README.md). ## Security considerations diff --git a/docs/architecture/deploy/README.md b/docs/architecture/deploy/README.md new file mode 100644 index 0000000..31b1cb5 --- /dev/null +++ b/docs/architecture/deploy/README.md @@ -0,0 +1,7 @@ +# Deploy — architecture + +Design docs for the **Deploy** stage: deploying the demo applications. + +_No architecture documents yet._ Deployment is currently handled by the Helm +charts under `apps/*/deploy`; design docs will be added here as the deploy story +grows. diff --git a/docs/architecture/run/README.md b/docs/architecture/run/README.md new file mode 100644 index 0000000..232f5ff --- /dev/null +++ b/docs/architecture/run/README.md @@ -0,0 +1,9 @@ +# Run — architecture + +Design docs for the **Run** stage: the running applications and how they surface +supply-chain state. + +## Supply Chain Observability + +- [CSSC Dashboard](cssc-dashboard.md) — a microservices web app that visualizes + the CSSC framework stage by stage. diff --git a/docs/architecture/apps/cssc-dashboard.md b/docs/architecture/run/cssc-dashboard.md similarity index 100% rename from docs/architecture/apps/cssc-dashboard.md rename to docs/architecture/run/cssc-dashboard.md diff --git a/docs/architecture/workflows/README.md b/docs/architecture/workflows/README.md deleted file mode 100644 index bbefc87..0000000 --- a/docs/architecture/workflows/README.md +++ /dev/null @@ -1,31 +0,0 @@ -# Workflow architecture - -Architecture documentation for the GitHub Actions workflows in this repository. - -Workflows fall into the following categories (see -[workflow naming conventions](../../contributing/workflow-naming.md)): - -| Category | Purpose | Status | -| -------- | ------- | ------ | -| **Mirror** | Copy / refresh upstream base images from Docker Hub into GHCR | Implemented | -| **Promote from quarantine** | Scan quarantined images and promote the ones that pass a vulnerability policy into `golden/` (or `base/...` for base/hardened images) | Implemented | -| **Build** | Build the demo applications under `apps/` on top of promoted `golden/*` bases, tag them with the semantic-version set (no `latest`), and attach supply-chain metadata (annotations, SBOM, provenance) | Implemented | -| **Report** | Watch other workflows and file/close CI-failure tracking issues | Implemented | - -## Documents - -- [Image mirror workflows](image-mirror-workflows.md) — how the Docker Hub → - GHCR mirroring actions are structured, the tooling they use, and what they do - and deliberately do not do. -- [Promote-from-quarantine workflows](promote-from-quarantine-workflows.md) — how quarantined - images are scanned with Trivy, gated on a severity threshold plus CVE - exceptions, promoted into `golden/` (or `base/...` for base/hardened - images) with a scan-report referrer, and - removed from quarantine. -- [CI failure notifications](ci-failure-notifications.md) — how a - `workflow_run` monitor opens and closes per-workflow CI-failure tracking - issues (and optional Slack alerts) when a monitored workflow run fails or - recovers. -- [Build workflows](build-workflows.md) — how the demo applications are built - into multi-arch OCI images tagged with the semantic-version set and stamped - with annotations, SBOM, and provenance. diff --git a/docs/contributing/workflow-naming.md b/docs/contributing/workflow-naming.md index 9de2251..c9f8897 100644 --- a/docs/contributing/workflow-naming.md +++ b/docs/contributing/workflow-naming.md @@ -95,7 +95,7 @@ images). - **Auth.** GHCR scan/copy/attach use the built-in `GITHUB_TOKEN` (`packages: write`). Deleting quarantine tags needs a separate `delete:packages` PAT (see the - [promote-from-quarantine architecture](../architecture/workflows/promote-from-quarantine-workflows.md)). + [promote-from-quarantine architecture](../architecture/catalog/promote-from-quarantine-workflows.md)). ### Adding a new promote-from-quarantine workflow @@ -120,7 +120,7 @@ subscribes to the mirror, promote-from-quarantine, and promote-override workflow via the `workflow_run` event and opens (or, on recovery, closes) a `CI failure: ` issue. It uses the `report-.yml` filename and the `report / ` display name. See the -[CI failure notifications design](../architecture/workflows/ci-failure-notifications.md). +[CI failure notifications design](../architecture/cross-cutting/ci-failure-notifications.md). ## Composite actions diff --git a/docs/guides/README.md b/docs/guides/README.md index fbee9a4..fe951e2 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -1,19 +1,14 @@ # Guides -How-to and operational guides for the `cssc-framework` repository. +How-to and operational guides for the `cssc-framework` repository, organized +around the **CSSC framework stages**. Within each stage, guides are grouped +under two cross-cutting themes where they apply: **Authenticity and Integrity** +and **Supply Chain Observability**. -- [Mirroring base images from Docker Hub to GHCR](mirroring-base-images.md) — - how the mirror actions work and how to add a new mirror for another image or - tag. -- [Configuring human-in-the-loop promotion overrides + Slack notifications](configuring-override-approval.md) — - how to enable the approve/deny override path for blocked images and wire up - Slack notifications. -- [Verifying and reading image SBOM and provenance](verifying-image-attestations.md) — - how to read and cross-check the SBOM and build provenance on the CSSC Dashboard - images, from both the embedded attestations and the OCI 1.1 referrers. -- [Reading image annotations](reading-image-annotations.md) — - how to read the OCI manifest annotations stamped onto each build and what each - one is used for. -- [Image tagging](image-tagging.md) — - the semantic-version tag set the build publishes, which tag to pin vs. track, - the no-`latest` policy, and how to pull by each tag. +- [Acquire](acquire/) — mirroring base images from Docker Hub into GHCR. +- [Catalog](catalog/) — promotion overrides and approvals for quarantined + images. +- [Build](build/) — image tagging, annotations, and attestations for the demo + app images. +- [Deploy](deploy/) — deploying the demo apps. +- [Run](run/) — running the applications. diff --git a/docs/guides/acquire/README.md b/docs/guides/acquire/README.md new file mode 100644 index 0000000..367850e --- /dev/null +++ b/docs/guides/acquire/README.md @@ -0,0 +1,9 @@ +# Acquire — guides + +How-to guides for the **Acquire** stage. + +## Authenticity and Integrity + +- [Mirroring base images from Docker Hub to GHCR](mirroring-base-images.md) — + how the mirror actions work and how to add a new mirror for another image or + tag. diff --git a/docs/guides/mirroring-base-images.md b/docs/guides/acquire/mirroring-base-images.md similarity index 91% rename from docs/guides/mirroring-base-images.md rename to docs/guides/acquire/mirroring-base-images.md index 8572858..9917be7 100644 --- a/docs/guides/mirroring-base-images.md +++ b/docs/guides/acquire/mirroring-base-images.md @@ -6,7 +6,7 @@ into the GitHub Container Registry (GHCR), and how to add a new mirror for an additional image or tag. It is a practical, task-oriented companion to the -[image mirror workflows architecture](../architecture/workflows/image-mirror-workflows.md) +[image mirror workflows architecture](../../architecture/acquire/image-mirror-workflows.md) document. If you only want to understand the design, read that document; if you want to *operate* or *extend* the mirrors, read this one. @@ -43,18 +43,18 @@ Mirrors run automatically on a daily schedule and can also be started manually. There are currently three mirror actions, one per base image. Each is a thin "caller" workflow that supplies image-specific values and delegates all logic to the shared reusable workflow -[`_mirror-image.yml`](../../.github/workflows/_mirror-image.yml). +[`_mirror-image.yml`](../../../.github/workflows/_mirror-image.yml). | Workflow file | Display name | Source (Docker Hub) | Destination (GHCR) | | ------------- | ------------ | ------------------- | ------------------ | -| [`mirror-python.yml`](../../.github/workflows/mirror-python.yml) | `mirror / quarantine/python` | `docker.io/library/python:3.14-slim` | `ghcr.io/toddysm/quarantine/python:3.14-slim` | -| [`mirror-node.yml`](../../.github/workflows/mirror-node.yml) | `mirror / quarantine/node` | `docker.io/library/node:26-alpine` | `ghcr.io/toddysm/quarantine/node:26-alpine` | -| [`mirror-openjdk.yml`](../../.github/workflows/mirror-openjdk.yml) | `mirror / quarantine/openjdk` | `docker.io/library/openjdk:27-ea-slim` | `ghcr.io/toddysm/quarantine/openjdk:27-ea-slim` | +| [`mirror-python.yml`](../../../.github/workflows/mirror-python.yml) | `mirror / quarantine/python` | `docker.io/library/python:3.14-slim` | `ghcr.io/toddysm/quarantine/python:3.14-slim` | +| [`mirror-node.yml`](../../../.github/workflows/mirror-node.yml) | `mirror / quarantine/node` | `docker.io/library/node:26-alpine` | `ghcr.io/toddysm/quarantine/node:26-alpine` | +| [`mirror-openjdk.yml`](../../../.github/workflows/mirror-openjdk.yml) | `mirror / quarantine/openjdk` | `docker.io/library/openjdk:27-ea-slim` | `ghcr.io/toddysm/quarantine/openjdk:27-ea-slim` | All three are structurally identical. They differ only in four input values (`source_image`, `source_tag`, `dest_image`, `dest_tag`), their display `name:`, and their `concurrency.group`. For example, -[`mirror-python.yml`](../../.github/workflows/mirror-python.yml) calls the +[`mirror-python.yml`](../../../.github/workflows/mirror-python.yml) calls the reusable workflow like this: ```yaml @@ -187,9 +187,9 @@ Decide on: ### 2. Create the caller workflow Copy an existing caller, for example -[`mirror-python.yml`](../../.github/workflows/mirror-python.yml), to a new file +[`mirror-python.yml`](../../../.github/workflows/mirror-python.yml), to a new file named `mirror-.yml`. Following the -[workflow naming conventions](../contributing/workflow-naming.md), the filename +[workflow naming conventions](../../contributing/workflow-naming.md), the filename must start with the `mirror-` prefix. Create `.github/workflows/mirror-golang.yml`: diff --git a/docs/guides/build/README.md b/docs/guides/build/README.md new file mode 100644 index 0000000..0aa6e10 --- /dev/null +++ b/docs/guides/build/README.md @@ -0,0 +1,18 @@ +# Build — guides + +How-to guides for the **Build** stage. + +## Authenticity and Integrity + +- [Image tagging](image-tagging.md) — the semantic-version tag set the build + publishes, which tag to pin vs. track, the no-`latest` policy, and how to pull + by each tag. +- [Verifying image attestations](verifying-image-attestations.md) — how to read + and cross-check the SBOM and build provenance from both the embedded + attestations and the OCI 1.1 referrers. (Also serves **Supply Chain + Observability**.) + +## Supply Chain Observability + +- [Reading image annotations](reading-image-annotations.md) — how to read the + OCI manifest annotations stamped onto each build and what each one is for. diff --git a/docs/guides/image-tagging.md b/docs/guides/build/image-tagging.md similarity index 91% rename from docs/guides/image-tagging.md rename to docs/guides/build/image-tagging.md index c0e3d61..206aced 100644 --- a/docs/guides/image-tagging.md +++ b/docs/guides/build/image-tagging.md @@ -4,7 +4,7 @@ This guide explains how the `build / cssc-dashboard` workflow **tags** the CSSC Dashboard images, which tag to use for which purpose, and how to pull by each tag. It is the companion to the [reading image annotations](reading-image-annotations.md) guide and the -[image annotations reference](../reference/image-annotations.md). +[image annotations reference](../../reference/image-annotations.md). ## The tag set @@ -47,7 +47,7 @@ derived without one. The immutable `build` tag is also recorded in the `org.opencontainers.image.version` annotation, and the full set is recorded in `com.toddysm.image.tags` (see the -[annotations reference](../reference/image-annotations.md)), so you can recover +[annotations reference](../../reference/image-annotations.md)), so you can recover every tag from the image itself. ## Pulling by tag @@ -81,5 +81,5 @@ docker pull "$REPO@$digest" - [Reading image annotations](reading-image-annotations.md) - [Verifying image attestations](verifying-image-attestations.md) -- [Image annotations reference](../reference/image-annotations.md) -- [Build workflows architecture](../architecture/workflows/build-workflows.md) +- [Image annotations reference](../../reference/image-annotations.md) +- [Build workflows architecture](../../architecture/build/build-workflows.md) diff --git a/docs/guides/reading-image-annotations.md b/docs/guides/build/reading-image-annotations.md similarity index 97% rename from docs/guides/reading-image-annotations.md rename to docs/guides/build/reading-image-annotations.md index a1cb813..3bc7d77 100644 --- a/docs/guides/reading-image-annotations.md +++ b/docs/guides/build/reading-image-annotations.md @@ -5,7 +5,7 @@ This guide shows how to read the **OCI manifest annotations** that the explains **what each annotation is for**. It is the task-oriented companion to the reference document -[image annotations](../reference/image-annotations.md), which lists the +[image annotations](../../reference/image-annotations.md), which lists the annotation set. If you only want the list, read that document; if you want to *read* the annotations off a built image and understand how to use them, read this one. @@ -192,6 +192,6 @@ crane manifest "$IMAGE" | jq -r '.annotations | { ## Related -- [Image annotations (reference)](../reference/image-annotations.md) +- [Image annotations (reference)](../../reference/image-annotations.md) - [Verifying and reading image SBOM and provenance](verifying-image-attestations.md) -- [`build / cssc-dashboard` workflow](../../.github/workflows/build-cssc-dashboard.yml) +- [`build / cssc-dashboard` workflow](../../../.github/workflows/build-cssc-dashboard.yml) diff --git a/docs/guides/verifying-image-attestations.md b/docs/guides/build/verifying-image-attestations.md similarity index 97% rename from docs/guides/verifying-image-attestations.md rename to docs/guides/build/verifying-image-attestations.md index d7ba8b7..654fde3 100644 --- a/docs/guides/verifying-image-attestations.md +++ b/docs/guides/build/verifying-image-attestations.md @@ -10,7 +10,7 @@ images, using **both** ways those attestations are published: with `oras discover` and pull with `oras`. It is the task-oriented companion to the reference document -[image attestations](../reference/image-attestations.md), which describes what +[image attestations](../../reference/image-attestations.md), which describes what the `build / cssc-dashboard` workflow produces. If you only want the summary, read that document; if you want to *inspect* or *verify* the attestations, read this one. @@ -302,6 +302,6 @@ for the current build. ## Related -- [Image attestations (reference)](../reference/image-attestations.md) -- [Image annotations (reference)](../reference/image-annotations.md) -- [`build / cssc-dashboard` workflow](../../.github/workflows/build-cssc-dashboard.yml) +- [Image attestations (reference)](../../reference/image-attestations.md) +- [Image annotations (reference)](../../reference/image-annotations.md) +- [`build / cssc-dashboard` workflow](../../../.github/workflows/build-cssc-dashboard.yml) diff --git a/docs/guides/catalog/README.md b/docs/guides/catalog/README.md new file mode 100644 index 0000000..9d3e962 --- /dev/null +++ b/docs/guides/catalog/README.md @@ -0,0 +1,9 @@ +# Catalog — guides + +How-to guides for the **Catalog** stage. + +## Authenticity and Integrity + +- [Configuring human-in-the-loop promotion overrides + Slack notifications](configuring-override-approval.md) + — how to enable the approve/deny override path for blocked images and wire up + Slack notifications. diff --git a/docs/guides/configuring-override-approval.md b/docs/guides/catalog/configuring-override-approval.md similarity index 96% rename from docs/guides/configuring-override-approval.md rename to docs/guides/catalog/configuring-override-approval.md index 8bd8da1..9607640 100644 --- a/docs/guides/configuring-override-approval.md +++ b/docs/guides/catalog/configuring-override-approval.md @@ -6,8 +6,8 @@ workflows, and how to configure **Slack** so the team is notified when an image is blocked, approved, or denied. It is a practical, task-oriented companion to the -[promote-from-quarantine override-approval architecture](../architecture/workflows/promote-from-quarantine-override-approval.md) -document and the [workflow actions reference](../reference/workflow-actions.md). +[promote-from-quarantine override-approval architecture](../../architecture/catalog/promote-from-quarantine-override-approval.md) +document and the [workflow actions reference](../../reference/workflow-actions.md). If you only want to understand the design, read the architecture document; if you want to *enable* or *operate* the override path, read this one. @@ -103,7 +103,7 @@ workflows already use; you only need to add `SLACK_WEBHOOK`. ## Step 3 — Enable approval on a workflow Approval is **opt-in per image**. Edit the per-image caller (for example -[`promote-from-quarantine-python.yml`](../../.github/workflows/promote-from-quarantine-python.yml)) +[`promote-from-quarantine-python.yml`](../../../.github/workflows/promote-from-quarantine-python.yml)) and add `enable_approval: true` to its `with:` block plus the `slack_webhook` secret: @@ -132,7 +132,7 @@ behavior — blocked images are left in quarantine with no issue or Slack messag ## Step 4 — Make sure the override caller is present The approve/deny decision is handled by the -[`promote-override.yml`](../../.github/workflows/promote-override.yml) caller, +[`promote-override.yml`](../../../.github/workflows/promote-override.yml) caller, which is repository-wide (not per image). It triggers on: - **`issue_comment`** — a `/approve` or `/deny` comment on an open issue carrying diff --git a/docs/guides/deploy/README.md b/docs/guides/deploy/README.md new file mode 100644 index 0000000..264ce52 --- /dev/null +++ b/docs/guides/deploy/README.md @@ -0,0 +1,5 @@ +# Deploy — guides + +How-to guides for the **Deploy** stage. + +_No guides yet._ Deployment currently uses the Helm charts under `apps/*/deploy`. diff --git a/docs/guides/run/README.md b/docs/guides/run/README.md new file mode 100644 index 0000000..e83945d --- /dev/null +++ b/docs/guides/run/README.md @@ -0,0 +1,5 @@ +# Run — guides + +How-to guides for the **Run** stage. + +_No guides yet._ diff --git a/docs/reference/image-annotations.md b/docs/reference/image-annotations.md index ffa3519..1f47cfa 100644 --- a/docs/reference/image-annotations.md +++ b/docs/reference/image-annotations.md @@ -6,7 +6,7 @@ workflow) are **OCI**, **multi-arch** (`linux/amd64`, `linux/arm64`), and carry OCI **manifest annotations** so supply-chain metadata travels with the image. For how those images are **tagged** (the semantic-version tag set and which -tag to pin), see the [image tagging guide](../guides/image-tagging.md). +tag to pin), see the [image tagging guide](../guides/build/image-tagging.md). Annotations are set at **both** the multi-arch **index** and each **per-platform manifest**, so they are visible regardless of which descriptor a tool inspects: diff --git a/docs/reference/workflow-actions.md b/docs/reference/workflow-actions.md index 910986c..ba33d72 100644 --- a/docs/reference/workflow-actions.md +++ b/docs/reference/workflow-actions.md @@ -153,7 +153,7 @@ Attach an empty OCI scan-report referrer to a promoted image. | `override-cves` | no | `""` | Pipe-separated CVEs that were overridden (when `override` is true). | The referrer artifact type is `application/vnd.cssc.scan-report.v1+json`; see the -[promote-from-quarantine architecture](../architecture/workflows/promote-from-quarantine-workflows.md#scan-report-referrer-artifact) +[promote-from-quarantine architecture](../architecture/catalog/promote-from-quarantine-workflows.md#scan-report-referrer-artifact) for the full annotation schema. ### delete-image