# boolean-autocrat/glutton architecture

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

- Interactive diagram: https://gitdiagram.com/boolean-autocrat/glutton
- Repository: https://github.com/boolean-autocrat/glutton

## Overview

1. **What the system is**
   Glutton is a single Go-based honeypot daemon that sits on a host and intercepts inbound network traffic, then pretends to be many common services at once. The architectural center is not a web backend but a **traffic-capture and protocol-emulation pipeline**.

2. **Process entrypoint and orchestration**
   The executable entrypoint is under `app/server.go`, with the root-level `server.go`, `glutton.go`, `system.go`, and `iptables.go` forming the core runtime orchestration. This layer is responsible for startup, configuration loading, system preparation, and wiring the major subsystems together.

3. **Network interception boundary**
   The first major boundary is the host network layer. Glutton uses **iptables + TPROXY** to redirect traffic into the process instead of letting it reach real services. That interception/setup logic lives in `iptables.go` and `system.go`, which means the honeypot is designed to operate at the OS/network edge rather than behind an application gateway.

4. **Connection capture and normalization**
   The `connection` package represents the incoming session/flow abstraction. It likely centralizes the remote/local addresses, protocol metadata, and raw bytes needed by downstream components so that protocol handlers do not depend on low-level socket details.

5. **Protocol identification and dispatch**
   The `protocols` package is the protocol-routing layer. `protocols/peek.go`, `protocols/protocols.go`, and `protocols/helpers` appear to inspect the initial bytes of a connection and decide which handler should take over. This is the main dispatch boundary between generic captured traffic and service-specific emulation.

6. **Service emulation handlers**
   Under `protocols/tcp`, the repository contains many concrete TCP protocol implementations: HTTP, FTP, SMTP, Telnet, SMB, RDP, MongoDB, MQTT, Memcache, SIP, Jabber, iSCSI, ADB, BitTorrent, Ethereum RPC, RFB, and others. These handlers emulate banners, responses, and/or simple protocol behavior so attackers see plausible services rather than closed ports.

7. **UDP handling**
   `protocols/udp` provides the UDP-side equivalent. The architecture treats UDP separately from TCP, which matters because UDP flows are stateless and usually need different parsing and response semantics than stream-oriented handlers.

8. **Rules and configurable behavior**
   The `rules` package, together with `config/rules.yaml` and `config/schema.json`, suggests a configurable decision layer for matching traffic and choosing responses or classifications. This is the main “policy” boundary: behavior is not hardcoded everywhere, but driven by configuration and rules.

9. **Logging/output pipeline**
   The `producer` package is the outbound reporting boundary. It contains a logger and a producer implementation, implying that captured events are transformed into structured output and sent to whatever sink Glutton uses for observation and analysis. The honeypot’s value is in this telemetry path as much as in the emulation itself.

10. **Extension points and interfaces**
    `protocols/interfaces` defines the contracts that bind the system together, and `protocols/mocks` shows those contracts are designed for testability. This makes protocol handlers and logging backends replaceable, which is important if you want to add new fake services or swap out output mechanisms.

11. **Embedded protocol resources**
    Some handlers depend on canned payloads and protocol-specific data under `protocols/tcp/resources` and nested protocol subpackages like `iscsi` and `rdp`. These resource files and submodules indicate that certain emulations are data-driven or protocol-specific rather than purely generic.

12. **Operational packaging**
    The repository includes `Dockerfile`, `Dockerfile.local`, `.devcontainer`, and GitHub Actions workflow files, showing that the service is intended to be run in containerized or reproducible environments. That matters architecturally because host-level packet redirection and Linux networking capabilities are part of the deployment model, not just the code.

13. **Overall data flow**
    The typical flow is: host traffic is redirected by kernel/network rules → the Go daemon accepts the connection → the connection is normalized → protocol is identified by peeking/parsing → the matching TCP/UDP handler emulates the service and logs activity → the producer emits the observation data for later analysis.

14. **Diagram takeaway**
    For an architecture diagram, the important boxes are: **host/network interception**, **connection normalization**, **protocol detection/dispatch**, **service-specific protocol handlers**, **rules/configuration**, and **event production/logging**. The main boundary is between the OS-level traffic redirector and the application-level protocol emulation engine.

