Documentation

Install

Pick whichever fits — see the full install matrix.

# Windows (winget)
winget install Bryan.WPSecScan

# macOS / Linux (pip)
pip install wpsecscan

# Docker
docker run --rm ghcr.io/bryanflowers/wpsecscan:2.8.4 --help

First scan

# Walk every check with a synthetic site
wpsecscan --demo

# Pull the latest CVE feed (8 sources, deduped)
wpsecscan db update

# Scan your site (passive checks only by default)
wpsecscan scan https://your-site.com

# Save the report
wpsecscan scan https://your-site.com --out report.html --format html

Aggressive mode

31 of the 294 checks send active payloads (SQLi probes, XSS reflections, SSRF, etc.). They're off by default. Opt-in with --aggressive. Active exploit verification needs a stricter consent gate: WPSECSCAN_OWNED_TARGETS=1 AND the target must be in your sites list (~/.wpsecscan/sites.json).

wpsecscan scan https://your-site.com --aggressive

# Active PoC verification (stricter consent)
WPSECSCAN_OWNED_TARGETS=1 wpsecscan scan https://your-site.com \
  --aggressive --verify-exploits

Report formats

12 native formats + 14 emit formats (via wpsecscan emit):

• html · interactive single-page
• pdf · executive report (needs [pdf] extra)
• json · machine-readable
• csv · spreadsheet-friendly
• xlsx · Excel
• md · GitHub-flavored Markdown
• sarif · for code-scanning UIs
• cyclonedx · SBOM-compatible
• badge · SVG shield
• burp · Burp Suite import
• zap · OWASP ZAP import
• eli5 · plain-English exec summary

v2.8.x subcommand families

New in v2.8.x: three umbrella subcommands that surface 37 export / push / AI helpers from saved scan reports.

# 14 export formats (SBOM, in-toto, CEF, LEEF, HIPAA, FedRAMP, CE+, E8, …)
wpsecscan emit spdx-sbom report.json --out sbom.json
wpsecscan emit cef report.json --out splunk-events.cef
wpsecscan emit hipaa-map report.json
wpsecscan emit --help        # list all 14 formats

# 16 push destinations
wpsecscan push gitlab-ci report.json
wpsecscan push sentry report.json
wpsecscan push defectdojo report.json
wpsecscan push chat report.json   # Mattermost / RocketChat / Telegram

# 7 LLM helpers (BYO OpenAI/Anthropic/Ollama key)
wpsecscan ai injection-check response.txt
wpsecscan ai control-map report.json --framework hipaa
wpsecscan ai waf-rule finding.json --target-waf cloudflare
wpsecscan ai drift https://example.com 42

v2.8.4 utilities

wpsecscan init                          # interactive first-run wizard
wpsecscan check disable wpgraphql       # toggle a check off
wpsecscan check enable wpgraphql        # turn it back on
wpsecscan check list --json             # machine-readable inventory
wpsecscan benchmark https://example.com # per-check timing table
wpsecscan export-config                 # show effective merged config
wpsecscan compare-pypi-version          # is your install behind PyPI?

Daemon mode

REST API for the GUI, mobile, and SDK clients.

wpsecscan daemon --config daemon.yaml
# OpenAPI 3.1 spec: github.com/bryanflowers/wpsecscan/blob/main/openapi/wpsecscan-api.yaml

Scheduled scans

wpsecscan sites add example --url https://example.com
wpsecscan schedule add example --cron "0 2 * * *"
wpsecscan schedule list
wpsecscan digest weekly

Companion plugin

For server-side checks (MFA audit, DB triggers, wp-cron jobs, webhook inventory): install wpsecscan-companion.zip in your WP admin → Plugins → Upload Plugin. Generate a shared secret in plugin settings, then store it in WPSecScan:

wpsecscan sites add example --url https://example.com \
  --companion-token sk_xxx

AI options (opt-in)

10 AI-assisted features behind an opt-in panel. All off by default. Require an LLM key (OpenAI / Anthropic / Ollama). PII masking on by default.

export OPENAI_API_KEY=sk-...
wpsecscan ai-options list
wpsecscan ai-options set severity_auto_tuner true
wpsecscan ai-options set exec_brief_audience cto

# Or via GUI: Tools → Advanced AI options...

Usage analytics (opt-in, local-first)

Off by default. Local-only by default (events never leave your machine unless you also set an upload URL). Per-event field allowlist prevents PII leaks.

wpsecscan analytics enable
wpsecscan analytics show 50      # inspect last 50 events
wpsecscan analytics export out.jsonl
wpsecscan analytics forget       # delete everything locally

Full doc: docs/analytics.md.

Enterprise mode

Self-hostable. Same codebase as the OSS scanner — no separate fork. Includes OIDC + SAML SSO, RBAC, HMAC-chained audit log, two-person sign-off for aggressive scans, multi-tenant namespacing, per-tenant quotas, Stripe metered-billing scaffold.

See wpsecscan/auth/, wpsecscan/enterprise/, and docs/api-reference.md.

Integrations

Windows Defender false-positive

Defender may flag wpsecscan.exe on first run. It's a known false-positive because the binary contains string-pattern signatures for webshells (so we can detect them in your site). The .exe is Sigstore-signed; verify the signature to confirm authenticity.

Workaround: add an exclusion via Tools → Add Windows Defender exclusion... in the GUI, or run the PowerShell helper:

Add-MpPreference -ExclusionPath "C:\Tools\wpsecscan.exe"

Writing a check

Drop a .py module in ~/.wpsecscan/plugins/ or contribute one upstream. The scaffolder generates a skeleton:

python scripts/new-check.py --id my_check
python scripts/lint-checks.py           # enforce hygiene

Full tutorial: docs/writing-a-check.md.