feat: Add Go module and workspace test fixtures
- Created expected JSON files for Go modules and workspaces. - Added go.mod and go.sum files for example projects. - Implemented private module structure with expected JSON output. - Introduced vendored dependencies with corresponding expected JSON. - Developed PostgresGraphJobStore for managing graph jobs. - Established SQL migration scripts for graph jobs schema. - Implemented GraphJobRepository for CRUD operations on graph jobs. - Created IGraphJobRepository interface for repository abstraction. - Added unit tests for GraphJobRepository to ensure functionality.
This commit is contained in:
StellaOps Bot
291
docs/modules/airgap/exporter-cli-coordination.md
Normal file
291
docs/modules/airgap/exporter-cli-coordination.md
Normal file
@@ -0,0 +1,291 @@
|
||||
# Exporter / AirGap / CLI Coordination Plan
|
||||
|
||||
> **Status:** APPROVED
|
||||
> **Version:** 1.0.0
|
||||
> **Last Updated:** 2025-12-06
|
||||
> **Owner:** AirGap CLI Guild
|
||||
> **Unblocks:** AIRGAP-54-001
|
||||
|
||||
## 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```json
|
||||
{
|
||||
"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)
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```yaml
|
||||
# /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:
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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 |
|
||||
266
docs/modules/airgap/mirror-dsse-plan.md
Normal file
266
docs/modules/airgap/mirror-dsse-plan.md
Normal file
@@ -0,0 +1,266 @@
|
||||
# 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
|
||||
|
||||
```json
|
||||
{
|
||||
"payloadType": "application/vnd.stellaops.mirror-bundle+json",
|
||||
"payload": "<base64-encoded manifest>",
|
||||
"signatures": [
|
||||
{
|
||||
"keyid": "sha256:<fingerprint>",
|
||||
"sig": "<base64-encoded signature>"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 2.4 Signing Process
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```yaml
|
||||
# .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
|
||||
|
||||
```yaml
|
||||
# .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`)
|
||||
|
||||
```bash
|
||||
#!/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 |
|
||||
Reference in New Issue
Block a user