WP Manifestindependent plugin directory
manifest / developer / wp-audit-tool

Ultimate WP Audit Tool

Enterprise forensic audit: Database + Logs + Hooks + Cron + Security + Performance. Production-safe, step-based execution with live progress.

by Muzammil · github.com/smhz101/wp-audit-tool

★ 0stars
0forks

Install

No release zip yet. The repository archive installs, but the folder name will carry the branch suffix and updates will not flow:

wp plugin install https://github.com/smhz101/wp-audit-tool/archive/refs/heads/main.zip
Readme github.com/smhz101/wp-audit-tool ↗

WordPress Database & Performance Audit Tool

Compatibility: WordPress 5.0+, PHP 7.4+
Hosting: Optimized for WP Engine (works on any hosting)

🎯 Overview

A production-safe, READ-ONLY forensic audit system for WordPress installations. This tool performs deep analysis of your WordPress database, identifies performance bottlenecks, plugin impacts, and provides actionable cleanup recommendations—without modifying any data.

Key Features

✅ Database Forensics - Complete table analysis, bloat detection, orphaned data identification
✅ Plugin Impact Analysis - Maps database usage to plugins, identifies heavy consumers
✅ Performance Assessment - Health scoring, risk levels, efficiency metrics
✅ Security Audits - Logging plugin detection, configuration checks
✅ Multi-Format Reports - Console (CLI), HTML (styled), JSON (machine-readable)
✅ WP Engine Optimized - Aware of managed hosting constraints
✅ 100% Safe - Read-only by default, no destructive operations

📋 Table of Contents

  1. Installation
  2. Usage
  3. Configuration
  4. Report Outputs
  5. What Gets Analyzed
  6. Understanding Results
  7. Cleanup Recommendations
  8. WP Engine Specific Notes
  9. Security Considerations
  10. Troubleshooting
  11. FAQ

🚀 Installation

Method 1: MU-Plugin (Recommended for Production)

# Navigate to your WordPress installation
cd /path/to/wordpress

# Create mu-plugins directory if it doesn't exist
mkdir -p wp-content/mu-plugins/wp-audit-tool

