Local WordPress plugin review, without uploading your source code.
WP Plugin Modernization is a local, read-only review tool for WordPress plugin folders and ZIP archives. It inventories PHP files, checks PHP syntax when a local PHP runtime is available, and produces focused review cues for request input, database access, output handling, and higher-risk PHP functions.
The application separates actionable review cues from mitigated observations. It does not call a plugin secure, compatible, malware-free, or ready for production based on pattern matching alone.
Developed by Jim Walker, The Hack Repair Guy, this project applies an evidence-first WordPress repair mindset to plugin code review: show what was observed, explain the limits, and keep final decisions in human hands.
| Capability | Why It Matters |
|---|---|
| Local folder and ZIP intake | Review custom, premium, archived, or public plugins without uploading source. |
| Read-only source handling | Reports are written to a new output directory; the selected plugin is not modified. |
| Safe ZIP extraction | Archive paths are checked before extraction to reject path traversal. |
| PHP syntax checks | Every first-party PHP file is checked with php -l when PHP is available. |
| Context-aware review cues | Request input, output, deserialization, and dynamic database patterns are interpreted with nearby controls. |
| Mitigation recognition | Nonces, capability wrappers, sanitization, escaping, constrained deserialization, and documented exceptions reduce noise. |
| JSON and Markdown reports | Keep a machine-readable artifact and a practical human review report from the same scan. |
| Tooling exclusions | .git, .claude, .codex, vendor, node_modules, and similar non-plugin trees are skipped. |
- Python 3.11 or newer
- PHP available on
PATHfor syntax checks
The foundation analyzer has no third-party Python dependencies.
git clone https://github.com/hackrepair/wp-plugin-modernization.git
cd wp-plugin-modernization
python3 -m venv .venv
source .venv/bin/activate
python -m pip install .
wp-plugin-modernization /path/to/plugin-or-plugin.zip \
--output /path/to/new-report-directoryYou can also run the compatibility entrypoint directly from a checkout:
python3 app/analyze_plugin.py /path/to/plugin-or-plugin.zip \
--output /path/to/new-report-directoryThe output directory must not already exist. A successful run creates:
new-report-directory/
├── report.json
└── report.md
Actionable review cues identify code that still needs contextual review. A cue is not proof of a vulnerability.
Mitigated observations record patterns where nearby controls were detected, such as capability and nonce checks, appropriate escaping, or unserialize() with object construction disabled and a type guard.
Unavailable checks explain when evidence could not be collected, for example when PHP is not installed locally.
WP Plugin Modernization is not a malware scanner, runtime debugger, penetration test, WordPress integrity checker, or automatic code-rewriting service.
The current foundation does not run WPCS, PHPStan, PHP compatibility rules, WordPress Plugin Check, live-site tests, or staging activation tests. These are planned as explicit adapters, with availability and provenance recorded in the report.
Do not deploy changes solely because a report is quiet. Mature plugins still require code review, staging activation, representative workflow tests, and production-specific judgment.
Plugin source remains on the local machine. The foundation analyzer does not upload files, send telemetry, require an account, contact a private scanning service, or access a WordPress site.
Future network-backed adapters must remain opt-in and disclose exactly what data leaves the machine.
Create an editable development environment:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --editable .Run the test suite:
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -vCurrent coverage includes source preservation, folder and ZIP intake, unsafe ZIP rejection, non-overwriting reports, embedded-worktree exclusion, guarded-input recognition, constrained deserialization, structured WordPress database calls, and documented stream output.
Pull requests run the test suite on Python 3.11 through 3.14 with PHP 8.3 available for lint coverage. GitHub Actions are pinned to immutable commit SHAs and maintained through Dependabot.
See PROJECT.md for the evidence model, architecture, implementation status, roadmap, and release requirements.
Project decision-making and maintenance responsibilities are documented in GOVERNANCE.md.
Contributions are welcome while the project is taking shape. Please read CONTRIBUTING.md before opening a pull request.
For a vulnerability in WP Plugin Modernization itself, follow SECURITY.md. Do not attach private or customer plugin source to a public issue.
GPL-2.0-or-later. See LICENSE.
Developed by Jim Walker, The Hack Repair Guy.
Repository: hackrepair/wp-plugin-modernization