whiterabbit

Grade the security posture of a web application — deployed or in source — in one command.

Agent-written code ships fast, but it ships with a predictable set of security gaps: missing headers, outdated JavaScript libraries, TLS misconfigurations, exposed admin panels, vulnerable dependencies, OWASP Top 10 code flaws. WhiteRabbit runs best-in-class scanners against a live target or a source repository and distills the results into a single letter grade (A+ through F) with actionable remediation for every finding.

# Scan a live web target
whiterabbit scan example.com

# Scan a GitHub repo for dependency CVEs and OWASP issues
whiterabbit scanrepo https://github.com/owner/repo

Automated code generation is accelerating how fast applications get deployed. The security fundamentals — transport encryption, header hardening, dependency hygiene — are exactly the things that slip through when speed is the priority. WhiteRabbit exists to catch those gaps post-deployment, before an attacker does.

WhiteRabbit was itself built with Claude Code — the CLAUDE.md in this repo is the real file used during development, not a demo. A scanner for agent-written code that was agent-written is the honest version of eating your own dogfood.

pip install -e ".[dev]"

Most scanners are pure Python. Several require external binaries:

testssl.sh on Windows: WhiteRabbit invokes testssl.sh through Git Bash. It searches PATH first, then falls back to the path in the WHITERABBIT_TESTSSL_PATH environment variable (default: C:/Tools/testssl/testssl.sh). Set this variable if your testssl.sh lives elsewhere:

set WHITERABBIT_TESTSSL_PATH=D:/path/to/testssl.sh

# Scan a target (runs all available scanners)
whiterabbit scan example.com

# Quick scan (SSL + headers only)
whiterabbit scan example.com --quick

# Run specific scanners
whiterabbit scan example.com --scanners ssl,headers

# Output to HTML report
whiterabbit scan example.com -o report.html

# Output as JSON
whiterabbit scan example.com --format json

# JSON to file
whiterabbit scan example.com --format json -o report.json

# Verbose output
whiterabbit scan example.com -v

# Custom timeout (per scanner, in seconds)
whiterabbit scan example.com --timeout 60

# List available scanners
whiterabbit list-scanners

# Check scanner dependencies
whiterabbit check-deps

# Scan a GitHub repo (clones, scans, cleans up)
whiterabbit scanrepo https://github.com/owner/repo

# Scan a local directory
whiterabbit scanrepo ./my-project

# Specific branch
whiterabbit scanrepo https://github.com/owner/repo --branch dev

# Run only the CVE scanner
whiterabbit scanrepo ./my-project --scanners cve

# Full clone (default is shallow, depth=1)
whiterabbit scanrepo https://github.com/owner/repo --depth 0

# Keep the cloned repo after scanning
whiterabbit scanrepo https://github.com/owner/repo --keep-clone

# Output to HTML or JSON
whiterabbit scanrepo ./my-project -o report.html
whiterabbit scanrepo ./my-project --format json -o report.json

# List available repo scanners
whiterabbit list-repo-scanners

# Check repo scanner dependencies
whiterabbit check-repo-deps

Both pipelines share the same pattern: scanners run concurrently via asyncio.TaskGroup with per-scanner timeouts. Every scanner is contractually forbidden from raising — it catches its own exceptions and returns a ScanResult with error set. This means a single broken or timed-out scanner never takes down the run or corrupts other results.

CLI (cli.py)
 ├─ scan command
 │   └─ ScanRunner (runner.py)
 │       └─ asyncio.TaskGroup
 │           ├─ SSLScanner        → ScanResult
 │           ├─ HeaderScanner     → ScanResult
 │           ├─ NucleiScanner     → ScanResult
 │           ├─ RetireJSScanner   → ScanResult
 │           └─ TestSSLScanner    → ScanResult
 │
 └─ scanrepo command
     ├─ clone_repo() (temp dir, auto-cleanup)
     └─ RepoScanRunner (repo_runner.py)
         └─ asyncio.TaskGroup
             ├─ CVEScanner        → ScanResult
             ├─ OWASPScanner      → ScanResult
             ├─ TrivyScanner      → ScanResult
             ├─ SecretScanner     → ScanResult
             ├─ BanditScanner     → ScanResult
             ├─ SlopsquatScanner  → ScanResult
             ├─ MalwareScanner   → ScanResult
             ├─ PinningScanner    → ScanResult
             └─ LogLeakScanner    → ScanResult
                     │
                     ▼
             ScanReport (aggregated findings + letter grade)

Each scanner is a single class implementing async scan(target, config) -> ScanResult. Repo scanners follow the same contract but take a local directory path instead of a URL, and use RepoScanConfig instead of ScanConfig.

For remote repos, scanrepo clones into a temporary directory (shallow by default) and cleans up automatically after the scan completes.

Nuclei is restricted by tag selection, not by a "passive-only" flag. The DEFAULT_TAGS are exposure, misconfig, and tech. The EXCLUDED_TAGS block: fuzz, exploit, intrusive, dos, brute, sqli, xss, rce, auth-bypass.

This is policy, not a guarantee — a community template tagged exposure that behaves intrusively would still run. Review your template set if this matters for your environment.

The header scanner and retire.js scanner disable TLS certificate verification (verify=False) on target-probing requests. This is intentional: a security scanner that refuses to connect to misconfigured hosts cannot assess misconfigured hosts.

The retire.js scanner uses a separate client with TLS certificate verification enabled to download its vulnerability database from GitHub (raw.githubusercontent.com).

Web scanning sends real HTTP requests and invokes external tools against the target. Only scan targets you own or have explicit permission to test. Unauthorized scanning may violate laws and terms of service.

Repository scanning is static analysis — it reads local files and queries public vulnerability databases (OSV.dev, PyPI, npm registry). No traffic is sent to the scanned application itself. You still need appropriate access rights to the source code.

The master branch enforces the following rules:

CI runs across a 2×3 matrix (Ubuntu + Windows, Python 3.11–3.13) and gates on pytest (≥80 % coverage), ruff check, ruff format, and mypy.

See CONTRIBUTING.md for instructions on adding new web scanners or repo scanners.

MIT