evidence upload

Synopsis

evidence upload <bundle> [options]

Description

The evidence upload command:

1. Verifies bundle integrity (checksums + signature)
2. Authenticates with evidence platform API
3. Uploads bundle to secure storage
4. Verifies upload completed successfully
5. Returns bundle ID and platform URL

Arguments

Options

Examples

Basic Upload

Upload with API key from environment:

export EVIDENCE_API_KEY=evd_api_...
evidence upload evidence-bundle-20260109-123456.tar.gz

Output:

Verifying bundle...
  ✓ Checksums valid (12/12 files)
  ✓ Signature valid

Uploading to evidence platform...
  ✓ Authenticated (organization: acme)
  ✓ Upload complete (2.3s, 35.1 KB)
  ✓ Verified on platform

✓ Upload successful

Bundle ID: bundle_abc123def456
Platform URL: https://app.evidence-platform.com/bundles/bundle_abc123def456

Timeline updated:
  Controls: CC6.1, CC6.6, CC7.2
  Period: 2026-01-09
  Status: Evidence collected

Upload with Explicit API Key

Provide API key directly:

evidence upload bundle.tar.gz \
  --api-key evd_api_your_key_here

Custom Endpoint

Upload to different environment:

# Staging environment
evidence upload bundle.tar.gz \
  --endpoint https://api.staging.evidence-platform.com

# Self-hosted instance
evidence upload bundle.tar.gz \
  --endpoint https://evidence.internal.company.com/api

Upload with Tags

Add metadata tags for organization:

evidence upload bundle.tar.gz \
  --tags "environment:production,team:security,compliance:soc2"

Tags visible in platform:

• Filter bundles by tag
• Search by tag
• Report by tag

Skip Verification

Upload without local verification (not recommended):

evidence upload bundle.tar.gz --verify-first=false

Use case: Bundle already verified, re-uploading

Warning: Platform still verifies bundle server-side

Custom Retention

Set bundle retention period:

evidence upload bundle.tar.gz --retention-days 730
# Keep for 2 years instead of default 1 year

Retention policies:

• Bundles auto-deleted after retention period
• Can be extended before expiration
• SOC 2 Type II typically requires 365+ days

Quiet Mode

Minimal output for scripts:

evidence upload bundle.tar.gz --quiet

Output (success):

bundle_abc123def456

Output (failure):

Error: Upload failed

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

Upload Process

Step 1: Pre-Upload Verification

Verifying bundle...
  ✓ Checksums valid
  ✓ Signature valid

Checks:

• Bundle integrity (SHA-256)
• Bundle authenticity (Ed25519)
• Manifest structure valid

Skip: --verify-first=false (not recommended)

Step 2: Authentication

✓ Authenticated (organization: acme)

Process:

1. Read API key from --api-key or EVIDENCE_API_KEY
2. Send authentication request to platform
3. Receive authentication token
4. Extract organization ID from token

API Key format:

evd_api_1234567890abcdef...

Required permissions:

• bundles:create
• bundles:upload

Step 3: Upload

Uploading to evidence platform...
  ✓ Upload complete (2.3s, 35.1 KB)

Process:

1. Request upload URL from platform
2. Upload bundle to secure storage (S3, GCS, etc.)
3. Notify platform of upload completion
4. Platform verifies bundle server-side

Upload methods:

• Direct upload to cloud storage
• Presigned URL (no credentials needed)
• Chunked upload for large bundles (>50MB)

Step 4: Platform Verification

✓ Verified on platform

Server-side checks:

• Bundle extracts successfully
• Checksums match
• Signature valid
• Manifest parses correctly
• Controls supported
• No policy violations

Step 5: Timeline Update

Timeline updated:
  Controls: CC6.1, CC6.6, CC7.2
  Period: 2026-01-09
  Status: Evidence collected

Platform actions:

1. Extract bundle metadata
2. Map artifacts to controls
3. Update compliance timeline
4. Generate compliance report
5. Send notifications (if configured)

API Authentication

API Key Creation

Create API key in platform:

1. Go to evidence platform → Settings → API Keys
2. Click "Create API Key"
3. Set permissions: bundles:create, bundles:upload
4. Copy API key (shown only once)
5. Store securely

Example API key:

evd_api_1234567890abcdefghijklmnopqrstuv

API Key Storage

Environment variable (recommended):

export EVIDENCE_API_KEY=evd_api_...

