evidence SDK and CLI

quick-start, guide for evidence collectors, examples.

Quick Start

Install the CLI and collect your first evidence bundle in under 10 minutes.

Get Started →

Guide

Understand core concepts: bundles, artifacts, controls, and the evidence SDK architecture.

Read Guide →

Reference

Complete API documentation for CLI commands, configuration options, and connectors.

Browse Reference →

Examples

Copy-paste ready configurations for common scenarios and production setups.

See Examples →

What You'll Collect

The evidence SDK currently supports SOC 2 Type I compliance with three core controls:

CC6.1 - Logical Access Controls (2FA enforcement, password policies, MFA requirements)
CC6.6 - Access Removal/Modification (code review enforcement, admin role management)
CC7.2 - Change Management (branch protection, audit logging, change tracking)

Supported Connectors

Connector	What It Collects	Required Scopes
GitHub	Org settings, branch protection, CODEOWNERS	`repo:read`, `read:org`
AWS	IAM password policy, CloudTrail logging, CloudWatch logs	`iam:Get`, `cloudtrail:Describe`, `logs:Describe*`
Google Workspace	2-step verification, admin roles, user lifecycle	`admin.directory.*.readonly`

How It Works

# 1. Install CLI
npm install -g @evidence-oss/cli

# 2. Generate signing keys
evidence init --generate-keys

# 3. Create configuration
cat > evidence.yaml <<EOF
framework: soc2_type1
controls:
  - CC6.1
  - CC6.6
  - CC7.2
sources:
  github:
    mode: token
    token_env: GITHUB_TOKEN
    org: your-org
    repos:
      - your-org/backend
bundle:
  signing:
    private_key_path: ~/.evidence/keys/private.pem
EOF

# 4. Set credentials
export GITHUB_TOKEN=ghp_your_token_here

# 5. Collect evidence
evidence collect
# Creates: evidence-bundles/evidence-bundle-*.tar.gz

# 6. Verify integrity
evidence verify evidence-bundle-*.tar.gz \
  --public-key ~/.evidence/keys/public.pem

What you get:

Signed .tar.gz bundle with all collected evidence
SHA-256 checksums for integrity verification
Ed25519 signature for authenticity
JSON artifacts ready for inspection
Control mappings showing compliance status

Current Status

Beta - v0.1.0

The evidence SDK is in active development. Core features are stable and production-ready, but the API may change before v1.0.

Ready for production:

GitHub connector
AWS connector (IAM, CloudTrail, CloudWatch)
Bundle creation and signing
CLI commands
GitHub Action

Coming soon:

Google Workspace connector
Additional SOC 2 controls (CC7.3, CC7.4, CC7.5, CC8.1)
SOC 2 Type II support
ISO 27001, PCI-DSS frameworks
Policy-as-code (OPA integration)

Next Steps

New to the evidence SDK? Start with the Quick Start to install the CLI and collect your first bundle.

Want to understand how it works? Read How It Works to learn about the architecture and evidence collection process.

Ready for production? Check out Multi-Source Example for production-ready configurations with multiple connectors.

Need detailed reference? Browse the CLI Reference or Connector Documentation.

evidence SDK and CLI

On this page