CLI Coordination Plan

Status: APPROVED Version: 1.0.0 Last Updated: 2025-12-06 Owner: AirGap CLI Guild Unblocks: AIRGAP-54-001

Currency note (2026-07-11): The command and endpoint examples below record the approved 2025 coordination target; they are not current runtime instructions. In current source, stella mirror create returns exit code 9 and writes no files, and the documented mirror sign|pack sequence is not a live command surface. Use stella feedser bundle export or stella mirror seed export, and consult ../mirror/architecture.md plus ../cli/architecture.md before operational use.

Overview

This document defines the coordination between the Export Center, AirGap Controller, and CLI for offline bundle creation and consumption.

Architecture

┌──────────────────────────────────────────────────────────────────────────────┐
│                     AirGap Bundle Flow                                        │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                               │
│  ONLINE ENVIRONMENT                    AIR-GAP ENVIRONMENT                    │
│  ─────────────────                    ──────────────────                     │
│                                                                               │
│  ┌─────────────┐                                                             │
│  │ Export      │                                                             │
│  │ Center      │─────┐                                                       │
│  └─────────────┘     │                                                       │
│         │            │                                                       │
│         ▼            │                                                       │
│  ┌─────────────┐     │      USB/Network    ┌─────────────┐                  │
│  │ CLI:        │     │      Transfer       │ CLI:        │                  │
│  │ stella      │─────┼────────────────────▶│ stella      │                  │
│  │ mirror      │     │                     │ airgap      │                  │
│  │ create      │     │                     │ import      │                  │
│  └─────────────┘     │                     └─────────────┘                  │
│         │            │                            │                          │
│         ▼            │                            ▼                          │
│  ┌─────────────┐     │                     ┌─────────────┐                  │
│  │ Bundle      │     │                     │ AirGap      │                  │
│  │ (.tar.gz)   │     │                     │ Controller  │                  │
│  │ + DSSE      │     │                     └─────────────┘                  │
│  └─────────────┘     │                            │                          │
│                      │                            ▼                          │
│                      │                     ┌─────────────┐                  │
│                      │                     │ Registry +  │                  │
│                      │                     │ Services    │                  │
│                      │                     └─────────────┘                  │
│                      │                                                       │
└──────────────────────┴───────────────────────────────────────────────────────┘

1. Export Center Integration

1.1 Export Jobs

The Export Center creates offline bundles via scheduled or on-demand jobs:

# Create full mirror bundle
stella export mirror \
  --format airgap \
  --include-images \
  --include-advisories \
  --output /exports/bundles/

# Create incremental update
stella export mirror \
  --format airgap \
  --incremental \
  --since 2025-12-01 \
  --output /exports/updates/

1.2 Export API

Endpoint	Method	Description
`/api/v1/export/mirror`	POST	Create new mirror bundle job
`/api/v1/export/mirror/{jobId}`	GET	Get job status
`/api/v1/export/mirror/{jobId}/download`	GET	Download bundle
`/api/v1/export/mirror/catalog`	GET	List available bundles

1.3 Bundle Catalog

{
  "bundles": [
    {
      "id": "stellaops-airgap-2025.10.0",
      "version": "2025.10.0",
      "created": "2025-12-06T10:00:00Z",
      "size": 4294967296,
      "sha256": "sha256:abc123...",
      "signature": "dsse://manifest.dsse",
      "type": "full",
      "contents": {
        "images": 15,
        "advisories": 45000,
        "schemas": 22
      }
    }
  ]
}

2. CLI Commands

2.1 Mirror Creation (Online)

# Create mirror bundle from release manifest
stella mirror create \
  --release deploy/releases/2025.10.0-airgap.yaml \
  --output ./bundle/

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

# Package for transfer
stella mirror pack ./bundle/ \
  --output stellaops-airgap-2025.10.0.tar.gz

2.2 AirGap Import (Offline)

# Verify and extract bundle
stella airgap import ./stellaops-airgap-2025.10.0.tar.gz \
  --verify \
  --registry localhost:5000

# Seal environment (block external network)
stella airgap seal \
  --config /etc/stellaops/sealed-mode.yaml

