evidence verify

Verify bundle integrity using checksums and cryptographic signatures.

Synopsis

evidence verify <bundle> [options]

Description

The evidence verify command performs complete bundle verification:

Extracts bundle archive
Validates manifest structure
Verifies SHA-256 checksums of all files
Verifies Ed25519 signature
Checks bundle format version

Arguments

Argument	Type	Required	Description
`<bundle>`	string	Yes	Path to bundle file (.tar.gz)

Options

Flag	Type	Default	Description
`--public-key`, `-k`	string	(auto-detect)	Public key file for signature verification
`--output`, `-o`	string	(temp dir)	Directory to extract bundle for inspection
`--verbose`, `-v`	boolean	`false`	Detailed verification output
`--quiet`, `-q`	boolean	`false`	Minimal output
`--help`, `-h`	boolean	`false`	Show help

Examples

Basic Verification

Verify bundle with auto-detected public key:

evidence verify evidence-bundle-20260109-123456.tar.gz

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: 9
  Size: 35.1 KB
  Signer: evidence-sdk/0.1.0
  Signature algorithm: Ed25519

Output (failure):

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

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

✗ Bundle verification failed

The bundle has been tampered with or corrupted.
Do not use this bundle for compliance purposes.

Verify with Specific Public Key

Use explicit public key file:

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

Use case: Verifying bundles from someone else

Verify with Public Key from Different Location

evidence verify bundle.tar.gz \
  --public-key /auditor/vendor-public-keys/acme-public.pem

Workflow:

Receive bundle from vendor
Receive public key via separate channel (email, phone verification)
Verify bundle with vendor's public key

Extract Bundle for Inspection

Extract to specific directory while verifying:

evidence verify evidence-bundle-*.tar.gz \
  --output ./extracted-bundle

Creates:

./extracted-bundle/
├── manifest.json
├── run.json
├── checksums.sha256
├── signature.sig
├── sources/
│   └── github/
│       └── org_settings.json
└── derived/
    ├── normalized.json
    └── hints.json

Inspect files:

cd extracted-bundle
cat manifest.json | jq
cat sources/github/org_settings.json | jq
cat derived/normalized.json | jq

Verbose Verification

Show detailed verification steps:

evidence verify bundle.tar.gz --verbose

Additional output:

[DEBUG] Extracting bundle to temp directory
[DEBUG] Reading manifest: manifest.json
[DEBUG] Validating manifest schema
[DEBUG] Bundle version: 1.0 (supported)
[DEBUG] Verifying file: manifest.json
[DEBUG]   Expected: abc123...
[DEBUG]   Actual:   abc123...
[DEBUG]   ✓ Match
[DEBUG] Verifying file: sources/github/org_settings.json
[DEBUG]   Expected: def456...
[DEBUG]   Actual:   def456...
[DEBUG]   ✓ Match
[DEBUG] Reading signer public key from manifest
[DEBUG] Signature algorithm: Ed25519
[DEBUG] Verifying signature...
[DEBUG]   Message: checksums.sha256 (sha256: ghi789...)
[DEBUG]   Signature: jkl012...
[DEBUG]   Public key: mno345...
[DEBUG]   ✓ Signature valid

Quiet Mode

Minimal output for scripts:

evidence verify bundle.tar.gz --quiet

Output (success):

OK

Output (failure):

FAILED: Checksum mismatch

Exit code: 0 on success, 1 on failure

Verification Process

Step 1: Bundle Extraction

✓ Bundle extracted

Checks:

Archive is valid tar.gz
Extracts without errors
Expected file structure present

Step 2: Manifest Validation

✓ Manifest valid

Checks:

manifest.json exists and parses as JSON
Required fields present:
- bundle_version
- framework
- controls
- artifacts
- signer
Bundle version supported (currently 1.0)
Artifact list matches actual files

Step 3: Checksum Verification

✓ Checksums verified (12/12 files)

Process:

Read checksums.sha256 file
For each file listed:
- Compute actual SHA-256 hash
- Compare with expected hash
- Report match/mismatch
Verify all files accounted for

Example checksums.sha256:

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

Verification:

# System tools can verify
cd extracted-bundle
sha256sum -c checksums.sha256
# Output: All OK

Step 4: Signature Verification

✓ Signature verified

Process:

Extract signer public key from manifest
Read signature.sig file
Verify signature over checksums.sha256 using Ed25519
Report valid/invalid

Algorithm: Ed25519 (fast, secure, 64-byte signatures)

Verification chain:

Files → SHA-256 → Checksums file → Ed25519 → Signature
                                          ↓
                                    Public Key → Valid/Invalid

Public Key Handling

Auto-Detection

If --public-key not specified, CLI attempts to find public key:

