evidence collect

Collect evidence from configured sources and create signed bundles.

Synopsis

evidence collect [options]

Description

The evidence collect command:

Validates configuration file
Tests connections to all configured sources
Collects artifacts via read-only APIs
Normalizes evidence to SOC 2 controls
Generates compliance hints
Creates signed bundle (.tar.gz)

Options

Flag	Type	Default	Description
`--config`, `-c`	string	`./evidence.yaml`	Configuration file path
`--output`, `-o`	string	`./evidence-bundles`	Output directory for bundles
`--upload`, `-u`	boolean	`false`	Auto-upload after collection
`--dry-run`, `-d`	boolean	`false`	Validate without collecting
`--verbose`, `-v`	boolean	`false`	Verbose output
`--quiet`, `-q`	boolean	`false`	Minimal output
`--help`, `-h`	boolean	`false`	Show help

Examples

Basic Collection

Collect using default configuration:

evidence collect

Output:

✓ Configuration valid: evidence.yaml
✓ Framework: soc2_type1
✓ Controls: CC6.1, CC6.6, CC7.2

Testing connections...
  ✓ GitHub (org: acme)
  ✓ AWS (region: us-east-1)

Collecting evidence...
  GitHub:
    ✓ Org settings
    ✓ Branch protection (acme/backend)
    ✓ Branch protection (acme/frontend)
    ✓ CODEOWNERS (acme/backend)
    ✓ CODEOWNERS (acme/frontend)

  AWS:
    ✓ IAM password policy
    ✓ CloudTrail trails
    ✓ CloudTrail status
    ✓ CloudWatch log groups

  Collected: 9 artifacts (34.2 KB)

Normalizing evidence...
  ✓ Mapped to CC6.1 (3 artifacts)
  ✓ Mapped to CC6.6 (2 artifacts)
  ✓ Mapped to CC7.2 (4 artifacts)

Generating compliance hints...
  ℹ 2 informational hints
  ✓ All controls have evidence

Creating bundle...
  ✓ Manifest created
  ✓ SHA-256 checksums generated
  ✓ Ed25519 signature created
  ✓ Compressed to tar.gz

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

Bundle Details:
  Size: 35.1 KB
  Artifacts: 9
  Controls: CC6.1, CC6.6, CC7.2
  Verified: ✓

Next steps:
  - Verify: evidence verify evidence-bundles/evidence-bundle-*.tar.gz
  - Upload: evidence upload evidence-bundles/evidence-bundle-*.tar.gz

Custom Configuration Path

Use specific configuration file:

evidence collect --config ./config/evidence.production.yaml

Custom Output Directory

Save bundles to specific location:

evidence collect --output /secure/evidence-bundles

Collect and Upload

Automatically upload after collection:

evidence collect --upload

Requires:

Upload configuration in evidence.yaml
EVIDENCE_API_KEY environment variable

Output:

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

Uploading bundle...
  ✓ Authenticated with evidence platform
  ✓ Upload complete (2.3s)
  ✓ Bundle verified on platform

Upload URL: https://app.evidence-platform.com/bundles/bundle_abc123

Bundle ID: bundle_abc123

Dry Run

Validate configuration without collecting:

evidence collect --dry-run

Output:

✓ Configuration valid
✓ Connections successful

Dry run complete. No evidence collected.

Would collect from:
  - GitHub (5 artifacts)
  - AWS (4 artifacts)

Estimated bundle size: ~35 KB

Verbose Output

Show detailed progress:

evidence collect --verbose

Additional output:

[DEBUG] Loading configuration: evidence.yaml
[DEBUG] Validating schema...
[DEBUG] Testing GitHub connection: https://api.github.com/orgs/acme
[DEBUG] GitHub rate limit: 4998/5000 remaining
[DEBUG] Collecting: GET /orgs/acme
[DEBUG] Collecting: GET /repos/acme/backend/branches/main/protection
[DEBUG] Writing artifact: sources/github/org_settings.json (456 bytes)
...

Quiet Mode

Minimal output (for scripts):

evidence collect --quiet

Output:

evidence-bundles/evidence-bundle-20260109-123456.tar.gz

Exit code: 0 on success, non-zero on failure

Collection Process

Step 1: Configuration Validation

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

Validation checks:

YAML syntax
Required fields (framework, controls, sources, bundle.signing)
Framework support
Control validity
Source configuration completeness

Step 2: Connection Testing

Testing connections...
  ✓ GitHub (token valid, scopes: repo:read, read:org)
  ✓ AWS (credentials valid, permissions: iam:Get*, cloudtrail:Describe*)

Connection checks:

Credentials exist in environment
API authentication successful
Required permissions granted
Rate limits not exceeded

Step 3: Artifact Collection

Collecting evidence...
  GitHub:
    ✓ Org settings (456 bytes)
    ✓ Branch protection: acme/backend (1.2 KB)
    ✓ CODEOWNERS: acme/backend (234 bytes)

Collection behavior:

Read-only API calls only
Exponential backoff on rate limits
Automatic retries on transient errors
Progress tracking per connector

