How boolean-autocrat/glutton works
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.go Protocol map · producer.go Producer · interfaces.go Interfaces · server.go Server core
Components 16
Runtime
Process entrypoint and host-level orchestration
- App entry · Binary entrypoint for starting the daemon
app/server.go - Server core · Top-level runtime wiring and server lifecycle
server.go - Glutton core · Main application coordination logic
glutton.go - System setup · Host preparation and environment coordination
system.go - Traffic redirect · iptables and TPROXY interception setup
iptables.go
Protocol Engine
Traffic capture, identification, and service emulation
- Connection flow · Normalized inbound connection and flow abstraction
connection/connection.go - Scanner · Inbound traffic intake and session handling
scanner/scanner.go - Peek router · Inspects initial bytes to identify protocol
protocols/peek.go - Protocol map · Routes traffic to the selected protocol handler
protocols/protocols.go - TCP emulators · Concrete TCP service emulations such as HTTP, SMTP, SMB, RDP, MQTT, and others
protocols/tcp/tcp.go - UDP emulators · UDP-side protocol handling and response logic
protocols/udp/udp.go - Interfaces · Shared contracts for honeypot, logger, and protocol components
protocols/interfaces/interfaces.go
Ops
Configuration, policy, and reporting
- Rules engine · Config-driven matching and behavior selection
rules/rules.go - Config files · Schema and YAML inputs for rules and runtime behavior
config/config.yaml - Producer · Event logging and outbound observation emission
producer/producer.go - Logger · Structured logging backend used by the producer
producer/logger.go
Connections 17
- 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