# Add to shell profile for persistence
echo 'export EVIDENCE_API_KEY=evd_api_...' >> ~/.zshrc
source ~/.zshrc

CI/CD secrets:

# GitHub Actions
env:
  EVIDENCE_API_KEY: ${{ secrets.EVIDENCE_API_KEY }}

# GitLab CI
variables:
  EVIDENCE_API_KEY: $CI_EVIDENCE_API_KEY

Never hardcode:

# ❌ BAD - never do this
evidence upload bundle.tar.gz --api-key evd_api_hardcoded

API Key Rotation

Rotate keys regularly:

1. Create new API key in platform
2. Update environment variables / CI secrets
3. Test with new key
4. Revoke old key in platform

Recommended frequency: Every 90 days

Environment Variables

Example:

export EVIDENCE_API_KEY=evd_api_...
export EVIDENCE_API_URL=https://api.staging.evidence-platform.com
export EVIDENCE_ORGANIZATION_ID=org_abc123

evidence upload bundle.tar.gz
# Uses environment variables

Exit Codes

Upload Configuration

In evidence.yaml

Configure default upload settings:

upload:
  enabled: true
  api_url: https://api.evidence-platform.com
  retention_days: 365
  tags:
    environment: production
    team: security
    compliance: soc2

Use in collection:

evidence collect --upload
# Uses upload config from evidence.yaml

Command Line Override

Override config file settings:

evidence upload bundle.tar.gz \
  --endpoint https://api.staging.evidence-platform.com \
  --retention-days 730 \
  --tags "environment:staging,test:true"

Platform Features

Bundle Storage

Secure storage:

• Encrypted at rest (AES-256)
• Encrypted in transit (TLS 1.3)
• Access-controlled (organization scoped)
• Audit logged (all access tracked)

Retention:

• Configurable retention period
• Auto-deletion after expiration
• Export before deletion
• Compliance period tracking

Compliance Timeline

Timeline visualization:

• Evidence collected over time
• Control coverage per period
• Gap identification
• Audit-ready reports

Example timeline:

2026:
  Jan: ✓ CC6.1, CC6.6, CC7.2 (9 artifacts)
  Feb: ✓ CC6.1, CC6.6, CC7.2 (9 artifacts)
  Mar: ✓ CC6.1, CC6.6, CC7.2 (10 artifacts)

Coverage: 3 months (SOC 2 Type I: ✓, Type II: ✗ need 3 more)

Compliance Reports

Auto-generated reports:

• Control status summary
• Evidence inventory
• Compliance gaps
• Remediation recommendations
• Audit export (PDF, CSV)

Notifications

Configurable alerts:

• Evidence collection success/failure
• Timeline gaps detected
• Compliance status changes
• Upcoming audits

Common Issues

Authentication Failed

Symptom:

✗ Authentication failed

Error: Invalid API key

HTTP 401: Unauthorized

Causes:

• API key invalid or revoked
• API key missing required permissions
• Environment variable not set

Solution:

# Verify API key set
echo $EVIDENCE_API_KEY

# Re-create API key in platform
# Update environment variable
export EVIDENCE_API_KEY=evd_api_new_key

Upload Timeout

Symptom:

✗ Upload failed

Error: Request timeout after 300s

Network error: Connection timeout

Causes:

• Large bundle size
• Slow network connection
• Platform downtime

Solution:

# Check bundle size
ls -lh bundle.tar.gz

# Retry upload
evidence upload bundle.tar.gz

# Contact platform support if persists

Rate Limit Exceeded

Symptom:

✗ Upload failed

Error: Rate limit exceeded

Try again in 60 seconds.

Causes:

• Too many uploads in short period
• Shared API key across multiple systems
• Platform-wide rate limiting

Solution:

# Wait for rate limit reset
sleep 60

# Retry
evidence upload bundle.tar.gz

Platform Verification Failed

Symptom:

✓ Upload complete
✗ Platform verification failed

Error: Signature verification failed on platform

Bundle was uploaded but rejected by platform.

Causes:

• Public key not registered in platform
• Bundle created with different private key
• Platform public key mismatch

Solution:

1. Go to evidence platform → Settings → Signing Keys
2. Upload your public key (from ~/.evidence/keys/public.pem)
3. Verify key fingerprint matches
4. Re-upload bundle

See Also

• evidence collect - Create bundles with upload
• evidence verify - Verify before upload
• Configuration Guide - Upload configuration
• GitHub Action - Auto-upload in CI/CD