Skip to content

PR_DESCRIPTION.md

Latest commit

 

History

History
147 lines (116 loc) · 4.44 KB

PR_DESCRIPTION.md

File metadata and controls

147 lines (116 loc) · 4.44 KB
Raw

Add Secret Scanning Protection with Gitleaks

Summary

Implements comprehensive secret scanning protection to prevent accidental commits of sensitive credentials (Stellar secret keys, JWT secrets, API tokens, etc.) to the repository.

Problem Statement

Previously, no automated protection existed against accidentally committing sensitive credentials like:

  • Stellar secret keys (S...)
  • JWT secrets
  • Private keys
  • API tokens
  • Soroban secrets

This posed a significant security risk as leaked credentials could compromise the entire VacciChain system.

Solution

Implemented multi-layered secret scanning using Gitleaks:

1. GitHub Actions CI/CD (.github/workflows/gitleaks.yml)

  • Runs on every push to main/develop branches
  • Runs on every pull request to main/develop
  • Blocks PRs if secrets are detected
  • Uploads detailed reports as artifacts for investigation

2. Pre-commit Hooks (.pre-commit-config.yaml)

  • Scans staged files before commit
  • Blocks commits containing secrets locally
  • Provides immediate feedback to developers
  • Prevents secrets from ever reaching the repository

3. Custom Configuration (.gitleaks.toml)

  • VacciChain-specific secret patterns:
    • Stellar secret keys: S[A-Z0-9]{55}
    • JWT secrets
    • Soroban secrets
    • Generic API keys
  • Allowlist for false positives (example files, tests, documentation)
  • Optimized for minimal false positives

4. Setup Scripts

  • scripts/setup-git-hooks.sh - For Linux/macOS users
  • scripts/setup-git-hooks.ps1 - For Windows users
  • Automated installation of gitleaks and pre-commit
  • One-command setup for new developers

5. Documentation (docs/secret-scanning-setup.md)

  • Complete setup guide
  • Usage instructions
  • Troubleshooting tips
  • Best practices

Changes Made

New Files

  • .gitleaks.toml - Gitleaks configuration with custom rules
  • .github/workflows/gitleaks.yml - GitHub Actions workflow
  • .pre-commit-config.yaml - Pre-commit hook configuration
  • scripts/setup-git-hooks.sh - Linux/macOS setup script
  • scripts/setup-git-hooks.ps1 - Windows setup script
  • docs/secret-scanning-setup.md - Complete documentation

Testing

Local Testing

# Test the setup script
./scripts/setup-git-hooks.sh

# Test manual scanning
gitleaks detect --source . --verbose --redact

# Test pre-commit hook
git add .
git commit -m "test"

CI/CD Testing

  • GitHub Actions workflow will run automatically on this PR
  • Verify workflow passes successfully
  • Check that gitleaks scans complete without errors

Acceptance Criteria Met

✅ Gitleaks runs on every PR and push to main

  • Implemented in .github/workflows/gitleaks.yml
  • Configured for main and develop branches

✅ Pre-commit hook configured to block secret commits locally

  • Implemented in .pre-commit-config.yaml
  • Setup scripts provided for easy installation

✅ Scan covers required secret types

  • Stellar secret keys (S...)
  • JWT secrets
  • Private keys
  • API tokens
  • Custom Soroban patterns

✅ Historical commit scan capability

  • Command provided in documentation
  • Can be run manually: gitleaks detect --source . --log-opts="--all"

Deployment Steps

  1. Merge this PR
  2. All developers run setup script:
    • Linux/macOS: ./scripts/setup-git-hooks.sh
    • Windows: .\scripts\setup-git-hooks.ps1
  3. Run historical scan (one-time): 
    gitleaks detect --source . --log-opts="--all" --verbose
  4. Rotate any found secrets immediately

Security Impact

  • High: Prevents credential leaks before they happen
  • Proactive: Catches secrets at commit time, not after push
  • Comprehensive: Multiple layers of protection (local + CI/CD)

Performance Impact

  • Pre-commit hook adds ~1-3 seconds per commit
  • GitHub Actions adds ~30-60 seconds to CI/CD pipeline
  • Minimal impact, significant security benefit

Breaking Changes

None. This is purely additive security enhancement.

Documentation

  • Complete setup guide in docs/secret-scanning-setup.md
  • Inline comments in configuration files
  • Setup scripts with helpful output messages

Follow-up Tasks

  • Run historical scan on entire repository
  • Rotate any secrets found in historical scan
  • Add secret scanning badge to README
  • Schedule periodic security audits
  • Consider adding additional secret patterns as needed

Related Issues

Closes #[issue-number] - Add secret scanning protection

Priority: High
Effort: Small
Security Impact: Critical