Git Security Scanner

Unified security scanner that catches leaked secrets, credentials, and code vulnerabilities before they reach your remote. Wraps gitleaks (400+ secret patter...

Security Scan

The skill's requirements and instructions are consistent with a git-focused secret/vulnerability scanner; nothing requested or instructed appears disproportionate to that purpose.

Purpose & Capability

The name/description match the declared dependencies: gitleaks for secret patterns and shipguard (Python) for SAST. Requiring gitleaks and python3 (for shipguard) is expected for this functionality. No unrelated credentials or system-level access are requested.

Instruction Scope

SKILL.md only instructs scanning git working trees/history, installing pre-commit hooks, and creating repo-level config files (.gitleaks.toml, .shipguard.yml). It does not ask the agent to read unrelated system files or environment variables, nor to transmit data to unexpected external endpoints.

Install Mechanism

This is an instruction-only skill with no install spec or code files. SKILL.md suggests running 'clawhub install' which 'adds the git-security-scan wrapper script', but no wrapper or installer is present in the package. The recommended installs for gitleaks (brew/GitHub releases) and shipguard (pipx/pip) are reasonable and from typical sources, but you should verify who provides the wrapper script or whether you must create it yourself.

Credentials

The skill declares no required environment variables or credentials, which is appropriate. It does write repo-local artifacts (pre-commit hook and config files) which are proportional to its stated behavior.

Persistence & Privilege

always:false and user-invocable:false mean it won't be force-enabled. The one persistence-related action is installing a repo pre-commit hook that can block commits on high/critical findings — this is expected behavior but you should be aware it modifies .git/hooks and can affect commit workflows.

Assessment

This skill appears to do what it claims, but check a few things before installing: 1) verify how the 'git-security-scan' wrapper is provided — the package contains no install spec or script, so confirm 'clawhub install' actually supplies it or be prepared to run the tools directly; 2) install gitleaks and shipguard from their official sources (GitHub releases / pipx) and verify signatures if available; 3) test the scanner in a disposable repo first because pre-commit hooks will be installed and can block commits; 4) remember scan outputs can include sensitive strings (detected secrets) — treat reports and generated files as sensitive. If any of these points are unclear, request the wrapper code or a full install spec from the skill author before use.

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

# 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

clawhub install git-security-scanner

This adds the git-security-scan wrapper script and the skill definition.

Set Up Pre-Commit Hook

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

# 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:

[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:

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:

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
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 — gitleaks 8.30.0 + shipguard 0.3.2 (48+ SAST rules, 4 output formats).