Skip to content

DOCUMENTATION.md

Latest commit

 

History

History
334 lines (249 loc) · 8.08 KB

DOCUMENTATION.md

File metadata and controls

334 lines (249 loc) · 8.08 KB

PluginHunter Documentation Index

Complete documentation for PluginHunter - Advanced WordPress Plugin Vulnerability Scanner

Author: LAKSHMIKANTHAN K (letchupkt)
Version: 1.3.0
License: MIT

Quick Links

Installation

pip install PluginHunter

That's it! No source code access needed.

Quick Start

Interactive Mode (Recommended)

PluginHunter

Command Line Scans

# Scan WordPress.org plugin
PluginHunter scan-plugin woocommerce

# Scan local directory
PluginHunter scan-local /path/to/plugin

# Scan GitHub repository
PluginHunter scan-github https://github.com/user/plugin

# Scan ZIP file
PluginHunter scan-zip plugin.zip

Server Mode

PluginHunter
# Select option 7 to configure
# Select option 8 to start

Features

Detection Capabilities

  • 48 Detection Rules across 15 categories
  • 40+ CWE Categories covered
  • 100% OWASP Top 10 2021 coverage
  • Advanced pattern matching with Semgrep-style syntax
  • Taint analysis with source-sink-sanitizer tracking
  • WordPress-specific security intelligence

Vulnerability Types Detected

  • Injection attacks (SQL, XSS, Command, LDAP, XXE, GraphQL, NoSQL, Email, Template)
  • Authentication & authorization issues (IDOR, privilege escalation, missing auth)
  • CSRF vulnerabilities (missing nonce, unprotected hooks)
  • File operations (upload, path traversal, zip slip)
  • Modern web attacks (SSRF, open redirect, CORS, cache poisoning, request smuggling)
  • Business logic flaws (price manipulation, mass assignment)
  • Cryptography issues (weak algorithms, insecure randomness, hardcoded credentials)
  • Advanced vulnerabilities (second-order SQLi, type juggling, timing attacks, JWT flaws, OAuth issues, race conditions)

Scan Modes

  • WordPress.org plugin repository
  • Local directories and ZIP files
  • GitHub repositories
  • Server mode for continuous scanning

Report Formats

  • JSON (machine-readable)
  • HTML (interactive dashboard)
  • CVE-ready Markdown (professional reports)

Documentation Files

Core Documentation

Specialized Guides

Community

Key Features Explained

1. AST-Based Analysis

Uses tree-sitter for accurate PHP parsing, enabling:

  • Precise code structure understanding
  • Context-aware vulnerability detection
  • Low false positive rate

2. Taint Analysis

Tracks data flow from sources to sinks:

  • Sources: User input ($_GET, $_POST, $_REQUEST, etc.)
  • Sinks: Dangerous functions (echo, query, exec, etc.)
  • Sanitizers: Security functions (esc_html, prepare, etc.)

3. Pattern Matching

Semgrep-style patterns with:

  • Metavariables ($VAR, $FUNC, $KEY)
  • Pattern lists (AND logic)
  • Pattern exclusions (pattern-not-inside)
  • Regex validation (metavariable-regex)

4. WordPress Intelligence

WordPress-specific analysis:

  • Hook registration detection
  • REST API endpoint analysis
  • Capability check validation
  • Nonce verification
  • WordPress function awareness

5. Server Mode

Automated continuous scanning:

  • Cron-based scheduling
  • Discord/Telegram notifications
  • WordPress.org API integration
  • Per-plugin report organization
  • Rate limiting and error handling

Usage Examples

Example 1: Basic Scan

PluginHunter scan-plugin contact-form-7

Output:

  • scan_contact-form-7_TIMESTAMP.json
  • scan_contact-form-7_TIMESTAMP.html
  • scan_contact-form-7_TIMESTAMP_cve.md (if critical/high findings)

Example 2: Local Plugin Development

PluginHunter scan-local ./my-plugin

Use during development to catch vulnerabilities early.

Example 3: Security Research

PluginHunter scan-github https://github.com/user/plugin

Analyze plugins from GitHub for security research.

Example 4: Continuous Monitoring

# Configure server mode
PluginHunter
# Select option 7, configure settings
# Select option 8 to start

# Or via command line
PluginHunter server-mode

Monitor multiple plugins continuously with notifications.

Report Interpretation

Severity Levels

  • Critical: Immediate action required (RCE, SQLi, Auth Bypass)
  • High: Serious vulnerabilities (XSS, IDOR, Privilege Escalation)
  • Medium: Important issues (Info Disclosure, CSRF)
  • Low: Minor concerns (Weak Crypto, Code Quality)

Confidence Levels

  • High: Very likely a real vulnerability
  • Medium: Requires context verification
  • Low: May be false positive, manual review needed

Taking Action

  1. Review findings in HTML report
  2. Check code context in source files
  3. Verify with manual testing if needed
  4. Apply recommended fixes
  5. Re-scan to confirm resolution

Advanced Configuration

Custom Rules

Add custom YAML rules to:

  • ~/.kiro/rules/ (user-level)
  • .kiro/rules/ (workspace-level)

Rule Format

rules:
- id: my-custom-rule
  mode: taint
  message: Description of vulnerability
  languages: [php]
  severity: ERROR
  pattern-sources:
    - pattern: $_GET[$KEY]
  pattern-sinks:
    - pattern: dangerous_function(...);
  pattern-sanitizers:
    - pattern: sanitize_function(...);
  metadata:
    cwe: ["CWE-XXX"]
    category: security

Troubleshooting

Common Issues

1. No Vulnerabilities Found

  • Ensure plugin has PHP files
  • Check if rules are loaded (see log output)
  • Try scanning a known vulnerable plugin for testing

2. False Positives

  • Review code context manually
  • Check if sanitization is properly detected
  • Report issues on GitHub for rule improvements

3. Scan Errors

  • Verify Python version (3.8+)
  • Check internet connection (for WordPress.org scans)
  • Ensure sufficient disk space for temp files

4. Server Mode Issues

  • Verify webhook URLs are correct
  • Check rate limiting settings
  • Review server_config.json for errors

Performance Tips

For Large Plugins

  • Use deep scan mode for thorough analysis
  • Allow sufficient time for AST parsing
  • Consider running in server mode overnight

For Multiple Plugins

  • Use server mode with scheduling
  • Configure rate limiting to avoid API throttling
  • Organize reports in separate directories

Support

Getting Help

Reporting Bugs

Include:

  1. PluginHunter version (PluginHunter version)
  2. Python version (python --version)
  3. Operating system
  4. Command used
  5. Error message or unexpected behavior
  6. Sample code (if applicable)

Feature Requests

Open a GitHub issue with:

  • Clear description of feature
  • Use case and benefits
  • Example of how it would work

Contributing

We welcome contributions! See CONTRIBUTING.md for:

  • Code contribution guidelines
  • Rule development guide
  • Testing requirements
  • Pull request process

License

MIT License - see LICENSE file for details

Changelog

See CHANGELOG.md for version history and changes.

Last Updated: 2026-02-28
Version: 1.3.0