Step 4: Normalization

Normalizing evidence...
  ✓ Mapped to CC6.1 (GitHub 2FA, AWS password policy)
  ✓ Mapped to CC6.6 (GitHub CODEOWNERS)
  ✓ Mapped to CC7.2 (GitHub branch protection, AWS CloudTrail)

Creates:

derived/normalized.json - Control mappings
Pass/fail status per control
Evidence references per control

Step 5: Hint Generation

Generating compliance hints...
  ℹ AWS password expiration: 90 days (consider 60 days)
  ℹ Branch protection: 2 reviewers (consider 3 for production)

Creates:

derived/hints.json - Compliance recommendations
Severity levels: critical, high, medium, low, info
Categories: missing, misconfigured, partial, improvement

Step 6: Bundle Creation

Creating bundle...
  ✓ Manifest created
  ✓ SHA-256 checksums (12 files)
  ✓ Ed25519 signature
  ✓ Compressed (34.2 KB → 35.1 KB .tar.gz)

Creates:

manifest.json - Bundle metadata
run.json - Execution context
checksums.sha256 - Integrity verification
signature.sig - Authenticity proof
evidence-bundle-*.tar.gz - Final compressed bundle

Environment Variables

Variable	Required	Description
`GITHUB_TOKEN`	If using GitHub	GitHub personal access token
`AWS_ACCESS_KEY_ID`	If using AWS	AWS access key
`AWS_SECRET_ACCESS_KEY`	If using AWS	AWS secret key
`AWS_REGION`	If using AWS	AWS region (or in config)
`GOOGLE_APPLICATION_CREDENTIALS`	If using Google	Path to service account JSON
`EVIDENCE_API_KEY`	If `--upload`	API key for evidence platform

Example:

export GITHUB_TOKEN=ghp_...
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...
export AWS_REGION=us-east-1

evidence collect

Exit Codes

Code	Meaning
`0`	Success - bundle created
`1`	Configuration error
`2`	Connection error (auth, network)
`3`	Collection error (API failure)
`4`	Policy violation (forbidden data detected)
`5`	Bundle creation error
`6`	Upload error (if `--upload` used)

Bundle Naming

Bundles are named with timestamp:

evidence-bundle-YYYYMMDD-HHMMSS.tar.gz

Example:

evidence-bundle-20260109-123456.tar.gz
  └─ Collected on: 2026-01-09 at 12:34:56 UTC

Multiple collections:

evidence-bundles/
├── evidence-bundle-20260101-120000.tar.gz  # January
├── evidence-bundle-20260201-120000.tar.gz  # February
└── evidence-bundle-20260301-120000.tar.gz  # March

Performance

Typical collection times:

Sources	Artifacts	Time
GitHub only	3-5	5-10s
GitHub + AWS	8-12	15-25s
All 3 sources	12-20	30-45s

Factors affecting speed:

Number of repositories
API rate limits
Network latency
Number of controls

Common Issues

Missing Credentials

Symptom:

✗ Connection test failed: GitHub

Error: GITHUB_TOKEN environment variable not set

Solution:

export GITHUB_TOKEN=ghp_your_token_here
evidence collect

Invalid Scopes

Symptom:

✗ Configuration validation failed

Error: Forbidden scope: repo (write access)

evidence SDK only uses read-only scopes.

Solution: Update token to use read-only scopes:

repo:read instead of repo
read:org instead of admin:org

Rate Limiting

Symptom:

⚠ GitHub API rate limit reached

Waiting 60s before retry... (3/5 attempts)

Behavior:

Automatic exponential backoff
Up to 5 retry attempts
Eventually fails if rate limit persists

Solution:

# Check rate limit status
curl -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/rate_limit

# Wait for rate limit reset, or use different token

Bundle Size Exceeded

Symptom:

✗ Bundle creation failed

Error: Bundle size (52.3 MB) exceeds limit (50 MB)

Large artifacts:
  - sources/github/repo_files.json (45 MB)

Solution:

# Option 1: Increase limit
bundle:
  max_size_mb: 100

# Option 2: Reduce collection scope
sources:
  github:
    repos:
      - acme/backend  # Collect fewer repos

Policy Violation

Symptom:

✗ Policy validation failed

Error: Artifact may contain secrets: sources/github/env_vars.json
Pattern matched: /api[_-]?key/i

Artifact excluded from bundle.

Behavior:

Collection continues
Violating artifact excluded
Warning in bundle manifest

evidence collect

Synopsis

Description

Options

Examples

Basic Collection

Custom Configuration Path

Custom Output Directory

Collect and Upload

Dry Run

Verbose Output

Quiet Mode

Collection Process

Step 1: Configuration Validation

Step 2: Connection Testing

Step 3: Artifact Collection

Step 4: Normalization

Step 5: Hint Generation

Step 6: Bundle Creation

Environment Variables

Exit Codes

Bundle Naming

Performance

Common Issues

Missing Credentials

Invalid Scopes

Rate Limiting

Bundle Size Exceeded

Policy Violation

See Also

On this page