Ensure packaged software can be traced back to the commits that built it

[ourchitectureio]

Task Type

task

Description

Review all sub-projects and the release process.

Ensure that attestations and/or SBOM, etc. are used as needed to ensure that any packaged release of the project's sub-projects can be traced back to the original commit that was used as the basis.

Priority

p1-high

Domain

security

Agent Processing

• This issue is suitable for autonomous AI agent processing.

[github-actions]

This issue is ready for agent processing. An agent can pick this up by running:

/plan-work issue_number=207

Or find it automatically with /find-work.

[ourchitectureio]

Implementation Plan

Posted by AI agent. Maintainer approval required before implementation begins.

Summary

Add build traceability to all packaged software releases through:

1. OCI image labels containing source commit SHA, build timestamp, and repository linkage
2. SBOM generation via docker/build-push-action's built-in SBOM attestation support
3. Build provenance attestations via docker/build-push-action's provenance support
4. Documentation of verification procedures for consumers

This ensures that any released container image can be traced back to its source commit and build context, meeting supply chain security best practices (SLSA, SBOM standards).

Estimated Complexity

Medium — touches 3 workflow files and all 7 Dockerfiles, but the changes follow well-established patterns and the docker/build-push-action@v7.1.0 already in use supports all required features.

Files to Create or Modify

Workflows to Modify

1. .github/workflows/container-publish.yml (6 jobs: go, nodejs, contract-tests, mcp-tools, mock-oauth, dev-tools)

   • Add OCI labels via build-push-action labels parameter
   • Enable provenance attestations (provenance: true)
   • Enable SBOM generation (sbom: true)
   • All jobs already use the correct action version

2. .github/workflows/container-build.yml (8 build jobs for PR/push validation)

   • Add same OCI labels for consistency
   • Enable provenance and SBOM for main pushes (not PRs to save time)
   • Draft PRs already skip these builds

3. .github/workflows/container-latest-tag.yml (if it updates tags after release)

   • Verify that it preserves attestations when re-tagging to latest

Dockerfiles to Modify (OCI LABEL directives)

Add LABEL directives to the final stage of each Dockerfile following OCI image spec:

4. stacks/go/net-http/rest/Dockerfile
5. stacks/nodejs/react-fastify/rest/bff/Dockerfile
6. stacks/nodejs/react-fastify/rest/web/Dockerfile
7. tests/Dockerfile
8. tools/mcp/Dockerfile
9. tools/mock-oauth/Dockerfile
10. .devcontainer/Dockerfile

Standard labels to add:

ARG BUILD_DATE
ARG VCS_REF
ARG VERSION

LABEL org.opencontainers.image.created="${BUILD_DATE}"
LABEL org.opencontainers.image.revision="${VCS_REF}"
LABEL org.opencontainers.image.version="${VERSION}"
LABEL org.opencontainers.image.source="https://github.com/ourchitecture/idp"
LABEL org.opencontainers.image.url="https://github.com/ourchitecture/idp"
LABEL org.opencontainers.image.vendor="Ourchitecture"
LABEL org.opencontainers.image.licenses="Apache-2.0"

Documentation to Create/Modify

11. docs/content/operations/verifying-releases.md (new file)

    • How to inspect SBOM and attestations for a published image
    • Using docker buildx imagetools inspect to view provenance
    • Using cosign or GitHub CLI to verify attestations
    • Example commands for common verification tasks

12. docs/content/architecture/decisions/0010-container-build-strategy.md (append)

    • Add section 10: Build Traceability
    • Document OCI labels, SBOM, and provenance attestation policy
    • Reference verification documentation

13. AGENTS.md (update Security Rules section)

    • Add requirement that all container builds must include attestations
    • Require SBOM review for high/critical vulnerabilities

14. Stack-level README files (if they document container usage)

    • stacks/go/net-http/rest/README.md
    • stacks/nodejs/react-fastify/rest/README.md
    • tools/mcp/README.md
    • Brief note on how to verify published images

Approach

Phase 1: Add OCI Labels to Dockerfiles (low risk, immediate value)

For each Dockerfile:

1. Add ARG directives before the final FROM statement for BUILD_DATE, VCS_REF, and VERSION
2. Add LABEL directives in the final runtime stage (after FROM runtime or final base image)
3. Keep labels together in one block for maintainability
4. Use conditional defaults where needed (e.g., ARG VERSION=dev)

Phase 2: Update container-publish.yml (versioned release builds)

For each publish job:

1. Add docker/metadata-action step to generate labels and tags
2. Pass computed labels to docker/build-push-action via labels input
3. Pass build-args for BUILD_DATE, VCS_REF, VERSION
4. Enable provenance: true and sbom: true (both supported by v7.1.0)
5. Ensure GITHUB_TOKEN has id-token: write and attestations: write permissions

Example workflow addition:

