# vhkarpuk/offensive-recon-agent architecture

> Architecture diagram of the GitHub repository vhkarpuk/offensive-recon-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vhkarpuk/offensive-recon-agent
- Repository: https://github.com/vhkarpuk/offensive-recon-agent

## Overview

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`](https://github.com/vhkarpuk/offensive-recon-agent/blob/main/agent.py) (Recon agent), [`tools/nmap_tool.py`](https://github.com/vhkarpuk/offensive-recon-agent/blob/main/tools/nmap_tool.py) (Nmap scan tool), [`redteam/recon_scan.py`](https://github.com/vhkarpuk/offensive-recon-agent/blob/main/redteam/recon_scan.py) (Banner-aware scanner), [`redteam/banner_injection_poc.py`](https://github.com/vhkarpuk/offensive-recon-agent/blob/main/redteam/banner_injection_poc.py) (Injection simulator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Recon workflow"]
  node_agent["Recon agent<br/>[agent.py]"]
  node_answer["Agent report<br/>[agent.py]"]
  node_structurer["Finding structurer<br/>[agent.py]"]
  node_claims["Claimed findings<br/>[agent.py]"]
end

subgraph group_scanning["Scan execution"]
  node_scan_tool["Nmap scan tool<br/>[nmap_tool.py]"]
  node_scan_data["Structured scan data<br/>[nmap_tool.py]"]
end

subgraph group_validation["Validation gate"]
  node_gate["Finding validator<br/>[scan_validator.py]"]
  node_verdict["Validation report<br/>[scan_validator.py]"]
end

subgraph group_redteam["Banner injection lab"]
  node_malicious_target["Poisoned HTTP target"]
  node_lab_scan["Banner-aware scanner<br/>[recon_scan.py]"]
  node_banner_data["Banner scan data<br/>[recon_scan.py]"]
  node_lab_agent["Injection simulator"]
end

node_user(("Recon requester"))
node_llm["Chat model"]
node_nmap["nmap process"]

node_user -->|"sets goal"| node_agent
node_agent -->|"requests interpretation"| node_llm
node_agent -->|"calls scan"| node_scan_tool
node_scan_tool -->|"runs subprocess"| node_nmap
node_scan_tool -->|"parses XML"| node_scan_data
node_llm -->|"returns report"| node_answer
node_agent -->|"structures report"| node_structurer
node_structurer -->|"extracts claims"| node_claims
node_agent -->|"validates claims"| node_gate
node_agent -->|"reuses tool output"| node_scan_data
node_gate -->|"classifies findings"| node_verdict
node_malicious_target -->|"serves banner"| node_lab_scan
node_lab_scan -->|"reuses runner"| node_scan_tool
node_lab_scan -->|"parses banner"| node_banner_data
node_lab_agent -->|"starts target"| node_malicious_target
node_lab_agent -->|"scans target"| node_lab_scan
node_lab_agent -->|"checks claims"| node_gate

click node_agent "https://github.com/vhkarpuk/offensive-recon-agent/blob/main/agent.py"
click node_scan_tool "https://github.com/vhkarpuk/offensive-recon-agent/blob/main/tools/nmap_tool.py"
click node_scan_data "https://github.com/vhkarpuk/offensive-recon-agent/blob/main/tools/nmap_tool.py"
click node_answer "https://github.com/vhkarpuk/offensive-recon-agent/blob/main/agent.py"
click node_structurer "https://github.com/vhkarpuk/offensive-recon-agent/blob/main/agent.py"
click node_claims "https://github.com/vhkarpuk/offensive-recon-agent/blob/main/agent.py"
click node_gate "https://github.com/vhkarpuk/offensive-recon-agent/blob/main/validators/scan_validator.py"
click node_verdict "https://github.com/vhkarpuk/offensive-recon-agent/blob/main/validators/scan_validator.py"
click node_malicious_target "https://github.com/vhkarpuk/offensive-recon-agent/blob/main/redteam/malicious_service.py"
click node_lab_scan "https://github.com/vhkarpuk/offensive-recon-agent/blob/main/redteam/recon_scan.py"
click node_banner_data "https://github.com/vhkarpuk/offensive-recon-agent/blob/main/redteam/recon_scan.py"
click node_lab_agent "https://github.com/vhkarpuk/offensive-recon-agent/blob/main/redteam/banner_injection_poc.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent,node_answer,node_structurer,node_claims toneBlue
class node_scan_tool,node_scan_data toneAmber
class node_gate,node_verdict,node_user toneMint
class node_malicious_target,node_lab_scan,node_banner_data,node_lab_agent toneRose
class node_llm,node_nmap toneIndigo
```

