git.stella-ops.org/src/Cli/OFFLINE_POE_VERIFICATION.md

Offline Proof of Exposure (PoE) Verification Guide

Last updated: 2025-12-23. Owner: CLI Guild.

This guide provides step-by-step instructions for verifying Proof of Exposure artifacts in offline, air-gapped environments. It covers exporting PoE bundles, transferring them securely, and running verification without network access.

---

1. Overview

1.1 What is Offline PoE Verification?

Offline verification allows auditors to validate vulnerability reachability claims without internet access by:

• Verifying DSSE signatures against trusted keys
• Checking content integrity via cryptographic hashes
• Confirming policy bindings
• (Optional) Validating Rekor inclusion proofs from cached checkpoints

1.2 Use Cases

• Air-gapped environments: Verify PoE artifacts in isolated networks
• Regulatory compliance: Provide auditable proof for SOC2, FedRAMP, PCI audits
• Sovereign deployments: Verify artifacts with regional crypto standards (GOST, SM2)
• Incident response: Analyze vulnerability reachability offline during security events

1.3 Prerequisites

Tools Required:

• stella CLI (StellaOps command-line interface)
• Trusted public keys for signature verification
• (Optional) Rekor checkpoint file for transparency log verification

Knowledge Required:

• Basic understanding of DSSE (Dead Simple Signing Envelope)
• Familiarity with container image digests and PURLs
• Understanding of CVE identifiers

---

2. Quick Start (5-Minute Walkthrough)

Step 1: Export PoE Artifact

On connected system:

stella poe export \
  --finding CVE-2021-44228:pkg:maven/log4j@2.14.1 \
  --scan-id scan-abc123 \
  --output ./poe-export/

# Output:
# Exported PoE artifacts to ./poe-export/
#   - poe.json (4.5 KB)
#   - poe.json.dsse (2.3 KB)
#   - trusted-keys.json (1.2 KB)
#   - rekor-checkpoint.json (0.8 KB) [optional]

Step 2: Transfer to Offline System

# Create tarball for transfer
tar -czf poe-bundle.tar.gz -C ./poe-export .

# Transfer via USB, secure file share, or other air-gap bridge
# Verify checksum before transfer:
sha256sum poe-bundle.tar.gz

Step 3: Verify on Offline System

On air-gapped system:

# Extract bundle
tar -xzf poe-bundle.tar.gz -C ./verify/

# Run verification
stella poe verify \
  --poe ./verify/poe.json \
  --offline \
  --trusted-keys ./verify/trusted-keys.json

# Output:
# PoE Verification Report
# =======================
# ✓ DSSE signature valid (key: scanner-signing-2025)
# ✓ Content hash verified
# ✓ Policy digest matches
# Status: VERIFIED

---

3. Detailed Export Workflow

3.1 Export Single PoE Artifact

Command:

stella poe export --finding <CVE>:<PURL> --scan-id <ID> --output <DIR>

Example:

stella poe export \
  --finding CVE-2021-44228:pkg:maven/log4j@2.14.1 \
  --scan-id scan-abc123 \
  --output ./poe-export/ \
  --include-rekor-proof

Output Structure:

./poe-export/
├── poe.json                     # Canonical PoE artifact
├── poe.json.dsse                # DSSE signature envelope
├── trusted-keys.json            # Public keys for verification
├── rekor-checkpoint.json        # Rekor transparency log checkpoint
└── metadata.json                # Export metadata (timestamp, version, etc.)

3.2 Export Multiple PoEs (Batch Mode)

Command:

stella poe export \
  --scan-id scan-abc123 \
  --all-reachable \
  --output ./poe-batch/

Output Structure:

./poe-batch/
├── manifest.json                # Index of all PoEs in bundle
├── poe-7a8b9c0d.json            # PoE for CVE-2021-44228
├── poe-7a8b9c0d.json.dsse
├── poe-1a2b3c4d.json            # PoE for CVE-2022-XXXXX
├── poe-1a2b3c4d.json.dsse
├── trusted-keys.json
└── rekor-checkpoint.json

3.3 Export Options

Option	Description	Default
--finding <CVE>:<PURL>	Specific finding to export	Required (unless --all-reachable)
--scan-id <ID>	Scan identifier	Required
--output <DIR>	Output directory	./poe-export/
--include-rekor-proof	Include Rekor inclusion proof	true
--include-subgraph	Include parent richgraph-v1	false
--include-sbom	Include SBOM artifact	false
--all-reachable	Export all reachable findings	false
--format <tar.gz|zip>	Archive format	tar.gz

---

4. Detailed Verification Workflow

4.1 Basic Verification

Command:

stella poe verify --poe <path-or-hash> [options]

Example:

