VEX Lens Offline Kit

Air-gapped operations guide for the VEX Lens consensus engine.

This guide is for operators running VEX Lens in disconnected or air-gapped environments. It covers offline bundle structure, creation, transfer, import, configuration, and the operational procedures that keep consensus data fresh without network access. For the general (connected) install, see VEX Lens Deployment.

1) Overview

VEX Lens can operate in fully air-gapped environments using pre-loaded VEX data and issuer directories. All trust roots, statements, and projections are delivered as signed bundles, verified against local trust anchors, and imported without any external connectivity.

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-web",
  "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
    postgresql:
      connectionString: Host=localhost;Database=stellaops;Username=stellaops;Password=password
    # No external cache
    valkey:
      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

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

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

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

11) See Also

• VEX Lens Deployment — connected (non-air-gapped) install and release checklist.
• VEX Lens architecture — consensus pipeline, storage, and export internals.
• Issuer Directory and Trust — trust roots and allowlists shipped inside offline bundles.