git.stella-ops.org/docs/modules/airgap/mirror-dsse-plan.md

Mirror Staffing & DSSE Signing Plan

Status: APPROVED Version: 1.0.0 Last Updated: 2025-12-06 Owner: Mirror Creator Guild Unblocks: AIRGAP-46-001, DEPLOY-AIRGAP-46-001, AIRGAP-54-001

Executive Summary

This document defines the staffing structure and DSSE (Dead Simple Signing Envelope) signing workflow for the StellaOps Mirror system. It provides the implementation plan required to unblock air-gap bundle creation, signing, and distribution.

1. Staffing Structure

1.1 Mirror Creator Guild Ownership

Role	Responsibility	Contact
Guild Lead	Overall mirror strategy, release coordination	mirror-guild@stella-ops.org
Bundle Engineer	Create, verify, and publish air-gap bundles	DevOps rotation
Signing Authority	Manage signing keys, approve releases	Security Guild delegate
QA Validator	Verify bundle integrity before publication	QA Guild delegate

1.2 Staffing Resolution (PGMI0101)

The Program Management Initiative PGMI0101 is resolved with the following assignments:

Initiative	Assignee	Effective Date
Mirror bundle creation	DevOps Guild (rotation)	2025-12-06
DSSE signing authority	Security Guild	2025-12-06
CLI integration	DevEx/CLI Guild	2025-12-06
Offline Kit updates	Deployment Guild	2025-12-06

2. DSSE Signing Workflow

2.1 Key Management

┌─────────────────────────────────────────────────────────────────────────────┐
│                         Key Hierarchy                                        │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  Root CA (offline, HSM-backed)                                               │
│  └── Signing CA (intermediate)                                               │
│      ├── mirror-signing-key (ECDSA P-256)                                   │
│      │   └── Used for: bundle.dsse, catalog.dsse                            │
│      ├── attestation-signing-key (ECDSA P-256)                              │
│      │   └── Used for: SBOM attestations, VEX attestations                  │
│      └── dev-signing-key (ECDSA P-256)                                      │
│          └── Used for: development/testing only                             │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

2.2 Key Locations

Key	Environment	Location	Access
Dev signing key	Development	tools/cosign/cosign.dev.key	Public (password: stellaops-dev)
CI signing key	CI/CD	COSIGN_PRIVATE_KEY_B64 secret	Gitea CI only
Production key	Production	HSM / Vault	Security Guild only

2.3 DSSE Envelope Structure

{
  "payloadType": "application/vnd.stellaops.mirror-bundle+json",
  "payload": "<base64-encoded manifest>",
  "signatures": [
    {
      "keyid": "sha256:<fingerprint>",
      "sig": "<base64-encoded signature>"
    }
  ]
}

2.4 Signing Process

# 1. Create bundle manifest
stella mirror create --output bundle/

# 2. Sign the manifest (dev)
stella mirror sign bundle/manifest.json \
  --key tools/cosign/cosign.dev.key \
  --output bundle/manifest.dsse

# 3. Sign the manifest (CI/prod)
stella mirror sign bundle/manifest.json \
  --key env://COSIGN_PRIVATE_KEY_B64 \
  --output bundle/manifest.dsse

# 4. Verify signature
stella mirror verify bundle/manifest.dsse \
  --key tools/cosign/cosign.pub

# 5. Package bundle
stella mirror pack bundle/ --output stellaops-airgap-2025.10.0.tar.gz

3. CI/CD Pipeline

3.1 Gitea Workflow: Mirror Bundle Creation

# .gitea/workflows/mirror-bundle.yml
name: Mirror Bundle
on:
  push:
    tags:
      - 'v*-airgap'
  workflow_dispatch:

