Katamari MCP Server

# Secret Scanning Setup for Katamari MCP This document describes the secret scanning setup implemented to prevent accidental commits of sensitive information. ## Overview Katamari MCP uses **Gitleaks** for comprehensive secret detection with the following protection layers: 1. **Pre-commit hooks** - Block commits containing secrets 2. **Release scanning script** - Full repository scan before releases 3. **Custom configuration** - Tailored for Katamari MCP patterns ## Files Added ### Core Configuration - **`.gitleaks.toml`** - Custom Gitleaks configuration with Katamari-specific rules - **`.pre-commit-config.yaml`** - Pre-commit hook configuration - **`scripts/release-security-scan.sh`** - Release scanning script ### Tools Installed - **Gitleaks v8.29.0** - Secret scanning engine (installed locally in `.local/bin/`) - **Pre-commit** - Hook management framework ## Custom Rules The configuration includes custom rules for Katamari MCP: ```toml # MCP-specific API keys [[rules]] id = "mcp-api-key" regex = '''mcp[_-]?key[_-]?=\s*['\"]?[a-zA-Z0-9+/]{20,}['\"]?''' # DuckDuckGo API keys [[rules]] id = "duckduckgo-api-key" regex = '''duckduckgo[_-]?api[_-]?key\s*=\s*['\"]?[a-zA-Z0-9-]{20,}['\"]?''' # Brave Search API keys [[rules]] id = "brave-api-key" regex = '''brave[_-]?api[_-]?key\s*=\s*['\"]?[a-zA-Z0-9-]{20,}['\"]?''' ``` ## Usage ### Development (Automatic Protection) Pre-commit hooks automatically scan staged files: ```bash # Try to commit a file with secrets git add file_with_secrets.py git commit -m "Add secrets" # ❌ BLOCKED by Gitleaks with detailed report ``` ### Release Scanning Before creating releases, run the comprehensive scan: ```bash # Scan current changes only ./scripts/release-security-scan.sh --current-only # Full repository scan ./scripts/release-security-scan.sh # Scan specific tag/branch ./scripts/release-security-scan.sh v1.0.0 # Generate SARIF report for CI/CD ./scripts/release-security-scan.sh -f sarif ``` ### Manual Scanning Direct Gitleaks usage: ```bash # Scan current directory .local/bin/gitleaks detect --source . --config .gitleaks.toml --no-git # Scan git history .local/bin/gitleaks detect --source . --config .gitleaks.toml ``` ## Allowlists The configuration automatically ignores: - Test files (`tests/`, `*.test.py`) - Documentation (`*.md`, `*.rst`) - Configuration templates (`*.template`, `*.example`) - Dependency files (`poetry.lock`, `requirements*.txt`) - Build/cache directories (`.git/`, `__pycache__/`, `.pytest_cache/`) ## Integration Options ### CI/CD Integration Add to your CI pipeline: ```yaml # GitHub Actions example - name: Scan for secrets run: ./scripts/release-security-scan.sh --no-history # GitLab CI example secret_scan: script: - ./scripts/release-security-scan.sh --current-only artifacts: reports: sast: gitleaks-release-report-*.sarif ``` ### Release Process Recommended release workflow: ```bash # 1. Ensure clean working directory git status # 2. Run full security scan ./scripts/release-security-scan.sh # 3. Create tag if scan passes git tag v1.0.0 # 4. Push release git push origin v1.0.0 ``` ## Configuration Options Environment variables for customization: ```bash # Custom Gitleaks path export GITLEAKS_PATH="/usr/local/bin/gitleaks" # Custom config file export CONFIG_FILE="./custom-gitleaks.toml" # Default report format export REPORT_FORMAT="sarif" ``` ## Testing The setup was tested with fake secrets and successfully detected: - ✅ DuckDuckGo API keys - ✅ Brave Search API keys - ✅ MCP-specific keys - ✅ Webhook URLs - ✅ Transport configuration secrets ## Maintenance ### Update Gitleaks ```bash # Download latest version wget https://github.com/gitleaks/gitleaks/releases/latest/download/gitleaks-linux-amd64 mv gitleaks-linux-amd64 .local/bin/gitleaks chmod +x .local/bin/gitleaks # Update pre-commit hook version in .pre-commit-config.yaml ``` ### Update Rules Edit `.gitleaks.toml` to add new patterns or modify existing ones. ### Update Allowlists Add new paths or patterns to ignore in the `[[allowlists]]` sections. ## Troubleshooting ### Common Issues 1. **Gitleaks not found**: Ensure `.local/bin/gitleaks` exists and is executable 2. **Permission denied**: Run `chmod +x .local/bin/gitleaks` 3. **Config errors**: Validate TOML syntax with online validator 4. **False positives**: Add patterns to allowlists ### Getting Help ```bash # Check Gitleaks version .local/bin/gitleaks version # Validate configuration .local/bin/gitleaks detect --config .gitleaks.toml --dry-run # Test pre-commit hook pre-commit run gitleaks --all-files ``` ## Security Best Practices 1. **Never commit real secrets** - Use environment variables 2. **Regular scans** - Run release scans before every deployment 3. **Review findings** - Investigate all detected secrets 4. **Update patterns** - Add new secret types as needed 5. **Monitor access** - Review who has access to scan reports This setup ensures Katamari MCP maintains strong security hygiene throughout the development lifecycle.