Git Security Scanner

# Git Security Scanner Scan your git repositories for leaked secrets, credentials, and security vulnerabilities in one command. Combines **gitleaks** (pattern-based secret detection) and **shipguard** (48+ SAST rules across 7 security layers) into a unified scanner with merged reporting. ## What You Get ### Two Scanning Engines | Engine | What it does | Rules | |--------|-------------|-------| | **gitleaks** | Pattern-based secret detection across files and git history | 400+ built-in rules, custom `.gitleaks.toml` support | | **shipguard** | Static analysis for secrets, shell injection, code injection, supply chain, config issues | 48+ rules: SEC-001–015, SHELL-001–009, PY-001–012, JS-001–008, GHA-001–005, CFG-001–003, SC-001–006 | ### Scanning Modes | Mode | Command | What it checks | |------|---------|---------------| | **Quick scan** | `git-security-scan` | Current working tree | | **Staged only** | `git-security-scan --staged-only` | Only staged files — for pre-commit hooks | | **Full history** | `git-security-scan --full-history` | Entire git history — finds secrets in old commits | | **Custom severity** | `git-security-scan --severity critical` | Filter by minimum severity level | ### What It Catches **Secrets (gitleaks + shipguard SEC rules):** - API keys (AWS, GCP, Azure, OpenAI, Anthropic, Stripe, GitHub, Slack, etc.) - Database connection strings with embedded passwords - SSH private keys and PEM files - JWT tokens and session secrets - Hardcoded passwords in config files - `.env` files accidentally staged - Credentials in comments or docstrings **Code vulnerabilities (shipguard SAST rules):** - Shell command injection (`SHELL-001–009`) - Python code injection: `eval()`, `exec()`, unsafe pickle, SQL injection (`PY-001–012`) - JavaScript injection: `innerHTML`, `eval()`, prototype pollution (`JS-001–008`) - GitHub Actions injection: script injection, unpinned actions (`GHA-001–005`) - Config issues: debug mode in production, permissive CORS, exposed admin routes (`CFG-001–003`) - Supply chain: unpinned dependencies, missing lockfiles, unsigned artifacts (`SC-001–006`) ### Output Formats | Format | Flag | Use case | |--------|------|----------| | **Terminal** (default) | `--format terminal` | Color-coded findings with severity icons | | **Markdown** | `--format markdown` | PR comments, documentation, reports | | **JSON** | `--format json` | CI/CD integration, programmatic analysis | | **SARIF** | `--format sarif` | GitHub Security tab integration | ## Installation ### Prerequisites ```bash # macOS brew install gitleaks pipx install shipguard # or: pip install shipguard # Linux # gitleaks: download from https://github.com/gitleaks/gitleaks/releases # shipguard: pipx install shipguard ``` ### Install the Skill ```bash clawhub install git-security-scanner ``` This adds the `git-security-scan` wrapper script and the skill definition. ### Set Up Pre-Commit Hook ```bash git-security-scan --install-hooks ``` This installs a pre-commit hook in the current repo that runs `git-security-scan --staged-only --severity high` on every commit. Commits with critical or high severity findings are blocked. ## Usage ### CLI ```bash # Scan current directory git-security-scan # Scan a specific project git-security-scan /path/to/project # Pre-commit mode (staged files only, block on high+) git-security-scan --staged-only --severity high # Full git history audit git-security-scan --full-history # Generate a markdown report git-security-scan --format markdown --output report.md # JSON for CI pipelines git-security-scan --format json --output .security-reports/scan.json # Skip one engine git-security-scan --skip-gitleaks # shipguard only git-security-scan --skip-shipguard # gitleaks only ``` ### AI Assistant Prompts **Quick scan:** > "Scan this repo for leaked secrets and security vulnerabilities" **Pre-commit setup:** > "Set up pre-commit hooks to block secrets before they're committed" **Full history audit:** > "Audit the entire git history for any credentials that were ever committed" **Custom rules:** > "Add a gitleaks rule to catch hardcoded Proxmox API tokens" **Targeted scan:** > "Run shipguard on just the Python files with severity high or above" ## Configuration ### gitleaks (`.gitleaks.toml`) Create in your repo root to add custom secret patterns: ```toml [extend] useDefault = true [[rules]] id = "proxmox-api-token" description = "Proxmox API Token" regex = '''PVEAPIToken=[A-Za-z0-9@!]+:[A-Za-z0-9-]+''' ``` ### shipguard (`.shipguard.yml`) Create in your repo root to configure SAST rules: ```yaml severity_threshold: medium exclude_paths: - tests/fixtures/ - node_modules/ - "*.min.js" disable_rules: - JS-008 # skip specific rule ``` ### Pre-commit config (`.shipguard-precommit.yml`) Stricter settings for the pre-commit hook: ```yaml severity_threshold: high exclude_paths: - tests/ - docs/ ``` ## Report Example Terminal output: ``` ============================================================ Git Security Scan Report ============================================================ Directory: /home/user/my-project Timestamp: 2026-03-19T10:30:00Z Tools: gitleaks (2 findings) shipguard (3 findings) Findings: 5 critical: 1 high: 1 medium: 3 🔴 [CRITICAL] aws-access-key-id (gitleaks) config/settings.py:42 AWS access key ID detected > AKIAIOSFODNN7EXAMPLE Fix: Rotate this credential immediately. Remove from git history. 🟠 [HIGH] SEC-003 (shipguard) src/api.py:18 Hardcoded database password in connection string > db_url = "postgres://admin:p4ssw0rd@localhost/app" Fix: Use environment variables instead of hardcoded credentials. 🟡 [MEDIUM] PY-003 (shipguard) src/utils.py:55 Use of eval() with user-controlled input > result = eval(user_expression) Fix: Use ast.literal_eval() or a safe expression parser. ``` ## Remediation Workflow When critical/high findings are detected: 1. **Rotate the credential** — Assume it's compromised if it was ever in git history 2. **Remove from history** — `git filter-repo --invert-paths --path <file>` or BFG Repo Cleaner 3. **Add to `.gitignore`** — Prevent re-staging of secret files 4. **Use environment variables** — Move secrets to `.env` (excluded from git) or a secret manager 5. **Re-scan** — Run `git-security-scan --full-history` to confirm the fix ## Troubleshooting | Problem | Fix | |---------|-----| | VirusTotal "suspicious" warning on install | This is a false positive — the skill *describes* secret patterns and vulnerability types, which triggers pattern detection. Use `clawhub install git-security-scanner --force` to proceed. Review the SKILL.md yourself to confirm. | | `gitleaks` not found | `brew install gitleaks` (macOS) or download from [gitleaks releases](https://github.com/gitleaks/gitleaks/releases) | | `shipguard` not found | `pipx install shipguard` or `pip install shipguard` | | No findings but secrets exist | Check if `.gitleaks.toml` or `.shipguard.yml` is excluding the path. Try `--severity low` to see all findings. | | Scan is slow | `--full-history` scans every commit. Use default mode (working tree only) for quick checks. | ## Links - **gitleaks:** https://github.com/gitleaks/gitleaks - **shipguard:** https://github.com/celstnblacc (part of ai_spec_sec) - **License:** MIT-0 (this skill) / Apache 2.0 (source tools) --- *Built by [celstnblacc](https://github.com/celstnblacc) — gitleaks 8.30.0 + shipguard 0.3.2 (48+ SAST rules, 4 output formats).*