# Check sealed status
stella airgap status

# Export evidence from sealed environment
stella airgap export-evidence \
  --output ./evidence-bundle.tar.gz

2.3 CLI Exit Codes

Code	Meaning
0	Success
1	General error
2	Signature verification failed
3	Checksum mismatch
4	Sealed mode violation
5	Registry unavailable
6	Bundle format invalid

3. AirGap Controller

3.1 Sealed Mode Enforcement

The AirGap Controller enforces network isolation:

# /etc/stellaops/sealed-mode.yaml
sealed:
  enabled: true
  allowedHosts:
    - localhost
    - "*.local"
    - "10.0.0.0/8"
  blockedPorts:
    - 80
    - 443
  egressPolicy: deny-all
  auditLog: /var/log/stellaops/sealed-audit.log

3.2 Controller API

Endpoint	Method	Description
`/api/v1/airgap/status`	GET	Sealed mode status
`/api/v1/airgap/seal`	POST	Activate sealed mode
`/api/v1/airgap/unseal`	POST	Deactivate sealed mode
`/api/v1/airgap/bundles`	GET	List imported bundles
`/api/v1/airgap/bundles/{id}`	DELETE	Remove bundle

3.3 Time Anchoring

For evidence validity in sealed environments:

# Set time anchor from trusted source
stella airgap time-anchor set \
  --source "2025-12-06T10:00:00Z" \
  --signature time-anchor.sig

# Verify time anchor
stella airgap time-anchor verify

4. Workflow Examples

4.1 Initial Deployment (Air-Gap)

# 1. On online workstation: create bundle
stella mirror create --release 2025.10.0 --output ./bundle/
stella mirror sign ./bundle/manifest.json --output ./bundle/manifest.dsse
stella mirror pack ./bundle/ --output stellaops-2025.10.0-airgap.tar.gz

# 2. Transfer to air-gap environment (USB, etc.)

# 3. On air-gap system: import and deploy
stella airgap import stellaops-2025.10.0-airgap.tar.gz --registry registry.local:5000
docker compose -f docker-compose.airgap.yaml up -d
stella airgap seal

4.2 Incremental Update

# 1. On online workstation: create update
stella mirror create --release 2025.10.1 --incremental --output ./update/
stella mirror sign ./update/manifest.json --output ./update/manifest.dsse
stella mirror pack ./update/ --output stellaops-2025.10.1-update.tar.gz

# 2. Transfer

# 3. On air-gap system: apply update
stella airgap unseal --reason "applying update"
stella airgap import stellaops-2025.10.1-update.tar.gz
stella concelier sync --advisory-update
stella airgap seal

4.3 Evidence Export

# Export scan evidence for external audit
stella airgap export-evidence \
  --from 2025-11-01 \
  --to 2025-12-01 \
  --include-attestations \
  --output audit-evidence-2025-12.tar.gz

# Verify evidence integrity
stella evidence verify audit-evidence-2025-12.tar.gz --verbose

5. Error Handling

5.1 Common Issues

Issue	Cause	Resolution
“Signature verification failed”	Key mismatch or tampered bundle	Re-download bundle, verify source
“Sealed mode violation”	Attempted external network access	Check service configurations
“Registry unavailable”	Local registry not running	Start registry container
“Bundle expired”	Advisory data too old	Create fresh bundle

5.2 Troubleshooting Commands

# Check sealed mode status
stella airgap status --verbose

# Audit sealed mode violations
stella airgap audit --since "24h"

# Verify bundle integrity
stella mirror verify ./bundle/ --checksums --signatures

# Test registry connectivity
stella registry ping localhost:5000

6. Tasks Unblocked

Task ID	Description	Status
AIRGAP-54-001	Exporter/AirGap/CLI coordination	✅ UNBLOCKED
CLI-AIRGAP-56-001	stella mirror create	✅ UNBLOCKED
CLI-AIRGAP-57-001	stella airgap import	✅ UNBLOCKED
CLI-AIRGAP-57-002	stella airgap seal	✅ UNBLOCKED

7. Changelog

Date	Version	Change
2025-12-06	1.0.0	Initial coordination plan with CLI commands, workflows, error handling