evidence init

Initialize configuration and generate signing keys.

Synopsis

evidence init [options]

Description

The evidence init command helps you get started with evidence collection by:

Generating Ed25519 signing key pairs (if --generate-keys flag used)
Creating interactive configuration (if --interactive flag used)
Validating existing configuration (if run in directory with evidence.yaml)

Options

Flag	Type	Default	Description
`--generate-keys`, `-g`	boolean	`false`	Generate Ed25519 signing key pair
`--interactive`, `-i`	boolean	`false`	Interactive configuration wizard
`--output`, `-o`	string	`~/.evidence/keys`	Output directory for generated keys
`--config`, `-c`	string	`./evidence.yaml`	Configuration file path
`--force`, `-f`	boolean	`false`	Overwrite existing keys/config
`--help`, `-h`	boolean	`false`	Show help

Examples

Generate Signing Keys

Create Ed25519 key pair for signing bundles:

evidence init --generate-keys

Output:

✓ Generated Ed25519 key pair

Private key: /Users/you/.evidence/keys/private.pem
Public key:  /Users/you/.evidence/keys/public.pem

Keep your private key secure. Share your public key for verification.

Public key fingerprint (SHA-256):
abc123def456789...

Files created:

~/.evidence/keys/private.pem - Private signing key (keep secret)
~/.evidence/keys/public.pem - Public verification key (safe to share)

Custom Output Location

Generate keys in specific directory:

evidence init --generate-keys --output ./keys

Output:

✓ Generated Ed25519 key pair

Private key: ./keys/private.pem
Public key:  ./keys/public.pem

Interactive Configuration Wizard

Create configuration through guided prompts:

evidence init --interactive

Prompts:

? Select compliance framework: (Use arrow keys)
  ❯ SOC 2 Type I
    SOC 2 Type II (coming soon)

? Select controls to collect evidence for: (Press <space> to select)
  ❯ ◯ CC6.1 - Logical Access Controls
    ◯ CC6.6 - Access Removal/Modification
    ◯ CC7.2 - Change Management

? Which connectors do you want to configure? (Press <space> to select)
  ◯ GitHub
  ◯ AWS
  ◯ Google Workspace

[GitHub Configuration]
? GitHub organization name: acme
? Token environment variable name: GITHUB_TOKEN
? Repositories to collect from:
  ◯ All repositories
  ❯ ◯ Specific repositories

? Enter repository names (comma-separated): acme/backend, acme/frontend

[Signing Configuration]
? Private key location: ~/.evidence/keys/private.pem

✓ Configuration saved to evidence.yaml

Creates:

framework: soc2_type1
controls:
  - CC6.1
  - CC6.6
  - CC7.2

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

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

Validate Existing Configuration

Run in directory with evidence.yaml:

evidence init

Output:

✓ Found existing configuration: evidence.yaml
✓ Configuration schema valid
✓ Framework supported: soc2_type1
✓ Controls valid: CC6.1, CC6.6, CC7.2
✓ Sources configured: github

Configuration is valid and ready to use.

Run 'evidence collect' to collect evidence.

Force Overwrite

Overwrite existing keys or configuration:

evidence init --generate-keys --force

Warning prompt:

⚠ Private key already exists: ~/.evidence/keys/private.pem

Overwriting this key will invalidate all bundles signed with it.
You will need to distribute the new public key to verifiers.

? Are you sure you want to overwrite the existing key? (y/N)

Key Management

Key Storage

Default locations:

Private key: ~/.evidence/keys/private.pem
Public key: ~/.evidence/keys/public.pem

Permissions:

# Private key should be readable only by owner
chmod 600 ~/.evidence/keys/private.pem

# Public key can be readable by everyone
chmod 644 ~/.evidence/keys/public.pem

Key Format

Private key (PEM format):

-----BEGIN PRIVATE KEY-----
MC4CAQAwBQYDK2VwBCIEIAbcd1234...
-----END PRIVATE KEY-----

