Configuration

Complete guide to evidence.yaml configuration with progressive examples.

Basic Configuration

The simplest possible configuration collects GitHub evidence for a single control:

framework: soc2_type1

controls:
  - CC6.1

sources:
  github:
    mode: token
    token_env: GITHUB_TOKEN
    org: your-org
    repos:
      - your-org/your-repo

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

What this collects:

GitHub organization 2FA settings
Branch protection rules for specified repo
CODEOWNERS file presence

Run:

export GITHUB_TOKEN=ghp_...
evidence collect

Framework Selection

Specify which compliance framework you're collecting evidence for:

framework: soc2_type1

Supported frameworks:

Framework	Description	Status
`soc2_type1`	SOC 2 Type I (point-in-time)	✅ Available
`soc2_type2`	SOC 2 Type II (over time)	🚧 Coming soon
`iso27001`	ISO 27001	🚧 Planned
`pci_dss`	PCI-DSS	🚧 Planned

Type I vs Type II:

Type I: Point-in-time snapshot of controls
Type II: Controls operating over 3-6 months

Control Selection

Specify which SOC 2 controls to collect evidence for:

controls:
  - CC6.1   # Logical Access Controls
  - CC6.6   # Access Removal/Modification
  - CC7.2   # Change Management

Available controls (SOC 2 Type I):

Control	Name	Connectors
`CC6.1`	Logical Access Controls	GitHub, AWS, Google Workspace
`CC6.6`	Access Removal/Modification	GitHub, Google Workspace
`CC7.2`	Change Management	GitHub, AWS

See SOC 2 Controls for detailed control mappings.

Source Configuration

Configure which systems to collect evidence from.

GitHub Connector

Basic (public repos):

sources:
  github:
    mode: token
    token_env: GITHUB_TOKEN
    org: your-org
    repos:
      - your-org/backend
      - your-org/frontend

Common (all repos in org):

sources:
  github:
    mode: token
    token_env: GITHUB_TOKEN
    org: your-org
    repos: '*'           # Collect for all repos
    branch: main         # Default branch to check

Advanced (multiple orgs):

sources:
  github:
    mode: token
    token_env: GITHUB_TOKEN
    orgs:
      - name: acme-corp
        repos:
          - acme-corp/backend
          - acme-corp/frontend
      - name: acme-labs
        repos:
          - acme-labs/research

Required scopes:

repo:read or public_repo (for public repos)
read:org

See GitHub Connector Reference for all options.

AWS Connector

Basic:

sources:
  aws:
    mode: env                    # Read from AWS env vars
    region: us-east-1
    log_groups:
      - /aws/lambda/api

Common (multiple regions):

sources:
  aws:
    mode: env
    regions:
      - us-east-1
      - us-west-2
    log_groups:
      - /aws/lambda/production-*
      - /aws/ecs/backend
    cloudtrail:
      trails:
        - production-trail
        - audit-trail

Advanced (cross-account):

sources:
  aws:
    mode: assume_role
    role_arn: arn:aws:iam::123456789012:role/evidence-collector
    external_id: evidence-sdk
    region: us-east-1
    log_groups:
      - /aws/lambda/prod-*

Required permissions:

iam:GetAccountPasswordPolicy
cloudtrail:DescribeTrails
cloudtrail:GetTrailStatus
logs:DescribeLogGroups

See AWS Connector Reference for all options.

Google Workspace Connector

Basic:

sources:
  google_workspace:
    mode: service_account
    credentials_env: GOOGLE_APPLICATION_CREDENTIALS
    customer_id: C0xxxxxxx
    admin_email: admin@example.com

Common (multiple domains):

sources:
  google_workspace:
    mode: service_account
    credentials_env: GOOGLE_APPLICATION_CREDENTIALS
    customer_id: C0xxxxxxx
    admin_email: admin@example.com
    domains:
      - example.com
      - subsidiary.example.com

Required scopes:

admin.directory.user.readonly
admin.directory.rolemanagement.readonly

See Google Workspace Connector Reference for all options.

Bundle Configuration

Control how bundles are created and signed.

Signing Configuration

Basic (default location):

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

Common (separate keys per environment):

bundle:
  signing:
    private_key_path: ./keys/production-private.pem
    # Public key derived automatically

Advanced (key from environment variable):

bundle:
  signing:
    private_key_env: EVIDENCE_SIGNING_KEY
    # Reads base64-encoded private key from env var

Bundle Size Limits

Default (50MB max):

bundle:
  max_size_mb: 50

Custom limit:

bundle:
  max_size_mb: 100  # Increase for large orgs

Why limits matter:

Prevents accidentally collecting source code (large files)
Ensures reasonable upload times
Policy enforcement (bundles should be small)

Upload Configuration

Configure automatic upload to evidence platform.

Disabled (default):

# No upload section = manual upload only

Basic upload:

upload:
  enabled: true
  api_url: https://api.evidence-platform.com

Common (with retention):

upload:
  enabled: true
  api_url: https://api.evidence-platform.com
  retention_days: 365
  tags:
    environment: production
    team: security

Advanced (conditional upload):

upload:
  enabled: true
  api_url: https://api.evidence-platform.com
  only_if_verified: true   # Only upload verified bundles
  retry_attempts: 3
  timeout_seconds: 300

