git:20260706.efbf5f9 to git:20260706.5298452

3 added, 1 removed. Audit A to A.

# CLAUDE.md — WordPress Malware Removal

> Project context for Claude Code. Authoritative for this project. Global rules from `~/.claude/CLAUDE.md` still apply; this file specializes and overrides where noted.

---

## 1. Identity

| Attribute | Value |

|---|---|

| Product | WordPress Malware Removal — agent-driven WP security tool (3 modes: **Audit · Remove · Harden**) |

| Brand | Aditya personal (adityaarsharma.com) |

| Repo | https://github.com/adityaarsharma/wordpress-malware-removal (PUBLIC, AGPL-3.0-or-later) |

| Local folder | `~/Claude Projects/wp-malware-hunter/` — **NOTE: folder name ≠ repo/skill name** (see §6) |

| Skill install path | `~/.claude/skills/wordpress-malware-removal` |

| Status | Remove ✅ shipped · Audit ✅ shipped · Harden 🟡 protocol only (actions not yet scripted) · CI green |

| Brain routing | `brain-aditya` (hard wall — never cross). **Do NOT write this project to the POSIMYTH brain.** |

| GitHub auth | `gh` logged in as **adityaarsharma** (repo scope) |

---

## 2. Stack & versions

| Layer | Choice + version |

|---|---|

| Language | Python 3 — **standard library ONLY** (argparse, json, re, hashlib, urllib, ssl, socket, shutil, datetime). Zero pip deps. |

| Framework | None. Runs over any WordPress MCP gateway (SproutOS recommended) or SSH+WP-CLI, or standalone CLI. |