Public key (PEM format):

-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAXyz9876...
-----END PUBLIC KEY-----

Key Verification

Verify key pair matches:

# Extract public key from private key
openssl pkey -in private.pem -pubout -out derived-public.pem

# Compare with generated public key
diff public.pem derived-public.pem
# Should show no differences

Public Key Distribution

Share public key with auditors and verifiers:

# Print public key
cat ~/.evidence/keys/public.pem

# Copy to clipboard (macOS)
cat ~/.evidence/keys/public.pem | pbcopy

# Generate fingerprint for out-of-band verification
openssl pkey -pubin -in public.pem -outform DER | \
  openssl dgst -sha256 -binary | \
  base64

Exit Codes

Code	Meaning
`0`	Success
`1`	Configuration error
`2`	Key generation error
`3`	File system error (permissions, disk full)
`4`	Invalid arguments

Environment Variables

Variable	Description
`EVIDENCE_KEYS_DIR`	Override default keys directory
`EVIDENCE_CONFIG_PATH`	Override default config file path

Example:

export EVIDENCE_KEYS_DIR=/secure/keys
export EVIDENCE_CONFIG_PATH=/config/evidence.production.yaml

evidence init --generate-keys
# Creates keys in /secure/keys/

Configuration File Schema

The evidence.yaml file created by --interactive:

# Framework selection (required)
framework: soc2_type1

# Controls to collect evidence for (required, min 1)
controls:
  - CC6.1

# Source connectors (required, min 1)
sources:
  # GitHub connector
  github:
    mode: token           # Authentication mode
    token_env: GITHUB_TOKEN  # Environment variable name
    org: your-org         # Organization name
    repos:                # Repositories to collect from
      - your-org/repo1
      - your-org/repo2

  # AWS connector
  aws:
    mode: env             # Use AWS environment variables
    region: us-east-1     # AWS region
    log_groups:           # CloudWatch log groups
      - /aws/lambda/api

  # Google Workspace connector
  google_workspace:
    mode: service_account
    credentials_env: GOOGLE_APPLICATION_CREDENTIALS
    customer_id: C0xxxxxxx
    admin_email: admin@example.com

# Bundle configuration (required)
bundle:
  signing:
    private_key_path: ~/.evidence/keys/private.pem
  max_size_mb: 50        # Optional, default 50

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

See Configuration Reference for complete schema.

Common Issues

Permission Denied Writing Keys

Symptom:

✗ Failed to write private key

Error: EACCES: permission denied, open '/root/.evidence/keys/private.pem'

Solution:

# Create directory with correct permissions
mkdir -p ~/.evidence/keys
chmod 700 ~/.evidence/keys

# Try again
evidence init --generate-keys

Key Already Exists

Symptom:

✗ Key generation failed

Error: Private key already exists: ~/.evidence/keys/private.pem

Use --force to overwrite

Solution:

# Backup existing keys first
cp ~/.evidence/keys/private.pem ~/.evidence/keys/private.pem.backup
cp ~/.evidence/keys/public.pem ~/.evidence/keys/public.pem.backup

# Generate new keys
evidence init --generate-keys --force

Invalid Configuration File

Symptom:

✗ Configuration validation failed

Error: Invalid YAML syntax at line 5, column 3

Solution:

# Validate YAML syntax
yamllint evidence.yaml

# Or use interactive mode to regenerate
evidence init --interactive --force

evidence init

Synopsis

Description

Options

Examples

Generate Signing Keys

Custom Output Location

Interactive Configuration Wizard

Validate Existing Configuration

Force Overwrite

Key Management

Key Storage

Key Format

Key Verification

Public Key Distribution

Exit Codes

Environment Variables

Configuration File Schema

Common Issues

Permission Denied Writing Keys

Key Already Exists

Invalid Configuration File

See Also

On this page