Bundle Format Specification

evidence-bundle-20260109-123456.tar.gz
└── (tar.gz extraction)
    ├── manifest.json          # Bundle metadata and table of contents
    ├── run.json               # Collection execution context
    ├── checksums.sha256       # SHA-256 checksums of all files
    ├── signature.sig          # Ed25519 signature of checksums file
    ├── sources/               # Raw evidence artifacts
    │   ├── github/
    │   │   ├── org_settings.json
    │   │   ├── repo_acme_backend_branch_protection.json
    │   │   └── repo_acme_backend_codeowners.json
    │   ├── aws/
    │   │   ├── iam_password_policy.json
    │   │   ├── cloudtrail_trail_production_status.json
    │   │   └── cloudwatch_log_group_aws_lambda_api.json
    │   └── google_workspace/
    │       ├── 2sv_enforcement.json
    │       ├── admin_roles.json
    │       └── user_lifecycle.json
    └── derived/               # SDK-generated analysis
        ├── normalized.json    # Normalized control mappings
        └── hints.json         # Compliance recommendations

{
  "bundle_version": "1.0",
  "created_at": "2026-01-09T12:34:56Z",
  "framework": "soc2_type1",
  "controls": ["CC6.1", "CC6.6", "CC7.2"],
  "sources": ["github", "aws", "google_workspace"],
  "artifacts": [
    {
      "filename": "sources/github/org_settings.json",
      "source": "github",
      "controls": ["CC6.1"],
      "collected_at": "2026-01-09T12:35:00Z",
      "checksum": "abc123def456..."
    }
  ],
  "signer": {
    "algorithm": "Ed25519",
    "public_key": "def456789abc...",
    "key_id": "evidence-sdk-v1"
  },
  "sdk_version": "0.1.0"
}

{
  "collection_started_at": "2026-01-09T12:34:56Z",
  "collection_completed_at": "2026-01-09T12:35:12Z",
  "duration_seconds": 16,
  "sdk_version": "0.1.0",
  "config_file": "evidence.yaml",
  "host": {
    "hostname": "github-actions-runner-1",
    "platform": "linux",
    "arch": "x64"
  },
  "environment": {
    "NODE_VERSION": "20.10.0",
    "RUNNER_OS": "ubuntu-22.04",
    "CI": "true"
  },
  "artifacts_collected": 9,
  "total_size_bytes": 35678,
  "errors": [],
  "warnings": [
    {
      "source": "github",
      "message": "Branch protection not configured for repository: acme/sandbox",
      "severity": "low"
    }
  ]
}

abc123def456...  manifest.json
def456ghi789...  run.json
ghi789jkl012...  sources/github/org_settings.json
jkl012mno345...  sources/github/repo_acme_backend_branch_protection.json
mno345pqr678...  sources/github/repo_acme_backend_codeowners.json
pqr678stu901...  sources/aws/iam_password_policy.json
stu901vwx234...  sources/aws/cloudtrail_trail_production_status.json
vwx234yz0567...  sources/google_workspace/2sv_enforcement.json
yz0567abc890...  derived/normalized.json
abc890def123...  derived/hints.json

# Standard Unix verification
sha256sum -c checksums.sha256

# macOS verification
shasum -a 256 -c checksums.sha256

0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b
2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d

# Using evidence CLI (recommended)
evidence verify bundle.tar.gz

# Manual verification (advanced)
# Requires Ed25519 library (libsodium, noble-ed25519, etc.)

sources/
├── github/
│   ├── org_settings.json
│   ├── repo_{owner}_{repo}_branch_protection.json
│   └── repo_{owner}_{repo}_codeowners.json
├── aws/
│   ├── iam_password_policy.json
│   ├── cloudtrail_trail_{name}_status.json
│   ├── cloudtrail_trail_{name}_config.json
│   └── cloudwatch_log_group_{name}.json
└── google_workspace/
    ├── 2sv_enforcement.json
    ├── admin_roles.json
    ├── user_lifecycle.json
    └── domain_security.json