| Database | None (reads target site's DB via the gateway; nothing local) |

| Package manager | None — must stay dependency-free (see §5) |

| Build / bundle | None |

| Tests | Custom harness: `tests/run_corpus.py` (malware) + `tests/run_audit_corpus.py` (code audit). NOT pytest. |

| Lint | None configured |

| Typecheck | None configured |

| Deploy | Push to GitHub `main` → skill consumed via `~/.claude/skills/`. No package registry. |

---

## 3. Verification commands (Claude MUST run before claiming "done")

```bash

cd "/Users/adityasharma/Claude Projects/wp-malware-hunter"

python3 -m py_compile scripts/*.py tests/*.py # compiles clean

python3 tests/run_corpus.py # malware corpus: all malicious caught, clean silent

python3 tests/run_audit_corpus.py # audit corpus: vulnerable caught, secure silent

gh run list --repo adityaarsharma/wordpress-malware-removal --limit 1 # CI must be "completed success"

```

Exit code 0 = pass. Any other exit code = NOT DONE. Paste the exit code in your "done" message.

CI (`.github/workflows/ci.yml`) runs on every push + weekly: validates JSON + regex compiles + skill tags, `py_compile`, then both corpora. Do not push red.

---

## 4. Project structure & source of truth

```

wp-malware-hunter/

├── SKILL.md — the methodology (3 modes). name: wordpress-malware-removal. SOURCE OF TRUTH for behavior.

├── SPEC.md — requirements, edge cases, non-goals

├── ROADMAP.md — next steps; §Harden-actions is the #1 open TODO

├── README.md — public value-first sales copy (agent-agnostic)

├── LICENSE — AGPL-3.0-or-later

├── scripts/ — pure-Python engine:

│ ├── scan_patterns.py + signatures.json — 38 malware families

│ ├── code_auditor.py + audit_rules.json — 10 vuln classes

│ ├── cloaking_diff.py — fetch-as-Googlebot vs browser

- │ ├── safety_gate.py — CODE-ENFORCED backup/quarantine/rollback

+ │ ├── safety_gate.py — REQUIRES a user-supplied backup (never creates one) → quarantine/rollback

│ ├── reinstall_clean.py, hardening_audit.py, posture_score.py, wordfence_client.py

├── tests/ — run_corpus.py + run_audit_corpus.py

├── references/ — 10 playbooks (detection, remediation, cloaking, families, edge-cases, gateways, wordfence, growing-db, case-study)

└── .github/workflows/ci.yml

```

Source-of-truth files: `SKILL.md` (behavior), `SPEC.md` (requirements), `scripts/signatures.json` + `scripts/audit_rules.json` (detection data).

---

## 5. Conventions Claude cannot infer from code

- **Dependency-free is a hard constraint.** CI has no `pip install` step. Never add a third-party import to `scripts/`. Optional enhancements (e.g. Playwright headless cloaking) must degrade gracefully when absent — never a hard import at module top.

- **All destructive actions route through `safety_gate.py`** — backup → quarantine (never delete in place) → rollback. Do not add a file-mutating path that bypasses it.

- **Detection data lives in JSON, not Python.** New malware families go in `signatures.json`, new vuln classes in `audit_rules.json` — then a corpus sample must be added proving catch + no false positive on clean code.

- **Mode names are deliberately plain**: Clean/Remove · Harden · Audit. No cutesy/marketing names in user-facing strings — the r/ProWordPress audience rejects AI-slop naming.

- **Harden policy**: auto-apply safe/reversible fixes, ASK before risky ones (XML-RPC off, REST restriction, 2FA enforcement) — all via `safety_gate.py`.

+ - **Backup policy**: the tool does NOT create backups. `safety_gate.py` *requires* a fresh (<24h) user/host-supplied backup and refuses every destructive step without one. Read-only Audit/Review never need it. Before any Clean, the agent must **hard-remind the user to take a full off-site backup** — never imply the tool took care of it.

+ - **Three focuses** (user-facing framing): Review/Audit (read-only) · Clean (Remove) · Harden. "Remove" and "Clean" are the same focus.

- **Delivery model**: any WP MCP gateway or SSH — this is NOT a standalone WordPress plugin, and must not become one.

---

## 6. Critical gotchas (real bugs you don't want repeated)

- **Folder name ≠ repo/skill name.** Local dir is `wp-malware-hunter`; git repo, skill `name:`, and install path are all `wordpress-malware-removal`. Keep the three canonical names (`wordpress-malware-removal`) consistent in SKILL.md, README, and CI; the local folder is the only place the old `wp-malware-hunter` name survives.

- **`heuristic`-tagged signatures are not yet validated against a real-malware corpus** — flagged in ROADMAP as a TODO. Treat their hits as lower-confidence until corpus-backed.

- Session cwd `~/Claude Projects/WordPress Malware Removal/` is an empty stray auto-created folder, NOT the project. Work in `wp-malware-hunter/`.

---

## 7. Pro / monetization

Pattern: **N/A** — open-source AGPL-3.0-or-later (chosen to close the SaaS loophole). No Free/Pro split. SproutOS (a POSIMYTH product) is the recommended gateway and the planned 1-click playbook host, but this tool itself stays free/OSS.

---

## 8. Outstanding decisions

- [ ] **Harden actions as scripts** (#1 gap, per ROADMAP) — idempotent, per-action-rollback fixers: REST user-enum, author enum, public `debug.log`, 2FA guidance, file perms, salts, headers, uploads PHP-block. Make Harden as deterministic as Remove.

- [ ] Headless-browser cloaking check (optional Playwright, graceful fallback).

- [ ] Real-malware corpus validation for `heuristic` signatures.

- [ ] SproutOS Playbook — 1-click Audit/Remove/Harden across many sites (agency).

- [ ] Reconcile local folder name with repo name, or leave as-is (documented in §6).

---

## 9. Quick-reference URLs

| Resource | URL |

|---|---|

| Repo | https://github.com/adityaarsharma/wordpress-malware-removal |

| Live audit finding (real) | `python3 scripts/hardening_audit.py https://nexterwp.com` — REST/author enum + public debug.log exposure |