Satisfies: U4 (false positive documentation), O4 (developer security guide)

This document describes the security scanning tools and practices for Manifold.

Manifold uses a defense-in-depth strategy for secret detection:

┌─────────────────────────────────────────────────────────────────────┐
│                         Security Layers                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   Developer Workstation          CI/CD Pipeline         Historical  │
│   ─────────────────────          ─────────────          ─────────── │
│                                                                     │
│   ┌─────────────────┐     ┌─────────────────────┐    ┌───────────┐ │
│   │   Pre-commit    │     │   Gitleaks (SARIF)  │    │TruffleHog │ │
│   │   (gitleaks)    │────▶│   Semgrep (SARIF)   │    │  (audit)  │ │
│   │                 │     │                     │    │           │ │
│   │  Catches        │     │  Catches leaked     │    │  Catches  │ │
│   │  secrets        │     │  secrets in PRs     │    │  secrets  │ │
│   │  BEFORE         │     │  BEFORE merge       │    │  in git   │ │
│   │  commit         │     │                     │    │  history  │ │
│   └─────────────────┘     └─────────────────────┘    └───────────┘ │
│                                                                     │
│   Fastest feedback          PR gate + SARIF           Deep scan    │
│                             integration                             │
└─────────────────────────────────────────────────────────────────────┘

Choose your preferred installation method:

macOS (Homebrew)

brew install gitleaks

Windows (Scoop)

scoop install gitleaks

Go Install

go install github.com/gitleaks/gitleaks/v8@latest

Linux/macOS (curl)

# Check https://github.com/gitleaks/gitleaks/releases for latest version
curl -sSfL https://github.com/gitleaks/gitleaks/releases/download/v8.18.0/gitleaks_8.18.0_linux_x64.tar.gz | tar xz
sudo mv gitleaks /usr/local/bin/

gitleaks version
# Should output: gitleaks version 8.x.x

The pre-commit hook is configured via .husky/pre-commit. Verify it works:

# Create a test file with a fake secret
echo 'AWS_SECRET_KEY="AKIAIOSFODNN7EXAMPLE"' > test-secret.txt

# Attempt to commit (should fail)
git add test-secret.txt
git commit -m "test: should fail"
# Expected: Gitleaks blocks the commit

# Clean up
rm test-secret.txt
git reset HEAD

DO NOT COMMIT. Follow these steps immediately:

1. Remove the secret from your code

   # Remove the offending line
   git checkout -- <file-with-secret>

2. Use environment variables instead

   // WRONG: Hardcoded secret
   const apiKey = "sk-1234567890abcdef";
   
   // CORRECT: Environment variable
   const apiKey = process.env.API_KEY;

3. If the secret was already committed (even locally):

   • Rotate the secret immediately - assume it's compromised
   • Contact the relevant service provider (AWS, GitHub, etc.)
   • Use git filter-branch or BFG Repo Cleaner to remove from history
   • Force push to overwrite history (coordinate with team)

4. Add to .env.example (without real values):

   # .env.example
   API_KEY=your-api-key-here
   DATABASE_URL=postgres://user:password@localhost:5432/db

Gitleaks may flag strings that look like secrets but aren't (e.g., test fixtures, example values, hashes).

1. Verify it's actually a false positive

   • Is it a real credential? If unsure, treat it as real.
   • Is it an example/placeholder that can't be used?
   • Is it a test fixture with no production access?

2. Add to .gitleaks.toml allowlist

   Create or edit .gitleaks.toml in the project root:

   # .gitleaks.toml
   title = "Manifold Gitleaks Configuration"
   
   [allowlist]
   description = "Allowlisted patterns and paths"
   
   # Allowlist specific files
   paths = [
     '''tests/fixtures/.*''',
     '''docs/examples/.*''',
   ]
   
   # Allowlist specific patterns (use with caution)
   regexes = [
     '''EXAMPLE_.*''',
     '''test-api-key-.*''',
   ]
   
   # Allowlist specific commits (for historical issues)
   commits = [
     '''abc123def456...''',
   ]

3. Document the rationale

   Always include a comment explaining WHY something is allowlisted:

   # Allowlist test fixtures - these are fake credentials
   # used only in unit tests and have no production access
   # Added: 2024-01-15 by @developer
   paths = [
     '''tests/fixtures/mock-credentials\.json''',
   ]

4. Get PR approval - allowlist changes should be reviewed

In rare cases, you may need to bypass the pre-commit hook:

# DANGER: Bypasses ALL pre-commit hooks
git commit --no-verify -m "emergency: fix production outage"

When this is acceptable:

• Active production incident where the secret check is blocking a critical fix
• The change contains NO actual secrets (you've verified manually)
• You immediately follow up with a proper commit

When this is NOT acceptable:

• "It's just a test credential" - add to allowlist instead
• "I'm in a hurry" - security is never optional
• "I'll fix it later" - you won't

The GitHub Actions security workflow runs automatically.

Scan results are uploaded to GitHub Security tab via SARIF format:

• Navigate to Security > Code scanning alerts
• View detected secrets with file locations
• Track remediation status

To run a security scan on-demand:

# Via GitHub CLI
gh workflow run security.yml

# Or via GitHub UI
# Actions > Security Scan > Run workflow

Gitleaks detects 100+ secret patterns including:

title = "Manifold Gitleaks Configuration"

# Extend the default rules
[extend]
useDefault = true

[allowlist]
description = "Manifold-specific allowlist"

# Paths that are safe to ignore
paths = [
  # Test fixtures with fake credentials
  '''tests/fixtures/.*''',
  # Documentation examples
  '''docs/examples/.*''',
  # Lock files
  '''bun\.lockb''',
  '''package-lock\.json''',
]

# Specific regex patterns to ignore
regexes = [
  # Example placeholders
  '''EXAMPLE_.*''',
  '''your-.*-here''',
  # Test identifiers
  '''test-[a-z]+-[0-9]+''',
]

#!/usr/bin/env sh
# Husky pre-commit hook
# Satisfies: O4 (secret detection before commit)

# Run gitleaks on staged files
gitleaks protect --staged --verbose

# If gitleaks fails, the commit is blocked

If you discover a security vulnerability in Manifold itself:

1. DO NOT create a public GitHub issue
2. DO NOT discuss in public channels (Slack, Discord, etc.)
3. Email: security@manifold.dev (or create a private security advisory on GitHub)
4. Include:
   • Description of the vulnerability
   • Steps to reproduce
   • Potential impact
   • Suggested fix (if any)

If you discover leaked credentials in the repository:

1. Rotate immediately - assume the credential is compromised
2. Notify the team via secure channel
3. Remove from history using git filter-branch or BFG Repo Cleaner
4. Document the incident for post-mortem

# Scan current directory
gitleaks detect --verbose

# Scan staged files only
gitleaks protect --staged --verbose

# Scan with custom config
gitleaks detect --config .gitleaks.toml --verbose

# Scan git history
gitleaks detect --log-opts="--all" --verbose

# Generate SARIF report
gitleaks detect --report-format sarif --report-path results.sarif

• Gitleaks Documentation
• TruffleHog Documentation
• Semgrep Documentation
• GitHub Code Scanning