Main entry points: [`protocols/protocols.go`](https://github.com/boolean-autocrat/glutton/blob/main/protocols/protocols.go) (Protocol map), [`producer/producer.go`](https://github.com/boolean-autocrat/glutton/blob/main/producer/producer.go) (Producer), [`protocols/interfaces/interfaces.go`](https://github.com/boolean-autocrat/glutton/blob/main/protocols/interfaces/interfaces.go) (Interfaces), [`server.go`](https://github.com/boolean-autocrat/glutton/blob/main/server.go) (Server core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app_server["App entry<br/>entrypoint<br/>[server.go]"]
  node_root_server["Server core<br/>orchestrator<br/>[server.go]"]
  node_glutton_core["Glutton core<br/>runtime core<br/>[glutton.go]"]
  node_system_setup["System setup<br/>host setup<br/>[system.go]"]
  node_iptables_tproxy["Traffic redirect<br/>network redirect<br/>[iptables.go]"]
end

subgraph group_engine["Protocol Engine"]
  node_connection_flow["Connection flow<br/>session model<br/>[connection.go]"]
  node_scanner["Scanner<br/>traffic intake<br/>[scanner.go]"]
  node_protocol_peek["Peek router<br/>protocol detect<br/>[peek.go]"]
  node_protocol_dispatch["Protocol map<br/>dispatch table<br/>[protocols.go]"]
  node_tcp_handlers["TCP emulators<br/>protocol handlers<br/>[tcp.go]"]
  node_udp_handlers["UDP emulators<br/>protocol handlers<br/>[udp.go]"]
  node_protocol_contracts["Interfaces<br/>contracts<br/>[interfaces.go]"]
end

subgraph group_ops["Ops"]
  node_rules_engine["Rules engine<br/>policy<br/>[rules.go]"]
  node_config_files["Config files<br/>configuration<br/>[config.yaml]"]
  node_producer["Producer<br/>telemetry output<br/>[producer.go]"]
  node_logger["Logger<br/>logging<br/>[logger.go]"]
end

node_app_server -->|"starts"| node_root_server
node_root_server -->|"wires"| node_glutton_core
node_glutton_core -->|"prepares"| node_system_setup
node_system_setup -->|"redirects"| node_iptables_tproxy
node_iptables_tproxy -->|"hands off"| node_scanner
node_scanner -->|"normalizes"| node_connection_flow
node_connection_flow -->|"feeds"| node_protocol_peek
node_protocol_peek -->|"selects"| node_protocol_dispatch
node_protocol_dispatch -->|"dispatches"| node_tcp_handlers
node_protocol_dispatch -->|"dispatches"| node_udp_handlers
node_rules_engine -.->|"influences"| node_protocol_dispatch
node_config_files -->|"loads"| node_rules_engine
node_tcp_handlers -->|"reports"| node_producer
node_udp_handlers -->|"reports"| node_producer
node_producer -->|"logs via"| node_logger
node_protocol_contracts -.->|"defines"| node_protocol_dispatch
node_protocol_contracts -.->|"defines"| node_producer

click node_app_server "https://github.com/boolean-autocrat/glutton/blob/main/app/server.go"
click node_root_server "https://github.com/boolean-autocrat/glutton/blob/main/server.go"
click node_glutton_core "https://github.com/boolean-autocrat/glutton/blob/main/glutton.go"
click node_system_setup "https://github.com/boolean-autocrat/glutton/blob/main/system.go"
click node_iptables_tproxy "https://github.com/boolean-autocrat/glutton/blob/main/iptables.go"
click node_connection_flow "https://github.com/boolean-autocrat/glutton/blob/main/connection/connection.go"
click node_scanner "https://github.com/boolean-autocrat/glutton/blob/main/scanner/scanner.go"
click node_protocol_peek "https://github.com/boolean-autocrat/glutton/blob/main/protocols/peek.go"
click node_protocol_dispatch "https://github.com/boolean-autocrat/glutton/blob/main/protocols/protocols.go"
click node_tcp_handlers "https://github.com/boolean-autocrat/glutton/blob/main/protocols/tcp/tcp.go"
click node_udp_handlers "https://github.com/boolean-autocrat/glutton/blob/main/protocols/udp/udp.go"
click node_rules_engine "https://github.com/boolean-autocrat/glutton/blob/main/rules/rules.go"
click node_config_files "https://github.com/boolean-autocrat/glutton/blob/main/config/config.yaml"
click node_producer "https://github.com/boolean-autocrat/glutton/blob/main/producer/producer.go"
click node_logger "https://github.com/boolean-autocrat/glutton/blob/main/producer/logger.go"
click node_protocol_contracts "https://github.com/boolean-autocrat/glutton/blob/main/protocols/interfaces/interfaces.go"

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_app_server,node_root_server,node_glutton_core,node_system_setup,node_iptables_tproxy toneBlue
class node_connection_flow,node_scanner,node_protocol_peek,node_protocol_dispatch,node_tcp_handlers,node_udp_handlers,node_protocol_contracts toneAmber
class node_rules_engine,node_config_files,node_producer,node_logger toneMint
```

## Components

### Runtime

Process entrypoint and host-level orchestration

- [App entry](https://github.com/boolean-autocrat/glutton/blob/main/app/server.go): entrypoint · Binary entrypoint for starting the daemon · `app/server.go`
- [Server core](https://github.com/boolean-autocrat/glutton/blob/main/server.go): orchestrator · Top-level runtime wiring and server lifecycle · `server.go`
- [Glutton core](https://github.com/boolean-autocrat/glutton/blob/main/glutton.go): runtime core · Main application coordination logic · `glutton.go`
- [System setup](https://github.com/boolean-autocrat/glutton/blob/main/system.go): host setup · Host preparation and environment coordination · `system.go`
- [Traffic redirect](https://github.com/boolean-autocrat/glutton/blob/main/iptables.go): network redirect · iptables and TPROXY interception setup · `iptables.go`

### Protocol Engine

Traffic capture, identification, and service emulation

- [Connection flow](https://github.com/boolean-autocrat/glutton/blob/main/connection/connection.go): session model · Normalized inbound connection and flow abstraction · `connection/connection.go`
- [Scanner](https://github.com/boolean-autocrat/glutton/blob/main/scanner/scanner.go): traffic intake · Inbound traffic intake and session handling · `scanner/scanner.go`
- [Peek router](https://github.com/boolean-autocrat/glutton/blob/main/protocols/peek.go): protocol detect · Inspects initial bytes to identify protocol · `protocols/peek.go`
- [Protocol map](https://github.com/boolean-autocrat/glutton/blob/main/protocols/protocols.go): dispatch table · Routes traffic to the selected protocol handler · `protocols/protocols.go`
- [TCP emulators](https://github.com/boolean-autocrat/glutton/blob/main/protocols/tcp/tcp.go): protocol handlers · Concrete TCP service emulations such as HTTP, SMTP, SMB, RDP, MQTT, and others · `protocols/tcp/tcp.go`
- [UDP emulators](https://github.com/boolean-autocrat/glutton/blob/main/protocols/udp/udp.go): protocol handlers · UDP-side protocol handling and response logic · `protocols/udp/udp.go`
- [Interfaces](https://github.com/boolean-autocrat/glutton/blob/main/protocols/interfaces/interfaces.go): contracts · Shared contracts for honeypot, logger, and protocol components · `protocols/interfaces/interfaces.go`

### Ops

Configuration, policy, and reporting

- [Rules engine](https://github.com/boolean-autocrat/glutton/blob/main/rules/rules.go): policy · Config-driven matching and behavior selection · `rules/rules.go`
- [Config files](https://github.com/boolean-autocrat/glutton/blob/main/config/config.yaml): configuration · Schema and YAML inputs for rules and runtime behavior · `config/config.yaml`
- [Producer](https://github.com/boolean-autocrat/glutton/blob/main/producer/producer.go): telemetry output · Event logging and outbound observation emission · `producer/producer.go`
- [Logger](https://github.com/boolean-autocrat/glutton/blob/main/producer/logger.go): logging · Structured logging backend used by the producer · `producer/logger.go`

## Connections

- App entry → Server core: starts · Entrypoint launches the server runtime
- Server core → Glutton core: wires · Server bootstrap delegates to core orchestration
- Glutton core → System setup: prepares · Core runtime prepares the host environment
- System setup → Traffic redirect: redirects · System setup installs packet interception rules
- Traffic redirect → Scanner: hands off · Redirected traffic is delivered into the capture path
- Scanner → Connection flow: normalizes · Incoming sockets and bytes are wrapped into a session model
- Connection flow → Peek router: feeds · Normalized traffic is inspected for protocol identity
- Peek router → Protocol map: selects · Peek results determine the handler route
- Protocol map → TCP emulators: dispatches · TCP traffic goes to service emulators
- Protocol map → UDP emulators: dispatches · UDP traffic goes to datagram handlers
- Rules engine → Protocol map: influences · Policy can steer classification and response behavior
- Config files → Rules engine: loads · Rules and schema drive runtime policy
- TCP emulators → Producer: reports · Emulated sessions emit observations
- UDP emulators → Producer: reports · UDP interactions emit observations
- Producer → Logger: logs via · Producer sends structured output to logging backend
- Interfaces → Protocol map: defines · Shared interfaces constrain dispatch and handlers
- Interfaces → Producer: defines · Shared interfaces support output and honeypot integration
