Collect Your First Evidence

Prerequisites

Before you begin, you'll need:

• Evidence CLI installed (Install CLI)
• A GitHub account with access to an organization or repository
• A GitHub personal access token with repo:read and read:org scopes

Step 1: Generate Signing Keys

Evidence bundles are cryptographically signed for verification. Generate your signing key pair:

evidence init --generate-keys

What this does:

• Creates ~/.evidence/keys/private.pem (Ed25519 private key)
• Creates ~/.evidence/keys/public.pem (Ed25519 public key)
• Private key signs bundles, public key verifies them

Expected output:

✓ Generated Ed25519 key pair
  Private key: /Users/you/.evidence/keys/private.pem
  Public key:  /Users/you/.evidence/keys/public.pem

Keep your private key secure. Share your public key for verification.

Important: Never share your private key. Store it securely.

Step 2: Create GitHub Personal Access Token

1. Go to GitHub → Settings → Developer Settings → Personal Access Tokens (Classic)

2. Click Generate new token (classic)

3. Set token name: evidence-collection

4. Select scopes:

   • ✅ repo → public_repo (or full repo for private repos)
   • ✅ admin:org → read:org

5. Click Generate token

6. Copy the token (starts with ghp_) — you won't see it again

Step 3: Create Configuration File

Create evidence.yaml in your working directory:

framework: soc2_type1

controls:
  - CC6.1

sources:
  github:
    mode: token
    token_env: GITHUB_TOKEN
    org: your-org          # Replace with your GitHub org
    repos:
      - your-org/your-repo # Replace with your repository

bundle:
  signing:
    private_key_path: ~/.evidence/keys/private.pem

Replace:

• your-org with your GitHub organization name
• your-org/your-repo with a repository you have access to

What this configuration does:

• Collects evidence for SOC 2 Type I, control CC6.1 (Logical Access Controls)
• Uses GitHub connector to collect org settings and branch protection
• Reads GitHub token from GITHUB_TOKEN environment variable
• Signs bundle with your private key

Step 4: Set Environment Variables

Export your GitHub token:

export GITHUB_TOKEN=ghp_your_token_here

For persistent setup, add to your shell profile:

# Add to ~/.bashrc or ~/.zshrc
echo 'export GITHUB_TOKEN=ghp_your_token_here' >> ~/.zshrc
source ~/.zshrc

Security note: Never commit tokens to git. Use environment variables or secret managers.

Step 5: Collect Evidence

Run the collect command:

evidence collect

What happens:

1. Validates configuration - Checks evidence.yaml structure
2. Tests GitHub connection - Verifies token and permissions
3. Collects artifacts:
   • Organization settings (2FA enforcement)
   • Repository branch protection rules
   • CODEOWNERS file existence
4. Creates bundle:
   • Packages artifacts as JSON
   • Generates SHA-256 checksums
   • Signs with Ed25519 private key
   • Compresses as .tar.gz

Expected output:

✓ Configuration valid
✓ GitHub connection successful

Collecting evidence...
  ✓ GitHub org settings
  ✓ GitHub branch protection (your-org/your-repo)
  ✓ GitHub CODEOWNERS (your-org/your-repo)

Creating bundle...
  ✓ Manifest created
  ✓ Checksums generated
  ✓ Bundle signed
  ✓ Compressed to tar.gz

✓ Bundle created: evidence-bundles/evidence-bundle-20260109-123456.tar.gz

Size: 12.3 KB
Artifacts: 3
Verified: ✓ (checksums + signature valid)

Step 6: Inspect Your Bundle

Your bundle is a standard .tar.gz file. Extract and inspect it:

cd evidence-bundles
tar -xzf evidence-bundle-*.tar.gz
cd evidence-bundle-*/

Bundle structure:

evidence-bundle-20260109-123456/
├── manifest.json          # Bundle metadata
├── run.json               # Collection context
├── checksums.sha256       # SHA-256 of all files
├── signature.sig          # Ed25519 signature
├── sources/
│   └── github/
│       ├── org_settings.json
│       ├── repo_your-org_your-repo_branch_protection.json
│       └── repo_your-org_your-repo_codeowners.json
└── derived/
    ├── normalized.json    # Control mappings
    └── hints.json        # Compliance recommendations

View an artifact:

cat sources/github/org_settings.json | jq

Example output:

{
  "two_factor_requirement_enabled": true,
  "members_can_create_repositories": false,
  "members_can_create_public_repositories": false,
  "members_can_fork_private_repositories": false
}

What You Collected

Your bundle contains evidence for CC6.1 - Logical Access Controls:

• Organization Settings

  • ✅ 2FA enforcement enabled
  • ✅ Repository creation restrictions

• Branch Protection (for each repo)

  • Required reviewers count
  • Required status checks
  • Admin enforcement

• Code Review

  • CODEOWNERS file presence
  • Enforced code review requirement

Success!

You've collected your first evidence bundle. The bundle is:

• ✅ Signed - Ed25519 signature proves authenticity
• ✅ Verified - SHA-256 checksums ensure integrity
• ✅ Inspectable - Standard tar.gz + JSON format
• ✅ Auditor-ready - Can be verified with system tools

Next Steps

Verify Bundle Integrity Learn how to cryptographically verify your bundle using the public key.

Verify Your Bundle →

Add More Connectors Expand your evidence collection to AWS, Google Workspace, and more.

Configure Connectors →

Integrate with CI/CD Automate evidence collection with GitHub Actions.

GitHub Action Guide →