stella poe verify \
  --poe ./verify/poe.json \
  --offline \
  --trusted-keys ./verify/trusted-keys.json

Verification Steps Performed:

1. ✓ Load PoE artifact and DSSE envelope
2. ✓ Verify DSSE signature against trusted keys
3. ✓ Compute BLAKE3-256 hash and verify content integrity
4. ✓ Parse PoE structure and validate schema
5. ✓ Display verification results

4.2 Advanced Verification (with Policy Binding)

Command:

stella poe verify \
  --poe ./verify/poe.json \
  --offline \
  --trusted-keys ./verify/trusted-keys.json \
  --check-policy sha256:abc123... \
  --verbose

Additional Checks:

• ✓ Verify policy digest matches expected value
• ✓ Validate policy evaluation timestamp is recent
• ✓ Display policy details (policyId, version)

4.3 Rekor Inclusion Verification (Offline)

Command:

stella poe verify \
  --poe ./verify/poe.json \
  --offline \
  --trusted-keys ./verify/trusted-keys.json \
  --rekor-checkpoint ./verify/rekor-checkpoint.json

Rekor Verification:

• ✓ Load cached Rekor checkpoint (from last online sync)
• ✓ Verify inclusion proof against checkpoint
• ✓ Validate log index and tree size
• ✓ Confirm timestamp is within acceptable window

4.4 Verification Options

Option	Description	Required
--poe <path-or-hash>	PoE file path or hash	Yes
--offline	Enable offline mode (no network)	Recommended
--trusted-keys <path>	Path to trusted keys JSON	Yes (offline mode)
--check-policy <digest>	Verify policy digest	No
--rekor-checkpoint <path>	Cached Rekor checkpoint	No
--verbose	Detailed output	No
--output <format>	Output format: table|json|summary	table
--strict	Fail on warnings (e.g., expired keys)	No

---

5. Verification Output Formats

5.1 Table Format (Default)

PoE Verification Report
=======================
PoE Hash:       blake3:7a8b9c0d1e2f3a4b...
Vulnerability:  CVE-2021-44228
Component:      pkg:maven/log4j@2.14.1
Build ID:       gnu-build-id:5f0c7c3c...
Generated:      2025-12-23T10:00:00Z

Verification Checks:
✓ DSSE signature valid (key: scanner-signing-2025)
✓ Content hash verified
✓ Policy digest matches (sha256:abc123...)
✓ Schema validation passed

Subgraph Summary:
  Nodes:        8 functions
  Edges:        12 call relationships
  Paths:        3 distinct paths (shortest: 4 hops)
  Entry Points: main(), UserController.handleRequest()
  Sink:         org.apache.logging.log4j.Logger.error()

Guard Predicates:
  - feature:dark-mode (1 edge)
  - platform:linux (0 edges)

Status: VERIFIED

5.2 JSON Format

stella poe verify --poe ./poe.json --offline --output json > result.json

Output:

{
  "status": "verified",
  "poeHash": "blake3:7a8b9c0d1e2f3a4b...",
  "subject": {
    "vulnId": "CVE-2021-44228",
    "componentRef": "pkg:maven/log4j@2.14.1",
    "buildId": "gnu-build-id:5f0c7c3c..."
  },
  "checks": {
    "dsseSignature": {"passed": true, "keyId": "scanner-signing-2025"},
    "contentHash": {"passed": true, "algorithm": "blake3"},
    "policyBinding": {"passed": true, "digest": "sha256:abc123..."},
    "schemaValidation": {"passed": true, "version": "v1"}
  },
  "subgraph": {
    "nodeCount": 8,
    "edgeCount": 12,
    "pathCount": 3,
    "shortestPathLength": 4
  },
  "timestamp": "2025-12-23T11:00:00Z"
}

5.3 Summary Format (Concise)

stella poe verify --poe ./poe.json --offline --output summary

Output:

CVE-2021-44228 in pkg:maven/log4j@2.14.1: VERIFIED
  Hash: blake3:7a8b9c0d...
  Paths: 3 (4-6 hops)
  Signature: ✓ scanner-signing-2025

---

6. Trusted Keys Management

6.1 Trusted Keys Format

File: trusted-keys.json

{
  "keys": [
    {
      "keyId": "scanner-signing-2025",
      "algorithm": "ECDSA-P256",
      "publicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEw...\n-----END PUBLIC KEY-----",
      "validFrom": "2025-01-01T00:00:00Z",
      "validUntil": "2025-12-31T23:59:59Z",
      "purpose": "Scanner signing",
      "revoked": false
    },
    {
      "keyId": "scanner-signing-2024",
      "algorithm": "ECDSA-P256",
      "publicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEw...\n-----END PUBLIC KEY-----",
      "validFrom": "2024-01-01T00:00:00Z",
      "validUntil": "2024-12-31T23:59:59Z",
      "purpose": "Scanner signing (previous year)",
      "revoked": false
    }
  ],
  "updatedAt": "2025-12-23T00:00:00Z"
}

