mcp-adr-analysis-server

# 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 ```bash 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 ```bash # 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) ```bash 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.