From 00c45c0bdbf2ec387699991674ba0920ac59f6ba Mon Sep 17 00:00:00 2001 From: cc1a2b Date: Mon, 4 May 2026 22:10:55 +0300 Subject: [PATCH] docs(readme): apply cc1a2b README house theme Restructure README around the canonical house style: centered badge block, tagline, About, ToC, grouped Features in
, Install, Quick Start, Examples, Command Reference, Advanced Usage, Contributing, License, Support, centered footer. Co-Authored-By: cc1a2b --- README.md | 445 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 257 insertions(+), 188 deletions(-) diff --git a/README.md b/README.md index 0df91c6..e1a3b91 100644 --- a/README.md +++ b/README.md @@ -1,269 +1,338 @@ -# PenHunter 🔍 +# PenHunter -[![Go Version](https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go)](https://golang.org/) -[![License](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT) -[![Version](https://img.shields.io/badge/Version-0.1.0-blue.svg)](https://github.com/cc1a2b/penhunter/releases) +
-**PenHunter** is a powerful, modular web vulnerability scanner written in Go. It provides comprehensive testing for common web vulnerabilities including XSS, SQL Injection, LFI, SSRF, RCE, Open Redirect, and CSRF. +[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) +[![Go Version](https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go)](https://golang.org) +[![Release](https://img.shields.io/github/release/cc1a2b/PenHunter.svg)](https://github.com/cc1a2b/PenHunter/releases) +[![GitHub stars](https://img.shields.io/github/stars/cc1a2b/PenHunter)](https://github.com/cc1a2b/PenHunter/stargazers) +[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey)](https://github.com/cc1a2b/PenHunter/releases) -## ✨ Features +**🔍 Modular Web Vulnerability Scanner** + +*Comprehensive testing for XSS, SQLi, LFI, SSRF, RCE, Open Redirect, and CSRF — built for penetration testers, bug bounty hunters, and security researchers.* + +
+ +## 📖 About + +**PenHunter** is a powerful, modular web vulnerability scanner written in Go. It provides comprehensive testing for common web vulnerabilities including XSS, SQL Injection, LFI, SSRF, RCE, Open Redirect, and CSRF — with concurrent scanning, advanced detection methods, WAF evasion, and integrations with industry tools like dalfox, sqlmap, and nuclei. + +
+PenHunter Demo Screenshot + +*PenHunter — modular vulnerability scanner with interactive and CLI modes.* +
+ +--- -- 🔍 **Multiple Vulnerability Scanners**: XSS, SQLi, LFI, SSRF, RCE, Open Redirect, CSRF -- 🚀 **High Performance**: Concurrent scanning with configurable thread pools -- 🎯 **Advanced Detection**: Boolean-based, time-based, error-based detection methods -- 🛡️ **WAF Evasion**: Payload mutation, header rotation, TLS fingerprint randomization -- 🔧 **External Tool Integration**: Supports dalfox, sqlmap, nuclei, and more -- 📊 **Multiple Output Formats**: JSON, HTML, TXT -- 🎨 **Interactive CLI**: Menu-driven interface matching the original shell script -- 🔄 **Auto-Update**: Built-in update mechanism via GitHub releases -- 📁 **Organized Results**: Automatic directory structure for scan results +## 📑 Table of Contents -## 📋 Requirements +- [About](#-about) +- [Features](#-features) +- [Installation](#-installation) +- [Quick Start](#-quick-start) +- [Usage Examples](#-usage-examples) +- [Command Reference](#-command-reference) +- [Advanced Usage](#-advanced-usage) +- [Contributing](#-contributing) +- [License](#-license) +- [Support](#-support) -- Go 1.21 or higher -- External tools (optional but recommended): - - `subfinder`, `assetfinder` - Subdomain enumeration - - `httpx` - HTTP probing - - `urlfinder`, `katana`, `gospider` - URL discovery - - `gau`, `gauplus`, `waybackurls` - Wayback machine URLs - - `cariddi`, `getJS` - Endpoint discovery - - `dalfox`, `sqlmap`, `nuclei` - Vulnerability scanning +--- + +## ✨ Features -## 🚀 Installation +### 🎯 Core Capabilities +- **🔍 Multiple Vulnerability Scanners**: XSS, SQLi, LFI, SSRF, RCE, Open Redirect, CSRF +- **🚀 High Performance**: Concurrent scanning with configurable thread pools +- **🎯 Advanced Detection**: Boolean-based, time-based, error-based detection methods +- **🛡️ WAF Evasion**: Payload mutation, header rotation, TLS fingerprint randomization +- **🔧 External Tool Integration**: dalfox, sqlmap, nuclei, and more +- **📊 Multiple Output Formats**: JSON, HTML, TXT +- **🎨 Interactive CLI**: Menu-driven interface for guided scans +- **🔄 Auto-Update**: Built-in update mechanism via GitHub releases +- **📁 Organized Results**: Automatic directory structure for scan results + +### 🧠 Intelligent Detection Engine +> **Differential analysis, boolean/time/error oracles, and payload mutation built in.** + +- **🎯 Differential Response Analysis**: Detects subtle behavior changes that confirm vulnerabilities +- **🏢 Multi-Method Coverage**: Boolean-based, time-based, and error-based detection paths per vuln class +- **🧠 Payload Mutation**: Automatic encoding, casing, and obfuscation variants for WAF bypass +- **📊 Confidence Scoring**: Per-finding confidence to filter true positives from noise + +### 🌐 Discovery Pipeline +
+Subdomain → URL → endpoint → vulnerability + +PenHunter integrates the best-in-class recon stack: + +**Subdomain enumeration:** +- **🔧 subfinder, assetfinder** — passive discovery +- **🍪 amass** (optional) — active + passive + +**HTTP probing & URL discovery:** +- **🎭 httpx** — live host probing +- **🌐 urlfinder, katana, gospider** — crawler-based URL collection +- **🧭 gau, gauplus, waybackurls** — wayback machine harvesting + +**Endpoint extraction:** +- **🔍 cariddi, getJS** — JS endpoint mining +- **📋 PenHunter native parsing** — built-in JS extractor + +**Vulnerability scanning:** +- **🛡️ dalfox, sqlmap, nuclei** — best-in-class engines, orchestrated through PenHunter + +
+ +### 🔐 Vulnerability Classes +
+Seven vulnerability classes, comprehensive coverage + +| Class | Detection Methods | Default Engine | +|---|---|---| +| **🔑 XSS** | Reflected, stored, DOM | Native + dalfox | +| **🎫 SQLi** | Boolean, time, error, union | Native + sqlmap | +| **🔥 LFI** | Path traversal, wrapper, log poisoning | Native | +| **📋 SSRF** | Internal, cloud metadata, gopher, file | Native + OOB | +| **🛡️ RCE** | Command injection, template injection | Native + nuclei | +| **🔗 Open Redirect** | Header, parameter, JS-based | Native | +| **📊 CSRF** | Missing token, weak token, predictable | Native | + +
+ +### 🌐 HTTP & Networking +
+Production-grade HTTP layer for scaling and stealth + +- **🔧 Custom Headers** (`-H`): Repeatable headers for authenticated scans +- **🍪 Cookie Support** (`-c`): Session cookies for protected resources +- **🎭 User-Agent Rotation**: Built-in UA rotation for evasion +- **⏱️ Rate Limiting**: Configurable request pacing +- **⏰ Timeouts**: Per-request timeout control +- **🔄 Retry Logic**: Exponential backoff on failures +- **🔗 Proxy Support**: Burp Suite and other intercepting proxies +- **🔒 TLS Bypass**: Optional certificate verification skip for testing + +
+ +### 📤 Output & Reporting +
+Three formats, organized result hierarchy + +- **🖥️ Console**: Color-coded terminal output with severity highlighting +- **📄 TXT**: Plain text logs for scripting +- **📊 JSON**: Structured output for automation pipelines +- **📈 HTML**: Self-contained reports for stakeholder review + +
+ +--- -### Quick Install (Go) +## 📦 Installation +### Go Install (Recommended) ```bash go install -v github.com/cc1a2b/PenHunter/cmd/penhunter@latest +penhunter --help ``` -The binary lands in `$(go env GOPATH)/bin/penhunter` — make sure that directory is on your `PATH`. - -> Note: `go install` only ships the binary. To get the bundled `config/` (payloads, encoders, user callbacks), clone the repo or use `make install`. - -### From Source +> Note: `go install` ships only the binary. To get the bundled `config/` (payloads, encoders, user callbacks), clone the repo or use `make install`. +### Build from Source ```bash -# Clone the repository git clone https://github.com/cc1a2b/PenHunter.git cd PenHunter - -# Build make build - -# Install to user home directory -make install -# This installs to $HOME/penhunter/ +make install # installs to $HOME/penhunter/ ``` -### Installation Paths - -- **Linux/macOS**: `$HOME/penhunter/` -- **Windows**: `%USERPROFILE%\penhunter\` - -After installation, add to your PATH: +### Add to PATH ```bash +# Linux/macOS export PATH="$HOME/penhunter/bin:$PATH" -``` -Or create a symlink: -```bash +# Or symlink sudo ln -sf $HOME/penhunter/bin/penhunter /usr/local/bin/penhunter ``` ### From Releases +Download the latest release from [GitHub Releases](https://github.com/cc1a2b/PenHunter/releases) and extract to your `$HOME/penhunter/` directory. -Download the latest release from [GitHub Releases](https://github.com/cc1a2b/penhunter/releases) and extract to your `$HOME/penhunter/` directory. +### System Requirements +- **Go 1.21+** (for building from source) +- **Linux, macOS, or Windows** (64-bit) +- **External recon tools** (optional but recommended): subfinder, assetfinder, httpx, katana, gau, dalfox, sqlmap, nuclei -## 📖 Usage +--- -### Interactive Mode +## 🚀 Quick Start +### Interactive mode ```bash penhunter ``` +Launches the menu where you choose between single-domain or subdomain scanning, vulnerability classes, and engines. -This launches the interactive menu system where you can: -1. Choose between single domain or subdomain scanning -2. Select vulnerability types to test -3. Choose between native scanner or external tools - -### Command Line Mode - +### Single URL scan ```bash -# Test single URL penhunter -u https://example.com -v xss,sqli +``` -# Test URL list +### Multi-URL scan with JSON output +```bash penhunter -l urls.txt -v xss -t 50 --json results.json +``` -# Update penhunter +### Update PenHunter +```bash penhunter --update +``` -# Check for updates -penhunter --check-update +--- -# Check installed tools -penhunter --check-tools -``` +## 💡 Usage Examples -### Options +```bash +# Test single URL for XSS + SQLi +penhunter -u https://example.com -v xss,sqli -``` --h, --help Show help message --v, --version Show version information ---update Update penhunter to the latest version ---check-update Check if a new version is available ---check-tools Check if all required tools are installed --u, --url Single URL to test --l, --list File containing list of URLs --v, --vulns Comma-separated vulnerabilities (xss,sqli,lfi,ssrf,rce,redirect,csrf) --e, --encoders Comma-separated encoders (url,base64,double,unicode) --t, --threads Number of concurrent threads (default: 25) ---silent Silent mode (minimal output) ---json Output results to JSON file ---html Output results to HTML file ---txt Output results to text file -``` +# Multi-URL scan with custom thread count +penhunter -l urls.txt -v xss -t 50 --json results.json -## 📁 Directory Structure +# Full vulnerability sweep +penhunter -u https://target.com -v xss,sqli,lfi,ssrf,rce,redirect,csrf -t 30 -``` -penhunter/ -├── bin/ # Compiled binary -├── config/ # Configuration files -│ ├── user_config.yaml # YOUR callback URLs (configure this!) -│ ├── payloads.yaml -│ ├── encoders.yaml -│ └── defaults.yaml -├── core/ # Core engine -│ ├── engine.go -│ ├── http.go -│ ├── logger.go -│ ├── runner.go -│ ├── tools.go -│ └── updater.go -├── scanners/ # Vulnerability scanners -│ ├── xss.go -│ ├── sqli.go -│ ├── lfi.go -│ ├── ssrf.go -│ ├── rce.go -│ ├── redirect.go -│ └── csrf.go -├── encoders/ # Payload encoders -│ ├── url.go -│ ├── base64.go -│ ├── double.go -│ └── unicode.go -├── cli/ # CLI interface -│ ├── flags.go -│ ├── banner.go -│ └── help.go -├── output/ # Output formatters -│ ├── json.go -│ ├── txt.go -│ └── html.go -├── utils/ # Utilities -│ ├── colors.go -│ ├── regex.go -│ └── random.go -├── types/ # Type definitions -│ └── finding.go -├── cmd/penhunter/main.go -├── go.mod -├── Makefile -└── README.md +# Stealth scan through Burp Suite +penhunter -u https://target.com -v xss --proxy http://127.0.0.1:8080 -R 1000 + +# Authenticated scan with cookies and headers +penhunter -u https://target.com -v xss,sqli \ + -c "session=abc123" \ + -H "Authorization: Bearer eyJ..." + +# Check installed external tools +penhunter --check-tools + +# Check for updates +penhunter --check-update ``` -## 🔧 Configuration +--- -### User Configuration (IMPORTANT) +## 📋 Command Reference -Before using blind XSS or callback-based testing, configure your callback URLs in: ``` -$HOME/penhunter/config/user_config.yaml +Usage: + penhunter [flags] + +Modes: + (no args) Launch interactive menu + -u, --url URL Test a single URL + -l, --list FILE Test URLs from a file + -v, --vulns LIST Comma-separated vulns + (xss, sqli, lfi, ssrf, rce, redirect, csrf) + +HTTP & Performance: + -t, --threads INT Concurrent threads (default: 10) + -H, --header "K: V" Custom HTTP headers (repeatable) + -c, --cookies STR Session cookies + -p, --proxy URL HTTP/HTTPS/SOCKS proxy + -k, --skip-tls Skip TLS verification + -R, --rate-limit MS Request delay (milliseconds) + +Output: + -o, --output FILE Output file + --json FILE Structured JSON output + --html FILE HTML report + +Maintenance: + --update Update PenHunter to latest + --check-update Check if a new version is available + --check-tools Verify external tools are installed + -h, --help Show help + -V, --version Show version ``` -Example configuration: -```yaml -# XSS Callback URL - Used for blind XSS testing -xss_callback: "https://xss.report/c/YOUR_ID" - -# Redirect Test Domain - Used for open redirect testing -redirect_domain: "evil.com" +--- -# SSRF Callback URL - Used for blind SSRF testing -ssrf_callback: "https://YOUR_BURP_COLLABORATOR.burpcollaborator.net" +## 🔧 Advanced Usage -# Out-of-Band (OOB) Server -oob_server: "https://YOUR_OOB_SERVER" +### Bug Bounty Workflow +```bash +# 1. Subdomain enumeration → URL collection → vuln scan +subfinder -d target.com | httpx | tee live.txt +gau < live.txt | tee urls.txt +penhunter -l urls.txt -v xss,sqli,redirect -t 30 --json findings.json ``` -You can use services like: -- [xss.report](https://xss.report) -- [Burp Collaborator](https://portswigger.net/burp/documentation/collaborator) -- [Interactsh](https://github.com/projectdiscovery/interactsh) - -### Results Directory +### CI / Continuous Scanning +```bash +penhunter -l production-urls.txt -v xss,sqli \ + --json "scan-$(date +%F).json" \ + -R 2000 \ + --proxy http://internal-proxy:8080 +``` -Results are saved to `$HOME/penhunter/`: -- `penhunter/one/YYYY-MM/domain/` - Single domain scans -- `penhunter/subdomains/YYYY-MM/domain/` - Subdomain scans +### WAF Evasion Scan +```bash +penhunter -u https://target.com -v xss \ + -H "X-Forwarded-For: 1.1.1.1" \ + -H "X-Real-IP: 1.1.1.1" \ + -R 1500 +``` -Each scan creates: -- `domain_urls_targets.txt` - Collected URLs -- `all_subdomains.txt` - All discovered subdomains -- `subs.txt` - Live subdomains -- Scanner-specific output files +--- -## Example +## 🤝 Contributing -![lfi](https://github.com/user-attachments/assets/03b219d6-2676-439f-ac02-9c9f43e6a767) -![xss](https://github.com/user-attachments/assets/2648f0c8-3c45-4024-b255-c3ea92547f8a) +Contributions welcome from the security community. -## 🛠️ Development +- **🐛 Report bugs** via [GitHub Issues](https://github.com/cc1a2b/PenHunter/issues) +- **💡 Suggest features** or new vulnerability classes +- **📝 Improve documentation** +- **🔧 Submit pull requests** with new payloads, detectors, or integrations +### Development Setup ```bash -# Build +git clone https://github.com/cc1a2b/PenHunter.git +cd PenHunter +go mod tidy make build - -# Install -make install - -# Clean -make clean ``` -## 🤝 Contributing +--- -Contributions are welcome! Please feel free to submit a Pull Request. +## 📄 License -1. Fork the repository -2. Create your feature branch (`git checkout -b feature/AmazingFeature`) -3. Commit your changes (`git commit -m 'Add some AmazingFeature'`) -4. Push to the branch (`git push origin feature/AmazingFeature`) -5. Open a Pull Request +PenHunter is released under the **MIT License**. See [LICENSE](https://github.com/cc1a2b/PenHunter/blob/main/LICENSE) for details. -## 📝 License +``` +Copyright (c) 2024-2026 Hussain Alsharman +Licensed under MIT License — free for commercial and personal use +``` -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. +--- -## ⚠️ Disclaimer +## ☕ Support -This tool is for authorized security testing only. Users are responsible for ensuring they have proper authorization before testing any systems. The authors are not responsible for any misuse or damage caused by this tool. +If PenHunter helps with your security research: -## 🙏 Acknowledgments +
-- Created by [cc1a2b](https://github.com/cc1a2b) -- Inspired by the original `penhunter.sh` script -- Built with Go and love ❤️ +[![Buy Me A Coffee](https://cdn.buymeacoffee.com/buttons/default-orange.png)](https://www.buymeacoffee.com/cc1a2b) -## 📞 Support +**⭐ Star this repo** • **🐦 Follow [@cc1a2b](https://twitter.com/cc1a2b)** • **📢 Share with the security community** -- **Issues**: [GitHub Issues](https://github.com/cc1a2b/penhunter/issues) -- **Discussions**: [GitHub Discussions](https://github.com/cc1a2b/penhunter/discussions) +
--- -**Made with ❤️ by cc1a2b** +
+ +**🔍 PenHunter — Modular Web Vulnerability Scanner** + +*Built with ❤️ by [cc1a2b](https://github.com/cc1a2b) for the security community* + +