6.2 Key Distribution

Online Distribution:

# Fetch latest trusted keys from StellaOps backend
stella keys fetch --output ./trusted-keys.json

Offline Distribution:

• Include trusted-keys.json in offline update kits
• Distribute via secure channels (USB, secure file share)
• Verify checksum before use

Key Pinning (Strict Mode):

# Only accept signatures from specific key ID
stella poe verify \
  --poe ./poe.json \
  --offline \
  --trusted-keys ./trusted-keys.json \
  --pin-key scanner-signing-2025

6.3 Key Rotation Handling

Scenario: PoE signed with old key (scanner-signing-2024), but you only have new key (scanner-signing-2025).

Solution:

1. Include both old and new keys in trusted-keys.json
2. Verification will succeed if any trusted key validates signature
3. (Optional) Set --strict to reject expired keys

Example:

stella poe verify \
  --poe ./poe.json \
  --offline \
  --trusted-keys ./trusted-keys.json
# Output: ✓ DSSE signature valid (key: scanner-signing-2024, EXPIRED but trusted)

---

7. Rekor Checkpoint Verification

7.1 What is a Rekor Checkpoint?

A Rekor checkpoint is a cryptographically signed snapshot of the transparency log state at a specific point in time. It includes:

• Log size (total entries)
• Root hash (Merkle tree root)
• Timestamp
• Signature by Rekor log operator

7.2 Checkpoint Format

File: rekor-checkpoint.json

{
  "origin": "rekor.sigstore.dev",
  "size": 50000000,
  "hash": "c0d23d6ad406973f9559f3ba2d1ca01f84147d8ffc5b8445c224f98b9591801d",
  "timestamp": "2025-12-23T00:00:00Z",
  "signature": "-----BEGIN SIGNATURE-----\n...\n-----END SIGNATURE-----"
}

7.3 Offline Rekor Verification

Command:

stella poe verify \
  --poe ./poe.json \
  --offline \
  --rekor-checkpoint ./rekor-checkpoint.json

Verification Steps:

1. Load PoE and DSSE envelope
2. Load cached Rekor checkpoint
3. Load Rekor inclusion proof (from poe.json.rekor)
4. Verify inclusion proof against checkpoint root hash
5. Confirm log index is within checkpoint size
6. Display verification result

Output:

Rekor Verification:
✓ Inclusion proof valid
✓ Log index: 12345678 (within checkpoint size: 50000000)
✓ Checkpoint timestamp: 2025-12-23T00:00:00Z
✓ Checkpoint signature valid
Status: VERIFIED

---

8. Troubleshooting

8.1 Signature Verification Failed

Error:

✗ DSSE signature verification failed
Reason: Signature does not match any trusted key

Possible Causes:

1. Wrong trusted keys file: Ensure trusted-keys.json contains the signing key
2. Corrupted artifact: Re-export PoE from source
3. Key ID mismatch: Check keyId in DSSE envelope matches trusted keys

Solution:

# Inspect DSSE envelope to see which key was used
jq '.signatures[0].keyid' poe.json.dsse

# Verify key is in trusted-keys.json
jq '.keys[] | select(.keyId == "scanner-signing-2025")' trusted-keys.json

# If key is missing, re-export with correct key or update trusted keys

8.2 Hash Mismatch

Error:

✗ Content hash verification failed
Expected: blake3:7a8b9c0d...
Computed: blake3:1a2b3c4d...

Possible Causes:

1. Corrupted file: File was modified during transfer
2. Encoding issue: Line ending conversion (CRLF vs LF)
3. Wrong file: Exported different PoE than expected

Solution:

# Verify file integrity with checksum
sha256sum poe.json

# Re-export PoE from source with checksum verification
stella poe export --finding CVE-2021-44228:pkg:maven/log4j@2.14.1 \
  --scan-id scan-abc123 \
  --output ./poe-export/ \
  --verify-checksum

8.3 Policy Digest Mismatch

Error:

✗ Policy digest verification failed
Expected: sha256:abc123...
Found:    sha256:def456...

Possible Causes:

1. Policy version changed: PoE was generated with different policy version
2. Wrong policy digest provided: CLI argument incorrect

Solution:

# Check PoE metadata for policy digest
jq '.metadata.policy.policyDigest' poe.json

# Verify against expected policy version
# If mismatch is expected (policy updated), omit --check-policy flag
stella poe verify --poe ./poe.json --offline

8.4 Rekor Checkpoint Too Old

Warning:

