# pikpikcu/airecon architecture

> Architecture diagram of the GitHub repository pikpikcu/airecon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pikpikcu/airecon
- Repository: https://github.com/pikpikcu/airecon

## Overview

AIRecon is an autonomous penetration-testing agent exposed through a Textual TUI and an HTTP service. A user submits a target and prompts; the agent iterates with an OpenAI-compatible model, moving through guided RECON, ANALYSIS, EXPLOIT, and REPORT stages while invoking security tools. Findings can be correlated, verified, reported, and learned from across sessions. README documents major integrations and capabilities; sampled excerpts do not show every route or tool-dispatch connection, so uncertain wiring is omitted.

Main entry points: [`airecon/proxy/agent/executors_dispatch.py`](https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/agent/executors_dispatch.py) (Tool dispatch), [`airecon/proxy/agent/loop.py`](https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/agent/loop.py) (Agent loop), [`airecon/proxy/agent/pipeline.py`](https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/agent/pipeline.py) (Phase pipeline), [`airecon/proxy/agent/loop_cycle_llm.py`](https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/agent/loop_cycle_llm.py) (LLM cycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interfaces"]
  node_tui["Textual TUI<br/>[app.py]"]
  node_server["HTTP service<br/>[server.py]"]
end

subgraph group_agent["Agent workflow"]
  node_agent_loop["Agent loop<br/>[loop.py]"]
  node_llm_cycle["LLM cycle<br/>[loop_cycle_llm.py]"]
  node_pipeline["Phase pipeline<br/>[pipeline.py]"]
  node_tool_dispatch["Tool dispatch"]
  node_recon["RECON<br/>[pipeline.py]"]
  node_analysis["ANALYSIS<br/>[pipeline.py]"]
  node_exploit["EXPLOIT<br/>[pipeline.py]"]
  node_report_stage["REPORT<br/>[pipeline.py]"]
end

subgraph group_security["Security capabilities"]
  node_scope["Scope guard<br/>[scope.py]"]
  node_sandbox["Kali sandbox<br/>[docker.py]"]
  node_browser["Browser automation<br/>[browser.py]"]
  node_fuzzer["Fuzzing<br/>[fuzzer.py]"]
  node_semgrep["Semgrep SAST<br/>[semgrep.py]"]
  node_caido_client["Caido integration<br/>[caido_client.py]"]
end

subgraph group_state["State and reporting"]
  node_correlation["Finding correlation"]
  node_memory[("Persistent memory<br/>[memory.py]")]
  node_session["Session state<br/>[session.py]"]
  node_reporting["Report generation<br/>[reporting.py]"]
end

subgraph group_integrations["External integrations"]
  node_llm["OpenAI-compatible gateway<br/>[llm.py]"]
end

node_user(("Tester"))
node_target(("Authorized target"))
node_docker_service["Docker runtime"]
node_caido_service["Caido proxy"]

node_user -->|"submits target"| node_tui
node_tui -->|"HTTP requests"| node_server
node_server -->|"initializes and serves"| node_agent_loop
node_agent_loop -->|"runs iteration"| node_llm_cycle
node_llm_cycle -->|"requests completion"| node_llm
node_llm -->|"returns response"| node_llm_cycle
node_llm_cycle -->|"dispatches tools"| node_tool_dispatch
node_agent_loop -->|"guides phases"| node_pipeline
node_pipeline -->|"selects phase"| node_recon
node_pipeline -->|"selects phase"| node_analysis
node_pipeline -->|"selects phase"| node_exploit
node_pipeline -->|"selects phase"| node_report_stage
node_tool_dispatch -->|"checks target scope"| node_scope
node_tool_dispatch -->|"runs commands"| node_sandbox
node_tool_dispatch -->|"invokes browser"| node_browser
node_tool_dispatch -->|"invokes fuzzing"| node_fuzzer
node_tool_dispatch -->|"invokes analysis"| node_semgrep
node_tool_dispatch -->|"invokes Caido tools"| node_caido_client
node_sandbox -->|"runs in"| node_docker_service
node_caido_client -.->|"queries proxy"| node_caido_service
node_tool_dispatch -->|"tests in-scope"| node_target
node_agent_loop -->|"updates session"| node_session
node_agent_loop -->|"recalls and persists"| node_memory
node_agent_loop -->|"correlates findings"| node_correlation
node_correlation -->|"provides attack chains"| node_session
node_report_stage -->|"generates report"| node_reporting
node_reporting -->|"uses findings"| node_session
node_server -->|"streams events"| node_tui

click node_tui "https://github.com/pikpikcu/airecon/blob/main/airecon/tui/app.py"
click node_server "https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/server.py"
click node_agent_loop "https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/agent/loop.py"
click node_llm_cycle "https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/agent/loop_cycle_llm.py"
click node_pipeline "https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/agent/pipeline.py"
click node_tool_dispatch "https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/agent/executors_dispatch.py"
click node_recon "https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/agent/pipeline.py"
click node_analysis "https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/agent/pipeline.py"
click node_exploit "https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/agent/pipeline.py"
click node_report_stage "https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/agent/pipeline.py"
click node_scope "https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/scope.py"
click node_sandbox "https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/docker.py"
click node_browser "https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/browser.py"
click node_fuzzer "https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/fuzzer.py"
click node_semgrep "https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/semgrep.py"
click node_caido_client "https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/caido_client.py"
click node_correlation "https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/agent/correlation_engine.py"
click node_memory "https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/memory.py"
click node_session "https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/agent/session.py"
click node_reporting "https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/reporting.py"
click node_llm "https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/llm.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_tui,node_server toneBlue
class node_agent_loop,node_llm_cycle,node_pipeline,node_tool_dispatch,node_recon,node_analysis,node_exploit,node_report_stage toneAmber
class node_scope,node_sandbox,node_browser,node_fuzzer,node_semgrep,node_caido_client toneMint
class node_correlation,node_memory,node_session,node_reporting toneRose
class node_llm,node_user,node_target,node_docker_service,node_caido_service toneIndigo
```

## Components

### User interfaces

- [Textual TUI](https://github.com/pikpikcu/airecon/blob/main/airecon/tui/app.py): `airecon/tui/app.py`
- [HTTP service](https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/server.py): `airecon/proxy/server.py`

### Agent workflow

- [Agent loop](https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/agent/loop.py): `airecon/proxy/agent/loop.py`
- [LLM cycle](https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/agent/loop_cycle_llm.py): `airecon/proxy/agent/loop_cycle_llm.py`
- [Phase pipeline](https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/agent/pipeline.py): `airecon/proxy/agent/pipeline.py`
- [Tool dispatch](https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/agent/executors_dispatch.py): `airecon/proxy/agent/executors_dispatch.py`
- [RECON](https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/agent/pipeline.py): `airecon/proxy/agent/pipeline.py`
- [ANALYSIS](https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/agent/pipeline.py): `airecon/proxy/agent/pipeline.py`
- [EXPLOIT](https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/agent/pipeline.py): `airecon/proxy/agent/pipeline.py`
- [REPORT](https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/agent/pipeline.py): `airecon/proxy/agent/pipeline.py`

### Security capabilities

- [Scope guard](https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/scope.py): `airecon/proxy/scope.py`
- [Kali sandbox](https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/docker.py): `airecon/proxy/docker.py`
- [Browser automation](https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/browser.py): `airecon/proxy/browser.py`
- [Fuzzing](https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/fuzzer.py): `airecon/proxy/fuzzer.py`
- [Semgrep SAST](https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/semgrep.py): `airecon/proxy/semgrep.py`
- [Caido integration](https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/caido_client.py): `airecon/proxy/caido_client.py`

### State and reporting

- [Finding correlation](https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/agent/correlation_engine.py): `airecon/proxy/agent/correlation_engine.py`
- [Persistent memory](https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/memory.py): `airecon/proxy/memory.py`
- [Session state](https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/agent/session.py): `airecon/proxy/agent/session.py`
- [Report generation](https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/reporting.py): `airecon/proxy/reporting.py`

### External integrations

- [OpenAI-compatible gateway](https://github.com/pikpikcu/airecon/blob/main/airecon/proxy/llm.py): `airecon/proxy/llm.py`

### Other components

- **Tester**
- **Authorized target**
- **Docker runtime**
- **Caido proxy**

## Connections

- Tester → Textual TUI: submits target
- Textual TUI → HTTP service: HTTP requests
- HTTP service → Agent loop: initializes and serves
- Agent loop → LLM cycle: runs iteration
- LLM cycle → OpenAI-compatible gateway: requests completion
- OpenAI-compatible gateway → LLM cycle: returns response
- LLM cycle → Tool dispatch: dispatches tools
- Agent loop → Phase pipeline: guides phases
- Phase pipeline → RECON: selects phase
- Phase pipeline → ANALYSIS: selects phase
- Phase pipeline → EXPLOIT: selects phase
- Phase pipeline → REPORT: selects phase
- Tool dispatch → Scope guard: checks target scope
- Tool dispatch → Kali sandbox: runs commands
- Tool dispatch → Browser automation: invokes browser
- Tool dispatch → Fuzzing: invokes fuzzing
- Tool dispatch → Semgrep SAST: invokes analysis
- Tool dispatch → Caido integration: invokes Caido tools
- Kali sandbox → Docker runtime: runs in
- Caido integration → Caido proxy: queries proxy
- Tool dispatch → Authorized target: tests in-scope
- Agent loop → Session state: updates session
- Agent loop → Persistent memory: recalls and persists
- Agent loop → Finding correlation: correlates findings
- Finding correlation → Session state: provides attack chains
- REPORT → Report generation: generates report
- Report generation → Session state: uses findings
- HTTP service → Textual TUI: streams events