docs consoliation work
This commit is contained in:
StellaOps Bot
408
docs/modules/vex-lens/operations/offline-kit.md
Normal file
408
docs/modules/vex-lens/operations/offline-kit.md
Normal file
@@ -0,0 +1,408 @@
|
||||
# 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
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```yaml
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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):
|
||||
```bash
|
||||
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):
|
||||
```bash
|
||||
stellaops vexlens import verify --bundle /import/weekly-bundle
|
||||
```
|
||||
|
||||
4. **Import** (Offline environment):
|
||||
```bash
|
||||
stellaops vexlens import --bundle /import/weekly-bundle --mode incremental
|
||||
```
|
||||
|
||||
5. **Recompute** (If needed):
|
||||
```bash
|
||||
stellaops vexlens consensus recompute --since $(date -d '7 days ago' +%Y-%m-%d)
|
||||
```
|
||||
|
||||
### 6.2 Staleness Monitoring
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```yaml
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```yaml
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user