## Components

### Recon workflow

- [Recon agent](https://github.com/vhkarpuk/offensive-recon-agent/blob/main/agent.py): `agent.py`
- [Agent report](https://github.com/vhkarpuk/offensive-recon-agent/blob/main/agent.py): `agent.py`
- [Finding structurer](https://github.com/vhkarpuk/offensive-recon-agent/blob/main/agent.py): `agent.py`
- [Claimed findings](https://github.com/vhkarpuk/offensive-recon-agent/blob/main/agent.py): `agent.py`

### Scan execution

- [Nmap scan tool](https://github.com/vhkarpuk/offensive-recon-agent/blob/main/tools/nmap_tool.py): `tools/nmap_tool.py`
- [Structured scan data](https://github.com/vhkarpuk/offensive-recon-agent/blob/main/tools/nmap_tool.py): `tools/nmap_tool.py`

### Validation gate

- [Finding validator](https://github.com/vhkarpuk/offensive-recon-agent/blob/main/validators/scan_validator.py): `validators/scan_validator.py`
- [Validation report](https://github.com/vhkarpuk/offensive-recon-agent/blob/main/validators/scan_validator.py): `validators/scan_validator.py`

### Banner injection lab

- [Poisoned HTTP target](https://github.com/vhkarpuk/offensive-recon-agent/blob/main/redteam/malicious_service.py): `redteam/malicious_service.py`
- [Banner-aware scanner](https://github.com/vhkarpuk/offensive-recon-agent/blob/main/redteam/recon_scan.py): `redteam/recon_scan.py`
- [Banner scan data](https://github.com/vhkarpuk/offensive-recon-agent/blob/main/redteam/recon_scan.py): `redteam/recon_scan.py`
- [Injection simulator](https://github.com/vhkarpuk/offensive-recon-agent/blob/main/redteam/banner_injection_poc.py): `redteam/banner_injection_poc.py`

### Other components

- **Recon requester**
- **Chat model**
- **nmap process**

## Connections

- Recon requester → Recon agent: sets goal (evidence: `README.md`)
- Recon agent → Chat model: requests interpretation (evidence: `agent.py`)
- Recon agent → Nmap scan tool: calls scan (evidence: `agent.py`)
- Nmap scan tool → nmap process: runs subprocess (evidence: `tools/nmap_tool.py`)
- Nmap scan tool → Structured scan data: parses XML (evidence: `tools/nmap_tool.py`)
- Chat model → Agent report: returns report (evidence: `agent.py`)
- Recon agent → Finding structurer: structures report (evidence: `agent.py`)
- Finding structurer → Claimed findings: extracts claims (evidence: `agent.py`)
- Recon agent → Finding validator: validates claims (evidence: `agent.py`)
- Recon agent → Structured scan data: reuses tool output (evidence: `agent.py`)
- Finding validator → Validation report: classifies findings (evidence: `validators/scan_validator.py`)
- Poisoned HTTP target → Banner-aware scanner: serves banner (evidence: `redteam/banner_injection_poc.py`)
- Banner-aware scanner → Nmap scan tool: reuses runner (evidence: `redteam/recon_scan.py`)
- Banner-aware scanner → Banner scan data: parses banner (evidence: `redteam/recon_scan.py`)
- Injection simulator → Poisoned HTTP target: starts target (evidence: `redteam/banner_injection_poc.py`)
- Injection simulator → Banner-aware scanner: scans target (evidence: `redteam/banner_injection_poc.py`)
- Injection simulator → Finding validator: checks claims (evidence: `redteam/banner_injection_poc.py`)
