# thalesgroup/dd-honeypot architecture

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

- Interactive diagram: https://gitdiagram.com/thalesgroup/dd-honeypot
- Repository: https://github.com/thalesgroup/dd-honeypot

## Overview

#### Purpose and execution model
DataTrap is a containerized, data-driven deception system for SSH, HTTP(S), MySQL, PostgreSQL, Redis, Telnet, and arbitrary TCP. It starts one or more configured honeypot instances, serves protocol-realistic interactions, and favors recorded responses before using AWS Bedrock for unknown inputs. Primary startup/orchestration paths are `src/honeypot_main.py`, `src/honeypot_main_utils.py`, and `Dockerfile`.

#### Configuration, registration, and lifecycle
Honeypot definitions are discovered from per-instance `config.json` directories, then mapped by type to implementations through a registry. Shared lifecycle concerns—session identity, client metadata, logging, configuration, and handler construction—belong to the base/wrapper layer. Key paths: `src/honeypot_registry.py`, `src/base_honeypot.py`, `src/infra/honeypot_wrapper.py`.

#### Protocol ingress layer
Protocol adapters own wire parsing, authentication/handshakes, connection/session state, and translating protocol requests into the common response pipeline. SSH and Telnet support shell-like interaction; HTTP supports application-style request handling; database/cache services implement their native request semantics. Key paths: `src/ssh_honeypot.py`, `src/http_honeypot.py`, `src/mysql_honeypot.py`, `src/postgresql_honeypot.py`, `src/redis_honeypot.py`, `src/telnet_honeypot.py`, `src/tcp_honeypot.py`.

#### Optional HTTP dispatcher
Dispatcher mode accepts traffic on one HTTP endpoint and routes it to backend honeypots through traffic inspection or LLM-assisted classification, retaining sticky session behavior. This is a control-flow boundary before normal protocol/data processing. Key paths: `src/http_honeypot.py`, `src/infra/chain_honeypot_action.py`, `docs/dispatcher.md`.

#### Chained response resolution
Incoming normalized requests traverse composable handlers: file-download simulation, fake-filesystem behavior, recorded dataset lookup, then LLM fallback. A handler may satisfy the request or delegate to the next stage, keeping protocol code separate from emulation/content decisions. Key paths: `src/infra/chained_data_handler.py`, `src/infra/data_handler.py`, `src/infra/file_download_handler.py`, `src/sql_data_handler.py`, `src/llm_utils.py`.

#### Dataset and fake-filesystem persistence
Recorded JSONL request/response pairs are loaded and queried through a datastore abstraction, with SQLite used for lookup/storage. The fake filesystem imports compressed JSONL into SQLite and exposes command/navigation behavior for shell-oriented honeypots. State and dynamic placeholders are resolved at this content boundary. Key paths: `src/infra/data_store.py`, `src/infra/json_to_sqlite.py`, `src/infra/fake_fs_datastore.py`, `src/infra/fake_fs/filesystem.py`, `src/infra/fake_fs/commands.py`.

#### External services, observability, and deployment
AWS Bedrock generates fallback responses and requires AWS credentials/region; visitor-based rate limiting and prompts constrain that path. Structured JSON logging is intended for fluent-bit and CloudWatch. Docker is the deployment runtime, with CI building/publishing images and running tests. Key paths: `src/llm_utils.py`, `src/logging.conf`, `Dockerfile`, `.github/workflows/build-and-deploy-docker-image.yaml`.

