@evidence/cli

Command-line interface for Evidence SDK - Collect SOC 2 Type I compliance evidence from your infrastructure.

Installation

Global Installation (Recommended)

npm install -g @evidence/cli

Local Installation

npm install @evidence/cli
# or
pnpm add @evidence/cli
# or
yarn add @evidence/cli

Quick Start

1. Initialize Configuration

Create an evidence.yaml configuration file:

evidence init

Or use interactive mode:

evidence init --interactive

2. Configure Your Sources

Edit the generated evidence.yaml file to configure your evidence sources:

framework: soc2_type1
controls:
  - CC6.1 # Logical Access Controls
  - CC6.6 # Logical Access - Removal
  - CC7.2 # System Operations - Change Management

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

  aws:
    mode: env
    region: us-east-1
    log_groups:
      - /aws/lambda/your-function

  google_workspace:
    mode: service_account
    credentials_env: GOOGLE_CREDENTIALS
    customer_id: C0xxxxxxx
    admin_email: [email protected]

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

3. Generate Signing Keys

Create Ed25519 signing keys:

mkdir -p ~/.evidence/keys
openssl genpkey -algorithm ed25519 -out ~/.evidence/keys/private.pem
openssl pkey -in ~/.evidence/keys/private.pem -pubout -out ~/.evidence/keys/public.pem

4. Set Environment Variables

Set required credentials:

export GITHUB_TOKEN=ghp_your_token_here
export AWS_ACCESS_KEY_ID=your_key_id
export AWS_SECRET_ACCESS_KEY=your_secret_key
export GOOGLE_CREDENTIALS='{"type":"service_account",...}'

5. Collect Evidence

Run evidence collection:

evidence collect

This will:

• Collect evidence from configured sources
• Validate against policy pack
• Generate checksums and signatures
• Create a signed tarball bundle in ./evidence-bundles/

Commands

evidence init

Initialize evidence collection configuration.

Options:

• -i, --interactive - Run in interactive mode with prompts
• -c, --config <path> - Config file path to create (default: ./evidence.yaml)

Examples:

# Create default config
evidence init

# Interactive setup
evidence init --interactive

# Custom config path
evidence init --config ./custom/evidence.yaml

evidence collect

Collect evidence and create signed bundle.

Options:

• -c, --config <path> - Path to config file (default: ./evidence.yaml)
• -o, --output <path> - Output directory for bundle (default: ./evidence-bundles)

Examples:

# Use default config and output
evidence collect

# Custom config path
evidence collect --config ./custom/evidence.yaml

# Custom output directory
evidence collect --output ./bundles

Output:

Collecting Evidence

Loading configuration from ./evidence.yaml...
✓ Configuration loaded
Validating environment variables...
✓ Environment validated
Loading signing key...
✓ Signing key loaded

Collecting Evidence from Sources

⠋ Collecting from GitHub (acme-org)...
✓ GitHub - 3 artifacts collected
⠋ Collecting from AWS (us-east-1)...
✓ AWS - 3 artifacts collected
⠋ Collecting from Google Workspace (C0xxxxxxx)...
✓ Google Workspace - 3 artifacts collected

Building Evidence Bundle

⠋ Creating bundle...
✓ Bundle created

Bundle Summary
✓ Bundle written to: ./evidence-bundles/evidence-bundle-2025-01-15-abc123.tar.gz

  Size: 124 KB
  Artifacts: 9
  Sources: github, aws, google-workspace
  Controls: CC6.1, CC6.6, CC7.2
  Signature: verified

evidence verify

Verify evidence bundle integrity.

Arguments:

• <bundle> - Path to bundle file (.tar.gz)

Options:

• -k, --public-key <path> - Path to public key file (optional, uses config if not provided)

Examples:

# Verify with explicit public key
evidence verify bundle.tar.gz --public-key ~/.evidence/keys/public.pem

# Verify using config file
evidence verify bundle.tar.gz

Output:

Verifying Evidence Bundle

Loading bundle: ./evidence-bundles/evidence-bundle-2025-01-15-abc123.tar.gz...
✓ Bundle loaded (124 KB)
Loading public key...
✓ Public key loaded

Verifying Bundle Integrity

✓ Signature verified
✓ Checksums valid
✓ Manifest valid

Bundle Information

  Framework: soc2_type1
  Controls: CC6.1, CC6.6, CC7.2
  Sources: github, aws, google-workspace
  Artifacts: 9
  Created: 2025-01-15T14:30:00Z
  Tool version: 0.1.0
  Bundle version: 1.0

✓ Bundle integrity: OK

evidence upload

Upload evidence bundle to SaaS platform.

Note: This command is currently a stub waiting for M8 (Upload Protocol) implementation.