{
  "controls": {
    "CC6.1": {
      "satisfied": true,
      "evidence": [
        {
          "artifact": "sources/github/org_settings.json",
          "field": "two_factor_requirement_enabled",
          "value": true,
          "requirement": "2FA must be enforced",
          "status": "pass"
        },
        {
          "artifact": "sources/aws/iam_password_policy.json",
          "field": "MinimumPasswordLength",
          "value": 14,
          "requirement": "Password length >= 12",
          "status": "pass"
        }
      ]
    },
    "CC6.6": {
      "satisfied": true,
      "evidence": [
        {
          "artifact": "sources/github/repo_acme_backend_codeowners.json",
          "field": "content",
          "value": "present",
          "requirement": "CODEOWNERS file exists",
          "status": "pass"
        }
      ]
    },
    "CC7.2": {
      "satisfied": true,
      "evidence": [
        {
          "artifact": "sources/github/repo_acme_backend_branch_protection.json",
          "field": "required_pull_request_reviews.required_approving_review_count",
          "value": 2,
          "requirement": "Required reviewers >= 1",
          "status": "pass"
        },
        {
          "artifact": "sources/aws/cloudtrail_trail_production_status.json",
          "field": "IsLogging",
          "value": true,
          "requirement": "CloudTrail must be logging",
          "status": "pass"
        }
      ]
    }
  },
  "summary": {
    "controls_satisfied": 3,
    "controls_total": 3,
    "evidence_count": 6,
    "overall_status": "pass"
  }
}

{
  "recommendations": [
    {
      "severity": "low",
      "control": "CC7.2",
      "title": "Branch protection not configured for acme/sandbox",
      "description": "Repository 'acme/sandbox' does not have branch protection enabled for the main branch.",
      "remediation": {
        "steps": [
          "Go to Repository → Settings → Branches",
          "Add branch protection rule for 'main'",
          "Enable 'Require a pull request before merging'",
          "Set required approvers to 2"
        ],
        "documentation": "https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches"
      }
    }
  ],
  "summary": {
    "total_recommendations": 1,
    "severity_breakdown": {
      "critical": 0,
      "high": 0,
      "medium": 0,
      "low": 1
    }
  }
}

tar -czf evidence-bundle-20260109-123456.tar.gz \
  -C /tmp/bundle \
  .

tar -xzf evidence-bundle-20260109-123456.tar.gz -C /output/dir

cd extracted-bundle/
sha256sum -c checksums.sha256

manifest.json: OK
run.json: OK
sources/github/org_settings.json: OK
...

evidence-bundle-20260109-120000.tar.gz
├── manifest.json           (2 KB)
├── run.json                (1 KB)
├── checksums.sha256        (500 bytes)
├── signature.sig           (64 bytes)
├── sources/
│   └── github/
│       └── org_settings.json (3 KB)
└── derived/
    ├── normalized.json     (2 KB)
    └── hints.json          (1 KB)

evidence-bundle-20260109-123456.tar.gz
├── manifest.json           (5 KB)
├── run.json                (2 KB)
├── checksums.sha256        (2 KB)
├── signature.sig           (64 bytes)
├── sources/
│   ├── github/
│   │   ├── org_settings.json (3 KB)
│   │   ├── repo_acme_backend_branch_protection.json (2 KB)
│   │   ├── repo_acme_backend_codeowners.json (1 KB)
│   │   ├── repo_acme_frontend_branch_protection.json (2 KB)
│   │   └── repo_acme_api_branch_protection.json (2 KB)
│   ├── aws/
│   │   ├── iam_password_policy.json (3 KB)
│   │   └── cloudtrail_trail_production_status.json (2 KB)
│   └── google_workspace/
│       ├── 2sv_enforcement.json (1 KB)
│       ├── admin_roles.json (5 KB)
│       └── user_lifecycle.json (3 KB)
└── derived/
    ├── normalized.json     (3 KB)
    └── hints.json          (2 KB)

#!/bin/bash
# verify-bundle.sh - Verify evidence bundle integrity

BUNDLE=$1

if [ -z "$BUNDLE" ]; then
  echo "Usage: verify-bundle.sh <bundle.tar.gz>"
  exit 1
fi

# Extract bundle
echo "Extracting bundle..."
TEMP_DIR=$(mktemp -d)
tar -xzf "$BUNDLE" -C "$TEMP_DIR"

cd "$TEMP_DIR"

# Verify checksums
echo "Verifying checksums..."
if sha256sum -c checksums.sha256; then
  echo "✓ Checksums valid"
else
  echo "✗ Checksum verification failed"
  exit 1
fi

# Verify signature (requires evidence CLI)
echo "Verifying signature..."
if command -v evidence &> /dev/null; then
  evidence verify "$BUNDLE"
else
  echo "⚠ evidence CLI not found, skipping signature verification"
  echo "  Install with: npm install -g @evidence-oss/cli"
fi

# Cleanup
cd /
rm -rf "$TEMP_DIR"

echo "✓ Bundle verification complete"