git.stella-ops.org/docs/modules/vexlens/operations/offline-kit.md

VexLens Offline Kit

Air-gapped deployment guide for VexLens consensus engine.

---

1) Overview

VexLens can operate in fully air-gapped environments with pre-loaded VEX data and issuer directories. This guide covers offline deployment, bundle creation, and operational procedures.

---

2) Offline Bundle Structure

2.1 Bundle Manifest

{
  "bundleId": "vexlens-bundle-2025-12-06",
  "version": "1.0.0",
  "createdAt": "2025-12-06T00:00:00Z",
  "createdBy": "stellaops-export",
  "checksum": "sha256:abc123...",
  "components": {
    "issuerDirectory": {
      "file": "issuers.json",
      "checksum": "sha256:def456...",
      "count": 150
    },
    "vexStatements": {
      "file": "vex-statements.ndjson.gz",
      "checksum": "sha256:ghi789...",
      "count": 50000
    },
    "projectionSnapshots": {
      "file": "projections.ndjson.gz",
      "checksum": "sha256:jkl012...",
      "count": 25000
    },
    "trustConfiguration": {
      "file": "trust-config.yaml",
      "checksum": "sha256:mno345..."
    }
  },
  "compatibility": {
    "minVersion": "1.0.0",
    "maxVersion": "2.0.0"
  }
}

2.2 Bundle Contents

vexlens-bundle-2025-12-06/
├── manifest.json
├── issuers.json
├── vex-statements.ndjson.gz
├── projections.ndjson.gz
├── trust-config.yaml
├── checksums.sha256
└── signature.dsse

---

3) Creating Offline Bundles

3.1 Export Command

# Export from online VexLens instance
stellaops vexlens export \
  --output /export/vexlens-bundle-$(date +%Y-%m-%d) \
  --include-issuers \
  --include-statements \
  --include-projections \
  --compress \
  --sign

3.2 Selective Export

# Export only specific tenants
stellaops vexlens export \
  --output /export/tenant-bundle \
  --tenant tenant-001,tenant-002 \
  --since 2025-01-01 \
  --compress

# Export only critical vulnerabilities
stellaops vexlens export \
  --output /export/critical-bundle \
  --vulnerability-pattern "CVE-202[45]-*" \
  --status affected,under_investigation \
  --compress

3.3 Bundle Signing

# Sign bundle with organization key
stellaops vexlens export sign \
  --bundle /export/vexlens-bundle-2025-12-06 \
  --key /keys/export-signing-key.pem \
  --output /export/vexlens-bundle-2025-12-06/signature.dsse

---

4) Importing Offline Bundles

4.1 Verification

# Verify bundle integrity and signature
stellaops vexlens import verify \
  --bundle /import/vexlens-bundle-2025-12-06 \
  --trust-root /etc/vexlens/trust-roots.pem

# Output:
# Bundle ID: vexlens-bundle-2025-12-06
# Created: 2025-12-06T00:00:00Z
# Signature: VALID (signed by: StellaOps Export Service)
# Checksums: VALID (all 4 files verified)
# Compatibility: COMPATIBLE (current version: 1.1.0)

4.2 Import Command

# Import bundle to offline VexLens
stellaops vexlens import \
  --bundle /import/vexlens-bundle-2025-12-06 \
  --mode merge \
  --verify-signature

# Import modes:
# - merge: Add new data, keep existing
# - replace: Replace all data with bundle contents
# - incremental: Only add data newer than existing

4.3 Staged Import

For large bundles, use staged import:

# Stage 1: Import issuers
stellaops vexlens import \
  --bundle /import/bundle \
  --component issuer-directory \
  --dry-run

# Stage 2: Import statements
stellaops vexlens import \
  --bundle /import/bundle \
  --component vex-statements \
  --batch-size 1000

# Stage 3: Import projections
stellaops vexlens import \
  --bundle /import/bundle \
  --component projections \
  --batch-size 5000

---

5) Offline Configuration

5.1 Air-Gap Mode Settings

vexlens:
  airgap:
    enabled: true
    # Disable external connectivity checks
    allowExternalConnections: false
    # Use file-based issuer directory
    issuerDirectorySource: file
    # Pre-compute consensus on import
    precomputeConsensus: true

  trust:
    # Stricter settings for air-gap
    allowUnsigned: false
    allowUnknownIssuers: false
    # Use local trust anchors
    trustAnchors: /etc/vexlens/trust-anchors.pem

  storage:
    # Local storage only
    mongodb:
      connectionString: mongodb://localhost:27017
    # No external cache
    redis:
      enabled: false

  time:
    # Use time anchor for staleness checks
    timeAnchorFile: /etc/vexlens/time-anchor.json
    # Maximum allowed drift
    maxDriftDays: 7

