# kamolchanok-saengtong/hydrapot architecture

> Architecture diagram of the GitHub repository kamolchanok-saengtong/hydrapot, 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/kamolchanok-saengtong/hydrapot
- Repository: https://github.com/kamolchanok-saengtong/hydrapot

## Overview

HydraPoT is a configurable, multi-agent SSH honeypot. An attacker connects over SSH; the session handler maintains shared context, scores command impact, and routes commands among Cowrie-style emulation and local or cloud LLM agents. Responses preserve session continuity, while command and event records support threat analysis and a SIEM dashboard. The source excerpts establish the entry-point wiring, session-aware routing behavior, and storage/dashboard access; the README documents the broader agent-routing design. Some subsystem links are therefore shown only where supported by those sources or documentation.

Main entry points: [`shell/session.py`](https://github.com/kamolchanok-saengtong/hydrapot/blob/main/shell/session.py) (Session handler), [`router.py`](https://github.com/kamolchanok-saengtong/hydrapot/blob/main/router.py) (Agent selection), [`storage.py`](https://github.com/kamolchanok-saengtong/hydrapot/blob/main/storage.py) (Event database), [`ssh_server.py`](https://github.com/kamolchanok-saengtong/hydrapot/blob/main/ssh_server.py) (SSH listener)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["SSH Capture"]
  node_main["Runtime startup<br/>[main.py]"]
  node_ssh["SSH listener<br/>[ssh_server.py]"]
  node_session["Session handler<br/>[session.py]"]
end

subgraph group_routing["Session Routing"]
  node_shared["Session state<br/>[state.py]"]
  node_impact["Impact scoring<br/>[fi_manager.py]"]
  node_router["Agent selection<br/>[router.py]"]
  node_needmodel["Session-aware routing<br/>[routing.py]"]
end

subgraph group_response["Command Responses"]
  node_cowrie["Cowrie agent<br/>[cowrie_agent.py]"]
  node_static["Static emulation<br/>[static_handler.py]"]
  node_ondevice["On-device agent<br/>[ondevice_agent.py]"]
  node_cloud["Cloud agent<br/>[cloud_agent.py]"]
  node_prompt["Prompt assembly<br/>[prompt_manager.py]"]
  node_guardrail["LLM safeguards<br/>[validator.py]"]
end

subgraph group_analysis["Threat Analysis"]
  node_store[("Event database<br/>[storage.py]")]
  node_intel["Threat intelligence<br/>[aggregator.py]"]
  node_sweeper["Alert sweeper<br/>[sweeper.py]"]
end

subgraph group_interfaces["User Interfaces"]
  node_api["Web API host<br/>[api_server.py]"]
  node_services["API services<br/>[findings.py]"]
  node_dashboard["SIEM dashboard<br/>[layout.py]"]
  node_dbpage["Database browser<br/>[database.py]"]
end

node_attacker(("SSH attacker"))
node_operator(("Operator"))
node_cloudservice["Cloud model service"]

node_main -->|"starts listener"| node_ssh
node_main -->|"connects agent"| node_cowrie
node_attacker -->|"opens SSH"| node_ssh
node_ssh -->|"dispatches commands"| node_session
node_session -->|"updates state"| node_shared
node_session -->|"scores command"| node_impact
node_session -->|"selects agent"| node_router
node_session -->|"checks model need"| node_needmodel
node_router -->|"routes command"| node_cowrie
node_router -->|"routes command"| node_ondevice
node_router -->|"routes command"| node_cloud
node_cowrie -->|"uses emulation"| node_static
node_session -->|"builds prompts"| node_prompt
node_prompt -->|"supplies prompts"| node_ondevice
node_ondevice -->|"validates output"| node_guardrail
node_cloud -.->|"requests inference"| node_cloudservice
node_session -->|"records events"| node_store
node_sweeper -->|"reads records"| node_store
node_sweeper -->|"processes threats"| node_intel
node_api -->|"dispatches requests"| node_services
node_services -->|"reads findings"| node_store
node_api -->|"hosts dashboard"| node_dashboard
node_dashboard -->|"renders browser"| node_dbpage
node_dbpage -->|"queries read-only"| node_store
node_operator -->|"views analytics"| node_dashboard

click node_main "https://github.com/kamolchanok-saengtong/hydrapot/blob/main/main.py"
click node_ssh "https://github.com/kamolchanok-saengtong/hydrapot/blob/main/ssh_server.py"
click node_session "https://github.com/kamolchanok-saengtong/hydrapot/blob/main/shell/session.py"
click node_shared "https://github.com/kamolchanok-saengtong/hydrapot/blob/main/shell/state.py"
click node_impact "https://github.com/kamolchanok-saengtong/hydrapot/blob/main/prompt/fi_manager.py"
click node_router "https://github.com/kamolchanok-saengtong/hydrapot/blob/main/router.py"
click node_needmodel "https://github.com/kamolchanok-saengtong/hydrapot/blob/main/shell/routing.py"
click node_cowrie "https://github.com/kamolchanok-saengtong/hydrapot/blob/main/agent_manager/cowrie_agent.py"
click node_static "https://github.com/kamolchanok-saengtong/hydrapot/blob/main/agent_manager/static_handler.py"
click node_ondevice "https://github.com/kamolchanok-saengtong/hydrapot/blob/main/agent_manager/ondevice_agent.py"
click node_cloud "https://github.com/kamolchanok-saengtong/hydrapot/blob/main/agent_manager/cloud_agent.py"
click node_prompt "https://github.com/kamolchanok-saengtong/hydrapot/blob/main/prompt/prompt_manager.py"
click node_guardrail "https://github.com/kamolchanok-saengtong/hydrapot/blob/main/guardrail/validator.py"
click node_store "https://github.com/kamolchanok-saengtong/hydrapot/blob/main/storage.py"
click node_intel "https://github.com/kamolchanok-saengtong/hydrapot/blob/main/threat_intel/aggregator.py"
click node_sweeper "https://github.com/kamolchanok-saengtong/hydrapot/blob/main/threat_intel/sweeper.py"
click node_api "https://github.com/kamolchanok-saengtong/hydrapot/blob/main/api_server.py"
click node_services "https://github.com/kamolchanok-saengtong/hydrapot/blob/main/api/services/findings.py"
click node_dashboard "https://github.com/kamolchanok-saengtong/hydrapot/blob/main/SIEM/layout.py"
click node_dbpage "https://github.com/kamolchanok-saengtong/hydrapot/blob/main/SIEM/pages/database.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_main,node_ssh,node_session toneBlue
class node_shared,node_impact,node_router,node_needmodel toneAmber
class node_cowrie,node_static,node_ondevice,node_cloud,node_prompt,node_guardrail toneMint
class node_store,node_intel,node_sweeper toneRose
class node_api,node_services,node_dashboard,node_dbpage,node_attacker,node_operator,node_cloudservice toneIndigo
```

## Components

### SSH Capture

- [Runtime startup](https://github.com/kamolchanok-saengtong/hydrapot/blob/main/main.py): `main.py`
- [SSH listener](https://github.com/kamolchanok-saengtong/hydrapot/blob/main/ssh_server.py): `ssh_server.py`
- [Session handler](https://github.com/kamolchanok-saengtong/hydrapot/blob/main/shell/session.py): `shell/session.py`

### Session Routing

- [Session state](https://github.com/kamolchanok-saengtong/hydrapot/blob/main/shell/state.py): `shell/state.py`
- [Impact scoring](https://github.com/kamolchanok-saengtong/hydrapot/blob/main/prompt/fi_manager.py): `prompt/fi_manager.py`
- [Agent selection](https://github.com/kamolchanok-saengtong/hydrapot/blob/main/router.py): `router.py`
- [Session-aware routing](https://github.com/kamolchanok-saengtong/hydrapot/blob/main/shell/routing.py): `shell/routing.py`

### Command Responses

- [Cowrie agent](https://github.com/kamolchanok-saengtong/hydrapot/blob/main/agent_manager/cowrie_agent.py): `agent_manager/cowrie_agent.py`
- [Static emulation](https://github.com/kamolchanok-saengtong/hydrapot/blob/main/agent_manager/static_handler.py): `agent_manager/static_handler.py`
- [On-device agent](https://github.com/kamolchanok-saengtong/hydrapot/blob/main/agent_manager/ondevice_agent.py): `agent_manager/ondevice_agent.py`
- [Cloud agent](https://github.com/kamolchanok-saengtong/hydrapot/blob/main/agent_manager/cloud_agent.py): `agent_manager/cloud_agent.py`
- [Prompt assembly](https://github.com/kamolchanok-saengtong/hydrapot/blob/main/prompt/prompt_manager.py): `prompt/prompt_manager.py`
- [LLM safeguards](https://github.com/kamolchanok-saengtong/hydrapot/blob/main/guardrail/validator.py): `guardrail/validator.py`

### Threat Analysis

- [Event database](https://github.com/kamolchanok-saengtong/hydrapot/blob/main/storage.py): `storage.py`
- [Threat intelligence](https://github.com/kamolchanok-saengtong/hydrapot/blob/main/threat_intel/aggregator.py): `threat_intel/aggregator.py`
- [Alert sweeper](https://github.com/kamolchanok-saengtong/hydrapot/blob/main/threat_intel/sweeper.py): `threat_intel/sweeper.py`

### User Interfaces

- [Web API host](https://github.com/kamolchanok-saengtong/hydrapot/blob/main/api_server.py): `api_server.py`
- [API services](https://github.com/kamolchanok-saengtong/hydrapot/blob/main/api/services/findings.py): `api/services/findings.py`
- [SIEM dashboard](https://github.com/kamolchanok-saengtong/hydrapot/blob/main/SIEM/layout.py): `SIEM/layout.py`
- [Database browser](https://github.com/kamolchanok-saengtong/hydrapot/blob/main/SIEM/pages/database.py): `SIEM/pages/database.py`

### Other components

- **SSH attacker**
- **Operator**
- **Cloud model service**

## Connections

- Runtime startup → SSH listener: starts listener
- Runtime startup → Cowrie agent: connects agent
- SSH attacker → SSH listener: opens SSH
- SSH listener → Session handler: dispatches commands
- Session handler → Session state: updates state
- Session handler → Impact scoring: scores command
- Session handler → Agent selection: selects agent
- Session handler → Session-aware routing: checks model need
- Agent selection → Cowrie agent: routes command
- Agent selection → On-device agent: routes command
- Agent selection → Cloud agent: routes command
- Cowrie agent → Static emulation: uses emulation
- Session handler → Prompt assembly: builds prompts
- Prompt assembly → On-device agent: supplies prompts
- On-device agent → LLM safeguards: validates output
- Cloud agent → Cloud model service: requests inference
- Session handler → Event database: records events
- Alert sweeper → Event database: reads records
- Alert sweeper → Threat intelligence: processes threats
- Web API host → API services: dispatches requests
- API services → Event database: reads findings
- Web API host → SIEM dashboard: hosts dashboard
- SIEM dashboard → Database browser: renders browser
- Database browser → Event database: queries read-only
- Operator → SIEM dashboard: views analytics