wp-vulnhunter 1.2.1
Advanced WordPress Plugin Vulnerability Scanner
License: MIT
Requires Python: >=3.8
Keywords: wordpress, security, vulnerability, scanner, static-analysis, penetration-testing

# WP-VulnHunter

Advanced WordPress Plugin Vulnerability Scanner

Author: LAKSHMIKANTHAN K (letchupkt)

## Overview

WP-VulnHunter is a comprehensive static analysis tool designed to identify security vulnerabilities in WordPress plugins. It performs deep code analysis without exploitation, focusing on finding dangerous patterns and weak security implementations.

## Features

### Core Capabilities

- **Multiple Input Sources**
  - WordPress.org Plugin Repository (by slug)
  - Local ZIP files
  - GitHub repositories
  - Automatic extraction and analysis

- **Advanced Detection**
  - SQL Injection vulnerabilities
  - Cross-Site Scripting (XSS)
  - File Inclusion (LFI/RFI)
  - Command Injection
  - Insecure File Uploads
  - Authentication Bypass
  - CSRF vulnerabilities
  - PHP Object Injection

- **Smart Analysis**
  - Pattern-based scanning
  - Custom YAML templates (Nuclei-like)
  - Semgrep integration
  - AJAX/REST endpoint detection
  - Risk scoring engine

- **Professional Reports**
  - JSON format
  - HTML comprehensive report
  - Text detailed report
  - Executive summary
  - CVE-ready drafts

## Installation

### Requirements

- Python 3.8 or higher
- pip package manager

### Install from PyPI

```bash
pip install wp-vulnhunter
```

### Verify Installation

```bash
wp-vulnhunter --version
```

### Optional: Install Semgrep

For advanced static analysis:

```bash
pip install semgrep
```

## Quick Start

After installation, run your first scan:

```bash
wp-vulnhunter contact-form-7
```

The tool will:
1. Download the plugin from WordPress.org
2. Extract and analyze the code
3. Generate comprehensive reports
4. Save results to `./reports/contact-form-7/`

## Usage

### Command Line Interface

#### Basic Scan

Scan a WordPress.org plugin:

```bash
wp-vulnhunter contact-form-7
```

Scan with verbose output:

```bash
wp-vulnhunter contact-form-7 --verbose
```

Scan and specify output directory:

```bash
wp-vulnhunter contact-form-7 -o reports/contact-form-7
```

#### Scan Local ZIP File

```bash
wp-vulnhunter /path/to/plugin.zip -v
```

#### Scan GitHub Repository

```bash
wp-vulnhunter https://github.com/user/wp-plugin -v
```

#### Interactive Mode

Launch interactive menu:

```bash
wp-vulnhunter --interactive
```

Or:

```bash
wp-vulnhunter -i
```

### Command Line Options

```
Usage: wp-vulnhunter [OPTIONS] [TARGET]

Options:
  -o, --output PATH       Output directory for reports
  -v, --verbose          Enable verbose output
  -f, --format [all|json|html|text|cve]
                         Report format (default: all)
  -i, --interactive      Launch interactive menu
  --version              Show version and exit
  --help                 Show this message and exit
```

## Examples

### Example 1: Quick Scan

Scan a popular plugin:

```bash
wp-vulnhunter woocommerce
```

Output:
```
[*] Starting scan of: woocommerce
[*] Downloading woocommerce from WordPress.org...
[*] Scanning for dangerous patterns...
[*] Detecting AJAX/REST endpoints...
[*] Analyzing file upload risks...
[*] Calculating risk scores...
[OK] Reports generated in: reports/woocommerce

Scan Summary:
  Critical: 0
  High: 5
  Medium: 12
  Low: 8
  Total: 25
```

### Example 2: Detailed Scan with Custom Output

```bash
wp-vulnhunter jetpack -o /home/user/security-reports/jetpack -v
```

### Example 3: Scan Local Plugin

```bash
wp-vulnhunter ./my-custom-plugin.zip -v -o ./reports/my-plugin
```

### Example 4: Scan from GitHub

```bash
wp-vulnhunter https://github.com/WordPress/gutenberg -v
```

### Example 5: Interactive Mode

```bash
wp-vulnhunter -i
```

Then select from menu:
```
1. Scan WordPress.org Plugin (by slug)
2. Scan Local ZIP File
3. Scan GitHub Repository
4. Manage Detection Rules (Unified)
5. View Scan History
6. Configuration Settings
7. About WP-VulnHunter
0. Exit
```

