FAQ

FAQ

General

What is this tool?

An MCP (Model Context Protocol) server that lets Claude Code scan, clean, and harden WordPress sites via SSH. It connects to your WordPress servers, runs WP-CLI commands, and manages the entire malware cleanup process.

Who is this for?

• Hosting companies managing client WordPress sites
• WordPress agencies with 20-100+ client sites
• Freelance developers handling cleanup for clients
• Security teams doing WordPress incident response

Does it work with any hosting provider?

Yes, as long as you have SSH access and WP-CLI is installed on the server. Works with shared hosting, VPS, dedicated servers, cloud hosting (AWS, DigitalOcean, etc.), and managed WordPress hosts.

Is it safe to use on production sites?

Yes. The tool is designed for production use:

• Quarantine moves files instead of deleting (recovery possible)
• Database is backed up before any cleanup
• Passwords are never stored on disk
• All actions are logged for audit trails
• File hashes are verified before operations

Setup

Do I need to install anything on the WordPress server?

Only WP-CLI, which most managed WordPress hosts already have. No agents, plugins, or daemons needed on the server side.

Can I use password auth instead of SSH keys?

Yes. Set auth_type="password" when adding a site. You'll need to pass the password parameter with every command. The password is never written to disk - it's passed via environment variable and discarded after the SSH session.

Do I need sshpass installed?

Only if using password authentication. Install with brew install sshpass on macOS or apt install sshpass on Ubuntu.

How many sites can I manage?

There's no hard limit. The tool has been tested with 30+ sites. For 100+ sites, consider splitting into groups and running parallel Claude Code sessions.

Scanning

How long does a full scan take?

Depends on the site size:

• Small site (few plugins): 1-2 minutes
• Medium site (20+ plugins): 3-5 minutes
• Large site (50+ plugins, lots of content): 5-10 minutes

Will scanning affect site performance?

Minimal impact. Scans run WP-CLI commands which have low overhead. The deep pattern scan (grep) may briefly increase disk I/O on the server. Running scans during low-traffic hours is recommended for large sites.

What's the difference between wp_full_scan and wp_full_scan_verbose?

wp_full_scan gives a summary report. wp_full_scan_verbose shows the output of every individual command, useful for debugging or understanding exactly what was checked.

How do I handle false positives?

Some legitimate code triggers detections. Known false positives:

• BuddyBoss .htaccess files in uploads directories
• bbpress and wbcomteam plugin names matching suspicious patterns
• Base64 encoding in image-handling plugins
• Minified JavaScript files

Use wp_read_file() to inspect flagged files before taking action.

Cleanup

Should I use wp_complete_cleanup or do it manually?

For most infections, wp_complete_cleanup handles everything in 16 steps. Use manual cleanup when:

• You want to preserve specific files/users
• The infection is unusual and needs custom handling
• You want more control over each step

What happens if cleanup is interrupted?

Each step is independent. If the process stops mid-way:

• Completed steps are already applied
• The database backup from Step 1 is still available
• Re-run wp_complete_cleanup or continue manually from where it stopped

Can I undo a cleanup?

Partially:

• Quarantined files can be restored from the quarantine directory
• Database can be restored from the backup
• Passwords and salts cannot be reversed (by design - they were compromised)
• Deleted malware files are gone (that's the point)

Does cleanup cause downtime?

Typically no visible downtime. The site stays accessible throughout. Users will need to log in again after:

• Salt regeneration (invalidates all sessions)
• Password reset (old passwords no longer work)

Threat Database

What is the auto-learning pipeline?

Every scan and cleanup action automatically records findings to a local SQLite database. Quarantined file hashes are stored so the same malware is instantly recognized on other sites.

Is the threat database shared between users?

The local database is private to your machine. You can optionally export and share discoveries with the community via wp_threat_export() and submitting a PR.

How do I sync community signatures?

wp_threat_db_sync()

This downloads the latest community-contributed malware signatures from GitHub.

Where is the database stored?

At ~/.wp-malware-cleanup/threat_intel.db (SQLite). Back it up - it contains your accumulated intelligence.

Security

Are my SSH credentials safe?

• SSH keys: Referenced by path, never copied or transmitted through the MCP protocol
• Passwords: Passed as runtime parameters, never written to disk, transmitted via SSHPASS environment variable only for the duration of the SSH command
• Site configs: Stored in ~/.wp-malware-cleanup/sites.json with hostnames and paths, but never passwords

Can this tool be used maliciously?

The tool requires SSH access to servers - if someone has SSH access, they already have full control. The tool makes legitimate security operations easier, it doesn't grant new access.

Are reports safe to share?

• wp_generate_report(anonymize=true) - Safe for public sharing, all identifying info removed
• wp_generate_report(anonymize=false) - Contains hostnames, IPs, usernames. Keep private.
• Case studies in docs/case-studies/ are auto-anonymized

Troubleshooting

"Connection refused" or "Connection timed out"

1. Verify hostname and port: ssh -p PORT user@host
2. Check if SSH is running on the server
3. Check firewall rules allow your IP
4. Try wp_test_connection("site-name") for diagnostics

"WP-CLI not found"

Install WP-CLI on the server:

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 SSH user can access the WordPress directory
3. Verify the user can run WP-CLI: ssh user@host "wp --info"

Scan finds nothing but site is clearly hacked

Some malware hides in the database rather than files:

1. Run wp_check_db_injections("site-name") specifically
2. Check wp_delete_malware_options("site-name", dry_run=True) for DB markers
3. Inspect wp_options for suspicious entries manually

Threat DB not recording anything

1. Check that database_v2.py exists in the MCP server directory
2. Run wp_threat_db_stats() - if it errors, the DB module isn't loading
3. Check the MCP server logs for import errors