Verify Bundle Integrity

Why Verification Matters

Evidence bundles are cryptographically signed to ensure:

1. Integrity - Bundle hasn't been modified since creation
2. Authenticity - Bundle was created by the holder of the private key
3. Non-repudiation - Creator cannot deny creating the bundle

This makes evidence bundles auditor-ready and legally defensible.

Verification Methods

You can verify bundles using:

1. evidence CLI (easiest) - evidence verify command
2. System tools (no dependencies) - sha256sum and openssl

Method 1: evidence CLI (Recommended)

The evidence CLI provides a single command for complete verification.

Verify Bundle

evidence verify evidence-bundle-*.tar.gz \
  --public-key ~/.evidence/keys/public.pem

What this checks:

1. ✅ Bundle extracts successfully
2. ✅ All files match SHA-256 checksums
3. ✅ Ed25519 signature is valid
4. ✅ Manifest structure is correct

Expected output (success):

Verifying bundle: evidence-bundle-20260109-123456.tar.gz

✓ Bundle extracted
✓ Manifest valid
✓ Checksums verified (12/12 files)
✓ Signature verified

Bundle is authentic and unmodified.

Bundle Details:
  Created: 2026-01-09T12:34:56Z
  Framework: soc2_type1
  Controls: CC6.1, CC6.6, CC7.2
  Sources: github, aws
  Artifacts: 12
  Signer: evidence-sdk/0.1.0

Output (failure):

Verifying bundle: evidence-bundle-20260109-123456.tar.gz

✓ Bundle extracted
✓ Manifest valid
✗ Checksums verified (11/12 files)
  ✗ sources/github/org_settings.json: checksum mismatch

✗ Bundle verification failed

The bundle has been tampered with or corrupted.

Verify with Different Public Key

To verify a bundle created by someone else, use their public key:

evidence verify evidence-bundle-*.tar.gz \
  --public-key /path/to/their-public-key.pem

Use case: Auditors verify bundles you've shared with them using your public key.

Method 2: System Tools (No Dependencies)

You can verify bundles without the evidence CLI using standard Unix tools. This demonstrates the inspectable nature of evidence bundles.

Step 1: Extract Bundle

tar -xzf evidence-bundle-20260109-123456.tar.gz
cd evidence-bundle-20260109-123456/

Step 2: Verify SHA-256 Checksums

sha256sum -c checksums.sha256

Expected output (success):

manifest.json: OK
run.json: OK
sources/github/org_settings.json: OK
sources/github/repo_acme_backend_branch_protection.json: OK
sources/aws/iam_password_policy.json: OK
derived/normalized.json: OK
derived/hints.json: OK

If any file is modified:

manifest.json: OK
sources/github/org_settings.json: FAILED
sha256sum: WARNING: 1 computed checksum did NOT match

Step 3: Verify Ed25519 Signature

Verify the signature over the checksums file:

# Extract signer's public key from manifest
cat manifest.json | jq -r '.signer.public_key' > signer-public-key.hex

# Convert hex to binary
xxd -r -p signer-public-key.hex > signer-public-key.bin

# Verify signature (requires openssl with Ed25519 support)
openssl dgst -sha256 -verify signer-public-key.pem -signature signature.sig checksums.sha256

Expected output:

Verified OK

Note: This method requires OpenSSL with Ed25519 support (OpenSSL 1.1.1+).

Verification Scenarios

Scenario 1: Auditor Verification

Auditor receives:

• evidence-bundle-20260109-123456.tar.gz
• Your public key (public.pem) via out-of-band channel (email, Slack, etc.)

Auditor verifies:

evidence verify evidence-bundle-20260109-123456.tar.gz \
  --public-key public.pem

Why out-of-band? Prevents man-in-the-middle attacks. Auditor confirms public key via separate channel (phone call, verified email, etc.).

Scenario 2: Continuous Verification

Set up automated verification in your CI/CD pipeline:

# .github/workflows/verify-evidence.yml
name: Verify Evidence Bundle

on:
  workflow_dispatch:

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Evidence CLI
        run: npm install -g @evidence-oss/cli

      - name: Verify bundle
        run: |
          evidence verify evidence-bundles/*.tar.gz \
            --public-key .evidence/public.pem

Scenario 3: Tamper Detection

Simulate tampering:

# Extract bundle
tar -xzf evidence-bundle-*.tar.gz
cd evidence-bundle-*/

# Modify an artifact
echo '{"two_factor_requirement_enabled": false}' > sources/github/org_settings.json

# Re-compress
cd ..
tar -czf evidence-bundle-tampered.tar.gz evidence-bundle-*/

# Try to verify
evidence verify evidence-bundle-tampered.tar.gz \
  --public-key ~/.evidence/keys/public.pem

Result:

✗ Checksums verified (11/12 files)
  ✗ sources/github/org_settings.json: checksum mismatch

✗ Bundle verification failed

Conclusion: Tampering is immediately detected by checksum mismatch.

Understanding the Verification Process

What Gets Hashed (SHA-256)

Each file in the bundle is hashed individually:

SHA256(manifest.json) = abc123...
SHA256(run.json) = def456...
SHA256(sources/github/org_settings.json) = ghi789...

These hashes are stored in checksums.sha256:

abc123...  manifest.json
def456...  run.json
ghi789...  sources/github/org_settings.json

What Gets Signed (Ed25519)

The checksums file itself is signed:

Signature = Ed25519_Sign(private_key, checksums.sha256)

This creates a chain of trust:

1. Files → Checksums (SHA-256)
2. Checksums → Signature (Ed25519)
3. Signature → Public Key (Verification)

Tamper any file → Checksum changes → Signature invalid

Public Key Distribution

Best Practices

1. Out-of-band distribution

   • Email public key separately from bundle
   • Confirm public key fingerprint via phone/video call
   • Use verified channels (company Slack, authenticated email)

2. Publish publicly

   • Add public.pem to your repository
   • Include in documentation
   • Verify fingerprint matches

3. Fingerprint verification

   # Generate fingerprint
   openssl pkey -pubin -in public.pem -outform DER | \
     openssl dgst -sha256 -binary | \
     base64

   Share fingerprint via multiple channels, verify match.

Security Note

Public keys are safe to share publicly. They can only verify signatures, not create them. Private keys must remain secret.

Common Issues

Signature Verification Fails (Wrong Public Key)

Symptom:

✗ Signature verification failed

Cause: Using wrong public key (not matching the private key that signed the bundle)

Solution:

• Confirm public key matches via out-of-band channel
• Check you're using the correct public key file
• Verify key hasn't been rotated

Checksum Verification Fails (Corruption)

Symptom:

✗ Checksums verified (11/12 files)

Cause: Bundle corrupted during transfer or storage

Solution:

• Re-download bundle
• Check file integrity before extraction
• Verify network transfer completed successfully

OpenSSL Ed25519 Not Supported

Symptom:

unknown option -verify

Cause: OpenSSL version too old (< 1.1.1)

Solution:

# Check version
openssl version
# Should be 1.1.1 or higher

# Upgrade OpenSSL (macOS)
brew upgrade openssl

# Use evidence CLI instead
evidence verify bundle.tar.gz --public-key public.pem

Next Steps

Understand How It Works Learn about the evidence SDK architecture: customer-run, read-only, inspectable.

How It Works →

Add More Evidence Sources Expand collection to AWS, Google Workspace, and more connectors.

Configure Connectors →

Automate with GitHub Actions Set up continuous evidence collection in your CI/CD pipeline.

GitHub Action Guide →

Troubleshooting Verification Issues See common verification problems and solutions.

Troubleshooting Guide →

Understand Bundle Format Deep dive into bundle structure and cryptographic signatures.

Bundle Format Reference →