5.2 Time Anchor Configuration

For air-gapped environments, use time anchors:

{
  "anchorTime": "2025-12-06T00:00:00Z",
  "signature": "base64...",
  "validUntil": "2025-12-13T00:00:00Z",
  "signedBy": "stellaops-time-authority"
}

---

6) Operational Procedures

6.1 Bundle Update Cycle

1. Export (Online environment):

   stellaops vexlens export --output /export/weekly-bundle --compress --sign
   

2. Transfer (Secure media):

   • Copy bundle to removable media
   • Verify checksums after transfer
   • Log transfer in custody chain

3. Verify (Offline environment):

   stellaops vexlens import verify --bundle /import/weekly-bundle
   

4. Import (Offline environment):

   stellaops vexlens import --bundle /import/weekly-bundle --mode incremental
   

5. Recompute (If needed):

   stellaops vexlens consensus recompute --since $(date -d '7 days ago' +%Y-%m-%d)
   

6.2 Staleness Monitoring

# Check data freshness
stellaops vexlens status --staleness

# Output:
# Data Freshness Report
# ---------------------
# Issuer Directory: 2 days old (OK)
# VEX Statements: 5 days old (OK)
# Projections: 5 days old (OK)
# Time Anchor: 2 days old (OK)
#
# Overall Status: FRESH

6.3 Audit Trail

All import operations are logged:

# View import history
stellaops vexlens import history --limit 10

# Output:
# Import History
# --------------
# 2025-12-06 08:00: vexlens-bundle-2025-12-06 (merge, 50000 statements)
# 2025-11-29 08:00: vexlens-bundle-2025-11-29 (incremental, 12000 statements)
# ...

---

7) Degraded Mode Operation

7.1 Degradation Matrix

Component	Degradation	Impact	Mitigation
Stale VEX data	>7 days old	Lower accuracy	Schedule bundle update
Missing issuers	Unknown issuer	Lower trust scores	Add issuer to directory
No projections	Cold start	Slower first queries	Pre-compute on import
Time drift	>24 hours	Staleness warnings	Update time anchor

7.2 Emergency Recovery

If bundle import fails:

# Check bundle integrity
stellaops vexlens import verify --bundle /import/bundle --verbose

# Attempt partial import
stellaops vexlens import --bundle /import/bundle --skip-corrupted

# Rollback to previous state
stellaops vexlens import rollback --to vexlens-bundle-2025-11-29

---

8) Bundle Management

8.1 Retention Policy

vexlens:
  bundles:
    # Keep last N bundles
    retentionCount: 5
    # Minimum age before deletion
    minimumAgeDays: 30
    # Archive location
    archivePath: /archive/vexlens-bundles

8.2 Storage Requirements

Data Type	Typical Size	Compression Ratio
Issuers	1-5 MB	5:1
Statements	100-500 MB	10:1
Projections	50-200 MB	8:1
Total Bundle	150-700 MB	8:1

8.3 Bundle Cleanup

# Clean old bundles
stellaops vexlens bundles cleanup --keep 5

# Archive bundles older than 30 days
stellaops vexlens bundles archive --older-than 30d --to /archive

---

9) Security Considerations

9.1 Bundle Signing

All bundles should be signed before transfer:

# Verify signature chain
stellaops vexlens import verify-chain \
  --bundle /import/bundle \
  --trust-root /etc/vexlens/root-ca.pem

9.2 Transfer Security

1. Use encrypted removable media
2. Maintain custody chain documentation
3. Verify checksums at each transfer point
4. Log all bundle operations

9.3 Access Control

vexlens:
  security:
    # Require authentication for import
    importRequiresAuth: true
    # Allowed import roles
    importRoles: [vexlens.admin, vexlens.operator]
    # Audit all imports
    auditImports: true

---

10) Troubleshooting

10.1 Common Issues

Issue	Cause	Resolution
Import fails	Corrupted bundle	Re-export from source
Signature invalid	Wrong trust root	Update trust anchors
Time anchor expired	Stale time anchor	Generate new anchor
Missing issuers	Incomplete export	Include issuers in export

10.2 Diagnostic Commands

# Verify bundle contents
stellaops vexlens bundle inspect /import/bundle

# Check import readiness
stellaops vexlens import preflight --bundle /import/bundle

# Generate diagnostic report
stellaops vexlens diagnostics --output /tmp/diag.json