# mushorg/glutton architecture

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

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

## Overview

##### Project type and purpose
- Glutton is a network‐level, protocol‐agnostic, low‐interaction honeypot written in Go.
- It intercepts all inbound traffic using iptables+TPROXY, demultiplexes by protocol, then logs or “replays” minimal responses to adversaries.

##### File structure
Top‐level folders
- app/              – main server bootstrap (app/server.go)
- connection/       – connection lifecycle manager (accept, close, timeouts)
- protocols/        – protocol handlers (tcp/, udp/), protocol‐agnostic interfaces & mocks
- scanner/          – packet inspection / payload scanner
- producer/         – logging/telemetry output (e.g., JSON, file, network sinks)
- rules/            – rules engine determining handshake behavior, drop/accept logic
- config/           – YAML/JSON schemas and default policy files
- docs/             – human‐readable usage & extension guides
Other important files
- glutton.go        – root CLI entry point
- server.go         – core server loop, TPROXY / iptables integration (system.go, iptables.go)
- Makefile/Dockerfile(s) – build and deployment automations
- .github/           – CI pipelines, funding, release workflows

##### README
- Confirms honeypot purpose, Go language, iptables+TPROXY interception.
- Links to full docs detailing setup, configuration, extension API.

##### Main components
a. Network Interception Layer
- iptables + TPROXY (kernel components)
- redirect traffic to userland socket (UDP/TCP)
b. Glutton Core Server
- CLI/entry (glutton.go) → initializes config, rules, producers
- Packet Receiver (server.go/system.go)
- Connection Manager (connection package)
c. Packet Scanner
- scanner package inspects payload, identifies protocol anomalies
d. Protocol Dispatcher & Handlers
- protocols package (interfaces, helpers)
- tcp/ and udp/ submodules, each handler implements a common interface
e. Rules Engine
- rules package loads config/rules.yaml, decides response strategy
f. Producer/Logger
- producer package formats and emits events to chosen sinks (file, JSON, remote)
g. Configuration Store
- config folder: config.yaml, schema.json, rules.yaml
h. External Services (optional)
- ELK/Graylog, InfluxDB, or any SIEM/log aggregator

##### Relationships & data flow
1. Incoming packets hit iptables → TPROXY → redirected to Glutton UDP/TCP sockets
2. Core server receives raw packets → passes to scanner
3. Scanner tags protocol type → dispatch to protocols dispatcher
4. Connection Manager wraps dispatch, applies timeouts, tracking
5. Protocol handler consults rules engine for handshake/interaction policy
6. Interaction events sent to Producer/Logger
7. Producer writes to disk or forwards to external log system

##### Architectural patterns & principles
- Modular plugin‐style protocol handlers (protocols/interfaces)
- Dependency injection for logger & honeypot modules (via mockery mocks)
- Configuration‐driven rules & schema validation
- Separation of concerns: network I/O, scanning, protocol logic, output

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Network Interception Layer"
        IPT["iptables.go"]:::network
        SYS["system.go"]:::network
    end

    subgraph "Core Application"
        GL["glutton.go"]:::core
        APP["app/server.go"]:::core
        SV["server.go"]:::core
        CM["connection/connection.go"]:::core
        SC["scanner/scanner.go"]:::core
    end

    subgraph "Protocols"
        PD["protocols/protocols.go"]:::protocol
        PK["protocols/peek.go"]:::protocol
        IF["protocols/interfaces/interfaces.go"]:::protocol
        HP["protocols/helpers/helpers.go"]:::protocol
        subgraph "TCP Handlers"
            TCP["protocols/tcp/"]:::protocol
        end
        UDPH["protocols/udp/udp.go"]:::protocol
    end

    RULE["rules/rules.go"]:::rules
    PROD["producer/producer.go\nproducer/logger.go"]:::producer
    CONFIG[(config/config.yaml\nschema.json\nrules.yaml)]:::config
    EXT["External SIEM/Log Aggregator"]:::external

    IPT --> SV
    SYS --> SV
    SV --> CM
    CM --> SC
    SC --> PD
    PD --> RULE
    RULE --> TCP
    RULE --> UDPH
    TCP --> PROD
    UDPH --> PROD
    PROD --> EXT
    GL --> CONFIG
    RULE --> CONFIG

    click IPT "https://github.com/mushorg/glutton/blob/main/iptables.go"
    click SYS "https://github.com/mushorg/glutton/blob/main/system.go"
    click GL "https://github.com/mushorg/glutton/blob/main/glutton.go"
    click APP "https://github.com/mushorg/glutton/blob/main/app/server.go"
    click SV "https://github.com/mushorg/glutton/blob/main/server.go"
    click CM "https://github.com/mushorg/glutton/blob/main/connection/connection.go"
    click SC "https://github.com/mushorg/glutton/blob/main/scanner/scanner.go"
    click PD "https://github.com/mushorg/glutton/blob/main/protocols/protocols.go"
    click PK "https://github.com/mushorg/glutton/blob/main/protocols/peek.go"
    click IF "https://github.com/mushorg/glutton/blob/main/protocols/interfaces/interfaces.go"
    click HP "https://github.com/mushorg/glutton/blob/main/protocols/helpers/helpers.go"
    click TCP "https://github.com/mushorg/glutton/tree/main/protocols/tcp/"
    click UDPH "https://github.com/mushorg/glutton/blob/main/protocols/udp/udp.go"
    click RULE "https://github.com/mushorg/glutton/blob/main/rules/rules.go"
    click PROD "https://github.com/mushorg/glutton/blob/main/producer/producer.go"
    click CONFIG "https://github.com/mushorg/glutton/blob/main/config/config.yaml"
    click CONFIG "https://github.com/mushorg/glutton/blob/main/config/schema.json"
    click CONFIG "https://github.com/mushorg/glutton/blob/main/config/rules.yaml"

    classDef network fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1;
    classDef core fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20;
    classDef protocol fill:#FFE0B2,stroke:#E65100,color:#E65100;
    classDef rules fill:#FFF9C4,stroke:#F57F17,color:#F57F17;
    classDef producer fill:#E1BEE7,stroke:#4A148C,color:#4A148C;
    classDef config fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20;
    classDef external fill:#E1BEE7,stroke:#4A148C,color:#4A148C;
```