- name: Extract metadata
  id: meta
  uses: docker/metadata-action@8e5442c4ef9f78752691e2d8f8d19755c6f78e81 # v5.5.1
  with:
    images: ${{ env.IMAGE_PREFIX }}/stemix-go-net-http-rest-${{ matrix.service }}
    tags: |
      type=semver,pattern={{version}},value=${{ steps.version.outputs.version }}
      type=semver,pattern={{major}}.{{minor}},value=${{ steps.version.outputs.version }}
      type=semver,pattern={{major}},value=${{ steps.version.outputs.version }}

- name: Build and push with attestations
  uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
  with:
    context: stacks/go/net-http/rest
    file: stacks/go/net-http/rest/Dockerfile
    build-args: |
      SERVICE=${{ matrix.service }}
      BUILD_DATE=${{ fromJSON(steps.meta.outputs.json).labels['org.opencontainers.image.created'] }}
      VCS_REF=${{ github.sha }}
      VERSION=${{ steps.version.outputs.version }}
    labels: ${{ steps.meta.outputs.labels }}
    push: true
    tags: ${{ steps.meta.outputs.tags }}
    provenance: true
    sbom: true

Phase 3: Update container-build.yml (PR and main edge builds)

Similar changes to container-publish.yml, but:

• Use conditional logic: only enable attestations for push to main (not PR builds)
• Use edge and pr-check tags as currently done
• VCS_REF uses github.sha, VERSION uses edge or pr-${{ github.event.pull_request.number }}

Phase 4: Documentation

1. Create docs/content/operations/verifying-releases.md:

   • Show how to inspect SBOM: docker buildx imagetools inspect --format "{{ json .SBOM }}" <image>
   • Show how to inspect provenance: docker buildx imagetools inspect --format "{{ json .Provenance }}" <image>
   • Show how to view OCI labels: docker inspect <image> --format='{{json .Config.Labels}}'
   • Link to GitHub Packages attestation verification via GitHub CLI or web UI

2. Update ADR-0010 with new section on traceability requirements

3. Update AGENTS.md to mandate attestations for all new container builds

Existing Patterns to Follow

• Pinned action versions with SHA comments: All workflow actions use full SHA pins with version comments (e.g., # v7.1.0)
• Multi-stage Dockerfile pattern: All existing Dockerfiles use builder + runtime + scanner stages
• Environment variable naming: Use OUR_IDP_ prefix for IDP-specific vars, standard OCI names for labels
• ADR intake threshold: Build traceability meets the threshold (cross-cutting, contract surface, multi-quarter longevity)

Risks and Open Questions

1. Attestation storage: GitHub Packages stores attestations alongside images. Verify that old attestations are retained when cleanup workflow runs (they should be, but worth testing).

2. Provenance mode: docker/build-push-action supports provenance: true (default mode) vs provenance: mode=max. Default mode is SLSA Provenance v1.0. Confirm this meets requirements or if mode=max is needed.

3. SBOM format: The action generates SPDX-format SBOMs by default. Confirm this is acceptable or if CycloneDX is required.

4. Performance impact: SBOM and provenance generation adds ~10-30 seconds per image build. For 6 images in container-publish.yml, this could add 1-5 minutes total. Acceptable for release builds.

5. PR build performance: Disable attestations for draft PRs and non-main pushes to keep PR validation fast. Only enable for main pushes and final ready-for-review PR builds.

6. Token permissions: Ensure container-publish.yml has id-token: write and attestations: write permissions. Current permissions block only has contents: read and packages: write.

7. Backward compatibility: Adding ARG and LABEL to Dockerfiles is backward-compatible. Old builds ignore unknown args.

Verification

Local verification (developer)

# Build with labels
docker build --build-arg BUILD_DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
  --build-arg VCS_REF=$(git rev-parse HEAD) \
  --build-arg VERSION=dev \
  -t localhost/stemix-go-net-http-rest-web:dev \
  -f stacks/go/net-http/rest/Dockerfile \
  stacks/go/net-http/rest

# Inspect labels
docker inspect localhost/stemix-go-net-http-rest-web:dev \
  --format='{{json .Config.Labels}}' | jq

CI verification (automated)

• Add step in container-publish.yml after each build to verify SBOM and provenance exist
• Use docker buildx imagetools inspect to confirm attestations are attached

Release verification (manual)

• After a release, maintainer should:
  1. Pull the published image
  2. Inspect OCI labels for correct commit SHA
  3. View SBOM via docker buildx imagetools inspect
  4. View provenance attestation
  5. Verify that the commit SHA matches the release tag

Documentation verification

• Follow the steps in docs/content/operations/verifying-releases.md against a live published image
• Ensure all commands work and return expected output

Implementation Handoff

Issue worktree path: .agents/worktrees/issue-207-ensure-packaged-software-traceability

Implementation steps:

1. Create or reuse the issue worktree via make worktree-ensure ISSUE_NUMBER=207 or moon run repo:worktree-ensure
2. Work in the worktree for all changes
3. Commit incrementally after each phase (Dockerfiles, then workflows, then docs)
4. Run make check-lint-md after documentation changes
5. Build containers locally to verify label injection works
6. Open PR from the issue branch created in the worktree
7. Wait for CI to validate container builds with new labels
8. Request maintainer review before merge