wordpress-malware-removal

<div align="center"> # WordPress Malware Removal ### Find the hidden malware your scanner can't see — and learn how they got in. [](https://github.com/adityaarsharma/wordpress-malware-removal/actions/workflows/ci.yml) [](LICENSE) [](#works-with-your-ai-agent) [](#standalone-scripts) [](#contributing) [](https://github.com/adityaarsharma/wordpress-malware-removal/stargazers) Google flagged your site. Or it redirects visitors to spam. Or your scanner says "all clean" while gambling pages rank under your domain. That's usually malware built to **hide** — from you, and from tools that only look at the site the way a browser does. **WordPress Malware Removal** finds the stealthy stuff — SEO-spam **cloaking**, the **Japanese keyword hack**, redirect malware, web-shells, and backdoors — by checking your site the way **Google and an attacker** see it. It cleans **safely** (full backup first, nothing deleted blind, and it puts a file back if a change breaks the site) and tells you **how the attacker got in**, so it doesn't happen again. **Free · open-source (AGPL-3.0) · runs with any AI coding agent — Claude Code, Cursor, Codex, or any MCP client.** </div> --- ## Table of contents - [What it does](#what-it-does) - [Works with your AI agent](#works-with-your-ai-agent) - [How it compares](#how-it-compares) - [How to use it](#how-to-use-it) - [Keeping it updated](#keeping-it-updated) - [How it works (the 12-layer scan)](#how-it-works) - [Connecting your site (gateways)](#connecting-your-site) - [What it detects (39 families)](#what-it-detects) - [Standalone scripts](#standalone-scripts) - [How it cleans safely](#how-it-cleans-safely) - [Documentation](#documentation) - [FAQ](#faq) - [A real example](#a-real-example) - [Contributing](#contributing) - [License](#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](https://github.com/posimyth/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 &amp; DB | WordPress files &amp; DB | Public pages + files (with agent) | Whole server, DB, logs, users | | **Checks pages as Googlebot** <br>_{(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 &amp; 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 <b>publicly documented approach</b> 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.** ```bash 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](#standalone-scripts) directly. **Step 3 — Connect your site** (see [gateways](#connecting-your-site)) — 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?"* <details> <summary><b>Optional: find the entry point with the free Wordfence vulnerability feed</b></summary> <br> The free [Wordfence Intelligence](https://www.wordfence.com/threat-intel/) 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. ```bash export WORDFENCE_API_KEY=your_free_key ``` This is optional — the core malware detection works without it. Setup details: [references/wordfence-integration.md](references/wordfence-integration.md). </details> --- ## 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`](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](references/growing-the-database.md). Contributions welcome — [open a PR or an issue](#contributing). --- ## How it works <details> <summary><b>The 12-layer forensic scan</b> — click to expand</summary> <br> Every scan runs these layers (each degrades gracefully to the access you actually have). Full commands per layer: [references/detection-playbook.md](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 &amp; drop-ins** | `db.php`, `object-cache.php`, must-use plugins that load on every request | | 7 | **Web-shells &amp; 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 &amp; 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 ``` </details> <details> <summary><b>How it decides what's malware (the no-false-alarm step)</b></summary> <br> 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. </details> --- ## Connecting your site <details> <summary><b>Three ways to connect (SproutOS recommended, none required)</b></summary> <br> | Gateway | Needs | Best for | |---|---|---| | **[SproutOS](https://github.com/posimyth/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](references/mcp-gateways.md). </details> --- ## What it detects <details> <summary><b>39 malware families</b> — click to expand</summary> <br> SEO-spam cloaking · the Japanese keyword hack · pharma &amp; 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](references/signature-library.md) · the deep-dive on each family and how it hides: [references/malware-families.md](references/malware-families.md). </details> --- ## Standalone scripts <details> <summary><b>Run the engine directly — zero dependencies, stock Python 3</b></summary> <br> You don't need Claude to use the core scripts: ```bash # 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 | What it does | |---|---| | `scripts/cloaking_diff.py` | Detects cloaking (bot vs browser, origin vs CDN, JS-redirect) | | `scripts/scan_patterns.py` | Pattern-scans a WordPress tree for candidates | | `scripts/wordfence_client.py` | Matches installed versions against known CVEs | | `scripts/safety_gate.py` | Code-enforced backup → quarantine → rollback (won't delete without a backup) | | `scripts/reinstall_clean.py` | Verifies core/plugins against official checksums; reinstalls from clean source | | `scripts/signatures.json` | The signature database (easy to extend) | </details> --- ## How it cleans safely <details> <summary><b>The "don't break the site" protocol</b></summary> <br> - 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](references/remediation-playbook.md). </details> --- ## Documentation <details> <summary><b>All guides — click to expand</b></summary> <br> | Document | What's inside | |---|---| | [SKILL.md](SKILL.md) | The full methodology the AI follows | | [SPEC.md](SPEC.md) | Product &amp; security specification | | [references/detection-playbook.md](references/detection-playbook.md) | Every layer's commands, per gateway | | [references/remediation-playbook.md](references/remediation-playbook.md) | Safe removal: backup → quarantine → verify → rollback | | [references/cloaking-detection.md](references/cloaking-detection.md) | The bot-vs-browser method in depth | | [references/malware-families.md](references/malware-families.md) | The malware families + 2026 threat landscape | | [references/signature-library.md](references/signature-library.md) | Human-readable signature list | | [references/edge-cases.md](references/edge-cases.md) | Multisite, custom prefixes, reinfection, safeguards | | [references/mcp-gateways.md](references/mcp-gateways.md) | Connecting via SproutOS / other MCP / SSH | | [references/wordfence-integration.md](references/wordfence-integration.md) | Free Wordfence feed setup | | [references/growing-the-database.md](references/growing-the-database.md) | How to grow the vulnerability + attack-pattern coverage | | [references/incident-case-study.md](references/incident-case-study.md) | A real hack, start to finish | </details> --- ## FAQ <details> <summary><b>How do I remove the Japanese keyword hack?</b></summary> <br> 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. </details> <details> <summary><b>My WordPress site redirects visitors to spam. Can it help?</b></summary> <br> 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. </details> <details> <summary><b>My scanner says the site is clean, but Google flags it. Why?</b></summary> <br> 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. </details> <details> <summary><b>Does it work without SSH?</b></summary> <br> Yes. Connect [SproutOS](https://github.com/posimyth/sproutos) (over an Application Password) and it runs without shell access. </details> <details> <summary><b>Will it break my site?</b></summary> <br> 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. </details> --- ## A real example <details> <summary><b>A hidden gambling-spam infection a normal scan didn't catch</b></summary> <br> 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](references/incident-case-study.md). </details> --- ## Contributing <details> <summary><b>New detection patterns are always welcome</b></summary> <br> Malware changes constantly. The pattern list ([`scripts/signatures.json`](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](https://github.com/adityaarsharma/wordpress-malware-removal/issues) with a sanitized sample. **If this helped you, a star helps others find it.** </details> --- ## Works well alongside [Wordfence](https://www.wordfence.com/), [MalCare](https://www.malcare.com/), and [Sucuri](https://sucuri.net/) are well-known WordPress security tools; running an independent second scan is always sensible. This project uses [SproutOS](https://github.com/posimyth/sproutos) as its recommended gateway and the free [Wordfence Intelligence](https://www.wordfence.com/threat-intel/) vulnerability feed. ## License [AGPL-3.0-or-later](LICENSE). 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. --- <div align="center"> _{Built by <a href="https://adityaarsharma.com">Aditya Sharma</a>} </div>