---

Table of contents

• What it does
• Works with your AI agent
• How it compares
• How to use it
• Keeping it updated
• How it works (the 12-layer scan)
• Connecting your site (gateways)
• What it detects (39 families)
• Standalone scripts
• How it cleans safely
• Documentation
• FAQ
• A real example
• Contributing
• License

---

What it does

In plain English:

1. Looks at your site the way Google and attackers do — not just the way a browser does.
2. Scans the whole server, your database, your logs, and your users — 12 checks in all.
3. Reads each suspicious file before touching it, so it's careful about false alarms.
4. Cleans safely — backs up first, moves bad files to quarantine (doesn't delete), and checks the site still loads after every step. If something breaks, it restores the file.
5. Tells you how they got in — a stolen password? an outdated plugin? — and helps you close that door.
6. Proves the spam is gone by re-checking your pages as Googlebot.

---

Works with your AI agent

Not just Claude. This is designed to be agent-agnostic:

• The Python scripts run on their own — no AI needed. Scan, detect cloaking, verify core integrity, and check vulnerabilities straight from your terminal.
• The cleanup methodology works with any capable AI coding agent — Claude Code, Cursor, Codex, or anything that can read a project and run commands. Point your agent at this repo and ask it to scan or clean.
• It connects to your site over MCP (an open standard) or SSH — so any MCP-compatible client can drive it. SproutOS is the recommended gateway (no SSH needed).
• Claude Code gets the tightest fit — it loads this as a native skill, so a plain "scan my site" just works.

One tool, your choice of agent. Nothing here is locked to a single vendor.

---

How it compares

These are all good tools that do different things. The table describes each one's publicly documented approach — it's a comparison of design, not a claim that any product is better or worse. Run this alongside your existing security plugin; a second, independent look never hurts.

	Manual cleaning	Wordfence	MalCare	Sucuri	This tool
What it is	Do-it-yourself	Security plugin	Plugin + cloud	Plugin + remote service	AI agent / Claude skill
Where it works	You, on the server	Inside WordPress	Synced copy on its cloud	Remote scan + cloud firewall	Over a connection or SSH — whole server
How it finds malware	Your own inspection	Signature matching	Behavioral signals	Signatures + remote checks	Reads each file in context
Looks at	Wherever you look	WordPress files & DB	WordPress files & DB	Public pages + files (with agent)	Whole server, DB, logs, users
Checks pages as Googlebot (spam shown only to Google)	Only if you know to	Scans files, not a crawler fetch	Scans files on its cloud	Remote scanner reads public pages	Yes — as Googlebot & at the origin
Scans outside wp-content	If you check there	WordPress-focused	WordPress-focused	Public URLs; server scan via agent	Yes — web root and above
Explains how the site was hacked	Only if you dig through logs	Live traffic / login logging	Activity-log add-on	Post-hack analysis (paid)	Built-in log forensics + free vuln check
Reduces false alarms	Depends on your skill	Pattern rules	Signal scoring	Signature rules	Reads each file before flagging
Risk of breaking the site	High — easy to delete the wrong file	Low–medium	Low	Low	Low — backup, quarantine, auto-rollback
Skill required	High	Low	Low	Low	Low — the AI drives it
Undo / rollback	Your own backups	Manual restore	Restore from backup	Restore from backup	Quarantine + automatic rollback
Open source	n/a	Free plugin is GPL	Plugin GPL; engine proprietary	Plugin GPL; platform proprietary	Fully open (AGPL-3.0)
Price	Your time	Freemium	Freemium	Paid platform (free remote scan)	Free

_{Comparison of each option's publicly documented approach as of 2026, for orientation only — not a claim that any product is better or worse, and features change often, so please check current versions. Product names are trademarks of their respective owners. These tools are complementary; running an independent second scan is always sensible.}

What this tool adds on top: it checks your pages as a search engine (to catch spam shown only to Google), scans outside wp-content (web root and above), removes threats quarantine-first with an automatic health check, and explains how the site was hacked.

---

How to use it

Step 1 — Get it.

git clone https://github.com/adityaarsharma/wordpress-malware-removal.git

Step 2 — Point your agent at it.

• Claude Code (native skill): ln -s "$(pwd)/wordpress-malware-removal" ~/.claude/skills/wordpress-malware-removal
• Cursor / Codex / other agents: open the folder in your agent and tell it to follow SKILL.md.
• No agent: run the scripts directly.

Step 3 — Connect your site (see gateways) — SproutOS (no SSH) or SSH.

Step 4 — Just ask (or run the scripts):

"Scan example.com for malware"
"My site shows gambling spam in Google — clean it"
"Remove the Japanese keyword hack"
"How was this site hacked?"

Optional: find the entry point with the free Wordfence vulnerability feed

The free Wordfence Intelligence feed (free account, no usage cap, commercial use allowed) lets the tool cross-check your installed plugins/themes against known vulnerabilities to find the likely way in.

export WORDFENCE_API_KEY=your_free_key

This is optional — the core malware detection works without it. Setup details: references/wordfence-integration.md.

---

Keeping it updated

New malware appears constantly, so the detection is built to grow.

• Update the tool: git pull — you get the latest detection patterns and fixes.
• Vulnerability data updates itself: the Wordfence feed refreshes automatically (force it with python3 scripts/wordfence_client.py --refresh).
• Add your own patterns: the signature list (scripts/signatures.json) is easy to extend, and a built-in test corpus + CI make sure a new pattern catches real malware without flagging clean code. Full guide: references/growing-the-database.md.

Contributions welcome — open a PR or an issue.

---

How it works

The 12-layer forensic scan — click to expand

Every scan runs these layers (each degrades gracefully to the access you actually have). Full commands per layer: references/detection-playbook.md.

#	Layer	What it checks
1	External cloaking	Fetches pages as Googlebot vs a browser (and at the origin behind your CDN) to catch spam shown only to search engines
2	Web-root sweep	Files/folders outside wp-content — where a lot of malware hides
3	Core integrity	Modified or extra WordPress core files
4	Plugin/theme integrity	Nulled/hidden plugins, injected code, fake plugins, unauthenticated REST routes
5	Uploads	Executable PHP where it shouldn't be
6	mu-plugins & drop-ins	db.php, object-cache.php, must-use plugins that load on every request
7	Web-shells & backdoors	File managers and tiny auto-login backdoors
8	Obfuscation	eval(base64…), packed/encoded code
9	Database	Injection in posts, options, users, redirects, and log tables
10	Persistence	Cron, .htaccess, PHP prepend, stream-wrappers, server-level backdoors
11	Users & sessions	Unexpected admins, rogue application passwords
12	Log forensics	Reconstructs the attack timeline and finds the entry point + attacker IP

Flow:

Scan (12 layers) -> verify each finding in context (reduce false alarms) -> back up ->
quarantine -> health-check + rollback -> re-check as Googlebot -> harden -> report

How it decides what's malware (the no-false-alarm step)

It never deletes on a pattern match alone. For every suspicious item it:

1. Reads the actual file/row in context and decides, like an engineer, whether it's malicious or legitimate (a minified library, a code-snippet plugin, an AMP handler, etc.).
2. Classifies it as confirmed, needs a human, or false alarm. Only confirmed items are removed.
3. When unsure, it flags for review instead of deleting. A file it leaves for you is recoverable; a wrongly deleted file that breaks your site is not.

---

Connecting your site

Three ways to connect (SproutOS recommended, none required)

Gateway	Needs	Best for
SproutOS (recommended)	An Application Password	No SSH — connects right inside WordPress
Any other WordPress MCP	The MCP connected	If you already run one
SSH + WP-CLI	Shell access	Most complete access

SproutOS turns any WordPress site into an MCP server over an Application Password — no SSH needed. It's a doorway, not a dependency. Command mapping for each gateway: references/mcp-gateways.md.

---

What it detects

39 malware families — click to expand

SEO-spam cloaking · the Japanese keyword hack · pharma & gambling spam · redirect malware · web-shells · auto-login backdoors · uploader scripts · PHP stream-wrapper payloads hidden in images · fake "core function" loaders that rebuild from the database · unauthenticated REST-route backdoors · PHP object injection · wp-config.php injection · malicious .htaccess rules and DirectoryIndex hijacks · ?g= query-string spam · malicious cron jobs · unexpected admin accounts · rogue application passwords · card skimmers · cryptominers · SSH-key backdoors · files disguised as images · core-filename typosquats · double-extension shells · injected sitemaps · server-level persistence · and more.

Full, explained list: references/signature-library.md · the deep-dive on each family and how it hides: references/malware-families.md.

---

Standalone scripts

Run the engine directly — zero dependencies, stock Python 3

You don't need Claude to use the core scripts:

# 1. Check for spam shown only to search engines, across your whole sitemap
python3 scripts/cloaking_diff.py --sitemap https://example.com/sitemap.xml --origin-ip 1.2.3.4

# 2. Deep-scan a WordPress folder for the 39 malware families
python3 scripts/scan_patterns.py /path/to/wordpress --since 2026-06-14 --json findings.json

# 3. Check installed plugins/themes against known vulnerabilities (free Wordfence feed)
python3 scripts/wordfence_client.py --installed installed.json

Script	Mode	What it does
scripts/cloaking_diff.py	Clean	Detects cloaking (bot vs browser, origin vs CDN, JS-redirect)
scripts/scan_patterns.py	Clean	Pattern-scans a WordPress tree for malware candidates
scripts/safety_gate.py	Clean/Harden	Code-enforced backup → quarantine → rollback (won't delete without a backup)
scripts/reinstall_clean.py	Clean	Verifies core/plugins against official checksums; reinstalls from clean source
scripts/hardening_audit.py	Audit	Read-only config/exposure check (REST user-enum, XML-RPC, debug.log, headers…)
scripts/code_auditor.py	Audit	Audits plugin/theme/custom code for vulnerabilities (SQLi, XSS, CSRF, access control…)
scripts/wordfence_client.py	Audit	Matches installed versions against known CVEs
scripts/posture_score.py	Audit	Aggregates findings into an A–F security score + ranked fixes
scripts/signatures.json / audit_rules.json	—	The malware + code-audit pattern databases

---

How it cleans safely

The "don't break the site" protocol

• Makes a full database backup first — and the tool won't delete anything until that backup exists (enforced in code by safety_gate.py, not just a guideline).
• For malware injected into real WordPress/plugin files, it replaces them from the official clean source (reinstall_clean.py) instead of risky hand-editing.
• Moves standalone bad files to a quarantine folder — it doesn't delete them.
• Checks the site still loads after every change; if a change breaks something, it restores the file automatically.
• Asks you before anything permanent.
• Re-checks as Googlebot to confirm the spam is actually gone.

It aims to remove every infection it finds and leave the site working. No scanner can promise a site is permanently clean against future or unknown attacks, so it's honest about that: it lists anything it couldn't fully check and suggests a follow-up scan a day or two later to catch anything that tries to come back. Full protocol: references/remediation-playbook.md.

---

Documentation

All guides — click to expand

Document	What's inside
SKILL.md	The full methodology the AI follows
SPEC.md	Product & security specification
references/detection-playbook.md	Every layer's commands, per gateway
references/remediation-playbook.md	Safe removal: backup → quarantine → verify → rollback
references/cloaking-detection.md	The bot-vs-browser method in depth
references/malware-families.md	The malware families + 2026 threat landscape
references/signature-library.md	Human-readable signature list
references/edge-cases.md	Multisite, custom prefixes, reinfection, safeguards
references/mcp-gateways.md	Connecting via SproutOS / other MCP / SSH
references/wordfence-integration.md	Free Wordfence feed setup
references/growing-the-database.md	How to grow the vulnerability + attack-pattern coverage
references/incident-case-study.md	A real hack, start to finish

---

FAQ

How do I remove the Japanese keyword hack?

Connect the tool to your site and say "remove the Japanese keyword hack." It looks for the spam pages that appear only to search engines, rogue sitemaps, .htaccess tricks, and database injections, cleans them safely, and re-checks as Googlebot to confirm they're gone.

My WordPress site redirects visitors to spam. Can it help?

Yes — it looks for redirect code in .htaccess, the database, theme files, and injected JavaScript, including redirects that only trigger on mobile or for search engines.

My scanner says the site is clean, but Google flags it. Why?

Some infections (called cloaking) show spam only to search engines and clean content to everyone else — including scanners. This tool checks your pages as Googlebot, which is how it can spot that kind of infection.

Does it work without SSH?

Yes. Connect SproutOS (over an Application Password) and it runs without shell access.

Will it break my site?

It's designed not to: it backs up first, quarantines instead of deleting, and checks the site after every step, restoring anything that causes a problem.

---

A real example

A hidden gambling-spam infection a normal scan didn't catch

A live WordPress site was infected with gambling spam that only appeared in Google search results — the site looked completely normal to visitors and to the security scanner that was active on it. The malware was hiding in folders outside wp-content, plus a tiny backdoor file that kept letting the attacker back in.

This tool is built to find exactly that kind of hidden infection. The full, step-by-step write-up is included as a worked example and regression test: references/incident-case-study.md.

---

Contributing

New detection patterns are always welcome

Malware changes constantly. The pattern list (scripts/signatures.json) is easy to extend — add a family, add a safeguard against false alarms, and open a PR. Found something it missed? Open an issue with a sanitized sample.

If this helped you, a star helps others find it.

---

Works well alongside

Wordfence, MalCare, and Sucuri are well-known WordPress security tools; running an independent second scan is always sensible. This project uses SproutOS as its recommended gateway and the free Wordfence Intelligence vulnerability feed.

License

AGPL-3.0-or-later. Strong copyleft: you're free to use, modify, and self-host it, but if you run a modified version as a network service, you must share your source. This keeps hosted derivatives open.

---