# Upload all files
cp -r wp-audit-tool/* wp-content/mu-plugins/wp-audit-tool/

# Move main file to mu-plugins root
mv wp-content/mu-plugins/wp-audit-tool/wp-audit-tool.php wp-content/mu-plugins/

Method 2: Regular Plugin

# Upload to plugins directory
cp -r wp-audit-tool wp-content/plugins/

# Activate via WordPress admin or WP-CLI
wp plugin activate wp-audit-tool

Method 3: Standalone Script (Temporary Audit)

# Upload to WordPress root (remove after audit)
cp -r wp-audit-tool /path/to/wordpress/

# Run immediately via WP-CLI
wp audit --path=/path/to/wordpress

💻 Usage

Via WordPress Admin (Primary Method)

  1. Install & Activate the plugin through the WordPress admin or WP-CLI
  2. Navigate to WP Audit in the left admin menu
  3. Click "Start Audit" button
  4. Watch real-time progress as each step completes (typically 30-90 seconds total)
  5. View the executive summary and download HTML/JSON reports

Features:

  • ✅ Real-time progress tracking with live step updates
  • ✅ Activity log showing each completed step
  • ✅ Executive summary with health score and risk assessment
  • ✅ Downloadable HTML and JSON reports
  • ✅ Non-blocking execution (won't timeout on large databases)
  • ✅ Cancel audit mid-process if needed

Via WP-CLI (Advanced)

# Basic audit (all default formats)
wp audit

# HTML report only
wp audit --format=html

# JSON export only
wp audit --format=json

# Multiple formats
wp audit --format=html,json

# Include optional cleanup SQL queries
wp audit --include-sql

# Custom output directory
wp audit --output-dir=/custom/path

Via WordPress Admin (Browser)

  1. Navigate to Tools → Database Audit
  2. Select desired output formats
  3. Optionally include SQL queries
  4. Click Run Audit
  5. Reports will be generated in wp-content/audit-reports/

Security: Admin page requires manage_options capability and nonce verification.

⚙️ Configuration

Default Configuration

The tool comes with sensible defaults. To customize, edit the main plugin file:

// In wp-audit-tool.php, find set_default_config() method

$this->config = [
    // Security
    'cli_only' => false,          // Set true to disable browser access
    'require_admin' => true,

    // Performance
    'batch_size' => 1000,
    'max_execution_time' => 300,  // 5 minutes
    'memory_limit' => '512M',

    // Alert thresholds
    'thresholds' => [
        'table_size_warning_mb' => 100,
        'table_size_critical_mb' => 500,
        'autoload_warning_kb' => 500,
        'autoload_critical_kb' => 1000,
        'revisions_warning' => 10,
        'revisions_critical' => 50,
        'postmeta_ratio_warning' => 5.0,
        'postmeta_ratio_critical' => 10.0,
    ],
];

WP Engine Specific Settings

For WP Engine hosting, the tool automatically detects the environment. No special configuration needed.

📊 Report Outputs

1. Console Output (WP-CLI)

Real-time progress and summary displayed in terminal:

===========================================
WordPress Database & Performance Audit
===========================================

DATABASE ANALYSIS
===========================================
  → Analyzing database structure...
  → Scanning all database tables...
  [... progress ...]

EXECUTIVE SUMMARY
Database Size: 2.45 GB
Health Score: 72/100
Risk Level: MEDIUM
Potential Savings: 412 MB (16.8%)

2. HTML Report

Professional, client-ready report with:

  • Executive Summary - Key metrics, health score, risk assessment
  • Database Analysis - Table sizes, meta key usage, orphaned data
  • Plugin Impact - Database footprint by plugin
  • Cleanup Opportunities - Prioritized actionable items
  • Recommendations - Preventive measures

Location: wp-content/uploads/wp-audit-reports/audit-report_YYYY-MM-DD_HH-MM-SS.html

Access: Reports are protected by .htaccess and can only be downloaded through the WordPress admin interface or accessed by administrators.

3. JSON Export

Machine-readable full results for:

  • CI/CD integration
  • Monitoring systems
  • Custom analysis tools

Location: wp-content/uploads/wp-audit-reports/audit-report_YYYY-MM-DD_HH-MM-SS.json

🔍 What Gets Analyzed

Database Forensics

  • All Tables: Size, row count, index size, engine type
  • Size Rankings: Largest tables identified
  • Growth Patterns: Abnormal growth detection
    • Postmeta larger than posts
    • Log table bloat
    • Action Scheduler accumulation
  • Meta Keys: Top 50 by count and size
  • Orphaned Data: Postmeta, usermeta, commentmeta without parent records
  • Revisions: Count, size, excessive revision detection
  • Autoload: Size and top offenders
  • Transients: Total, expired, size

Plugin Impact

  • Table Ownership: Heuristic mapping of tables to plugins
  • Database Footprint: Per-plugin size estimates
  • Cron Jobs: Excessive scheduled events detection
  • Logging Plugins: Detection of security/audit log plugins
  • Cleanup Status: Identifies plugins without retention policies

WordPress Health

  • Version Checks: WP, PHP, database versions
  • Memory Limits: PHP and WP memory settings
  • Caching: Object cache, page cache detection
  • Cron Status: WP-Cron health
  • REST API: Connectivity check
  • Constants: Debug settings, revision limits
  • Hosting Detection: WP Engine, Kinsta, etc.

Performance Signals

  • Database Efficiency: Size per post ratio
  • Meta Ratios: Postmeta-to-post ratio
  • Bloat Score: 0-100 scale
  • Health Score: 100 - bloat score
  • Risk Level: LOW | MEDIUM | HIGH | CRITICAL

📈 Understanding Results

Health Score (0-100)

  • 90-100: Excellent - Well-maintained database
  • 70-89: Good - Minor optimization opportunities
  • 50-69: Fair - Moderate cleanup recommended
  • 30-49: Poor - Significant issues present
  • 0-29: Critical - Urgent action required

Risk Levels

  • LOW: Normal operations, preventive maintenance only
  • MEDIUM: Optimization recommended within 30 days
  • HIGH: Performance degradation likely, address within 7 days
  • CRITICAL: Immediate action required, site at risk

Key Metrics

Metric Good Warning Critical
Postmeta Ratio < 5:1 5-10:1 > 10:1
Autoload Size < 500 KB 500-1000 KB > 1 MB
Table Size < 100 MB 100-500 MB > 500 MB
Orphaned Rows < 1,000 1K-10K > 10K
Revisions < 1,000 1K-5K > 5K

🧹 Cleanup Recommendations

Understanding Cleanup Opportunities

The tool provides prioritized, actionable recommendations without executing any changes.

Priority Levels

  • CRITICAL: Immediate attention required
  • HIGH: Address within 1 week
  • MEDIUM: Schedule within 1 month
  • LOW: Nice to have, low urgency

Optional SQL Queries

When --include-sql is enabled, the tool provides commented-out SQL for manual execution:

-- OPTIONAL: Clean orphaned postmeta
-- BACKUP YOUR DATABASE FIRST!
-- Test with SELECT first, then uncomment DELETE

/*
DELETE pm FROM wp_postmeta pm
LEFT JOIN wp_posts p ON pm.post_id = p.ID
WHERE p.ID IS NULL
LIMIT 1000;
*/

⚠️ Always:

  1. Backup your database before running any cleanup
  2. Test on staging first
  3. Run in batches (LIMIT 1000)
  4. Verify results before proceeding

Recommended Cleanup Plugins

For automated, safe cleanup:

  • WP-Optimize - Database optimization
  • Advanced Database Cleaner - Orphaned data removal
  • WP-Sweep - Database cleanup
  • WP Rocket (Database optimization feature)

🏢 WP Engine Specific Notes

Automatic Detection

The tool automatically detects WP Engine hosting and:

  • Recognizes EverCache (built-in object cache)
  • Skips page cache recommendations (EverCache handles this)
  • Adjusts execution limits for environment

WP Engine Features Detected

  • ✅ EverCache (object cache)
  • ✅ CDN availability
  • ✅ Managed WordPress optimizations

Running on WP Engine

