Sources Configuration

Complete schema reference for configuring evidence sources in evidence.yaml.

Schema

sources:
  github:        # GitHub connector (optional)
    # ... GitHub configuration

  aws:           # AWS connector (optional)
    # ... AWS configuration

  google_workspace:  # Google Workspace connector (optional)
    # ... Google Workspace configuration

Requirements:

At least one source must be configured
Each source is optional but at least one required
Source names are fixed: github, aws, google_workspace

GitHub Source

Basic Schema

sources:
  github:
    mode: token                    # Required: 'token' (only mode currently)
    token_env: GITHUB_TOKEN        # Required: environment variable name
    org: your-org                  # Required: GitHub organization name
    repos:                         # Required: list of repositories
      - your-org/repo1
      - your-org/repo2
    branch: main                   # Optional: branch to check (default: main)

Fields

Field	Type	Required	Default	Description
`mode`	enum	Yes	-	Authentication mode: `token`
`token_env`	string	Yes	-	Environment variable containing GitHub token
`org`	string	Yes	-	GitHub organization name
`repos`	array	Yes	-	Repositories to collect from (format: `org/repo`)
`branch`	string	No	`main`	Branch to check for protection rules

Examples

Single repository:

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

Multiple repositories:

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

All repositories (wildcard):

sources:
  github:
    mode: token
    token_env: GITHUB_TOKEN
    org: acme
    repos: '*'  # Collects from all repos in org

Custom branch:

sources:
  github:
    mode: token
    token_env: GITHUB_TOKEN
    org: acme
    repos:
      - acme/backend
    branch: production  # Check 'production' branch instead of 'main'

Required Scopes

GitHub token must have these scopes:

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

Never use: repo (write access), admin:org (admin access)

Environment Variable

export GITHUB_TOKEN=ghp_your_token_here

Token format: ghp_ prefix (classic tokens)

AWS Source

Basic Schema

sources:
  aws:
    mode: env                      # Required: 'env' or 'assume_role'
    region: us-east-1              # Required: AWS region
    log_groups:                    # Optional: CloudWatch log groups
      - /aws/lambda/api
    cloudtrail:                    # Optional: CloudTrail configuration
      trails:
        - production-trail

Fields

Field	Type	Required	Default	Description
`mode`	enum	Yes	-	Authentication: `env` or `assume_role`
`region`	string	Yes	-	AWS region (e.g., `us-east-1`)
`regions`	array	No	-	Multiple regions (for multi-region)
`log_groups`	array	No	`[]`	CloudWatch log group names/patterns
`cloudtrail.trails`	array	No	`[]`	CloudTrail trail names

Authentication Modes

Environment mode (env):

sources:
  aws:
    mode: env
    region: us-east-1

Requires environment variables:

export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...
export AWS_REGION=us-east-1  # Optional, uses config if not set

Assume role mode (assume_role):

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

Examples

Basic (IAM + CloudTrail):

sources:
  aws:
    mode: env
    region: us-east-1

With log groups:

sources:
  aws:
    mode: env
    region: us-east-1
    log_groups:
      - /aws/lambda/production-api
      - /aws/lambda/production-worker
      - /aws/ecs/backend

With CloudTrail:

sources:
  aws:
    mode: env
    region: us-east-1
    cloudtrail:
      trails:
        - production-audit-trail
        - security-trail

Multi-region:

sources:
  aws:
    mode: env
    regions:
      - us-east-1
      - us-west-2
      - eu-west-1
    log_groups:
      - /aws/lambda/production-*

Wildcard log groups:

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

Required Permissions

IAM policy with these permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iam:GetAccountPasswordPolicy",
        "cloudtrail:DescribeTrails",
        "cloudtrail:GetTrailStatus",
        "logs:DescribeLogGroups"
      ],
      "Resource": "*"
    }
  ]
}

Never grant: Write permissions (Put*, Create*, Delete*)

Google Workspace Source

Basic Schema

sources:
  google_workspace:
    mode: service_account                          # Required: 'service_account'
    credentials_env: GOOGLE_APPLICATION_CREDENTIALS  # Required: env var
    customer_id: C0xxxxxxx                         # Required: customer ID
    admin_email: admin@example.com                 # Required: admin email
    domains:                                       # Optional: domains list
      - example.com

Fields

Field	Type	Required	Default	Description
`mode`	enum	Yes	-	Authentication: `service_account`
`credentials_env`	string	Yes	-	Environment variable with service account JSON path
`customer_id`	string	Yes	-	Google Workspace customer ID (format: `C0xxxxxxx`)
`admin_email`	string	Yes	-	Admin email for domain-wide delegation
`domains`	array	No	`[]`	Domains to collect from

Examples

Basic:

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

Multiple domains:

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

Required Scopes

Service account must have domain-wide delegation with these scopes:

https://www.googleapis.com/auth/admin.directory.user.readonly
https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly

Environment Variable

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

Service account JSON format:

{
  "type": "service_account",
  "project_id": "your-project",
  "private_key_id": "...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...",
  "client_email": "evidence@your-project.iam.gserviceaccount.com",
  "client_id": "...",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token"
}

Multi-Source Configuration

Configure multiple sources for comprehensive evidence collection:

sources:
  # Code repository
  github:
    mode: token
    token_env: GITHUB_TOKEN
    org: acme
    repos: '*'

  # Infrastructure
  aws:
    mode: env
    region: us-east-1
    log_groups:
      - /aws/lambda/production-*
    cloudtrail:
      trails:
        - production-audit-trail

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

Validation

The evidence SDK validates source configuration:

Schema Validation

# ❌ Missing required field
sources:
  github:
    mode: token
    # Missing: token_env, org, repos

Error:

Configuration validation failed:
  - sources.github.token_env: required field missing
  - sources.github.org: required field missing
  - sources.github.repos: required field missing

Value Validation

# ❌ Invalid value
sources:
  github:
    mode: invalid_mode  # Only 'token' supported

Error:

Configuration validation failed:
  - sources.github.mode: must be 'token'

Connection Testing

Before collection, SDK tests each source:

Testing connections...
  ✓ GitHub (org: acme, scopes: repo:read, read:org)
  ✓ AWS (region: us-east-1, permissions: iam:Get*, cloudtrail:Describe*)
  ✓ Google Workspace (customer: C0xxxxxxx, scopes: directory.readonly)

Sources Configuration

Schema

GitHub Source

Basic Schema

Fields

Examples

Required Scopes

Environment Variable

AWS Source

Basic Schema

Fields

Authentication Modes

Examples

Required Permissions

Google Workspace Source

Basic Schema

Fields

Examples

Required Scopes

Environment Variable

Multi-Source Configuration

Validation

Schema Validation

Value Validation

Connection Testing

See Also

On this page