https://github.com/pepperonas/wp-shield
WordPress security audit scanner — clean-room WPScan alternative with free local CVE database (WPVulnerability.net + optional Wordfence v3). Python · async · CLI · JSON/HTML/SARIF reports.
https://github.com/pepperonas/wp-shield
async cli cve httpx infosec pentest python sarif security security-audit security-scanner typer vulnerability-scanner wordpress wpscan
Last synced: 11 days ago
JSON representation
WordPress security audit scanner — clean-room WPScan alternative with free local CVE database (WPVulnerability.net + optional Wordfence v3). Python · async · CLI · JSON/HTML/SARIF reports.
- Host: GitHub
- URL: https://github.com/pepperonas/wp-shield
- Owner: pepperonas
- License: other
- Created: 2026-05-29T18:50:35.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-29T18:58:56.000Z (about 1 month ago)
- Last Synced: 2026-05-29T20:21:54.786Z (about 1 month ago)
- Topics: async, cli, cve, httpx, infosec, pentest, python, sarif, security, security-audit, security-scanner, typer, vulnerability-scanner, wordpress, wpscan
- Language: Python
- Homepage: https://github.com/pepperonas/wp-shield
- Size: 71.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# 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
```bash
pip install wp-shield
# or for development:
git clone https://github.com/pepperonas/wp-shield.git
cd wp-shield
pip install -e ".[dev]"
```
## Quickstart
```bash
# 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
```bash
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.
> `wpvulnerability.com/` is used as the demo target because its maintainer publishes the very vulnerability data this tool consumes — it is an explicitly invited test surface. Replace the URL with **any system you own or have written authorization to test**.
## 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`:
```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