Complete Examples

Example 1: Minimal GitHub-Only

framework: soc2_type1
controls:
  - CC6.1

sources:
  github:
    mode: token
    token_env: GITHUB_TOKEN
    org: acme
    repos:
      - acme/backend

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

Use case: Small team, single repo, getting started

Example 2: Multi-Source Production

framework: soc2_type1
controls:
  - CC6.1
  - CC6.6
  - CC7.2

sources:
  github:
    mode: token
    token_env: GITHUB_TOKEN
    org: acme
    repos:
      - acme/backend
      - acme/frontend
      - acme/api
    branch: main

  aws:
    mode: env
    region: us-east-1
    log_groups:
      - /aws/lambda/production-api
      - /aws/lambda/production-worker
    cloudtrail:
      trails:
        - production-audit-trail

  google_workspace:
    mode: service_account
    credentials_env: GOOGLE_APPLICATION_CREDENTIALS
    customer_id: C0xxxxxxx
    admin_email: admin@acme.com

bundle:
  signing:
    private_key_path: ~/.evidence/keys/production.pem
  max_size_mb: 75

upload:
  enabled: true
  api_url: https://api.evidence-platform.com
  retention_days: 365
  tags:
    environment: production
    compliance: soc2

Use case: Full SOC 2 Type I collection across all systems

Example 3: CI/CD Scheduled Collection

framework: soc2_type1
controls:
  - CC6.1
  - CC6.6
  - CC7.2

sources:
  github:
    mode: token
    token_env: GITHUB_TOKEN
    org: acme
    repos: '*'  # All repos in org

  aws:
    mode: env
    region: us-east-1
    log_groups: '*'  # All log groups

bundle:
  signing:
    private_key_env: EVIDENCE_SIGNING_KEY  # From GitHub Secrets
  max_size_mb: 100

upload:
  enabled: true
  api_url: https://api.evidence-platform.com
  only_if_verified: true

Use case: Automated monthly collection in GitHub Actions

Environment Variables

Reference environment variables in configuration:

Token/Credentials:

token_env: GITHUB_TOKEN           # Reads from $GITHUB_TOKEN
credentials_env: GOOGLE_CREDS     # Reads from $GOOGLE_CREDS

Private Keys:

private_key_env: SIGNING_KEY      # Reads base64-encoded key from $SIGNING_KEY

Setting environment variables:

# Local development
export GITHUB_TOKEN=ghp_...
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

# GitHub Actions
# Set in repository secrets, referenced in workflow
env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  EVIDENCE_SIGNING_KEY: ${{ secrets.EVIDENCE_SIGNING_KEY }}

Configuration Validation

The evidence CLI validates configuration before collection:

evidence collect --config evidence.yaml

Validation checks:

Schema validation
- YAML syntax correct
- Required fields present
- Field types correct
Framework validation
- Framework supported
- Controls valid for framework
Source validation
- Connector configuration valid
- Required fields present for connector mode
Credential validation
- Environment variables set
- Files exist at specified paths
- Keys have correct format
Connection testing
- API credentials work
- Permissions sufficient
- Rate limits not exceeded

Example validation output:

✓ Configuration schema valid
✓ Framework supported: soc2_type1
✓ Controls valid: CC6.1, CC6.6, CC7.2

Validating sources...
  ✓ GitHub token found: GITHUB_TOKEN
  ✓ GitHub scopes valid: repo:read, read:org
  ✓ GitHub connection successful
  ✓ AWS credentials found
  ✓ AWS permissions valid
  ✓ AWS connection successful

✓ Configuration valid. Ready to collect evidence.

Configuration Best Practices

1. Use Environment Variables for Secrets

Good:

token_env: GITHUB_TOKEN
private_key_env: SIGNING_KEY

Bad:

token: ghp_hardcoded_token_here  # Never do this!

2. Version Control Configuration

Good:

git add evidence.yaml
git commit -m "Add evidence collection config"

Exclude secrets:

# .gitignore
*.pem
.env
.env.local

3. Separate Configs Per Environment

evidence.dev.yaml      # Development
evidence.staging.yaml  # Staging
evidence.prod.yaml     # Production

evidence collect --config evidence.prod.yaml

4. Document Required Permissions

# evidence.yaml
# Required environment variables:
#   GITHUB_TOKEN - Personal access token with repo:read, read:org
#   AWS_ACCESS_KEY_ID - AWS access key
#   AWS_SECRET_ACCESS_KEY - AWS secret key
#   EVIDENCE_SIGNING_KEY - Base64-encoded Ed25519 private key

framework: soc2_type1
# ...

5. Start Small, Expand Gradually

# Week 1: GitHub only
sources:
  github: {...}

# Week 2: Add AWS
sources:
  github: {...}
  aws: {...}

# Week 3: Add Google Workspace
sources:
  github: {...}
  aws: {...}
  google_workspace: {...}

Next Steps

Explore Connectors Learn what each connector collects and how to configure them.

Connector Guide →

Understand Bundle Format See how configuration affects bundle structure.

Bundle Format →

Set Up GitHub Actions Automate evidence collection with CI/CD.

GitHub Action Guide →

Configuration

On this page