Guide

Run Collectors

Gather evidence from GitHub, AWS, Okta, and other systems automatically.

Prerequisites

  • epack installed with -tags components
  • An epack.yaml with collectors configured
  • API tokens for each collector in environment variables

1. Configure collectors in epack.yaml

Add collectors to your configuration file:

epack.yaml
stream: myorg/prod

collectors:
  github:
    source: locktivity/epack-collector-github@v1
    config:
      organization: myorg
    secrets:
      - GITHUB_TOKEN

  aws:
    source: locktivity/epack-collector-aws@v1
    config:
      regions:
        - us-east-1
        - us-west-2
    secrets:
      - AWS_ACCESS_KEY_ID
      - AWS_SECRET_ACCESS_KEY

2. Set environment variables

Export secrets for each collector:

export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."

3. Run collection

Run all collectors and build the pack:

epack collect
Expected output 
Locking collectors...
  ✓ github locked to sha256:a1b2c3...
  ✓ aws locked to sha256:d4e5f6...

Syncing collectors...
  ✓ github synced
  ✓ aws synced

Running collectors...
  ✓ github (3 artifacts)
  ✓ aws (5 artifacts)

✓ Built evidence-2025-02-23-153000.epack
  Stream: myorg/prod
  Artifacts: 8

4. Sign the pack

epack sign packs/*.epack

Variations

Run a single collector

epack collector run --only github

Run in CI with locked versions

Use --frozen to fail if the lockfile doesn't match:

epack collect --frozen

Update collector versions

Re-resolve all collectors to their latest matching versions:

epack lock --all-platforms

Run individual steps

The collect command runs lock → sync → run → build. You can run these separately:

epack lock              # Resolve versions to digests
epack sync              # Download collector binaries
epack collector run     # Execute all collectors
epack build out.pack ./artifacts/*