How thalesgroup/dd-honeypot works
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: chained_data_handler.py Chained handlers · honeypot_registry.py Honeypot registry · http_honeypot.py HTTP(S) honeypot · base_honeypot.py Base lifecycle
Components 20
Startup & Registration
- Instance orchestration · Discovers configured honeypot instances and starts them.
src/honeypot_main.py - Honeypot registry · Maps configured types to protocol implementations.
src/honeypot_registry.py - Base lifecycle · Provides session identity, client metadata, logging, and handler construction.
src/base_honeypot.py
Protocol Ingress
- HTTP(S) honeypot
src/http_honeypot.py - SSH honeypot
src/ssh_honeypot.py - Telnet honeypot
src/telnet_honeypot.py - MySQL honeypot
src/mysql_honeypot.py - PostgreSQL honeypot
src/postgresql_honeypot.py - Redis honeypot
src/redis_honeypot.py - TCP honeypot
src/tcp_honeypot.py - HTTP dispatcher · Inspects traffic or classifies it while retaining sticky sessions.
src/infra/chain_honeypot_action.py
Response Resolution
- Chained handlers · Delegates normalized requests through ordered response handlers.
src/infra/chained_data_handler.py - Download simulation
src/infra/file_download_handler.py - Recorded response lookup
src/sql_data_handler.py - Bedrock fallback · Generates constrained responses when recorded content does not match.
src/llm_utils.py
Content & State
- Fake filesystem · Provides command and navigation behavior for shell sessions.
src/infra/fake_fs/filesystem.py - SQLite datastore · Loads and queries recorded JSONL request/response data.
src/infra/data_store.py
Operations
- Container runtime
Dockerfile - Structured logging · Emits JSON logs for fluent-bit and CloudWatch.
src/logging.conf - Image build and publish
.github/workflows/build-and-deploy-docker-image.yaml
Connections 26
- 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