pepperonas/wp-shield

# wp-shield **WordPress security audit scanner** — a clean-room, open-source alternative to [WPScan](https://wpscan.com/), built for legitimate black-box security audits of WordPress installations you own or are authorized to test.

_ _ _ _ __ ___ __ ___| |__ (_) ___| | __| | \ \ /\ / / '_ \ _____/ __| '_ \| |/ _ \ |/ _` | \ V V /| |_) |____\__ \ | | | | __/ | (_| | \_/\_/ | .__/ |___/_| |_|_|\___|_|\__,_| |_| ## Features (v0.1) - **Component enumeration** — WordPress core version, plugins, themes, users - **Misconfiguration detection** — exposed `wp-config.php` backups, debug logs, directory listings, dangerous xmlrpc/wp-cron exposure, missing security headers, open registration - **CVE matching** — local SQLite cache of the [WPVulnerability.net](https://www.wpvulnerability.net/) feed (free, no API key, no commercial fee). Wordfence Intelligence v3 is supported as an opt-in source if you have a Bearer token (their previously-free v1/v2 endpoints returned HTTP 410 Gone in 2025). - **Multi-format reports** — CLI tables (Rich), JSON, standalone HTML, SARIF 2.1.0 (GitHub Code Scanning) - **Polite by default** — respects `robots.txt`, rate-limited, identifies as `wp-shield/0.1` user-agent ## Roadmap - v0.2: Web dashboard (FastAPI + HTMX), scheduled scans - v0.3: Headless Chromium mode (Playwright) for SPA WordPress sites - v0.4: Opt-in authentication-stress module (gated by owned-domains allow-list) ## Installation pip install wp-shield # or for development: git clone https://github.com/pepperonas/wp-shield.git cd wp-shield pip install -e ".[dev]" ## Quickstart # 1) Sync the local vulnerability database (~once per day, default source: WPVulnerability) wp-shield update # default: source=wpvulnerability, plugin_limit=500, theme_limit=200 # or for Wordfence Intelligence (requires Bearer token): # WORDFENCE_API_TOKEN=xxx wp-shield update --source wordfence # 2) Run a scan — auto-saves report.{html,json,sarif,txt} into ./out/_/ wp-shield scan https://example.com # 3) Same scan but also open the HTML report in your browser when done wp-shield scan https://example.com --open # 4) Skip the on-disk artefact (CLI-only) wp-shield scan https://example.com --no-save # 5) Stream JSON to stdout (useful in pipelines) wp-shield scan https://example.com --output json --no-save # 6) Custom output directory (also configurable via config.yaml) wp-shield scan https://example.com --output-dir /var/lib/wp-shield/scans # 7) Database stats wp-shield db stats ### Auto-save layout Every scan creates a timestamped subdirectory inside `out/` (or your configured `output.output_dir`): out/ └── 20260529-185717_wpvulnerability.com/ ├── report.txt # ANSI-stripped Rich CLI snapshot — audit-trail friendly ├── report.html # standalone styled report (open in browser) ├── report.json # full Pydantic dump (machine-readable) └── report.sarif # SARIF 2.1.0 — upload to GitHub Code Scanning `out/` is in `.gitignore` by default so scan artefacts never get committed. ### One-liner: live demo against a public WordPress site cd /Users/martin/claude/wp-shield && source .venv/bin/activate && \ wp-shield scan https://wpvulnerability.com/ --mode mixed --rate-limit 3 --open This runs a polite mixed-mode scan, prints the live Rich table, writes all four report formats into `out/_wpvulnerability.com/`, and opens the HTML report in your default browser. ## Detection Modes `--mode passive` — analyze HTML only (zero "noisy" requests) `--mode mixed` _(default)_ — passive + targeted readme.txt / style.css probes `--mode aggressive` — full plugin/theme wordlist enumeration (~1–10 min, may trigger WAFs) ## Configuration Defaults can be overridden via `~/.config/wp-shield/config.yaml`: http: timeout: 15 max_concurrency: 10 user_agent: "wp-shield/0.1 (+https://github.com/pepperonas/wp-shield)" respect_robots_txt: true rate_limit_per_second: 5 scan: default_mode: mixed enumerate_users: true follow_redirects: true ## Legal & Ethics `wp-shield` is intended **exclusively for authorized security testing**. Running this tool against sites you do not own or have explicit written permission to test may be illegal in your jurisdiction (StGB §202a/b in Germany, Computer Fraud and Abuse Act in the US, UK Computer Misuse Act, etc.). The author is not responsible for misuse. By using this software you agree that: 1. You will only scan systems you own or are explicitly authorized to test 2. You accept full responsibility for any consequences of running scans 3. You will respect rate-limits, `robots.txt`, and target system stability The brute-force module (planned for v0.4) is **deliberately gated** behind a local `~/.config/wp-shield/owned-domains.txt` allow-list to prevent accidental misuse. ## Architecture - **Stack**: Python 3.11+, `httpx` (async), `BeautifulSoup` + `lxml`, `typer` + `rich` (CLI), `pydantic` (models), `sqlite3` (vuln cache), `jinja2` (reports/UI) - **Vuln data sources**: - **Default**: [WPVulnerability.net](https://www.wpvulnerability.net/) — free, no API key, per-component lookup. We pre-warm the cache with the top-N plugin/theme slugs from a built-in wordlist. - **Optional**: [Wordfence Intelligence v3](https://www.wordfence.com/products/wordfence-intelligence/) — requires a free Bearer token since the 2025 v3 migration (their v1/v2 endpoints now return HTTP 410 Gone). See `docs/ARCHITECTURE.md` (planned). ## License GPL-3.0-or-later — same license as the original WPScan and WPVulnerability projects. ## Acknowledgements Inspired by: - [WPScan](https://github.com/wpscanteam/wpscan) (Ruby, GPL-3.0) — the reference implementation - [WPVulnerability](https://www.wpvulnerability.com/) — open vulnerability database - [Wordfence](https://www.wordfence.com/) — for the free, commercial-use intelligence feed