Main entry points: [`src/infra/chained_data_handler.py`](https://github.com/thalesgroup/dd-honeypot/blob/main/src/infra/chained_data_handler.py) (Chained handlers), [`src/honeypot_registry.py`](https://github.com/thalesgroup/dd-honeypot/blob/main/src/honeypot_registry.py) (Honeypot registry), [`src/http_honeypot.py`](https://github.com/thalesgroup/dd-honeypot/blob/main/src/http_honeypot.py) (HTTP(S) honeypot), [`src/base_honeypot.py`](https://github.com/thalesgroup/dd-honeypot/blob/main/src/base_honeypot.py) (Base lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup &amp; Registration"]
  node_startup["Instance orchestration<br/>startup<br/>[honeypot_main.py]"]
  node_registry["Honeypot registry<br/>registration"]
  node_lifecycle["Base lifecycle<br/>shared runtime<br/>[base_honeypot.py]"]
end

subgraph group_ingress["Protocol Ingress"]
  node_http["HTTP&#40;S&#41; honeypot<br/>protocol adapter<br/>[http_honeypot.py]"]
  node_ssh["SSH honeypot<br/>protocol adapter<br/>[ssh_honeypot.py]"]
  node_telnet["Telnet honeypot<br/>protocol adapter<br/>[telnet_honeypot.py]"]
  node_mysql["MySQL honeypot<br/>protocol adapter<br/>[mysql_honeypot.py]"]
  node_postgresql["PostgreSQL honeypot<br/>protocol adapter"]
  node_redis["Redis honeypot<br/>protocol adapter<br/>[redis_honeypot.py]"]
  node_tcp["TCP honeypot<br/>protocol adapter<br/>[tcp_honeypot.py]"]
  node_dispatcher{{"HTTP dispatcher<br/>routing boundary"}}
end

subgraph group_resolution["Response Resolution"]
  node_chain["Chained handlers<br/>response pipeline"]
  node_file_download["Download simulation<br/>response handler"]
  node_recorded_data["Recorded response lookup<br/>response handler"]
  node_llm["Bedrock fallback<br/>AI response generator<br/>[llm_utils.py]"]
end

subgraph group_data["Content &amp; State"]
  node_fake_fs["Fake filesystem<br/>shell emulation<br/>[filesystem.py]"]
  node_datastore[("SQLite datastore<br/>persistence<br/>[data_store.py]")]
end

subgraph group_operations["Operations"]
  node_container["Container runtime<br/>deployment"]
  node_logging["Structured logging<br/>observability<br/>[logging.conf]"]
  node_ci["Image build and publish<br/>CI pipeline"]
end

node_container -->|"runs"| node_startup
node_ci -->|"builds and publishes"| node_container
node_startup -->|"resolves types"| node_registry
node_registry -->|"registers"| node_http
node_registry -->|"registers"| node_ssh
node_registry -->|"registers"| node_telnet
node_registry -->|"registers"| node_mysql
node_registry -->|"registers"| node_postgresql
node_registry -->|"registers"| node_redis
node_registry -->|"registers"| node_tcp
node_lifecycle -->|"constructs"| node_chain
node_http -.->|"dispatcher mode"| node_dispatcher
node_dispatcher -->|"routes normalized requests"| node_chain
node_http -->|"normalizes requests"| node_chain
node_ssh -->|"normalizes requests"| node_chain
node_telnet -->|"normalizes requests"| node_chain
node_mysql -->|"normalizes requests"| node_chain
node_postgresql -->|"normalizes requests"| node_chain
node_redis -->|"normalizes requests"| node_chain
node_tcp -->|"normalizes requests"| node_chain
node_chain -->|"first handler"| node_file_download
node_file_download -.->|"delegates shell content"| node_fake_fs
node_chain -->|"recorded lookup"| node_recorded_data
node_recorded_data -->|"queries"| node_datastore
node_chain -.->|"fallback on miss"| node_llm
node_lifecycle -->|"emits events"| node_logging

click node_container "https://github.com/thalesgroup/dd-honeypot/blob/main/Dockerfile"
click node_startup "https://github.com/thalesgroup/dd-honeypot/blob/main/src/honeypot_main.py"
click node_registry "https://github.com/thalesgroup/dd-honeypot/blob/main/src/honeypot_registry.py"
click node_lifecycle "https://github.com/thalesgroup/dd-honeypot/blob/main/src/base_honeypot.py"
click node_http "https://github.com/thalesgroup/dd-honeypot/blob/main/src/http_honeypot.py"
click node_ssh "https://github.com/thalesgroup/dd-honeypot/blob/main/src/ssh_honeypot.py"
click node_telnet "https://github.com/thalesgroup/dd-honeypot/blob/main/src/telnet_honeypot.py"
click node_mysql "https://github.com/thalesgroup/dd-honeypot/blob/main/src/mysql_honeypot.py"
click node_postgresql "https://github.com/thalesgroup/dd-honeypot/blob/main/src/postgresql_honeypot.py"
click node_redis "https://github.com/thalesgroup/dd-honeypot/blob/main/src/redis_honeypot.py"
click node_tcp "https://github.com/thalesgroup/dd-honeypot/blob/main/src/tcp_honeypot.py"
click node_dispatcher "https://github.com/thalesgroup/dd-honeypot/blob/main/src/infra/chain_honeypot_action.py"
click node_chain "https://github.com/thalesgroup/dd-honeypot/blob/main/src/infra/chained_data_handler.py"
click node_file_download "https://github.com/thalesgroup/dd-honeypot/blob/main/src/infra/file_download_handler.py"
click node_recorded_data "https://github.com/thalesgroup/dd-honeypot/blob/main/src/sql_data_handler.py"
click node_fake_fs "https://github.com/thalesgroup/dd-honeypot/blob/main/src/infra/fake_fs/filesystem.py"
click node_datastore "https://github.com/thalesgroup/dd-honeypot/blob/main/src/infra/data_store.py"
click node_llm "https://github.com/thalesgroup/dd-honeypot/blob/main/src/llm_utils.py"
click node_logging "https://github.com/thalesgroup/dd-honeypot/blob/main/src/logging.conf"
click node_ci "https://github.com/thalesgroup/dd-honeypot/blob/main/.github/workflows/build-and-deploy-docker-image.yaml"

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_startup,node_registry,node_lifecycle toneBlue
class node_http,node_ssh,node_telnet,node_mysql,node_postgresql,node_redis,node_tcp,node_dispatcher toneAmber
class node_chain,node_file_download,node_recorded_data,node_llm toneMint
class node_fake_fs,node_datastore toneRose
class node_container,node_logging,node_ci toneIndigo
```

## Components

### Startup & Registration

- [Instance orchestration](https://github.com/thalesgroup/dd-honeypot/blob/main/src/honeypot_main.py): startup · Discovers configured honeypot instances and starts them. · `src/honeypot_main.py`
- [Honeypot registry](https://github.com/thalesgroup/dd-honeypot/blob/main/src/honeypot_registry.py): registration · Maps configured types to protocol implementations. · `src/honeypot_registry.py`
- [Base lifecycle](https://github.com/thalesgroup/dd-honeypot/blob/main/src/base_honeypot.py): shared runtime · Provides session identity, client metadata, logging, and handler construction. · `src/base_honeypot.py`

### Protocol Ingress

- [HTTP(S) honeypot](https://github.com/thalesgroup/dd-honeypot/blob/main/src/http_honeypot.py): protocol adapter · `src/http_honeypot.py`
- [SSH honeypot](https://github.com/thalesgroup/dd-honeypot/blob/main/src/ssh_honeypot.py): protocol adapter · `src/ssh_honeypot.py`
- [Telnet honeypot](https://github.com/thalesgroup/dd-honeypot/blob/main/src/telnet_honeypot.py): protocol adapter · `src/telnet_honeypot.py`
- [MySQL honeypot](https://github.com/thalesgroup/dd-honeypot/blob/main/src/mysql_honeypot.py): protocol adapter · `src/mysql_honeypot.py`
- [PostgreSQL honeypot](https://github.com/thalesgroup/dd-honeypot/blob/main/src/postgresql_honeypot.py): protocol adapter · `src/postgresql_honeypot.py`
- [Redis honeypot](https://github.com/thalesgroup/dd-honeypot/blob/main/src/redis_honeypot.py): protocol adapter · `src/redis_honeypot.py`
- [TCP honeypot](https://github.com/thalesgroup/dd-honeypot/blob/main/src/tcp_honeypot.py): protocol adapter · `src/tcp_honeypot.py`
- [HTTP dispatcher](https://github.com/thalesgroup/dd-honeypot/blob/main/src/infra/chain_honeypot_action.py): routing boundary · Inspects traffic or classifies it while retaining sticky sessions. · `src/infra/chain_honeypot_action.py`

### Response Resolution

- [Chained handlers](https://github.com/thalesgroup/dd-honeypot/blob/main/src/infra/chained_data_handler.py): response pipeline · Delegates normalized requests through ordered response handlers. · `src/infra/chained_data_handler.py`
- [Download simulation](https://github.com/thalesgroup/dd-honeypot/blob/main/src/infra/file_download_handler.py): response handler · `src/infra/file_download_handler.py`
- [Recorded response lookup](https://github.com/thalesgroup/dd-honeypot/blob/main/src/sql_data_handler.py): response handler · `src/sql_data_handler.py`
- [Bedrock fallback](https://github.com/thalesgroup/dd-honeypot/blob/main/src/llm_utils.py): AI response generator · Generates constrained responses when recorded content does not match. · `src/llm_utils.py`

### Content & State

- [Fake filesystem](https://github.com/thalesgroup/dd-honeypot/blob/main/src/infra/fake_fs/filesystem.py): shell emulation · Provides command and navigation behavior for shell sessions. · `src/infra/fake_fs/filesystem.py`
- [SQLite datastore](https://github.com/thalesgroup/dd-honeypot/blob/main/src/infra/data_store.py): persistence · Loads and queries recorded JSONL request/response data. · `src/infra/data_store.py`

### Operations

- [Container runtime](https://github.com/thalesgroup/dd-honeypot/blob/main/Dockerfile): deployment · `Dockerfile`
- [Structured logging](https://github.com/thalesgroup/dd-honeypot/blob/main/src/logging.conf): observability · Emits JSON logs for fluent-bit and CloudWatch. · `src/logging.conf`
- [Image build and publish](https://github.com/thalesgroup/dd-honeypot/blob/main/.github/workflows/build-and-deploy-docker-image.yaml): CI pipeline · `.github/workflows/build-and-deploy-docker-image.yaml`

## Connections

- Container runtime → Instance orchestration: runs
- Image build and publish → Container runtime: builds and publishes
- Instance orchestration → Honeypot registry: resolves types
- Honeypot registry → HTTP(S) honeypot: registers
- Honeypot registry → SSH honeypot: registers
- Honeypot registry → Telnet honeypot: registers
- Honeypot registry → MySQL honeypot: registers
- Honeypot registry → PostgreSQL honeypot: registers
- Honeypot registry → Redis honeypot: registers
- Honeypot registry → TCP honeypot: registers
- Base lifecycle → Chained handlers: constructs
- HTTP(S) honeypot → HTTP dispatcher: dispatcher mode
- HTTP dispatcher → Chained handlers: routes normalized requests
- HTTP(S) honeypot → Chained handlers: normalizes requests
- SSH honeypot → Chained handlers: normalizes requests
- Telnet honeypot → Chained handlers: normalizes requests
- MySQL honeypot → Chained handlers: normalizes requests
- PostgreSQL honeypot → Chained handlers: normalizes requests
- Redis honeypot → Chained handlers: normalizes requests
- TCP honeypot → Chained handlers: normalizes requests
- Chained handlers → Download simulation: first handler
- Download simulation → Fake filesystem: delegates shell content
- Chained handlers → Recorded response lookup: recorded lookup
- Recorded response lookup → SQLite datastore: queries
- Chained handlers → Bedrock fallback: fallback on miss
- Base lifecycle → Structured logging: emits events
