# samugit83/redamon architecture

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

- Interactive diagram: https://gitdiagram.com/samugit83/redamon
- Repository: https://github.com/samugit83/redamon

## Overview

RedAmon is a self-hosted AI penetration-testing platform. Its documented main workflow moves from authorized reconnaissance through graph-backed attack-surface analysis and human-gated exploitation, then AI triage, automated code remediation, and a GitHub pull request. The graph also preserves distinct AI-surface scanning, supply-chain scanning, traffic capture, and knowledge-base capabilities. The README supports the high-level workflow; source-index references and excerpts support only the cited internal links, so other connections are omitted rather than inferred.

Main entry points: [`recon/main.py`](https://github.com/samugit83/redamon/blob/master/recon/main.py) (Recon Controller), [`agentic/orchestrator.py`](https://github.com/samugit83/redamon/blob/master/agentic/orchestrator.py) (Agent Orchestrator), [`graph_db/neo4j_client.py`](https://github.com/samugit83/redamon/blob/master/graph_db/neo4j_client.py) (Neo4j Graph), [`agentic/cypherfix_triage/orchestrator.py`](https://github.com/samugit83/redamon/blob/master/agentic/cypherfix_triage/orchestrator.py) (Finding Triage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_recon["Reconnaissance"]
  node_recon_controller["Recon Controller<br/>[main.py]"]
  node_recon_stages["Recon Modules"]
  node_recon_settings["Recon Settings"]
  node_batch_groups["Recon Batching<br/>[batch_groups.py]"]
  node_circuit_breaker["Recon Circuit Breaker<br/>[circuit_breaker.py]"]
end

subgraph group_graph["Attack Graph"]
  node_graph_store[("Neo4j Graph<br/>[neo4j_client.py]")]
  node_graph_governor["Resource Governor"]
end

subgraph group_agent["Agentic Testing"]
  node_agent_orchestrator["Agent Orchestrator<br/>[orchestrator.py]"]
  node_agent_state["Agent State<br/>[state.py]"]
  node_agent_loop["Human Approval Loop<br/>[broker.py]"]
  node_sandbox_tools["Sandbox Tools"]
  node_llm_guard["LLM Guard<br/>[llm_guard.py]"]
end

subgraph group_remediation["Triage and Fixes"]
  node_triage["Finding Triage<br/>[orchestrator.py]"]
  node_triage_scoring["Triage Scoring<br/>[score_model.py]"]
  node_codefix["CodeFix Agent<br/>[orchestrator.py]"]
  node_workspace["Workspace Import<br/>[http_routes.py]"]
end

subgraph group_capabilities["Security Capabilities"]
  node_ai_surface["AI Surface Scan<br/>[main.py]"]
  node_supply_chain["Supply-Chain Scan<br/>[main.py]"]
  node_traffic_capture["Traffic Capture<br/>[ingest_worker.py]"]
  node_knowledge_base["Security Knowledge Base<br/>[data_ingestion.py]"]
end

node_operator(("Security Operator"))

node_operator -->|"starts recon"| node_recon_controller
node_recon_controller -->|"runs modules"| node_recon_stages
node_recon_controller -->|"loads settings"| node_recon_settings
node_recon_stages -->|"builds attack graph"| node_graph_store
node_recon_controller -->|"uses resource limits"| node_graph_governor
node_operator -->|"starts testing"| node_agent_orchestrator
node_agent_orchestrator -->|"requests approval"| node_agent_loop
node_agent_orchestrator -->|"runs tools"| node_sandbox_tools
node_agent_orchestrator -->|"queries attack graph"| node_graph_store
node_agent_orchestrator -.->|"tracks run state"| node_agent_state
node_operator -.->|"launches AI scan"| node_ai_surface
node_ai_surface -->|"writes findings"| node_graph_store
node_operator -.->|"submits scan"| node_supply_chain
node_supply_chain -->|"writes findings"| node_graph_store
node_traffic_capture -.->|"stores transactions"| node_graph_store
node_knowledge_base -->|"loads knowledge"| node_graph_store
node_agent_orchestrator -->|"passes findings"| node_triage
node_triage -->|"scores findings"| node_triage_scoring
node_triage -->|"hands off remediation"| node_codefix
node_codefix -->|"proposes pull request"| node_operator
node_operator -.->|"imports project files"| node_workspace
node_workspace -->|"checks requests"| node_llm_guard
node_agent_loop -->|"checks requests"| node_llm_guard
node_recon_controller -.->|"uses batch settings"| node_batch_groups
node_recon_controller -->|"uses scan controls"| node_circuit_breaker

click node_recon_controller "https://github.com/samugit83/redamon/blob/master/recon/main.py"
click node_recon_stages "https://github.com/samugit83/redamon/tree/master/recon/main_recon_modules"
click node_recon_settings "https://github.com/samugit83/redamon/blob/master/recon/project_settings.py"
click node_graph_store "https://github.com/samugit83/redamon/blob/master/graph_db/neo4j_client.py"
click node_graph_governor "https://github.com/samugit83/redamon/blob/master/graph_db/resource_governor.py"
click node_agent_orchestrator "https://github.com/samugit83/redamon/blob/master/agentic/orchestrator.py"
click node_agent_state "https://github.com/samugit83/redamon/blob/master/agentic/state.py"
click node_agent_loop "https://github.com/samugit83/redamon/blob/master/agentic/agent_in_the_loop/broker.py"
click node_sandbox_tools "https://github.com/samugit83/redamon/tree/master/mcp/servers"
click node_ai_surface "https://github.com/samugit83/redamon/blob/master/scanners/ai_attack_surface_scan/main.py"
click node_supply_chain "https://github.com/samugit83/redamon/blob/master/scanners/supply_chain_scan/main.py"
click node_traffic_capture "https://github.com/samugit83/redamon/blob/master/scanners/capture_proxy/ingest_worker.py"
click node_knowledge_base "https://github.com/samugit83/redamon/blob/master/services/knowledge_base/curation/data_ingestion.py"
click node_triage "https://github.com/samugit83/redamon/blob/master/agentic/cypherfix_triage/orchestrator.py"
click node_triage_scoring "https://github.com/samugit83/redamon/blob/master/agentic/cypherfix_triage/score_model.py"
click node_codefix "https://github.com/samugit83/redamon/blob/master/agentic/cypherfix_codefix/orchestrator.py"
click node_workspace "https://github.com/samugit83/redamon/blob/master/agentic/workspace_import/http_routes.py"
click node_llm_guard "https://github.com/samugit83/redamon/blob/master/agentic/llm_guard.py"
click node_batch_groups "https://github.com/samugit83/redamon/blob/master/recon/helpers/batch_groups.py"
click node_circuit_breaker "https://github.com/samugit83/redamon/blob/master/recon/helpers/circuit_breaker.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_recon_controller,node_recon_stages,node_recon_settings,node_batch_groups,node_circuit_breaker toneBlue
class node_graph_store,node_graph_governor toneAmber
class node_agent_orchestrator,node_agent_state,node_agent_loop,node_sandbox_tools,node_llm_guard toneMint
class node_triage,node_triage_scoring,node_codefix,node_workspace toneRose
class node_ai_surface,node_supply_chain,node_traffic_capture,node_knowledge_base,node_operator toneIndigo
```

## Components

### Reconnaissance

- [Recon Controller](https://github.com/samugit83/redamon/blob/master/recon/main.py): `recon/main.py`
- [Recon Modules](https://github.com/samugit83/redamon/tree/master/recon/main_recon_modules): `recon/main_recon_modules`
- [Recon Settings](https://github.com/samugit83/redamon/blob/master/recon/project_settings.py): `recon/project_settings.py`
- [Recon Batching](https://github.com/samugit83/redamon/blob/master/recon/helpers/batch_groups.py): `recon/helpers/batch_groups.py`
- [Recon Circuit Breaker](https://github.com/samugit83/redamon/blob/master/recon/helpers/circuit_breaker.py): `recon/helpers/circuit_breaker.py`

### Attack Graph

- [Neo4j Graph](https://github.com/samugit83/redamon/blob/master/graph_db/neo4j_client.py): `graph_db/neo4j_client.py`
- [Resource Governor](https://github.com/samugit83/redamon/blob/master/graph_db/resource_governor.py): `graph_db/resource_governor.py`

### Agentic Testing

- [Agent Orchestrator](https://github.com/samugit83/redamon/blob/master/agentic/orchestrator.py): `agentic/orchestrator.py`
- [Agent State](https://github.com/samugit83/redamon/blob/master/agentic/state.py): `agentic/state.py`
- [Human Approval Loop](https://github.com/samugit83/redamon/blob/master/agentic/agent_in_the_loop/broker.py): `agentic/agent_in_the_loop/broker.py`
- [Sandbox Tools](https://github.com/samugit83/redamon/tree/master/mcp/servers): `mcp/servers`
- [LLM Guard](https://github.com/samugit83/redamon/blob/master/agentic/llm_guard.py): `agentic/llm_guard.py`

### Triage and Fixes

- [Finding Triage](https://github.com/samugit83/redamon/blob/master/agentic/cypherfix_triage/orchestrator.py): `agentic/cypherfix_triage/orchestrator.py`
- [Triage Scoring](https://github.com/samugit83/redamon/blob/master/agentic/cypherfix_triage/score_model.py): `agentic/cypherfix_triage/score_model.py`
- [CodeFix Agent](https://github.com/samugit83/redamon/blob/master/agentic/cypherfix_codefix/orchestrator.py): `agentic/cypherfix_codefix/orchestrator.py`
- [Workspace Import](https://github.com/samugit83/redamon/blob/master/agentic/workspace_import/http_routes.py): `agentic/workspace_import/http_routes.py`

### Security Capabilities

- [AI Surface Scan](https://github.com/samugit83/redamon/blob/master/scanners/ai_attack_surface_scan/main.py): `scanners/ai_attack_surface_scan/main.py`
- [Supply-Chain Scan](https://github.com/samugit83/redamon/blob/master/scanners/supply_chain_scan/main.py): `scanners/supply_chain_scan/main.py`
- [Traffic Capture](https://github.com/samugit83/redamon/blob/master/scanners/capture_proxy/ingest_worker.py): `scanners/capture_proxy/ingest_worker.py`
- [Security Knowledge Base](https://github.com/samugit83/redamon/blob/master/services/knowledge_base/curation/data_ingestion.py): `services/knowledge_base/curation/data_ingestion.py`

### Other components

- **Security Operator**

## Connections

- Security Operator → Recon Controller: starts recon (evidence: `README.md`)
- Recon Controller → Recon Modules: runs modules (evidence: `recon/main.py`)
- Recon Controller → Recon Settings: loads settings (evidence: `recon/main.py`)
- Recon Modules → Neo4j Graph: builds attack graph (evidence: `README.md`)
- Recon Controller → Resource Governor: uses resource limits
- Security Operator → Agent Orchestrator: starts testing (evidence: `README.md`)
- Agent Orchestrator → Human Approval Loop: requests approval (evidence: `README.md`)
- Agent Orchestrator → Sandbox Tools: runs tools (evidence: `README.md`)
- Agent Orchestrator → Neo4j Graph: queries attack graph (evidence: `README.md`)
- Agent Orchestrator → Agent State: tracks run state
- Security Operator → AI Surface Scan: launches AI scan
- AI Surface Scan → Neo4j Graph: writes findings (evidence: `scanners/ai_attack_surface_scan/main.py`)
- Security Operator → Supply-Chain Scan: submits scan
- Supply-Chain Scan → Neo4j Graph: writes findings (evidence: `scanners/supply_chain_scan/main.py`)
- Traffic Capture → Neo4j Graph: stores transactions
- Security Knowledge Base → Neo4j Graph: loads knowledge (evidence: `services/knowledge_base/curation/data_ingestion.py`)
- Agent Orchestrator → Finding Triage: passes findings (evidence: `README.md`)
- Finding Triage → Triage Scoring: scores findings (evidence: `agentic/cypherfix_triage/orchestrator.py`)
- Finding Triage → CodeFix Agent: hands off remediation (evidence: `README.md`)
- CodeFix Agent → Security Operator: proposes pull request (evidence: `README.md`)
- Security Operator → Workspace Import: imports project files
- Workspace Import → LLM Guard: checks requests (evidence: `agentic/workspace_import/http_routes.py`)
- Human Approval Loop → LLM Guard: checks requests (evidence: `agentic/agent_in_the_loop/routes.py`)
- Recon Controller → Recon Batching: uses batch settings (evidence: `recon/main.py`)
- Recon Controller → Recon Circuit Breaker: uses scan controls (evidence: `recon/main.py`)