# SSH into your WP Engine environment
ssh environment@environment.ssh.wpengine.net

# Navigate to WordPress root
cd sites/yoursitename

# Run audit
wp audit --format=html,json

# Download reports
# Reports are in wp-content/audit-reports/

WP Engine Limitations

  • Max Execution Time: Usually 120 seconds (tool handles this)
  • Memory Limit: Typically 512MB-1GB
  • Database Access: Full read access available
  • Cron: Managed by WP Engine

🔒 Security Considerations

Read-Only by Default

The tool NEVER modifies data unless you manually execute provided SQL.

Access Control

  • Requires WordPress admin capability (manage_options)
  • Nonce verification on all requests
  • Optional CLI-only mode for production

Sensitive Information

Reports may contain:

  • Database table names
  • Plugin names and versions
  • Server configuration details

Do not share reports publicly. Store in secure location.

Production Safety

// Force CLI-only mode in wp-config.php
define('WP_AUDIT_CLI_ONLY', true);

Report Storage

Reports are stored in wp-content/audit-reports/ with:

  • .htaccess protection (Apache)
  • No direct web access

For added security:

# Move reports to non-web-accessible directory
mv wp-content/audit-reports /home/user/secure-reports

🐛 Troubleshooting

"Maximum execution time exceeded"

# Increase timeout in wp-config.php
define('WP_AUDIT_MAX_TIME', 600); // 10 minutes

Or use PHP CLI directly:

php -d max_execution_time=600 wp-cli.phar audit

"Memory limit exhausted"

# Increase memory in wp-config.php
define('WP_AUDIT_MEMORY_LIMIT', '1024M');

"Permission denied" on report directory

# Fix permissions
chmod 755 wp-content/audit-reports
chown www-data:www-data wp-content/audit-reports

Large Database Timeouts

For databases > 5GB:

# Run in batches
wp audit --format=json  # JSON is fastest

WP-CLI Not Found

# Install WP-CLI
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

❓ FAQ

How long does an audit take?

  • Small sites (< 500 MB): 30-60 seconds
  • Medium sites (500 MB - 2 GB): 1-3 minutes
  • Large sites (2-10 GB): 3-10 minutes
  • Very large (> 10 GB): 10-30 minutes

Can I run this on a live production site?

Yes. The tool is read-only and designed for production use. However:

  • Run during low-traffic periods
  • Monitor server resources
  • Test on staging first for very large databases

Will this slow down my site?

The audit runs as a one-time process. It may temporarily increase:

  • Database CPU usage (10-30%)
  • Memory usage
  • Database connections (1-2 connections)

Impact on visitors: Minimal to none on properly configured servers.

How often should I run audits?

Recommended schedule:

  • Monthly: General health monitoring
  • Quarterly: Pre-optimization planning
  • After major updates: Plugin/theme updates
  • Before migrations: Pre-migration assessment

What if I find critical issues?

  1. Don't panic - Issues are identified, not emergencies
  2. Review recommendations - Prioritized list provided
  3. Backup first - Before any cleanup
  4. Test on staging - Never run cleanup on production first
  5. Implement gradually - One category at a time

Can I automate this?

Yes, via cron:

# Add to crontab (monthly audit)
0 2 1 * * /usr/local/bin/wp audit --path=/var/www/html --format=json

Does this work with multisite?

Partial support. The tool analyzes the database as a whole but:

  • Network-wide tables are included
  • Per-site breakdowns are not provided
  • Best for single-site or network-wide assessment

📝 Changelog

Version 1.0.0 (2026-01-15)

  • Initial release
  • Database forensics module
  • Plugin impact analyzer
  • WordPress health checker
  • HTML/JSON/Console reports
  • WP Engine detection
  • Read-only safety
  • CLI and browser interfaces

🤝 Support

Issues or Questions?

For enterprise support or custom development:

  • Email: wordpress-performance@example.com
  • Documentation: Full docs

Contributing

This tool was developed for internal use. If you have improvements:

  1. Test thoroughly on staging
  2. Document changes
  3. Submit via your organization's process

📄 License

GPL-2.0+

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation.

⚠️ Disclaimer

READ-ONLY AUDIT TOOL

This tool performs read-only analysis. No data is modified during the audit process. Any cleanup operations require manual execution of provided SQL queries (which are disabled and commented out by default).

Always backup your database before performing any cleanup operations.

The authors are not responsible for data loss resulting from improper use of cleanup recommendations.

🎓 Best Practices

Before Running Audit

  1. ✅ Test on staging environment first
  2. ✅ Ensure adequate disk space for reports
  3. ✅ Schedule during low-traffic periods
  4. ✅ Notify team members

After Receiving Results

  1. ✅ Review executive summary first
  2. ✅ Prioritize by risk level
  3. ✅ Back up database
  4. ✅ Test cleanup on staging
  5. ✅ Monitor performance after changes

Ongoing Maintenance

  1. ✅ Run monthly audits
  2. ✅ Track trends over time
  3. ✅ Implement preventive measures
  4. ✅ Document cleanup actions

Built with ❤️ for WordPress Performance

A production-grade tool for professional WordPress database auditing.