How vhkarpuk/offensive-recon-agent works
Offensive Recon Agent turns an authorized natural-language goal into an nmap scan, structures the agent’s report, and checks its claims against the captured scan data with a deterministic gate. The main workflow is documented in the README and implemented in agent.py, tools/nmap_tool.py, and validators/scan_validator.py. A separate banner-injection lab demonstrates how target-controlled service banners can steer claims and how the gate rejects unsupported findings. The source index supports the lab’s module relationships; unsampled files are not assumed to add further behavior.
Main entry points: agent.py Recon agent · nmap_tool.py Nmap scan tool · recon_scan.py Banner-aware scanner · banner_injection_poc.py Injection simulator
Components 15
Recon workflow
- Recon agent
agent.py - Agent report
agent.py - Finding structurer
agent.py - Claimed findings
agent.py
Scan execution
- Nmap scan tool
tools/nmap_tool.py - Structured scan data
tools/nmap_tool.py
Validation gate
- Finding validator
validators/scan_validator.py - Validation report
validators/scan_validator.py
Banner injection lab
- Poisoned HTTP target
redteam/malicious_service.py - Banner-aware scanner
redteam/recon_scan.py - Banner scan data
redteam/recon_scan.py - Injection simulator
redteam/banner_injection_poc.py
Other components
- Recon requester
- Chat model
- nmap process
Connections 17
- Recon requester → Recon agent: sets goal
README.md - Recon agent → Chat model: requests interpretation
agent.py - Recon agent → Nmap scan tool: calls scan
agent.py - Nmap scan tool → nmap process: runs subprocess
tools/nmap_tool.py - Nmap scan tool → Structured scan data: parses XML
tools/nmap_tool.py - Chat model → Agent report: returns report
agent.py - Recon agent → Finding structurer: structures report
agent.py - Finding structurer → Claimed findings: extracts claims
agent.py - Recon agent → Finding validator: validates claims
agent.py - Recon agent → Structured scan data: reuses tool output
agent.py - Finding validator → Validation report: classifies findings
validators/scan_validator.py - Poisoned HTTP target → Banner-aware scanner: serves banner
redteam/banner_injection_poc.py - Banner-aware scanner → Nmap scan tool: reuses runner
redteam/recon_scan.py - Banner-aware scanner → Banner scan data: parses banner
redteam/recon_scan.py - Injection simulator → Poisoned HTTP target: starts target
redteam/banner_injection_poc.py - Injection simulator → Banner-aware scanner: scans target
redteam/banner_injection_poc.py - Injection simulator → Finding validator: checks claims
redteam/banner_injection_poc.py