Skip to content

.pre-commit-setup.md

Latest commit

 

History

History
124 lines (88 loc) · 3.42 KB

.pre-commit-setup.md

File metadata and controls

124 lines (88 loc) · 3.42 KB
Raw

Pre-commit Setup Summary

This document summarizes the pre-commit configuration and security measures implemented for the MCP ADR Analysis Server.

Implemented Security Features

1. Secret Detection

  • Tool: Gitleaks v8.28.0
  • Configuration: .gitleaks.toml
  • Features:
    • Scans for common secrets (API keys, tokens, credentials)
    • Custom rules for Twilio SID, Stripe keys, OpenRouter keys
    • Smart allowlist for test files and placeholders
    • Integrated into both pre-commit and pre-push hooks

2. Pre-commit Hooks (.husky/pre-commit)

  • Security checks:
    • Gitleaks secret scanning
    • Private key detection (excluding test patterns)
  • Code quality:
    • Code formatting with Prettier via lint-staged
    • TypeScript type checking
    • Project build validation
    • Smoke test execution

3. Pre-push Hooks (.husky/pre-push)

  • Final security scan: Comprehensive gitleaks check
  • Dependency security: npm audit for vulnerabilities
  • Build validation: Ensures clean build before push
  • Test suite: Runs full test suite (allows performance test failures)

4. Configuration Files

.gitleaks.toml

  • Extends default gitleaks configuration
  • Custom rules for project-specific secrets
  • Smart allowlisting for test files and safe patterns

.pre-commit-config.yaml

  • Comprehensive pre-commit framework configuration
  • Multiple hooks for security, formatting, and quality
  • Integrates with existing tools

Fixed Issues

  1. Secret Detection Issue:

    • Fixed Twilio Account SID in tests/utils/tree-sitter-analyzer.test.ts:781
    • Replaced test credentials with safe placeholder patterns

  2. Security Gaps:

    • Added comprehensive secret scanning
    • Implemented private key detection
    • Added dependency vulnerability checks

  3. Hook Optimization:

    • Enhanced error handling and user feedback
    • Balanced security with developer experience
    • Graceful handling of test failures

Installation and Usage

Prerequisites

brew install gitleaks  # For secret scanning
npm install           # Install project dependencies

Hooks are automatically active via Husky

  • Pre-commit: Runs on every commit
  • Pre-push: Runs before pushing to remote

Manual Testing

# Test secret scanning
gitleaks detect --source . --verbose

# Test pre-commit hook
./.husky/pre-commit

# Test pre-push hook
./.husky/pre-push

Best Practices

  1. For Developers:

    • Use placeholder values for secrets in tests (e.g., ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx)
    • Review security warnings before bypassing
    • Keep dependencies updated

  2. For Test Files:

    • Use clearly identifiable placeholder patterns
    • Document test data as non-real in comments
    • Follow established patterns for consistency

  3. For CI/CD:

    • Hooks run locally and in CI environments
    • Build failures block pushes for security
    • Test failures are logged but don't block (for known performance test issues)

Troubleshooting

Common Issues

  1. Gitleaks false positives: Add patterns to .gitleaks.toml allowlist
  2. Build failures: Check TypeScript compilation and dependencies
  3. Test failures: Performance tests may fail intermittently (allowed)

Bypassing Hooks (Emergency Only)

git commit --no-verify    # Skip pre-commit
git push --no-verify      # Skip pre-push

Note: Only use --no-verify in emergencies and address issues immediately after.