jobs:
  create-bundle:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Create air-gap bundle
        run: |
          stella mirror create \
            --images deploy/releases/${{ github.ref_name }}.yaml \
            --output bundle/

      - name: Sign bundle
        env:
          COSIGN_PRIVATE_KEY: ${{ secrets.COSIGN_PRIVATE_KEY_B64 }}
          COSIGN_PASSWORD: ${{ secrets.COSIGN_PASSWORD }}
        run: |
          stella mirror sign bundle/manifest.json \
            --key env://COSIGN_PRIVATE_KEY \
            --output bundle/manifest.dsse

      - name: Package bundle
        run: |
          stella mirror pack bundle/ \
            --output stellaops-airgap-${{ github.ref_name }}.tar.gz

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: airgap-bundle
          path: stellaops-airgap-*.tar.gz

3.2 Gitea Workflow: Bundle Verification

# .gitea/workflows/mirror-verify.yml
name: Mirror Verify
on:
  workflow_run:
    workflows: ["Mirror Bundle"]
    types: [completed]

jobs:
  verify-bundle:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Download bundle
        uses: actions/download-artifact@v4
        with:
          name: airgap-bundle

      - name: Verify signature
        run: |
          tar xzf stellaops-airgap-*.tar.gz
          stella mirror verify bundle/manifest.dsse \
            --key tools/cosign/cosign.pub

      - name: Verify checksums
        run: |
          stella mirror verify-checksums bundle/

4. Air-Gap Load Script

4.1 Load Script (deploy/airgap/load.sh)

#!/usr/bin/env bash
# StellaOps Air-Gap Bundle Loader
# Usage: ./load.sh <bundle.tar.gz> [registry:port]

set -euo pipefail

BUNDLE="${1:?Bundle path required}"
REGISTRY="${2:-localhost:5000}"

echo "==> Extracting bundle..."
tar xzf "$BUNDLE" -C /tmp/airgap-bundle

echo "==> Verifying signature..."
stella mirror verify /tmp/airgap-bundle/manifest.dsse \
  --key /tmp/airgap-bundle/public-key.pem

echo "==> Loading images to registry..."
for image in /tmp/airgap-bundle/images/*.tar; do
  echo "    Loading $(basename "$image")..."
  docker load -i "$image"

  # Retag for local registry
  original=$(docker inspect --format='{{index .RepoTags 0}}' "$(docker load -i "$image" -q)")
  retagged="${REGISTRY}/$(echo "$original" | cut -d'/' -f2-)"
  docker tag "$original" "$retagged"
  docker push "$retagged"
done

echo "==> Importing advisory data..."
stella concelier import /tmp/airgap-bundle/advisories/

echo "==> Done! Registry: $REGISTRY"

5. Offline Kit Integration

5.1 Bundle Contents

stellaops-airgap-2025.10.0/
├── manifest.json              # Bundle manifest
├── manifest.dsse              # DSSE-signed manifest
├── public-key.pem             # Verification key
├── SHA256SUMS                 # Checksums
├── SHA256SUMS.sig             # Signed checksums
├── images/                    # Container images
│   ├── authority-v2025.10.0.tar
│   ├── concelier-v2025.10.0.tar
│   ├── scanner-web-v2025.10.0.tar
│   ├── scanner-worker-v2025.10.0.tar
│   └── ...
├── advisories/                # Advisory data
│   ├── nvd-2025-12-01.json.gz
│   ├── ghsa-2025-12-01.json.gz
│   └── ...
├── scripts/
│   ├── load.sh                # Registry loader
│   ├── verify.sh              # Verification script
│   └── update.sh              # Incremental update
└── docs/
    ├── INSTALL.md             # Installation guide
    ├── VERIFY.md              # Verification guide
    └── TROUBLESHOOT.md        # Troubleshooting

6. Tasks Unblocked

This plan unblocks:

Task ID	Description	Status
AIRGAP-46-001	Mirror staffing + DSSE plan	✅ UNBLOCKED
DEPLOY-AIRGAP-46-001	Air-gap load scripts	✅ UNBLOCKED
AIRGAP-54-001	Exporter/AirGap/CLI coordination	✅ UNBLOCKED
DEVPORT-64-002	DevPortal Offline (already DONE)	✅ N/A

7. Changelog

Date	Version	Change
2025-12-06	1.0.0	Initial plan with staffing, DSSE workflow, CI/CD pipelines