⚠ Rekor checkpoint is outdated
Checkpoint timestamp: 2025-01-15T00:00:00Z
PoE generated: 2025-12-23T10:00:00Z

Possible Causes:

1. Stale checkpoint: Checkpoint was cached before PoE was generated
2. Clock skew: System clocks are out of sync

Solution:

# Accept warning (PoE is still valid, just can't verify Rekor inclusion)
stella poe verify --poe ./poe.json --offline --skip-rekor

# Or fetch updated checkpoint (requires online access)
stella rekor checkpoint-fetch --output ./rekor-checkpoint.json

---

9. Batch Verification

9.1 Verify All PoEs in Directory

Command:

stella poe verify-batch \
  --input ./poe-batch/ \
  --offline \
  --trusted-keys ./trusted-keys.json \
  --output ./verification-results.json

Output:

{
  "totalPoEs": 15,
  "verified": 14,
  "failed": 1,
  "results": [
    {"poeHash": "blake3:7a8b9c0d...", "status": "verified", "vulnId": "CVE-2021-44228"},
    {"poeHash": "blake3:1a2b3c4d...", "status": "failed", "vulnId": "CVE-2022-XXXXX", "error": "Signature verification failed"},
    ...
  ]
}

9.2 Parallel Verification

Command:

stella poe verify-batch \
  --input ./poe-batch/ \
  --offline \
  --trusted-keys ./trusted-keys.json \
  --parallel 4  # Use 4 worker threads

Performance:

PoE Count	Serial Time	Parallel Time (4 threads)	Speedup
10	5s	2s	2.5x
50	25s	8s	3.1x
100	50s	15s	3.3x

---

10. Best Practices

10.1 Security Best Practices

1. Verify checksums before and after transfer:

   sha256sum poe-bundle.tar.gz > poe-bundle.tar.gz.sha256
   

2. Use strict mode in production:

   stella poe verify --poe ./poe.json --offline --strict
   

3. Pin keys for critical environments:

   stella poe verify --poe ./poe.json --pin-key scanner-signing-2025
   

4. Rotate keys every 90 days and update trusted-keys.json

5. Archive verified PoEs for audit trails

10.2 Operational Best Practices

1. Export PoEs regularly: Include in CI/CD pipeline
2. Test offline verification before relying on it for audits
3. Document key rotation procedures
4. Automate batch verification for large datasets
5. Monitor verification failures and investigate root causes

---

11. Example Workflows

11.1 SOC2 Audit Preparation

Goal: Prepare PoE artifacts for SOC2 auditor review

Steps:

# 1. Export all PoEs for production images
stella poe export \
  --all-reachable \
  --scan-id prod-release-v42 \
  --output ./audit-bundle/ \
  --include-rekor-proof \
  --include-sbom

# 2. Create audit package
tar -czf soc2-audit-$(date +%Y%m%d).tar.gz -C ./audit-bundle .

# 3. Generate checksum manifest
sha256sum soc2-audit-*.tar.gz > checksum.txt

# 4. Provide to auditor with verification instructions
cp OFFLINE_POE_VERIFICATION.md ./audit-package/

Auditor Workflow:

# 1. Extract bundle
tar -xzf soc2-audit-20251223.tar.gz -C ./verify/

# 2. Verify all PoEs
stella poe verify-batch \
  --input ./verify/ \
  --offline \
  --trusted-keys ./verify/trusted-keys.json \
  --output ./audit-results.json

# 3. Review results
jq '.verified, .failed' ./audit-results.json

11.2 Incident Response Investigation

Goal: Analyze vulnerability reachability during security incident

Steps:

# 1. Export PoE for suspected CVE
stella poe export \
  --finding CVE-2024-XXXXX:pkg:npm/vulnerable-lib@1.0.0 \
  --scan-id incident-scan-123 \
  --output ./incident-poe/

# 2. Verify offline (air-gapped IR environment)
stella poe verify \
  --poe ./incident-poe/poe.json \
  --offline \
  --verbose

# 3. Analyze call paths
jq '.subgraph.edges' ./incident-poe/poe.json

# 4. Identify entry points
jq '.subgraph.entryRefs' ./incident-poe/poe.json

---

12. Cross-References

• PoE Specification: src/Attestor/POE_PREDICATE_SPEC.md
• Subgraph Extraction: src/Scanner/__Libraries/StellaOps.Scanner.Reachability/SUBGRAPH_EXTRACTION.md
• Sprint Plan: docs/implplan/SPRINT_3500_0001_0001_proof_of_exposure_mvp.md
• Advisory: docs/product-advisories/23-Dec-2026 - Binary Mapping as Attestable Proof.md

---

Last updated: 2025-12-23. See Sprint 3500.0001.0001 for implementation plan.