From manifest: Extract signer.public_key field
From default location: ~/.evidence/keys/public.pem
From environment: EVIDENCE_PUBLIC_KEY variable

Example manifest:

{
  "signer": {
    "algorithm": "Ed25519",
    "public_key": "def456...",
    "key_id": "evidence-sdk-v1"
  }
}

Explicit Public Key

Provide specific public key file:

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

Public key format (PEM):

-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAXyz9876...
-----END PUBLIC KEY-----

Out-of-Band Verification

Best practice for auditor verification:

Receive bundle: via email, file transfer, etc.
Receive public key: via separate channel (phone, Slack, verified email)
Verify fingerprint: Confirm public key fingerprint matches
Verify bundle: Use confirmed public key

Generate fingerprint:

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

Example fingerprint:

abc123def456ghi789jkl012mno345pqr678stu901vwx234=

Confirm this matches via phone/video call.

Environment Variables

Variable	Description
`EVIDENCE_PUBLIC_KEY`	Path to public key file (if not specified)
`EVIDENCE_TEMP_DIR`	Temporary directory for extraction

Example:

export EVIDENCE_PUBLIC_KEY=/auditor/vendor-keys/acme.pem
evidence verify bundle.tar.gz
# Uses EVIDENCE_PUBLIC_KEY automatically

Exit Codes

Code	Meaning
`0`	Success - bundle verified
`1`	Verification failed - bundle tampered/corrupted
`2`	Extraction error - invalid archive
`3`	Manifest error - invalid structure
`4`	Public key error - not found or invalid
`5`	Unsupported bundle version

Verification Failures

Checksum Mismatch

Symptom:

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

Causes:

File tampered with after signing
File corrupted during transfer
Bundle extracted and re-compressed

Impact: Bundle is invalid, do not use

Signature Invalid

Symptom:

✗ Signature verification failed

Signature does not match checksums file.

Causes:

Wrong public key used
Checksums file modified
Signature created by different private key

Impact: Bundle is invalid, do not use

Missing Files

Symptom:

✗ Checksums verified (8/12 files)
  ✗ sources/aws/iam_password_policy.json: NOT FOUND

Causes:

Incomplete bundle extraction
Files deleted from bundle
Bundle corrupted

Impact: Bundle is incomplete, do not use

Manual Verification

Verify bundle without evidence CLI using system tools:

Step 1: Extract Bundle

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

Step 2: Verify Checksums

sha256sum -c checksums.sha256

Expected output:

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

Step 3: Verify Signature

Extract public key from manifest:

cat manifest.json | jq -r '.signer.public_key' > signer-key.hex

Convert hex to PEM (requires OpenSSL with Ed25519 support):

# This is complex, use evidence CLI instead
evidence verify ../evidence-bundle-*.tar.gz

Recommendation: Use evidence verify command for signature verification.

Common Issues

Public Key Not Found

Symptom:

✗ Verification failed

Error: Public key not found

Tried:
  - Command line argument (--public-key)
  - Manifest signer field
  - ~/.evidence/keys/public.pem
  - EVIDENCE_PUBLIC_KEY environment variable

Solution:

# Option 1: Specify public key
evidence verify bundle.tar.gz --public-key /path/to/public.pem

# Option 2: Set environment variable
export EVIDENCE_PUBLIC_KEY=/path/to/public.pem
evidence verify bundle.tar.gz

Bundle Corrupted During Transfer

Symptom:

✗ Bundle extraction failed

Error: gzip: invalid compressed data--format violated

Solution:

# Re-download bundle
# Verify download completed successfully
ls -lh bundle.tar.gz

# Check file integrity if hash provided
sha256sum bundle.tar.gz

Unsupported Bundle Version

Symptom:

✗ Manifest validation failed

Error: Unsupported bundle version: 2.0

This CLI supports bundle versions: 1.0

Update evidence CLI to latest version.

Solution:

npm install -g @evidence-oss/cli@latest
evidence verify bundle.tar.gz

evidence verify

Synopsis

Description

Arguments

Options

Examples

Basic Verification

Verify with Specific Public Key

Verify with Public Key from Different Location

Extract Bundle for Inspection

Verbose Verification

Quiet Mode

Verification Process

Step 1: Bundle Extraction

Step 2: Manifest Validation

Step 3: Checksum Verification

Step 4: Signature Verification

Public Key Handling

Auto-Detection

Explicit Public Key

Out-of-Band Verification

Environment Variables

Exit Codes

Verification Failures

Checksum Mismatch

Signature Invalid

Missing Files

Manual Verification

Step 1: Extract Bundle

Step 2: Verify Checksums

Step 3: Verify Signature

Common Issues

Public Key Not Found

Bundle Corrupted During Transfer

Unsupported Bundle Version

See Also

On this page