1- # PentestAgent — Phase 1: Reconnaissance & Scanning
1+ # PentestAgent - Phase 1: Reconnaissance & Scanning
22
3- Autonomous penetration testing agent — Phase 1 module.
3+ Autonomous penetration testing agent - Phase 1 module.
44
55```
66⚠️ LEGAL WARNING
@@ -24,7 +24,7 @@ Authorized environments: HackTheBox, TryHackMe, personal lab VMs.
2424- Security headers analysis
2525
2626### Active Reconnaissance
27- - ** Nmap — 3 passes:**
27+ - ** Nmap - 3 passes:**
2828 1 . Host discovery (` -sn ` )
2929 2 . Top-1000 port scan (` -sT -T4 ` )
3030 3 . Service + script detection (` -sV -sC -O ` )
@@ -40,150 +40,3 @@ Authorized environments: HackTheBox, TryHackMe, personal lab VMs.
4040- Executive summary
4141- Critical findings with CVE references
4242- Attack vectors with probability and recommended tools
43- - Next steps for exploitation
44-
45- ### Reporting
46- - PDF report (WeasyPrint)
47- - JSON structured export
48- - Real-time terminal output (Rich)
49- - Session log (` output/<target>/session.log ` )
50-
51- ---
52-
53- ## Installation
54-
55- ** Prerequisites:**
56- ``` bash
57- sudo apt install nmap smbclient
58- ```
59-
60- ** Python dependencies:**
61- ``` bash
62- python3 -m venv venv
63- source venv/bin/activate
64- pip install -r requirements.txt
65- ```
66-
67- ** API keys (optional but recommended):**
68- ``` bash
69- cp .env.example .env
70- # Edit .env and add your GROQ_API_KEY and SHODAN_API_KEY
71- ```
72-
73- ---
74-
75- ## Usage
76-
77- ``` bash
78- # Scan a single IP
79- python main.py --target 192.168.1.10
80-
81- # Scan a CIDR range
82- python main.py --target 192.168.1.0/24
83-
84- # Scan a domain
85- python main.py --target example.com
86-
87- # Passive recon only (no direct contact with target)
88- python main.py --target 192.168.1.10 --passive-only
89-
90- # Custom output directory
91- python main.py --target 192.168.1.10 --output /tmp/report_client
92-
93- # Verbose output
94- python main.py --target 192.168.1.10 --verbose
95-
96- # Adjust delay between requests
97- python main.py --target 192.168.1.10 --delay 2.0
98- ```
99-
100- ** Output structure:**
101- ```
102- output/<target>_<timestamp>/
103- ├── report.pdf # Full PDF report
104- ├── report.json # Structured JSON export
105- └── session.log # Detailed scan log
106- ```
107-
108- ---
109-
110- ## Project Structure
111-
112- ```
113- pentest-agent/
114- ├── main.py # CLI entry point
115- ├── core/
116- │ ├── engine.py # Main scan orchestrator
117- │ ├── target.py # Target class (IP/CIDR/domain)
118- │ └── session.py # Session state & logging
119- ├── modules/
120- │ ├── recon/
121- │ │ ├── passive.py # WHOIS, DNS, Shodan, HTTP tech
122- │ │ └── active.py # High-level active recon orchestrator
123- │ ├── scanner/
124- │ │ ├── port_scanner.py # Nmap wrapper (3-pass)
125- │ │ ├── web_scanner.py # HTTP fingerprinting + dir brute
126- │ │ └── service_scanner.py # SMB, LDAP, banner grabbing
127- │ └── ai/
128- │ └── analyzer.py # Groq AI analysis
129- ├── reporting/
130- │ ├── generator.py # Aggregates findings
131- │ ├── pdf_report.py # WeasyPrint PDF generation
132- │ └── json_export.py # JSON export
133- ├── templates/
134- │ └── report.html # Jinja2 PDF template
135- ├── wordlists/
136- │ ├── common.txt # Web dirs/files (~300 entries)
137- │ └── subdomains.txt # Subdomains (~200 entries)
138- └── tests/
139- ├── test_target.py
140- ├── test_passive_recon.py
141- └── test_port_scanner.py
142- ```
143-
144- ---
145-
146- ## Roadmap
147-
148- | Phase | Module | Status |
149- | -------| --------| --------|
150- | 1 | Reconnaissance & Scanning | ✅ Done |
151- | 2 | Vulnerability Analysis | 🔜 Planned |
152- | 3 | Exploitation | 🔜 Planned |
153- | 4 | Post-Exploitation | 🔜 Planned |
154- | 5 | Full Orchestration | 🔜 Planned |
155-
156- ---
157-
158- ## Branch Strategy
159-
160- ```
161- main ← stable releases (tagged)
162- develop ← integration
163- feature/phase-1-recon ← Phase 1 (this branch)
164- feature/phase-2-* ← next phases
165- ```
166-
167- ---
168-
169- ## Running Tests
170-
171- ``` bash
172- pytest tests/ -v
173- ```
174-
175- ---
176-
177- ## Dependencies
178-
179- - ` python-nmap ` — Nmap Python wrapper
180- - ` dnspython ` — DNS queries
181- - ` shodan ` — Shodan API
182- - ` impacket ` — SMB/LDAP enumeration
183- - ` groq ` — Groq AI API (llama-3.1-70b)
184- - ` python-whois ` — WHOIS lookups
185- - ` requests ` / ` httpx ` — HTTP
186- - ` rich ` — Terminal UI
187- - ` weasyprint ` — PDF generation
188- - ` jinja2 ` — HTML templates
189- - ` python-dotenv ` — Environment variables
0 commit comments