## Report Formats

### JSON Report

Machine-readable format for automation:

```json
{
  "plugin_info": {
    "name": "Contact Form 7",
    "version": "5.8",
    "author": "Takayuki Miyoshi"
  },
  "summary": {
    "total_findings": 15,
    "critical_findings": 0,
    "high_findings": 3,
    "medium_findings": 8,
    "low_findings": 4
  },
  "vulnerabilities": [...]
}
```

### HTML Report

Comprehensive visual report with:
- Executive summary
- Vulnerability details
- Code snippets
- Risk scores
- Remediation suggestions

### Text Report

Detailed text format for easy reading:

```
VULNERABILITY REPORT
Plugin: Contact Form 7
Version: 5.8

CRITICAL VULNERABILITIES: 0
HIGH VULNERABILITIES: 3
MEDIUM VULNERABILITIES: 8
LOW VULNERABILITIES: 4

[HIGH] Cross-Site Scripting (XSS)
File: includes/contact-form.php
Line: 245
Risk Score: 8.5/10
Description: Unescaped output of user input
```

### CVE Drafts

Ready-to-submit CVE format:

```
CVE-YYYY-XXXXX

Title: Cross-Site Scripting in Contact Form 7

Description:
A Cross-Site Scripting vulnerability exists in Contact Form 7
version 5.8 in the file includes/contact-form.php at line 245.

CVSS Score: 8.5 (High)
CWE: CWE-79
OWASP: A03:2021
```

## Detection Templates

WP-VulnHunter uses custom YAML templates for vulnerability detection.

### Bundled Templates

The tool comes with 18+ pre-built detection rules:
- SQL Injection
- Cross-Site Scripting (XSS)
- File Inclusion (LFI/RFI)
- Command Injection
- Insecure File Uploads
- Authentication Bypass
- CSRF vulnerabilities
- And more...

### Community Templates

Access community-contributed templates:

Repository: https://github.com/yourusername/wp-vulnhunter-templates

### Using Community Templates

1. Browse available templates at the repository
2. Download templates you need
3. Place in `~/.wp_vulnhunter/templates/`
4. Reload rules in interactive mode

Or use the CLI:

```bash
wp-vulnhunter -i
# Select: Manage Detection Rules > Download Semgrep Rules
```

### Creating Custom Templates

Create your own detection template:

```yaml
id: my-custom-check

info:
  name: My Custom Vulnerability Check
  author: your-name
  severity: high
  description: Detects custom vulnerability pattern
  tags:
    - wordpress
    - custom
  metadata:
    cwe: CWE-79
    owasp: A03:2021

file-extensions:
  - .php

matchers:
  - name: dangerous-pattern
    type: regex
    regex:
      - "dangerous_function\\(\\$_GET"
    condition: or
```

Save to: `~/.wp_vulnhunter/templates/my-custom-check.yaml`

### Contributing Templates

Want to share your templates with the community?

1. Visit: https://github.com/yourusername/wp-vulnhunter-templates
2. Fork the repository
3. Add your template to the appropriate category
4. Submit a pull request
5. Include documentation and test cases

Template contributions are welcome and help the entire WordPress security community!

## Configuration

### Default Directories

- **Downloads**: `./downloads/` (current directory)
- **Reports**: `./reports/` (current directory)
- **Custom Templates**: `~/.wp_vulnhunter/templates/`
- **Semgrep Rules**: `~/.wp_vulnhunter/cache/semgrep_rules/`

### Bundled Rules

Location: `wp_vulnhunter/rules/`

- Custom templates: `wp_vulnhunter/rules/custom-templates/`
- Semgrep rules: `wp_vulnhunter/rules/semgrep-rules/`

## Advanced Usage

### Python API

Use WP-VulnHunter programmatically:

```python
from wp_vulnhunter import VulnHunter

# Initialize scanner
scanner = VulnHunter(verbose=True)

# Scan plugin
results = scanner.scan_plugin('contact-form-7', 'reports/cf7')

# Access results
print(f"Total findings: {results['summary']['total_findings']}")
print(f"Critical: {results['summary']['critical_findings']}")

# Iterate vulnerabilities
for vuln in results['vulnerabilities']:
    print(f"{vuln['severity']}: {vuln['type']}")
    print(f"File: {vuln['file']}")
    print(f"Line: {vuln['line']}")
```

