# 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 — 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 |