KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #ai-agent #claude-code #mcp #typescript #codex #cli #rust #deepseek-harness

wp-malware-cleanup-mcp

★ 30 Open GitHub ↗

MCP server for cleaning malware from WordPress sites via SSH and WP-CLI. Batch operations for 20+ sites.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# WordPress Malware Cleanup MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io)
[![WordPress](https://img.shields.io/badge/WordPress-6.0%2B-21759B.svg)](https://wordpress.org)

A production-ready Model Context Protocol (MCP) server for cleaning malware from WordPress sites via SSH and WP-CLI. Designed for agencies and developers managing multiple WordPress installations.

**Author:** Varun Dubey
**Company:** [Wbcom Designs](https://wbcomdesigns.com)
**Version:** 3.0.0

---

> **IMPORTANT SAFETY NOTICE**
>
> This tool performs **irreversible operations** on live WordPress sites including file deletion,
> database modification, password resets, and core file replacement. **Always create a full backup
> before using any cleanup tool.** The authors are not liable for data loss.
> See the [Tool Risk Matrix](#tool-risk-matrix) below.

---

> **New here?** The [Usage Guide](docs/USAGE.md) walks through the safety model and the
> backup → preview → execute → re-scan workflow task by task.
>
> **Hosting companies and agencies:** See the [Wiki](https://github.com/vapvarun/wp-malware-cleanup-mcp/wiki) for setup guides, daily scan automation, and the hosting company playbook.

## Table of Contents

- [Before You Start](#before-you-start)
- [Tool Risk Matrix](#tool-risk-matrix)
- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Configuration](#configuration)
- [Quick Start](#quick-start)
- [Available Tools](#available-tools)
- [Usage Examples](#usage-examples)
- [Cleanup Workflow](#cleanup-workflow)
- [Security Considerations](#security-considerations)
- [Troubleshooting](#troubleshooting)
- [Project Structure](#project-structure)
- [Contributing](#contributing)
- [License](#license)
- [Credits](#credits)

---

## Before You Start

Before using any cleanup or hardening tools on a live WordPress site:

1. **Create a full server backup** (files + database). Use your hosting provider's backup tool or:
   ```
   wp_backup_database("site-name")
   ```
   A database backup alone is not sufficient — back up the entire `wp-content/` directory as well.

2. **Test on staging first** if possible. Clone the infected site to a staging environment and run cleanup there before touching production.

3. **Keep an SSH session open** to monitor the server during cleanup. Watch for errors or unexpected behavior.

4. **Note current admin passwords** before running `wp_reset_passwords`. After reset, the old passwords are gone permanently.

5. **Destructive tools require `confirm=True`**. Tools like `wp_reinstall_core`, `wp_reset_passwords`, `wp_complete_cleanup`, etc. will show a preview manifest when called without `confirm=True`. Review the manifest before confirming.

---

## Tool Risk Matrix

All tools are classified into three risk tiers:

### SAFE (read-only)

These tools only read data. No files or database records are modified.

| Tool | Description |
|------|-------------|
| `wp_scan` | All malware scans via one tool; `scope=` selects depth (quick/full/deep) or a category (uploads/webshells/themes/cron/wpconfig/…) |
| `wp_fleet_status` | Fleet scorecard across all sites |
| `wp_host_group_status` | One account's sites + reinfection check |
| `wp_check_cron_events` | Scan cron events for suspicious hooks |
| `wp_list_admins` | List all administrator users |
| `wp_audit_user` | Detailed audit of user activity |
| `wp_find_recent_users` | Find users created recently |
| `wp_list_sites` | List all configured sites |
| `wp_get_site` | Get site information |
| `wp_test_connection` | Test SSH and WP-CLI connectivity |
| `wp_read_file` | Read file contents for analysis |
| `wp_version` | Show version information |
| `wp_export_sites` | Export site configurations |
| `wp_generate_report` | Generate cleanup report |
| `wp_generate_case_study` | Generate anonymized case study |
| `wp_batch_scan` | Scan all configured sites |
| `wp_scan_status` | Check background scan status |
| `wp_scan_result` | Get background scan results |
| `wp_list_scans` | List scan tasks |
| `wp_threat_db_stats` | Show threat database statistics |
| `wp_threat_check_file` | Check file against threat database |
| `wp_threat_top_signatures` | Show most detected signatures |
| `wp_threat_export` | Export signatures |
| `wp_monitor_http_requests` | Monitor outgoing HTTP requests |

### MODERATE (reversible changes)

These tools make changes that can be undone or automatically create backups.

| Tool | Description |
|------|-------------|
| `wp_backup_database` | Create database backup |
| `wp_quarantine_file` | Move file to quarantine (recoverable) |
| `wp_add_site` | Add a site to configuration |
| `wp_update_site` | Update site configuration |
| `wp_remove_site` | Remove site from configuration |
| `wp_harden_wpconfig` | Add security constants to wp-config.php |
| `wp_add_security_htaccess` | Add security rules to .htaccess |
| `wp_install_security_mu_plugin` | Install security MU-plugin |
| `wp_fix_permissions` | Set secure file permissions |
| `wp_disable_file_editing` | Disable theme/plugin editor |
| `wp_threat_db_sync` | Sync community threat signatures |
| `wp_threat_add_signature` | Add malware signature to local DB |
| `wp_threat_learn_from_cleanup` | Record malware hash for future detection |
| `wp_start_background_scan` | Start background scan task |

### DESTRUCTIVE (irreversible — requires `confirm=True`)

These tools permanently delete files, reset credentials, or overwrite data. **Always create a backup first.** Tools marked with `confirm` will show a preview manifest when called without `confirm=True`.

| Tool | `confirm` gate | Description |
|------|:--------------:|-------------|
| `wp_complete_cleanup` | Yes | Full cleanup + hardening (20 destructive steps) |
| `wp_reinstall_core` | Yes | Overwrite wp-admin/, wp-includes/, root PHP files |
| `wp_reinstall_all_plugins` | Yes | Reinstall all plugins from WordPress.org |
| `wp_reinstall_all_themes` | Yes | Reinstall all themes from WordPress.org |
| `wp_reset_passwords` | Yes | Reset all administrator passwords |
| `wp_regenerate_salts` | Yes | Replace security salts, invalidate all sessions |
| `wp_revoke_app_passwords` | Yes | Delete all application passwords |
| `wp_reinstall_plugin` | Yes (since 2.1.0) | Reinstall a single plugin from repo |
| `wp_delete_user` | Yes | Delete a WordPress user |
| `wp_clean_uploads_php` | Yes | Remove all PHP files from uploads |
| `wp_clean_core_injections` | Yes (since 2.1.0) | Delete injected core files (also supports `dry_run=True`) |
| `wp_clean_db_spam` | Yes | Remove spam comments |
| `wp_delete_malware_options` | Yes (since 2.1.0) | Delete malware markers from wp_options (also supports `dry_run=True`) |
| `wp_remove_mu_plugin` | Yes (since 2.1.0) | Quarantine an mu-plugin |
| `wp_update_all` | — | Update core, plugins, themes |
| `wp_batch_update` | — | Update all clean sites |
| `wp_full_harden` | — | Complete hardening in one command |

---

## Features

### Multi-Site Management
- Add and manage 20+ WordPress sites from a single interface
- Persistent configuration storage
- Batch operations across all sites
- Status tracking and reporting

### Comprehensive Malware Scanning
- **Core File Verification** - Compare against official WordPress checksums
- **Plugin Integrity Check** - Verify plugins against WordPress.org
- **MU-Plugins Detection** - Scan must-use plugins for backdoors
- **Uploads Security** - Find PHP files that shouldn't exist
- **Deep Pattern Matching** - Detect obfuscated code and known signatures
- **Database Injection Scan** - Find malicious content in posts/options
- **Recently Modified Files** - Identify infection timeline

### User Security
- List and audit administrator accounts
- Track user activity before deletion
- Find recently created suspicious users
- Safe user deletion with content reassignment

### Safe Cleanup Operations
- **Quarantine System** - Move files instead of deleting (allows recovery)
- **Automatic Backups** - Database export before changes
- **Core Reinstallation** - Restore official WordPress files
- **Plugin Reinstallation** - Fresh install from repository
- **Permission Fixes** - Set secure file permissions

### Security Hardening
- Reset all admin passwords
- Regenerate security salts
- Disable admin file editing
- Add .htaccess security rules
- Update WordPress, plugins, and themes

### Reporting & Logging
- Detailed cleanup reports
- Action logging per site
- Export configurations
- Status summaries

---

## Requirements

### Your Mac (Client)
- macOS 13+ (Ventura or later)
- [Homebrew](https://brew.sh)
- [Claude Code](https://claude.com/claude-code) CLI
- [uv](https://docs.astral.sh/uv/) (Python package manager)

### WordPress Servers
- SSH access (password or key-based)
- WP-CLI installed and in PATH
- WordPress 5.0+

---

## macOS Setup Guide

Complete setup from scratch on a fresh Mac. Takes ~5 minutes.

### Prerequisites

- [Homebrew](https://brew.sh) installed
- [Claude Code](https://claude.com/claude-code) CLI installed
- [uv](https://docs.astral.sh/uv/) installed (`curl -LsSf https://astral.sh/uv/install.sh | sh`)

### Step 1: Install System Dependencies

```bash
# Python 3.12 (macOS system Python is too old for the mcp package)
brew install python@3.12

# sshpass (required for password-based SSH auth)
brew install sshpass
```

### Step 2: Clone the Repository

```bash
git clone https://github.com/vapvarun/wp-malware-cleanup-mcp.git ~/.claude/wp-malware-cleanup-mcp
cd ~/.claude/wp-malware-cleanup-mcp
```

### Step 3: Create Virtual Environment & Install Dependencies

```bash
# Create venv with Python 3.12
uv venv --python 3.12 .venv

# Install dependencies into venv
uv pip install -r requirements.txt
```

### Step 4: Register MCP Server with Claude Code

```bash
# Register globally (available in all Claude Code sessions)
claude mcp add -s user wp-malware-cleanup -- \
  ~/.claude/wp-malware-cleanup-mcp/.venv/bin/python \
  ~/.claude/wp-malware-cleanup-mcp/server.py
```

### Step 5: Verify

```bash
claude mcp list
# Should show: wp-malware-cleanup: ... ✓ Connected
```

### Step 6: Restart Claude Code

Close and reopen Claude Code so the new MCP tools are loaded.

---

## Configuration

### Claude Code (Recommended)

The `claude mcp add` command in Step 4 automatically writes to `~/.claude.json`:

```json
{
  "mcpServers": {
    "wp-malware-cleanup": {
      "command": "/Users/YOU/.claude/wp-malware-cleanup-mcp/.venv/bin/python",
      "args": ["/Users/YOU/.claude/wp-malware-cleanup-mcp/server.py"]
    }
  }
}
```

### Claude Desktop (Optional)

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

> **Note:** Replace `/Users/YOU` with your actual home directory path.

### Data Storage Locations

```
~/.wp-sites/
└── sites.json          # Site configurations (shared with wp-site-doctor-mcp)

~/.wp-malware-cleanup/
├── sites.json          # Legacy copy (kept in sync for backward compatibility)
├── quarantine/         # Quarantined malicious files
├── reports/            # Generated cleanup reports
├── scans/              # Persisted scan results, one JSON per run (since 2.2.0)
│   └── <site>/<scan_id>.json
├── logs/               # Per-site action logs
└── threat_intelligence.db  # Local threat intel SQLite DB
```

Site configurations live at `~/.wp-sites/sites.json` so both this MCP and
[wp-site-doctor-mcp](https://github.com/vapvarun/wp-site-doctor-mcp) see the same
sites. A copy is also written to the legacy location so any existing tooling
that reads the old path keeps working.

> The shared registry is read tolerantly (since 2.2.0): unknown keys written by
> another MCP are ignored rather than crashing the loader, so the two servers
> can evolve their own fields without corrupting the shared file.

Every whole-site `wp_scan` run (quick/full/deep) also writes a
structured result record to `~/.wp-malware-cleanup/scans/<site>/`, so scan
history is queryable and can be diffed before/after a cleanup.

---

## Quick Start

After setup, restart Claude Code and use these tools in conversation:

### 1. Add Your First Site

**With password auth** (common for InstaWP, managed hosting):
```
wp_add_site(
    name="my-site",
    host="147.182.198.163",
    username="sshuser",
    wp_path="/home/sshuser/web/example.com",
    auth_type="password",
    site_url="https://example.com"
)
```

**With SSH key auth** (recommended for production):
```
wp_add_site(
    name="client-blog",
    host="example.com",
    username="deploy",
    wp_path="/var/www/html",
    auth_type="key",
    key_path="~/.ssh/id_rsa"
)
```

**Grouping sites that share a server / cPanel account** (`host_group`):
```
# Two sites under the same cPanel user — group them so cross-site reinfection
# can be reasoned about. host_group defaults to `host` when omitted.
wp_add_site(name="shop-acme", host="srv12.host.net", username="acme",
            wp_path="/home/acme/shop", auth_type="key", host_group="acme")
wp_add_site(name="blog-acme", host="srv12.host.net", username="acme",
            wp_path="/home/acme/blog", auth_type="key", host_group="acme")
```

> On shared hosting, one infected site commonly reinfects its siblings under the
> same account. Setting a shared `host_group` records that relationship for
> fleet-wide reasoning. Update it any time with
> `wp_update_site("blog-acme", host_group="acme")`.

### 2. Test the Connection

```
# Password auth - provide password each time (not stored on disk for security)
wp_test_connection("my-site", password="your-ssh-password")

# Key auth - no password needed
wp_test_connection("client-blog")
```

> **Security note:** Passwords are never stored on disk. They are passed via the `SSHPASS` environment variable at runtime and discarded after the SSH session ends.

### 3. Run a Full Scan

```
wp_scan("my-site", password="your-ssh-password")
```

### 4. View All Sites

```
wp_list_sites()
```

### 5. See the Whole Fleet at a Glance

```
wp_fleet_status()                 # instant scorecard from the last stored scans
wp_fleet_status(refresh=True)     # quick-scan every site first, then report
wp_host_group_status("acme")      # one cPanel account + reinfection assessment
```

---

## Available Tools

### Site Management

| Tool | Description |
|------|-------------|
| `wp_add_site` | Add a new WordPress site |
| `wp_update_site` | Update site configuration |
| `wp_get_site` | Get detailed site information |
| `wp_list_sites` | List all sites with status |
| `wp_remove_site` | Remove a site from configuration |
| `wp_test_connection` | Test SSH and WP-CLI connectivity |

### Fleet (since 2.2.0)

| Tool | Description |
|------|-------------|
| `wp_fleet_status` | At-a-glance scorecard across all sites, worst-first, with risk scores. Instant from stored scans; pass `refresh=True` to quick-scan the fleet first. Flags clean siblings of an infected site as **AT RISK**. |
| `wp_host_group_status` | All sites in one server / cPanel account (`host_group`) plus a cross-site reinfection assessment and clean order. |

### Scanning — one tool, many scopes

All scans run through a single tool, `wp_scan(name, scope="full")`. Pick a
`scope` for depth or a specific area; if unsure, use the default `full`.

```
wp_scan("my-site")                          # full scan (default)
wp_scan("my-site", scope="quick")           # 2-3 min triage
wp_scan("my-site", scope="deep")            # most thorough, step-by-step
wp_scan("my-site", scope="uploads")         # one targeted category
```

| `scope` | Scans |
|---------|-------|
| `quick` | Fast triage (core + key plugins + uploads) |
| `full` *(default)* | All categories comprehensively |
| `deep` | Full scan with step-by-step progress |
| `verbose` | Full scan showing every command run |
| `core` | WordPress core checksums |
| `plugins` | Plugins vs WordPress.org |
| `suspicious-plugins` | Random/malware-named plugin folders |
| `hidden-plugins` | Self-hiding plugins |
| `themes` | Malware themes |
| `mu-plugins` | Must-use plugin malware |
| `uploads` | Dangerous files in uploads |
| `webshells` | Web shells / file-manager backdoors |
| `hidden-admins` | Suspicious admin accounts |
| `app-passwords` | Suspicious application passwords |
| `malware-patterns` | Malware signature patterns |
| `recently-modified` | Recently changed files |
| `db` | Database injection check |
| `cron` | Suspicious wp-cron events |
| `wpconfig` | wp-config.php injection (read-only) |

Whole-site scopes (`quick`/`full`/`deep`/`verbose`) persist a result for the
fleet scorecard (`wp_fleet_status`); targeted scopes report without changing the
site's overall verdict.

### User Audit Tools

| Tool | Description |
|------|-------------|
| `wp_list_admins` | List all administrator users |
| `wp_audit_user` | Detailed audit of user activity |
| `wp_find_recent_users` | Find users created recently |
| `wp_delete_user` | Delete user after audit |

### Cleanup Tools

| Tool | Description |
|------|-------------|
| `wp_complete_cleanup` | Full cleanup + hardening in one command (20 steps). Use without `confirm` for preview manifest. |
| `wp_quarantine_file` | Move malicious file to quarantine (auto-learns hash) |
| `wp_read_file` | Read file contents for analysis |
| `wp_remove_mu_plugin` | Quarantine an mu-plugin |
| `wp_reinstall_core` | Reinstall WordPress core files |
| `wp_reinstall_plugin` | Reinstall a plugin from repo |
| `wp_clean_uploads_php` | Remove all PHP from uploads |
| `wp_clean_core_injections` | Delete injected core files that `wp core download --force` misses |
| `wp_clean_db_spam` | Delete spam/trash comments (backup-gated — see below) |
| `wp_delete_malware_options` | Delete known malware campaign markers from `wp_options` (backup-gated) |
| `wp_clean_cron_events` | Delete malicious wp-cron events (the #1 reinfection vector) |
| `wp_clean_malicious_htaccess` | Quarantine hostile `.htaccess`/`.user.ini` in uploads/wp-content |
| `wp_revoke_app_passwords` | Revoke all application passwords across all users |
| `wp_fix_permissions` | Fix file/directory permissions |

> **Backup gate (since 2.2.0).** Tools that delete data they cannot restore —
> `wp_clean_db_spam`, `wp_delete_malware_options` — refuse to run unless a
> recent backup is found in the action log (within 30 minutes). Run
> `wp_backup_database("site")` first, or pass `force=True` to override when you
> accept the risk. Reversible tools (quarantine-based, like `wp_quarantine_file`
> and `wp_clean_uploads_php`) are not gated — their preview explains recovery.

### Security Hardening

| Tool | Description |
|------|-------------|
| `wp_reset_passwords` | Reset all admin passwords |
| `wp_regenerate_salts` | Regenerate security salts |
| `wp_disable_file_editing` | Disable theme/plugin editor |
| `wp_harden_wpconfig` |Apply security constants to wp-config.php |
| `wp_install_security_mu_plugin` |Install persistent security MU-plugin |
| `wp_full_harden` |Complete hardening in one command |
| `wp_update_all` | Update core, plugins, themes |
| `wp_add_security_htaccess` | Add security rules to .htaccess |

### Database Tools

| Tool | Description |
|------|-------------|
| `wp_scan` (scope="db") | Scan database for injected malware |
| `wp_backup_database` | Create database backup |
| `wp_clean_db_spam` | Remove spam comments |

### Batch Operations

| Tool | Description |
|------|-------------|
| `wp_batch_scan` | Scan all configured sites |
| `wp_batch_update` | Update all clean sites |

### Reporting

| Tool | Description |
|------|-------------|
| `wp_generate_report` | Generate detailed cleanup report |
| `wp_incident_report` | Client-facing incident report: timeline, IOCs, before/after, clean sign-off |
| `wp_generate_case_study` |Generate anonymized case study for public sharing |
| `wp_export_sites` | Export site configurations |
| `wp_version` | Show version information |

### Case Studies

Anonymized malware case studies are available in [`docs/case-studies/`](docs/case-studies/). These document real-world infections with:
- Detection signatures and IOCs
- Code analysis and behavior
- Remediation steps
- Lessons learned

### Threat Intelligence Database

| Tool | Description |
|------|-------------|
| `wp_threat_db_stats` | Show database statistics (signatures, detections) |
| `wp_threat_db_sync` | Sync with GitHub community signatures |
| `wp_threat_add_signature` | Add new malware signature to local database |
| `wp_threat_learn_from_cleanup` | Learn malware hash from cleanup for future detection |
| `wp_threat_check_file` | Check specific file against threat database |
| `wp_threat_export` | Export signatures for GitHub contribution |
| `wp_threat_top_signatures` | Show most frequently detected signatures |

---

## Usage Examples

### Adding Multiple Sites

```python
# Site with SSH key
wp_add_site(
    name="site1",
    host="server1.example.com",
    username="deploy",
    wp_path="/var/www/site1",
    auth_type="key",
    key_path="~/.ssh/id_rsa"
)

# Site with different port
wp_add_site(
    name="site2",
    host="server2.example.com",
    port=2222,
    username="admin",
    wp_path="/home/admin/public_html",
    auth_type="key",
    key_path="~/.ssh/server2_key"
)
```

### Batch Scanning All Sites

```python
# Scan all sites
wp_batch_scan()

# Scan only pending sites
wp_batch_scan(status_filter="pending")
```

### Complete Cleanup Workflow

```python
# 1. Backup first!
wp_backup_database("infected-site")

# 2. Run full scan
wp_scan("infected-site")

# 3. Audit suspicious users
wp_list_admins("infected-site")
wp_audit_user("infected-site", "suspicious_user")

# 4. Delete malicious user
wp_delete_user("infected-site", "suspicious_user", "real_admin", confirm=True)

# 5. Clean malicious files
wp_clean_uploads_php("infected-site", confirm=True)
wp_remove_mu_plugin("infected-site", "malware.php")

# 6. Reinstall core and plugins (confirm=True required for destructive tools)
wp_reinstall_core("infected-site", confirm=True)

# 7. Harden security (confirm=True required)
wp_reset_passwords("infected-site", confirm=True)
wp_regenerate_salts("infected-site", confirm=True)
wp_disable_file_editing("infected-site")
wp_add_security_htaccess("infected-site")

# 8. Update everything
wp_update_all("infected-site")

# 9. Verify cleanup
wp_scan("infected-site")

# 10. Generate report
wp_generate_report("infected-site")
```

### One-Command Cleanup (with preview)

```python
# Preview what will happen (dry run — no changes made)
wp_complete_cleanup("infected-site")

# Review the manifest, then execute
wp_complete_cleanup("infected-site", confirm=True)
```

---

## Cleanup Workflow

### Phase 1: Assessment

1. **Backup Database**
   ```
   wp_backup_database("site-name")
   ```

2. **Run Full Scan**
   ```
   wp_scan("site-name")
   ```

3. **Check Recently Modified Files**
   ```
   wp_scan("site-name", scope="recently-modified")
   ```

### Phase 2: User Audit

1. **List Admin Users**
   ```
   wp_list_admins("site-name")
   ```

2. **Find Recent Users**
   ```
   wp_find_recent_users("site-name", days=30)
   ```

3. **Audit Suspicious Users**
   ```
   wp_audit_user("site-name", "suspicious_username")
   ```

4. **Delete Malicious Users**
   ```
   wp_delete_user("site-name", "hacker", "legitimate_admin", confirm=True)
   ```

### Phase 3: File Cleanup

1. **Clean Uploads Directory**
   ```
   wp_clean_uploads_php("site-name", confirm=True)
   ```

2. **Remove Malicious MU-Plugins**
   ```
   wp_scan("site-name", scope="mu-plugins")
   wp_remove_mu_plugin("site-name", "malware.php")
   ```

3. **Quarantine Suspicious Files**
   ```
   wp_quarantine_file("site-name", "/full/path/to/file.php")
   ```

### Phase 4: Core Restoration

1. **Reinstall WordPress Core** (preview first, then confirm)
   ```
   wp_reinstall_core("site-name")              # Preview manifest
   wp_reinstall_core("site-name", confirm=True) # Execute
   ```

2. **Verify Core Files**
   ```
   wp_scan("site-name", scope="core")
   ```

3. **Reinstall Affected Plugins**
   ```
   wp_reinstall_plugin("site-name", "plugin-slug")
   ```

### Phase 5: Security Hardening

1. **Reset All Passwords** (preview first, then confirm)
   ```
   wp_reset_passwords("site-name")              # Preview affected users
   wp_reset_passwords("site-name", confirm=True) # Execute
   ```
   > Save the new passwords securely!

2. **Regenerate Salts** (preview first, then confirm)
   ```
   wp_regenerate_salts("site-name")              # Preview
   wp_regenerate_salts("site-name", confirm=True) # Execute
   ```

3. **Disable File Editing**
   ```
   wp_disable_file_editing("site-name")
   ```

4. **Add Security Rules**
   ```
   wp_add_security_htaccess("site-name")
   ```

5. **Fix Permissions**
   ```
   wp_fix_permissions("site-name")
   ```

### Phase 6: Updates & Verification

1. **Update Everything**
   ```
   wp_update_all("site-name")
   ```

2. **Final Verification Scan**
   ```
   wp_scan("site-name")
   ```

3. **Generate Report**
   ```
   wp_generate_report("site-name")
   ```

---

## Security Considerations

### SSH Key Authentication (Recommended)

Always use SSH keys instead of passwords:

```bash
# Generate SSH key
ssh-keygen -t ed25519 -C "malware-cleanup"

# Copy to server
ssh-copy-id -i ~/.ssh/id_ed25519 user@server
```

### Data Storage Security

- Site configurations are stored locally in `~/.wp-sites/sites.json` (shared
  with wp-site-doctor-mcp) and mirrored to `~/.wp-malware-cleanup/sites.json`
  for backward compatibility.
- **Passwords are NEVER stored** — provide them at runtime via the tool's
  `password` parameter; they pass through as an env var to `sshpass`, never
  appearing on the command line.
- **Database credentials never appear in `ps`** — tools that need to run SQL
  go through `WpConfigService.run_query()`, which delegates to WP-CLI's
  `wp db query`. Credentials stay inside the WP-CLI process. Fixed in 2.1.0.
- Quarantined files are kept on the remote server under
  `wp-content/quarantine/`. Originals are renamed with a timestamp + hash
  for traceability.
- Reports may contain sensitive information — store securely.

### Principle of Least Privilege

- Use a dedicated SSH user for cleanup operations
- Grant only necessary permissions
- Consider using sudo for specific WP-CLI commands

### Audit Trail

All actions are logged to `~/.wp-malware-cleanup/logs/{site-name}.log`

---

## Troubleshooting

### "Connection refused" or "Connection timed out"

1. Verify the hostname and port are correct
2. Check if SSH is running on the server
3. Verify firewall allows SSH connections
4. Test manually: `ssh -p PORT user@host`

### "WP-CLI not found"

Install WP-CLI on the WordPress server:

```bash
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp
```

### "Permission denied"

1. Check SSH key permissions: `chmod 600 ~/.ssh/id_rsa`
2. Verify the user has access to the WordPress directory
3. Check if the user can run WP-CLI: `wp --info`

### "sshpass not found"

If using password authentication:
- Ubuntu/Debian: `sudo apt install sshpass`
- macOS: `brew install hudochenkov/sshpass/sshpass`
- **Recommended:** Use SSH keys instead

### Command Timeout

For large sites, increase the timeout:
- Database exports may take longer
- Full scans on large sites need more time
- Consider running scans during low-traffic periods

### False Positives in Malware Scan

Some legitimate code may trigger false positives:
- Base64 encoding in plugins (e.g., for image handling)
- Minified JavaScript
- Vendor libraries

Review each finding manually before taking action.

---

## Threat Intelligence & Auto-Learning

This project includes a threat intelligence database that **automatically learns from every cleanup**. No manual steps required — every scan and cleanup action feeds data back into the local DB.

### Auto-Learning Pipeline

Every detection and cleanup action is automatically recorded to the threat database:

| Action | What Gets Recorded |
|--------|--------------------|
| Quarantine a file | File hash + path + auto-added to `known_malicious_files` for cross-site recognition |
| Scan finds hidden plugin | Plugin slug + risk flags (self-hiding, user-hiding, self-healing) |
| Scan finds malware theme | Theme slug + detection reasons (timestamp name, webshells, wp-config.php) |
| Delete injected core file | File path of each removed injection |
| Delete malware DB option | Option name + value that was removed |
| Revoke app passwords | User ID + username for each revocation |
| Complete cleanup | Summary with total steps completed |
| MU-plugin user-hiding detected | Filenames of MU-plugins with user-hiding hooks |

This means:
- **Quarantined file hashes are stored in `known_malicious_files`** and can be matched against any file with `wp_threat_check_file("site", "/path/to/file")`, including on a different site.
- **Learned and community signatures feed the scanner.** Since 2.7.0, `wp_scan(scope="malware-patterns")` (and the full scan) greps every active threat-DB signature across the site — so a signature learned while cleaning site A detects on site B. String signatures match literally; regex signatures use PCRE.
- **`cleanup_records`** builds a searchable history of every action across all sites
- **All recording is best-effort** — a DB failure never blocks a cleanup operation

### Community Database

Sync with community-contributed signatures and contribute back:

```python
# Sync latest signatures from GitHub
wp_threat_db_sync()

# Check current database stats (includes cleanup_records count)
wp_threat_db_stats()

# After confirming malware, teach the system
wp_threat_learn_from_cleanup("/path/to/malware.php", "abc123hash", "backdoor", "Description")

# Export for contribution
wp_threat_export()
```

### Community Files

| File | Description |
|------|-------------|
| `community-signatures.json` | Malware detection patterns (50+ signatures) |
| `community-hashes.json` | Known malicious file hashes |

### Security Features

- **Secure Random Filenames**: All backup files, reports, and quarantine directories use cryptographically secure random names to prevent attackers from guessing file locations
- **Restricted Permissions**: Quarantine and backup directories are created with 700 permissions
- **No Predictable Paths**: File naming uses SHA256-based random tokens

---

## Project Structure

Since v2.1.0 the codebase is split into a thin entry point plus three packages:

```
wp-malware-cleanup-mcp/
├── server.py                  # 60-line entry point: setup_logging() + import tools + mcp.run()
├── config.py                  # Config dataclass + every malware/cron/HTTP detection constant
├── models.py                  # SiteConfig, ScanResult, DatabaseCredentials, exception hierarchy
├── database_v2.py             # Threat-intel SQLite store (thread-safe, WAL)
├── threat_feeds_v2.py         # GitHub community-signature sync + pattern analysis
│
├── core/                      # Shared services — pure logic, no MCP coupling
│   ├── sites.py               #   SiteManager (mtime-cached, dual-write to shared registry)
│   ├── paths.py               #   WpPaths helpers (uploads_dir, plugins_dir, …)
│   ├── wpconfig.py            #   WpConfigService.get_db_credentials + run_query via WP-CLI
│   ├── safety.py              #   require_confirm(), safety_banner(), log_action()
│   ├── reports.py             #   ScanReport / CleanupReport markdown formatters
│   ├── orchestrator.py        #   Step / Orchestrator primitives for scan + cleanup pipelines
│   ├── threat_db.py           #   facade over database_v2 + threat_feeds_v2
│   └── legacy.py              #   compat shims for helpers still in transition
│
├── tools/                     # One module per tool category — each registers @mcp.tool()
│   ├── _registry.py           #   shared FastMCP instance
│   ├── sites.py               #   add/update/list/get/remove/test_connection  (6 tools)
│   ├── scanning.py            #   verify/scan_* + quick/deep/full scans       (17 tools)
│   ├── cleanup.py             #   quarantine/clean_*/complete_cleanup/backup  (8 tools)
│   ├── hardening.py           #   permissions/salts/wpconfig/mu-plugin/etc.   (7 tools)
│   ├── reinstall.py           #   core/plugin/all-plugins/all-themes          (4 tools)
│   ├── users.py               #   list_admins/audit/find/delete/reset/revoke  (6 tools)
│   ├── threat.py              #   wp_threat_* (db stats, sync, learn, …)      (13 tools)
│   ├── reporting.py           #   generate_report/case_study/export_sites     (3 tools)
│   ├── batch.py               #   batch_scan/batch_update/update_all          (3 tools)
│   ├── background.py          #   start_background_scan/status/result/list    (4 tools)
│   ├── misc.py                #   version/read_file/check_cron/monitor_http   (4 tools)
│   └── interactive_scans.py   #   internal worker for background scans
│
├── utils/                     # Low-level helpers
│   ├── ssh.py                 #   SSHConnectionPool (ControlMaster), run_ssh_command, run_wpcli
│   ├── validation.py          #   path-traversal defense, shell escaping, log redaction
│   └── progress.py            #   ProgressReporter, TaskManager, BackgroundTask
│
├── scripts/
│   ├── count_tools.py         #   walks the FastMCP registry; `--diff` checks tools-baseline.txt
│   └── tools-baseline.txt     #   frozen 75-tool roster; CI's parity check
│
└── tests/
    ├── conftest.py            #   MockSSH fixture + with_site fixture
    ├── test_sites.py          #   SiteManager (mtime-invalidation, dual-write, migration)
    ├── test_wpconfig.py       #   asserts DB password never appears on `mysql` command line
    ├── test_safety.py         #   confirm gate, backup warning, banner
    ├── test_confirm_gates.py  #   the four destructive tools that need confirm=True
    ├── test_scanning_integration.py  #   MockSSH-driven smoke tests for scanning tools
    └── …                      #   paths, reports, orchestrator, validation, models
```

**Dependency rule (one-way):** `tools/` → `core/` → `utils/` → `models/`. Tools
never import from `server`; `server.py` only knows about `tools._registry.mcp`
and side-effect imports the `tools` package to trigger registration. This lets
you add or rename tool modules without touching server.py.

---

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes (with tests where it makes sense)
4. Run `make smoke && make parity && make test` before submitting
5. Submit a pull request

### Contributing Signatures

To contribute malware signatures:

1. Use `wp_threat_export()` to export your local signatures
2. Fork this repository
3. Add your signatures to `community-signatures.json` or `community-hashes.json`
4. Submit a pull request with a description of what malware the signatures detect

**Guidelines:**
- Only submit confirmed malware signatures
- Include clear descriptions
- Test for false positives before submitting
- Do not include sensitive information

### Development Setup

```bash
git clone https://github.com/vapvarun/wp-malware-cleanup-mcp.git
cd wp-malware-cleanup-mcp

# Create a venv (Python 3.10+) and install dev dependencies
python3.12 -m venv .venv
source .venv/bin/activate
make install         # equivalent to: pip install -e ".[dev]"
```

### Adding a new tool

1. Pick the right category module under `tools/` (or create a new one — register
   it in `tools/__init__.py` so the side-effect import wires it up).
2. Decorate with `@mcp.tool()` (import `mcp` from `tools._registry`).
3. Use `core.get_site_manager()` for site lookups, `core.WpPaths` for path
   construction, and — for destructive tools — `core.safety.require_confirm()`
   for the confirm gate.
4. Add the tool name to `scripts/tools-baseline.txt` (or regenerate the file).
5. Add at least one integration test against the `mock_ssh` + `with_site`
   fixtures in `tests/conftest.py`.

### Running tests / quality gates

```bash
make smoke     # python -c "import server"
make parity    # asserts tools/__init__ wires up exactly the 75 baseline tools
make test      # full pytest run (excludes the 6 known-pre-existing validation
               # failures tracked separately)
make test-all  # everything, including the known failures
make lint      # ruff check (config in pyproject.toml)
```

`MockSSH` (in `tests/conftest.py`) replaces `utils.ssh.run_ssh_command` and
`run_wpcli` with a deterministic stub — register responses with
`mock_ssh.expect(substr_or_callable, (success, output))` and inspect issued
commands via `mock_ssh.calls`. Integration tests for scanning/cleanup/threat
tools should go through this fixture rather than hitting a real server.

---

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## Credits

**Author:** Varun Dubey
**Company:** [Wbcom Designs](https://wbcomdesigns.com)

### Built With

- [Model Context Protocol (MCP)](https://modelcontextprotocol.io) - Protocol for LLM integrations
- [WP-CLI](https://wp-cli.org) - Command-line interface for WordPress
- [FastMCP](https://github.com/jlowin/fastmcp) - Python MCP server framework

### Acknowledgments

- WordPress Security Team for security best practices
- The WP-CLI community for the excellent command-line tool
- Anthropic for the Model Context Protocol specification

---

## Support

For support, questions, or custom development:

- **Website:** [https://wbcomdesigns.com](https://wbcomdesigns.com)
- **GitHub Issues:** [Report a bug](https://github.com/vapvarun/wp-malware-cleanup-mcp/issues)

---

## Changelog

### Version 3.0.0 (2026)

A fleet-operations release that turns the per-site cleanup tool into a fleet
incident-response console, plus a deep re-audit that fixed a large amount of
functionality the 2.1.0 package-split refactor had shipped silently broken.

**Breaking**

- **Scan tools consolidated under `wp_scan(name, scope="full")`.** The 17 separate scan tools (`wp_full_scan`, `wp_quick_scan`, `wp_deep_scan`, `wp_scan_uploads`, `wp_scan_webshells`, …) are removed as individual tools; `scope` selects depth (`quick`/`full`/`deep`/`verbose`) or a category (`uploads`, `webshells`, `themes`, `core`, `plugins`, `hidden-admins`, `cron`, `wpconfig`, `db`, …). Scripts calling the old tool names must switch to `wp_scan(scope=...)`.
- **Removed 6 non-functional threat tools** (`wp_threat_sync_wpscan`, `wp_threat_sync_patchstack`, `wp_threat_sync_all`, `wp_threat_download_plugin_signatures`, `wp_threat_learn_from_plugins`, `wp_threat_report`) — they called methods that did not exist and crashed at runtime, advertising external feeds the server could not fetch.

**New — fleet console**

- `wp_fleet_status` — at-a-glance scorecard across all sites, worst-first, risk-scored. Instant from stored scans, or `refresh=True` to quick-scan first. Clean siblings of an infected site (same `host_group`) are flagged **AT RISK**.
- `wp_host_group_status` — one server / cPanel account's sites plus a cross-site reinfection assessment and suggested clean order.
- `host_group` on `wp_add_site` / `wp_update_site` to record which sites share an account.

**New — incident response**

- `wp_incident_report` — client-facing "proof of clean": infection timeline, IOCs (path + hash), before/after comparison, and a clean sign-off when the latest whole-site scan is clean. Anonymized by default.
- `wp_clean_cron_events` — delete malicious wp-cron hooks (the #1 reinfection vector).
- `wp_clean_malicious_htaccess` — quarantine hostile `.htaccess`/`.user.ini` that re-enable PHP execution or redirect traffic.
- `wp_scan(scope="wpconfig")` — read-only scan for injected code in wp-config.php (survives core reinstalls).
- `wp_complete_cleanup` now removes cron + `.htaccess`, scans wp-config.php, then runs a post-cleanup verification scan and sets status from the result — it no longer reports "clean" unconditionally.

**New — threat intelligence**

- The threat DB now **feeds the scanner** (it was write-only). `wp_scan(scope="malware-patterns")` greps every active signature — community-synced and learned-from-cleanup — so a signature learned cleaning one site detects on the next. (`grep -F` for strings, `grep -P` for regex, invalid patterns dropped, best-effort.)
- Persistent scan results — every whole-site scan writes a structured record to `~/.wp-malware-cleanup/scans/<site>/` (capped at 200/site), enabling history and before/after diffs. Targeted scans are recorded but never set the fleet verdict.

**Improve**

- Detection — web-shell detection requires ≥2 distinct file-manager indicators (cuts false positives from a lone `scandir`/`is_writable`); backup/migration plugins added to the false-positive paths; the obfuscation scan now also catches `eval($var)` and variable-function backdoors (`$f($_GET[...])`).
- Safety — backup gate on irreversible data deletion (`wp_clean_db_spam`, `wp_delete_malware_options`) with a `force=True` override.
- Resilience — the shared `sites.json` loader tolerates unknown keys instead of renaming the file to `.bak`, so it coexists with other MCPs.

**Fix (refactor-orphaned silent failures)**

- `wp_complete_cleanup` was a near-no-op — it called ~14 functions never imported into its module; wrapped in try/except, every step failed silently. All imports fixed; a full-chain test now guards it.
- `wp_generate_report`, `wp_generate_case_study`, `wp_export_sites`, `wp_quick_scan`, `wp_deep_scan`, `wp_batch_scan`, `wp_threat_db_sync`, `wp_threat_export`, and `wp_full_scan` steps all referenced names removed by the refactor and failed silently. Fixed and covered by a static undefined-name (F821) sweep and an execute-every-tool smoke test.
- `wp_audit_user` crashed (`UnboundLocalError`) on a user with a missing registration date.
- Case studies and reports were written into the installed package instead of the data dir.
- Validation: `validate_hostname` rejects invalid IPv4; `generate_secure_filename` keeps the extension dot (backups were missing `.sql`); `sanitize_filename` returns `unnamed` for blank input.

Tools: 75 → 59. Tests: 152 passing, no skips.

### Version 2.1.0 (2026)

- **Package-split refactor** — server.py shrank from 8,176 to 60 lines; 75 tools moved into per-category modules under `tools/` (sites, scanning, cleanup, hardening, reinstall, users, threat, reporting, batch, background, misc).
- New `core/` package — `SiteManager`, `WpPaths`, `WpConfigService`, `require_confirm()`, `ScanReport`, `CleanupReport`, threat DB facade, scan orchestrator.
- **Confirm gates** added to `wp_reinstall_plugin`, `wp_clean_core_injections`, `wp_delete_malware_options`, `wp_remove_mu_plugin`. Each now requires `confirm=True`; without it they return a preview manifest.
- **DB-password leak fix** — `wp_scan_hidden_admins` and `wp_scan_app_passwords` previously built `mysql -u <user> -p<pass>` commands visible in `ps` on the target. They now route through WP-CLI via `WpConfigService.run_query()`, keeping credentials inside the WP-CLI process.
- v1 modules (`database.py`, `threat_feeds.py`) deleted; `V2_MODULES_AVAILABLE` branching removed; legacy fallback SSH impls removed.
- `pyproject.toml`, `Makefile`, and `MockSSH` test fixture added. Test count: 75 (up from 33 unit tests in 2.0.0).

### Version 2.0.0 (2026)

- **Auto-learning pipeline** — every scan/cleanup action auto-records to threat DB
- Cross-site hash recognition — quarantined files are auto-detected on other sites
- SSH connection pooling and thread-safe DB connections
- Signature caching with TTL and pre-compiled regex
- New tools: `wp_scan_hidden_plugins`, `wp_scan_themes`, `wp_clean_core_injections`, `wp_delete_malware_options`, `wp_revoke_app_passwords`, `wp_complete_cleanup`, `wp_scan_hidden_admins`, `wp_scan_app_passwords`, `wp_scan_webshells`, `wp_harden_wpconfig`, `wp_install_security_mu_plugin`, `wp_full_harden`, `wp_generate_case_study`
- GitHub community signature sync (`wp_threat_db_sync`)
- Anonymized case study generation
- v2 config, models, and utils modules

### Version 1.0.0 (2024)

- Initial release
- Multi-site management
- Comprehensive malware scanning
- User audit capabilities
- Safe cleanup operations
- Security hardening tools
- Batch operations
- Detailed reporting

wp-malware-cleanup-mcp

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README