Arguments:

• <bundle> - Path to bundle file (.tar.gz)

Options:

• -e, --endpoint <url> - API endpoint URL

Examples:

evidence upload bundle.tar.gz
evidence upload bundle.tar.gz --endpoint https://api.evidence-platform.com

Configuration File Format

The evidence.yaml file follows this structure:

# Compliance framework
framework: soc2_type1

# Controls to collect evidence for
controls:
  - CC6.1
  - CC6.6
  - CC7.2

# Evidence sources
sources:
  # GitHub configuration
  github:
    mode: token
    token_env: GITHUB_TOKEN
    org: your-org
    repos:
      - your-org/repo1
      - your-org/repo2

  # AWS configuration
  aws:
    mode: env
    region: us-east-1
    log_groups:
      - /aws/lambda/function1
      - /aws/lambda/function2

  # Google Workspace configuration
  google_workspace:
    mode: service_account
    credentials_env: GOOGLE_CREDENTIALS
    customer_id: C0xxxxxxx
    admin_email: [email protected]

# Bundle configuration
bundle:
  signing:
    private_key_path: ~/.evidence/keys/private.pem
  max_size_mb: 50

# Upload configuration (optional)
upload:
  enabled: false
  api_url: https://api.evidence-platform.com
  retention_days: 365

Environment Variables

Required

Depending on your configured sources:

• GitHub: GITHUB_TOKEN - Personal access token with repo:read and org:read scopes
• AWS: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY - AWS credentials with read-only IAM permissions
• Google Workspace: GOOGLE_CREDENTIALS - Service account JSON credentials

Optional

• DEBUG=evidence:* - Enable debug logging

Exit Codes

The CLI uses standard exit codes for automation and CI/CD integration:

• 0 - Success
• 1 - User error (invalid config, missing credentials, validation failure)
• 2 - System error (file I/O, network, unexpected errors)

Troubleshooting

Missing Environment Variables

Error:

✗ Missing required environment variables: GITHUB_TOKEN

Solution: Set the required environment variable:

export GITHUB_TOKEN=ghp_your_token_here

Configuration File Not Found

Error:

✗ Configuration file not found: ./evidence.yaml

Solution: Run evidence init to create a configuration file, or specify the correct path with --config.

Invalid Signing Key

Error:

✗ Private key file not found: ~/.evidence/keys/private.pem

Solution: Generate signing keys:

mkdir -p ~/.evidence/keys
openssl genpkey -algorithm ed25519 -out ~/.evidence/keys/private.pem
openssl pkey -in ~/.evidence/keys/private.pem -pubout -out ~/.evidence/keys/public.pem

Bundle Verification Failed

Error:

✗ Signature verification failed

Possible Causes:

• Bundle was tampered with
• Using wrong public key
• Bundle corrupted during transfer

Solution: Ensure you're using the correct public key that corresponds to the private key used for signing.

Security Considerations

Read-Only Access

The Evidence CLI only requests read-only scopes:

• GitHub: repo:read, org:read
• AWS: Read-only IAM permissions (GetAccountPasswordPolicy, DescribeTrails, etc.)
• Google Workspace: admin.directory.user.readonly

No Sensitive Data Collection

The CLI explicitly excludes:

• Repository source code
• Secrets and credentials
• Environment variables
• User passwords
• API keys

Only configuration data is collected for compliance evidence.

Bundle Integrity

All bundles are:

• Signed with Ed25519
• Include SHA-256 checksums
• Verifiable without vendor tools
• Inspectable (standard tar/gzip format)

CI/CD Integration

GitHub Actions

name: Evidence Collection
on:
  schedule:
    - cron: '0 0 1 * *' # Monthly
  workflow_dispatch:

jobs:
  collect:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Install Evidence CLI
        run: npm install -g @evidence/cli

      - name: Collect Evidence
        env:
          GITHUB_TOKEN: ${{ secrets.EVIDENCE_GITHUB_TOKEN }}
          AWS_ACCESS_KEY_ID: ${{ secrets.EVIDENCE_AWS_KEY }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.EVIDENCE_AWS_SECRET }}
          GOOGLE_CREDENTIALS: ${{ secrets.EVIDENCE_GOOGLE_CREDS }}
        run: evidence collect

      - name: Upload Bundle
        uses: actions/upload-artifact@v3
        with:
          name: evidence-bundle
          path: evidence-bundles/*.tar.gz

Development

Running from Source

# Install dependencies
pnpm install

# Build the CLI
pnpm build

# Run in development mode
pnpm dev -- init

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

License

MIT

Support

• Documentation: https://github.com/your-org/evidence-sdk
• Issues: https://github.com/your-org/evidence-sdk/issues
• Security: [email protected]