An agentic security research framework for WordPress plugins and themes. Built for the Wordfence Bug Bounty Program, wpguard orchestrates 20+ specialized AI agents through Claude Code to find, verify, and report vulnerabilities at scale.
This is not a scanner. wpguard is an autonomous research system — it downloads source code, maps attack surfaces, delegates deep analysis to expert agents, verifies findings in a live sandbox, and prepares submission-ready reports.
Caution
Run wpguard in a VM or dedicated host only. This tool grants broad permissions to autonomous AI agents — filesystem access, Docker control, shell execution, network requests, and process management. Agents operate with the full privileges of the user running Claude Code. Running on your personal machine or a shared server risks unintended file modifications, data loss, or system damage. Use a disposable VM or a dedicated research box.
Not suitable for running inside Docker. wpguard itself spawns Docker containers (WordPress sandbox) and requires Docker socket access. Running inside a container creates Docker-in-Docker complexity and breaks sandbox networking. Install directly on the VM host.
You: /pm audit flavor-starter (a WordPress theme with 50k installs)
PM Orchestrator
|
+--> Downloads theme, checks Wordfence scope, rebuilds sandbox
+--> Delegates to surface-mapper (2-min grep recon)
| Returns: 12 SQLi candidates, 8 XSS candidates, 3 auth gaps
|
+--> Launches experts in parallel (each gets prioritized file targets):
| sqli-expert --> finds blind SQLi in search handler
| xss-expert --> finds stored XSS in theme options
| missing-auth-expert --> finds unprotected AJAX endpoint
| data-flow-expert --> finds option-write -> include() chain
| critical-thinker --> chains CSRF + option write -> LFI
|
+--> Verification pipeline (mandatory for every finding):
| poc-writer --> writes standalone PoC scripts
| poc-runner --> executes against sandbox, catches false positives
| qa-triage --> scope check, CVSS, writeup, Discord notification
| impact-assessor --> rejects obscure impact, downgrades inflated CVSS
| bb-submission --> clean sandbox repro, Wordfence submission format
| poc-recorder --> terminal + browser video evidence
|
+--> Discord: "3 validated findings for flavor-starter"
- 20+ specialized agents — each expert covers a specific vulnerability class with deep domain knowledge
- PM orchestrator (
/pm) — coordinates the entire research lifecycle, never skips phases - Surface mapper — fast grep-based recon that prioritizes file:line targets for each expert
- Context survival protocol — agents save progress incrementally, checkpoint every 10 tool calls, survive context exhaustion
- Mandatory verification — every finding passes through PoC writer -> PoC runner -> QA triage -> impact assessor -> BB submission
| Agent | Focus |
|---|---|
sqli-expert |
SQL injection (UNION, blind, second-order, identifier injection) |
xss-expert |
Stored, reflected, DOM-based XSS |
file-rce-expert |
File upload/read/write/delete, path traversal, RCE |
missing-auth-expert |
Missing capability checks on AJAX/REST/admin endpoints |
idor-expert |
Insecure Direct Object Reference |
priv-esc-expert |
Privilege escalation, options update chains, role manipulation |
object-injection-expert |
PHP object injection, phar deserialization |
ssrf-expert |
Server-side request forgery, cloud metadata |
race-condition-expert |
TOCTOU, database races, limit bypass |
csrf-expert |
CSRF, missing nonce validation |
data-flow-expert |
Cross-feature data flows — writes in one feature consumed unsafely by another |
critical-thinker |
Cross-domain chains, second-order bugs, multi-step vulns |
lfi-rfi-expert |
Local/remote file inclusion |
xxe-expert |
XML external entity injection |
deserialization-expert |
JSON/YAML parsing, type juggling |
logic-flaw-expert |
Business logic bugs, payment bypass |
info-disclosure-expert |
Sensitive data exposure, debug endpoints |
code-injection-expert |
eval, call_user_func, dynamic dispatch |
open-redirect-expert |
wp_redirect, header Location, JS redirects |
Full research support for both WordPress plugins and themes:
- Download & extract source code from wordpress.org
- SVN integration — commit history, diffs between revisions, remote diffing (no local downloads needed)
- Global monitoring — track recently updated and newly added plugins/themes across the ecosystem
- Changelog enrichment — parsed changelogs and SVN commit logs for high-value updates
Docker-based WordPress instance for live exploitation testing:
- Authenticated requests at any role level (subscriber, contributor, author)
- Nonce extraction from pages/endpoints accessible at the attacker's auth level
- Plugin/theme installation via WP-CLI
- Mandatory rebuild between audits — no artifact contamination
- Ecosystem setup — WooCommerce, BuddyPress, Elementor environments with test data
Built-in rules for the Wordfence Bug Bounty Program:
- Automatic eligibility checking by install count and vulnerability type
- Auth level validation (subscriber through author, editor/admin out of scope)
- Excluded vendor detection
- CVSS scoring guidance
Track the entire WordPress ecosystem for research opportunities:
/watch plugins # Scan recently updated plugins
/watch themes # Scan recently updated themes
/watch new-plugins # Scan newly added plugins
/watch new-themes # Scan newly added themes
/watch list # Check watchlist for SVN-level changes
/watch all # Run everything (verbose; only on demand)
/loop 30m /watch plugins # Continuous monitoring every 30 minutes
- Global plugin updates — recently updated plugins with changelog + SVN log
- Global theme updates — recently updated themes with changelog + SVN log
- New plugins — freshly added to wordpress.org (zero prior scrutiny)
- New themes — freshly added themes
- Watchlist — SVN-level change tracking for specific slugs
- Dedup — only surfaces new changes since last check
Claude Code
(PM Orchestrator)
|
/pm /watch /recon /nday ...
|
MCP Protocol (stdio / http)
|
+-------+-------+-------+-------+
| | | |
wpguard MCP | | Veloria MCP
(60+ tools) | | (WordPress-wide
| | | regex code search,
| | | private by default)
| Playwright devrag
| (browser (RAG over web-pentest KB,
| automation) optional)
+-----+-----+-----+-----+
| | | | |
Plugin Theme SVN Sandbox Findings
API API Client (Docker) Manager
| | | | |
v v v v v
WordPress.org plugins.svn wp_app state.json
Plugins API themes.svn container findings.json
Themes API (Docker)
| Category | Tools | Description |
|---|---|---|
| Plugin Discovery | wpguard_plugin_info, wpguard_search, wpguard_download, wpguard_bulk_download |
Search, inspect, and download plugins |
| Theme Discovery | wpguard_theme_info, wpguard_theme_search, wpguard_theme_download |
Search, inspect, and download themes |
| Plugin SVN | wpguard_svn_log, wpguard_svn_diff, wpguard_svn_revision |
Plugin commit history and diffs |
| Theme SVN | wpguard_theme_svn_log, wpguard_theme_svn_diff |
Theme commit history and diffs |
| Watch (Plugins) | wpguard_watch_add, wpguard_watch_check, wpguard_watch_global, wpguard_watch_new |
Plugin monitoring and global updates |
| Watch (Themes) | wpguard_watch_global_themes, wpguard_watch_new_themes |
Theme monitoring and global updates |
| Sandbox | wpguard_sandbox_start, wpguard_sandbox_request, wpguard_sandbox_wp_cli, wpguard_sandbox_get_nonce, wpguard_sandbox_list_endpoints, wpguard_sandbox_map_nonces |
Docker WordPress instance, REST discovery, nonce mapping |
| Data-flow oracle | wpguard_sink_trace |
Runtime tracer: records every hit on a dangerous sink (SQL, option/user/meta write, HTTP/SSRF, mail) with the PHP backtrace + optional Xdebug internal-function trace. Confirms writes/forges/priv-changes against ground truth (enable → run PoC → read). |
| Scope | wpguard_scope_check_plugin, wpguard_scope_check_finding, wpguard_scope_get_vulns |
Wordfence bounty eligibility |
| Findings | wpguard_finding_create, wpguard_finding_update, wpguard_finding_list, wpguard_finding_stats |
Vulnerability tracking and management |
| CVE Database | wpguard_cve_search, wpguard_cve_get, wpguard_cve_stats |
Wordfence vulnerability database |
| Discord | wpguard_discord_notify_finding, wpguard_discord_notify_summary |
Real-time notifications |
| Scoring | wpguard_target_score |
Priority scoring for target selection (installs, CVEs, audit history) |
| Regression | wpguard_regression_check |
Re-run previous PoCs to detect incomplete patches |
| Dedup | wpguard_finding_check_duplicate |
Check for duplicate findings before creation |
| Project | wpguard_init_research |
Initialize research project with all agents and commands |
Tested on Debian 13 (trixie). Adapt repo URLs and package names for other distros. Commands are intended to be run on a disposable VM or dedicated research host (see warning at the top of this README).
curl -fsSL https://claude.ai/install.sh | bashsudo apt remove $(dpkg --get-selections docker.io docker-compose docker-doc podman-docker containerd runc | cut -f1)3.1. Add Docker repo:
# Add Docker's official GPG key:
sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
# Add the repository to Apt sources:
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: trixie
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt update3.2. Install Docker:
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin3.3. Start Docker:
sudo systemctl start docker3.4. Add your user to the docker group:
sudo usermod -aG docker $USER && newgrp dockercurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash4.1. Add proper exports to .zshrc or .bashrc:
export NVM_DIR="$HOME/.config/nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion4.2. Source your config:
source ~/.zshrcnvm install 24npm install -g svg-term-cli
sudo apt install subversion
sudo apt install ffmpeg
pipx install asciinema
pipx install semgrep
pipx install playwright && playwright install chromium && npx playwright install-deps chromium && sudo mkdir -p /opt/google/chrome && sudo ln -s /usr/bin/chromium /opt/google/chrome/chromeGet the proper architecture binary from asciinema/agg releases.
curl -L https://github.com/asciinema/agg/releases/download/v1.8.1/agg-x86_64-unknown-linux-gnu -o ~/.local/bin/agg && chmod +x ~/.local/bin/aggSign up at wordfence.com/threat-intel, then go to Account → Integrations to get your API key.
For finding notifications. Server Settings → Integrations → Webhooks.
# Set API keys
export WORDFENCE_API_KEY="your-key-here"
export DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/..." # optionalClone the repo and install from source:
git clone https://github.com/0xQRx/wpguard.git
cd wpguard
pipx install .wpguard init wpsecThis creates the full project structure inside wpsec/: CLAUDE.md, all agent definitions, slash commands, .mcp.json (wpguard, playwright, devrag, veloria), and settings.local.json permissions.
cd wpsec && claudeClaude will prompt you to approve the MCP servers configured in .mcp.json. Disable devrag for now — it requires a separate knowledge-base configuration. Leave the others (wpguard, playwright, veloria) enabled.
devrag provides RAG-powered search over curated security research documents (PayloadsAllTheThings, HackTricks, OWASP, etc.) and significantly improves expert-agent effectiveness. Not required to start, but recommended once you're ready to set up a corpus. See github.com/0xQRx/devrag for setup. Once configured, set:
export WPGUARD_RAG_DOCS="/path/to/WebPentestRAG"and re-run wpguard init <project> so the new .devrag/config.json picks it up.
/pm audit flavor starter theme with 50k installs
The PM orchestrator handles everything — download, scope check, sandbox setup, surface mapping, expert delegation, verification pipeline, and submission prep.
| Command | Purpose |
|---|---|
/pm |
PM orchestrator — start all research here |
/watch |
Ecosystem monitor — scan for updated plugins/themes |
/target-research |
Find and scope plugins/themes for analysis |
/recon |
Lightweight assessment before full audit |
/status |
Dashboard of current audit progress |
/findings |
List all findings with status and severity |
/nday |
N-day research — PoCs for known/patched CVEs |
/diff |
Security-focused version diff — flag dangerous code changes |
/patrol |
Lightweight audit watchdog for cron loops — checks progress, re-triggers stalls |
# Plugin operations
wpguard info akismet
wpguard search "gallery" --per-page 50
wpguard download --search backup --min-installs 50000 --count 10 --extract
# Watch operations
wpguard watch add akismet wordfence contact-form-7
wpguard watch check
wpguard watch --interval 30m --send-report
# SVN operations
wpguard svn log akismet --limit 20
wpguard svn diff akismet 3000000 3001000 --show-diff1. Download wpguard_download / wpguard_theme_download
2. Scope check wpguard_scope_check_plugin
3. CVE history wpguard_cve_search
4. Sandbox rebuild wpguard_sandbox_destroy + wpguard_sandbox_start
5. Surface map surface-mapper agent (grep recon, file:line targets)
6. Expert analysis Parallel expert agents with specific targets
7. Escalation vuln-escalator tests lower auth levels
8. PoC writing poc-writer for each finding
9. PoC execution poc-runner against sandbox
10. QA validation qa-triage (scope, CVSS, writeup)
11. Impact review impact-assessor (mandatory — rejects obscure impact)
12. Submission bb-submission (clean repro, Wordfence format)
13. Video evidence poc-recorder (terminal + browser recordings)
Large codebases exhaust agent context. wpguard agents are designed to survive:
- Save-first — create progress report scaffold within first 3 tool calls
- Checkpoint — update progress every 10 tool calls
- Immediate saves — findings saved as drafts the moment they're discovered
- Relaunchable — PM detects partial analysis and relaunches with progress context
| Min Installs | Vulnerability Types | Max Auth Level |
|---|---|---|
| 25 | RCE, File Upload/Read/Delete, Options Update, Auth Bypass, Priv Esc | Author |
| 500 | SQL Injection, Stored XSS | Author |
| 50,000 | Reflected XSS, CSRF, Missing Auth, IDOR, SSRF, Object Injection | Author |
research-project/
+-- CLAUDE.md # Project instructions for agents
+-- .claude/
| +-- commands/ # Slash commands (/pm, /watch, /recon, ...)
| +-- agents/ # 20+ agent definitions
| | +-- sqli-expert/agent.md
| | +-- xss-expert/agent.md
| | +-- data-flow-expert/agent.md
| | +-- ...
| +-- settings.local.json # MCP tool permissions
+-- .mcp.json # MCP server config
+-- targets/{slug}/extracted/ # Plugin/theme source code
+-- reports/{slug}/
| +-- PLAN.md # Audit plan and progress
| +-- surface_map.md # Attack surface report
| +-- progress_{agent}.md # Per-agent progress
| +-- {finding_id}/
| +-- poc.py # PoC script
| +-- writeup.md # Vulnerability writeup
+-- wpguard_findings.json # Findings database
+-- recently_updated.json # Plugin update monitor output
+-- recently_updated_themes.json # Theme update monitor output
+-- state.json # Watch state
Combine /loop with slash commands for fully autonomous operation. These run inside Claude Code.
Step 1: Launch the audit with /pm (run once, with your strategy):
/pm — HIGH THREAT TIER research. Focus:
- RCE, File Upload/Read/Delete, Options Update, Auth Bypass, Priv Esc to admin
- CVSS < 7.5 = REJECT — do not write PoCs, do not waste pipeline
- 50K+ installs minimum (unless recently updated with suspicious changelog)
- Unauth, Customer, Subscriber roles. Contributor/Author OK for RCE/File/Options only
- Pick target: run wpguard_target_score, prefer plugins with 5-15 CVEs + frontend interaction
- Run ALL phases, no skipping, each phase confirmed before next
This starts the first audit. PM creates the plan, launches experts, runs the full pipeline.
Step 2: Set /patrol on a cron to keep things moving:
/loop 15m /patrol
/patrol is a lightweight watchdog (~50 lines vs PM's ~300). Every 15 minutes it:
- Running normally → one-line status, exits (< 500 tokens)
- Stalled → re-triggers the stuck agent directly (doesn't reload PM)
- Complete → records audit, scores targets, calls
/pmto start next audit - No audit → picks next target, calls
/pm
90% of cron cycles cost 1/10th of what /pm would cost. PM only loads when a new audit needs to start.
/loop 30m /watch plugins
Scans WordPress.org every 30 minutes for plugin updates (swap plugins for themes, new-plugins, new-themes, or list as needed). Results saved to recently_updated.json and recently_updated_themes.json. The research loop above picks these up automatically.
/loop 2h /compact
Compresses conversation context every 2 hours to prevent context exhaustion during long autonomous sessions.
| Variable | Description |
|---|---|
WORDFENCE_API_KEY |
Wordfence Intelligence API key (for CVE database) |
WPGUARD_RAG_DOCS |
Path to web pentesting knowledge base for devrag (PayloadsAllTheThings, HackTricks, etc.) |
DISCORD_WEBHOOK_URL |
Discord webhook for finding notifications |
WP_SANDBOX_HOST |
Sandbox host (default: 172.17.0.1) |
WP_SANDBOX_PORT |
Sandbox port (default: 8000) |
WPGUARD_SANDBOX_DIR |
Custom sandbox Docker Compose directory |
MIT License - see LICENSE for details.
This tool is for authorized security research within the Wordfence Bug Bounty Program. All analysis is performed on downloaded source code and controlled sandbox environments. Always respect WordPress.org terms of service and individual plugin/theme licenses.
wpguard grants autonomous AI agents broad system access including filesystem writes, Docker management, shell execution, and network requests. Always run in an isolated environment (VM or dedicated host). The authors are not responsible for damage caused by running this tool on production or personal systems.