### Batch Scanning

Scan multiple plugins:

```bash
#!/bin/bash
plugins=("contact-form-7" "woocommerce" "jetpack" "akismet")

for plugin in "${plugins[@]}"; do
    echo "Scanning $plugin..."
    wp-vulnhunter "$plugin" -o "reports/$plugin"
done
```

### CI/CD Integration

GitHub Actions example:

```yaml
name: Security Scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: '3.10'
      
      - name: Install WP-VulnHunter
        run: |
          pip install wp-vulnhunter
          pip install semgrep
      
      - name: Scan Plugin
        run: |
          wp-vulnhunter ./plugin.zip -o reports -v
      
      - name: Upload Reports
        uses: actions/upload-artifact@v2
        with:
          name: security-reports
          path: reports/
```

## Troubleshooting

### Common Issues

#### Issue: Plugin not found

```
Error: Plugin 'xyz' not found on WordPress.org
```

Solution: Verify plugin slug at wordpress.org/plugins/

#### Issue: Semgrep not available

```
[!] Semgrep not installed - advanced rules will use fallback patterns
```

Solution: Install Semgrep:
```bash
pip install semgrep
```

#### Issue: Permission denied

```
Error: Permission denied: /path/to/reports
```

Solution: Check directory permissions or use different output path:
```bash
wp-vulnhunter plugin-name -o ~/reports/plugin-name
```

### Debug Mode

Enable verbose output for debugging:

```bash
wp-vulnhunter plugin-name -v
```

## Performance

### Scan Times

Typical scan times (approximate):

- Small plugin (< 100 files): 10-30 seconds
- Medium plugin (100-500 files): 30-90 seconds
- Large plugin (> 500 files): 2-5 minutes

### Optimization Tips

1. Use specific output directory to avoid conflicts
2. Run Semgrep scans separately for large plugins
3. Use pattern scanning only for quick checks
4. Enable verbose mode only when needed

## Security Considerations

### Responsible Disclosure

If you find vulnerabilities:

1. Do NOT exploit the vulnerability
2. Report to plugin author privately
3. Allow reasonable time for fix (90 days)
4. Coordinate public disclosure

### Legal Notice

This tool is for:
- Security research
- Authorized testing
- Educational purposes

Always ensure you have permission before scanning plugins.

## Contributing

### Report Issues

Found a bug or have a suggestion?

Visit: https://github.com/yourusername/wp-vulnhunter-templates/issues

Note: The main tool is distributed via PyPI only. GitHub is for documentation and template contributions.

### Submit Templates

Create and share detection templates:

1. Visit: https://github.com/yourusername/wp-vulnhunter-templates
2. Fork the repository
3. Add your template with documentation
4. Submit a pull request

### Template Guidelines

When contributing templates:
- Follow the template format
- Include clear documentation
- Add test cases
- Specify CWE/OWASP mappings
- Test thoroughly before submitting

## Distribution

### PyPI Package

WP-VulnHunter is distributed exclusively through PyPI:

```bash
pip install wp-vulnhunter
```

Package page: https://pypi.org/project/wp-vulnhunter/

### GitHub Repository

The GitHub repository is for:
- Documentation
- Template contributions
- Issue tracking
- Community discussions

Repository: https://github.com/yourusername/wp-vulnhunter-templates

Note: The tool source code is private. Only templates and documentation are public.

## License

MIT License

Copyright (c) 2026 LAKSHMIKANTHAN K (letchupkt)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

## Changelog

### Version 1.2.1 (2026-02-09)

- Initial public release
- Unified rule management system
- Custom YAML templates support
- Semgrep integration
- Multiple input sources
- Professional report generation
- Interactive CLI mode
- 18+ bundled detection rules

## Support

- PyPI Package: https://pypi.org/project/wp-vulnhunter/
- Documentation: https://github.com/yourusername/wp-vulnhunter-templates
- Templates: https://github.com/yourusername/wp-vulnhunter-templates
- Issues: https://github.com/yourusername/wp-vulnhunter-templates/issues

## Acknowledgments

- Semgrep rules adapted from wordpress-plugin-semgrep-rules
- WordFence for security research
- WordPress security community
- All template contributors

---

Made with dedication by LAKSHMIKANTHAN K (letchupkt)

Available on PyPI: pip install wp-vulnhunter