Metadata-Version: 2.4
Name: pluginhunter
Version: 1.3.0
Summary: Advanced WordPress Plugin Vulnerability Scanner with AI-powered detection
Author-email: LAKSHMIKANTHAN K <letchupkt.dev@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/letchupkt/pluginhunter
Project-URL: Repository, https://github.com/letchupkt/pluginhunter
Project-URL: Issues, https://github.com/letchupkt/pluginhunter/issues
Keywords: wordpress,security,vulnerability,scanner,plugin,static-analysis,taint-tracking
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: tree-sitter>=0.20.0
Requires-Dist: tree-sitter-php>=0.20.0
Requires-Dist: requests>=2.28.0
Requires-Dist: networkx>=3.0
Requires-Dist: packaging>=21.0
Provides-Extra: dynamic
Requires-Dist: docker>=6.0.0; extra == "dynamic"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# PluginHunter 🔍

[![Version](https://img.shields.io/badge/version-1.3.0-blue.svg)](https://github.com/yourusername/PluginHunter)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

Advanced WordPress Plugin Vulnerability Scanner with AI-powered detection, featuring 48 comprehensive security rules and sophisticated pattern matching.

## 🚀 Features

### Core Capabilities
- **48 Detection Rules** covering basic to advanced vulnerabilities
- **AST-Based Analysis** using tree-sitter for accurate PHP parsing
- **Taint Analysis** with source-sink-sanitizer tracking
- **Pattern Matching** supporting metavariables and complex logic
- **WordPress-Specific** intelligence for hooks, REST API, and capabilities
- **Multiple Scan Modes** - WordPress.org plugins, local files, GitHub repos
- **Server Mode** for continuous automated scanning
- **Rich Reports** in JSON, HTML, and CVE-ready Markdown formats

### Vulnerability Coverage

#### Injection Attacks (18 rules)
- SQL Injection (traditional & second-order)
- Cross-Site Scripting (reflected & stored)
- Command Injection
- LDAP Injection
- XXE Injection
- GraphQL Injection
- NoSQL/MongoDB Injection
- Email Header Injection
- Template Injection (SSTI)

#### Authentication & Authorization (12 rules)
- IDOR (Insecure Direct Object Reference)
- Privilege Escalation
- Missing Authorization Checks
- Missing CSRF/Nonce Protection
- Type Juggling/Loose Comparison
- Timing Attacks
- JWT Vulnerabilities
- OAuth Flaws
- Session Fixation

#### File & Path Operations (3 rules)
- Arbitrary File Upload
- Path Traversal
- Zip Slip

#### Modern Web Attacks (8 rules)
- SSRF (Server-Side Request Forgery)
- Open Redirect
- CORS Misconfiguration
- Cache Poisoning
- HTTP Request Smuggling
- DOM Clobbering
- Race Conditions (TOCTOU)
- ReDoS

#### Business Logic & Data (4 rules)
- Price/Quantity Manipulation
- Mass Assignment
- Information Disclosure
- Array Pollution

#### Cryptography (3 rules)
- Weak Algorithms
- Insecure Randomness
- Hardcoded Credentials

## 📦 Installation

### Quick Install (Recommended)
```bash
pip install PluginHunter
```

### From Source
```bash
git clone https://github.com/yourusername/PluginHunter.git
cd PluginHunter
pip install -e .
```

### Requirements
- Python 3.8+
- tree-sitter & tree-sitter-php
- All dependencies auto-installed via pip

## 🎯 Quick Start

### Interactive Menu (Default)
```bash
PluginHunter
```

### Scan WordPress.org Plugin
```bash
PluginHunter scan-plugin woocommerce
```

### Scan Local Plugin
```bash
PluginHunter scan-local /path/to/plugin
```

### Scan GitHub Repository
```bash
PluginHunter scan-github https://github.com/user/plugin
```

### Scan Local ZIP File
```bash
PluginHunter scan-zip plugin.zip
```

## 📊 Usage Examples

### Basic Scan
```bash
# Scan a plugin from WordPress.org
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)
```

### Advanced Options
```bash
# Scan with specific output directory
PluginHunter scan-plugin woocommerce --output ./reports

# Scan local directory with deep analysis
PluginHunter scan-local ./my-plugin --deep-scan

# Scan GitHub repo with specific branch
PluginHunter scan-github https://github.com/user/plugin --branch develop
```

### Server Mode
```bash
# Configure server mode (interactive wizard)
PluginHunter configure-server

# Start server mode
PluginHunter server-mode

# Features:
# - Continuous scanning
# - Cron-based scheduling
# - Discord/Telegram notifications
# - WordPress.org API integration
# - Automated report generation
```

## 🔧 Configuration

### Interactive Menu Options
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. Server Mode Configuration
8. Start Server Mode
9. About PluginHunter
0. Exit

### Server Mode Configuration
- **Scan Mode**: Continuous or Cron-based
- **Notifications**: Discord webhooks, Telegram bots
- **Targets**: Plugin lists, categories, search queries
- **Rate Limiting**: Configurable delays
- **Reports**: Per-plugin organized directories

## 📈 Detection Rules

### Rule Categories
- **XSS**: 2 rules (reflected, stored)
- **SQL Injection**: 2 rules (traditional, second-order)
- **RCE**: 2 rules (dangerous functions, SSTI)
- **File Operations**: 3 rules (upload, traversal, zip slip)
- **Command Injection**: 1 rule
- **Other Injections**: 5 rules (LDAP, XXE, GraphQL, NoSQL, Email)
- **SSRF**: 1 rule
- **Auth/Authz**: 12 rules (IDOR, privilege escalation, etc.)
- **CSRF**: 4 rules (nonce checks, hook protection)
- **Crypto**: 3 rules (weak algorithms, randomness, credentials)
- **Info Disclosure**: 2 rules (sensitive data, deserialization)
- **Business Logic**: 2 rules (price manipulation, mass assignment)
- **Web Attacks**: 6 rules (redirect, CORS, cache, smuggling, etc.)
- **Modern Attacks**: 4 rules (JWT, OAuth, timing, race conditions)

### CWE Coverage
40+ CWE categories including:
- CWE-79 (XSS), CWE-89 (SQLi), CWE-94 (Code Injection)
- CWE-200 (Info Exposure), CWE-208 (Timing)
- CWE-269 (Privilege), CWE-338 (Weak PRNG)
- CWE-352 (CSRF), CWE-367 (Race Condition)
- CWE-434 (File Upload), CWE-601 (Open Redirect)
- And many more...

### OWASP Top 10 2021
✅ Complete coverage of all OWASP Top 10 2021 categories

## 📝 Report Formats

### JSON Report
```json
{
  "scan_id": "abc123",
  "plugin_info": {...},
  "statistics": {...},
  "findings": [
    {
      "rule_id": "wp-reflected-xss",
      "severity": "high",
      "line": 42,
      "file": "plugin.php",
      "message": "...",
      "cwe": ["CWE-79"],
      "confidence": "HIGH"
    }
  ]
}
```

### HTML Report
- Interactive dashboard
- Severity-based filtering
- Code snippets with line numbers
- CWE and OWASP mappings
- Remediation guidance

### CVE-Ready Markdown
- Professional vulnerability reports
- CVSS scoring
- Proof of concept
- Remediation steps
- Ready for CVE submission

## 🏗️ Architecture

### Core Components
- **AST Parser**: PHP code parsing with tree-sitter
- **Taint Engine**: Data flow analysis
- **Pattern Matcher**: Semgrep-style pattern matching
- **WordPress Analyzer**: Hook and REST API analysis
- **Rule Loader**: YAML-based rule management
- **Report Generator**: Multi-format output

### Detection Flow
1. **Load Rules**: 48 YAML rules loaded
2. **Parse Code**: AST generation for PHP files
3. **Pattern Match**: Apply detection patterns
4. **Taint Analysis**: Track data flow
5. **WordPress Analysis**: Check hooks, capabilities, nonces
6. **Generate Reports**: JSON, HTML, CVE formats

## 🔬 Advanced Features

### Pattern Matching
- **Metavariables**: `$VAR`, `$FUNC`, `$KEY`
- **Pattern Lists**: AND logic for multiple conditions
- **Pattern Exclusions**: `pattern-not-inside`
- **Regex Validation**: `metavariable-regex`
- **Sanitizer Detection**: AST tree walking

### Taint Analysis
- Source-sink-sanitizer tracking
- Data flow across scopes
- Variable tracking through assignments
- Context-aware analysis

### WordPress Intelligence
- Hook registration analysis
- REST API endpoint detection
- Capability check validation
- Nonce verification
- WordPress function awareness

## 📚 Documentation

- [Quick Start Guide](QUICK_START.md)
- [Server Mode Guide](SERVER_MODE.md)
- [Complete Rule Documentation](VULNERABILITY_RULES_COMPLETE.md)
- [Release Notes](RELEASE_v1.3.0.md)
- [FAQ](FAQ.md)
- [Contributing Guide](CONTRIBUTING.md)
- [Security Policy](SECURITY.md)

## 🤝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Areas for Contribution
- New detection rules
- Improved pattern matching
- False positive reduction
- Performance optimization
- Documentation improvements

## 🐛 Known Issues

1. **Sanitizer Detection**: Some sanitized code may be flagged (v1.3.1 fix planned)
2. **Duplicate Findings**: Some rules may produce duplicates (v1.3.1 fix planned)
3. **Variable Tracking**: Limited assignment tracking (v1.3.1 enhancement planned)

## 🗺️ Roadmap

### v1.3.1 (Next Release)
- Improved sanitizer detection
- Finding deduplication
- Enhanced variable tracking
- Reduced false positives

### v1.4.0 (Future)
- API security rules
- Microservice vulnerabilities
- Container security
- Supply chain analysis
- Machine learning integration

## 📊 Statistics

- **48 Detection Rules**
- **40+ CWE Categories**
- **15 Rule Categories**
- **8 Severity Levels**
- **3 Confidence Levels**
- **100% OWASP Top 10 Coverage**

## 🏆 Use Cases

- **Security Researchers**: Find 0-days in WordPress plugins
- **Plugin Developers**: Secure your code before release
- **Security Teams**: Automated vulnerability scanning
- **Bug Bounty Hunters**: Discover vulnerabilities faster
- **Penetration Testers**: Comprehensive security assessment

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details

## 👤 Author

**LAKSHMIKANTHAN K (letchupkt)**
- Email: letchupkt.dev@gmail.com
- GitHub: [@letchupkt](https://github.com/letchupkt)

## 🙏 Acknowledgments

- WordPress Security Team
- OWASP Foundation
- Semgrep Community
- Tree-sitter Project

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/yourusername/PluginHunter/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/PluginHunter/discussions)
- **Email**: letchupkt.dev@gmail.com

## ⚠️ Disclaimer

This tool is for security research and testing purposes only. Always obtain proper authorization before scanning systems you don't own. The authors are not responsible for misuse of this tool.

---

**Made with ❤️ for WordPress Security**
