# datasoft/honeyd architecture

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

- Interactive diagram: https://gitdiagram.com/datasoft/honeyd
- Repository: https://github.com/datasoft/honeyd

## Overview

##### Project Type and Purpose
- Honeyd is a network honeypot daemon written in C with optional Python extensions.
- Purpose: create and emulate multiple “virtual hosts” on a LAN, simulate TCP/IP stacks and arbitrary services, or proxy connections to real services.

##### File Structure
Top‐level components:
- Core daemon (honeyd.c, network.c/h, arp.c/h, tcp.c/h, udp.c/h, parse.c/y, config.c, condition.c)
- Subsystems folder (subsystems/smtp, subsystems/proxy, etc.): service‐specific simulation modules, each with a _main entry and message definitions.
- Plugin support (plugins.c/h, plugins_config.c/h) for dynamic loading of protocol handlers.
- Packet libraries:
– pcap capture/injection: pypcap/, dpkt/
– packet creation: libdnet via compat/libdnet
– event loop: libevent
– regex: libpcre (optional)
- CLI/control tools: honeydctl.c, hsniff.c, honeydstats.c
- Web UI: webserver/ (server.py, support.py, htmltmpl.py, static templates & CSS)
- Regression/tests: regress/
- Scripts & sample configurations: scripts/, sample-config/

##### Insights from README
- Relies on raw sockets (packet sniffing/injection) and event‐based dispatch (libevent).
- Configuration file drives which virtual hosts exist, which services they expose, OS personalities.
- Can drop privileges and run chrooted.
- Optional Python modules for scripting, testing, web UI.

##### Main Components & Relationships
a. Packet I/O Layer
- OS Kernel interfaces → libpcap & libdnet → packet capture/injection
b. Event Dispatcher
- libevent-based loop schedules read/write events on raw sockets
c. Core Engine
- Packet parser (parse.c/y) decodes Ethernet/IP/TCP/UDP
- Configuration manager (config.c, condition.c) matches packets to virtual host definitions
- Personality engine adapts TCP/IP responses to mimic OS behavior
d. Subsystem Manager
- Loads each subsystem (SMTP, Proxy, etc.) via plugins.c → calls subsystem_main for connection handling
- Plugins return crafted payloads or forward traffic to real backend
e. Logging & Stats
- log.c collects events, honeydstats aggregates, rrdtool.c optionally generates graphs
f. Control & Management
- honeydctl CLI for runtime commands (start/stop hosts, stats)
- hsniff for live packet dumps
g. Web Interface
- Python-based simple HTTP server (webserver/server.py)
- Serves dynamic pages (status, graphs) using templates
h. Test & Regression Framework
- Python scripts under regress/ drive automated consistency tests

##### Architectural Patterns & Principles
- Modular design with clear separation: network I/O, parsing, configuration, subsystems, logging, UI.
- Plugin/subsystem architecture: new protocols or behaviors can be added without touching core.
- Event-driven loop decouples packet arrival from business logic.
- Multi-language: core C for performance, Python for extensibility/UI/testing.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Network I/O Layer
    subgraph "Network I/O Layer"
        direction TB
        Kernel["OS Kernel / Raw Sockets"]:::network
        PacketIO["Packet I/O<br/>(libpcap, libdnet)"]:::network
    end

    %% Event Dispatcher
    subgraph "Event Dispatcher"
        direction TB
        EventLoop["Event Loop<br/>(libevent)"]:::network
    end

    %% Core Engine
    subgraph "Core Engine"
        direction TB
        Daemon["honeyd.c (Entry Point)"]:::core
        Parser["Packet Parser<br/>(parse.c/y, arp.c/h, ethernet.c/h,<br/>ipfrag.c/h, tcp.c/h, udp.c/h)"]:::core
        Personality["Personality Emulation<br/>(personality.c/h)"]:::core
        Dispatch["Main Dispatcher<br/>(daemon.c)"]:::core
    end

    %% Configuration Manager
    subgraph "Configuration Manager"
        direction TB
        ConfigMgr["Config Manager<br/>(config.c, condition.c,<br/>config.sample)"]:::core
    end

    %% Subsystem & Plugin Manager
    subgraph "Subsystem & Plugin Manager"
        direction TB
        PluginLoader["Plugin Loader<br/>(plugins.c/h, plugins_config.c/h)"]:::core
        SubsystemIface["Subsystem Interface<br/>(subsystem.c/h)"]:::core
        SMTP["SMTP Subsystem<br/>(subsystems/smtp_*.c/h)"]:::core
        Proxy["Proxy Subsystem<br/>(subsystems/proxy_*.c/h)"]:::core
    end

    %% Logging & Metrics
    subgraph "Logging & Metrics"
        direction TB
        Logging["Logging Core<br/>(log.c/h)"]:::core
        Stats["Statistics<br/>(stats.c/h,<br/>honeydstats*.c/h)"]:::core
        RRD["RRDTool Support<br/>(rrdtool.c/h)"]:::core
        Hist["Histograms<br/>(histogram.c/h)"]:::core
    end

    %% Interfaces
    subgraph "Interfaces"
        direction TB
        CLI["CLI Tools<br/>(honeydctl.c, hsniff.c, analyze.c)"]:::interface
        WebUI["Web UI Server<br/>(webserver/server.py,<br/>support.py, htmltmpl.py)"]:::interface
    end

    %% Testing & Regression
    subgraph "Testing & Regression"
        direction TB
        Regression["Regression Harness<br/>(regress/*.py)"]:::test
    end

    %% Sample Config & Scripts
    SampleConfig["Sample Config & Scripts<br/>(sample-config/, scripts/)"]:::core

    %% Connections
    Kernel -->|"Raw Packet"| PacketIO
    PacketIO -->|"Captured Packet"| EventLoop
    EventLoop -->|"Event"| Dispatch
    Dispatch --> Parser
    Parser --> ConfigMgr
    ConfigMgr --> SubsystemIface
    Dispatch --> Personality
    Personality --> SubsystemIface
    SubsystemIface --> SMTP
    SubsystemIface --> Proxy
    SMTP -->|"Generated Response"| PacketIO
    Proxy -->|"Proxied Traffic"| PacketIO
    Dispatch --> Logging
    Dispatch --> Stats
    Stats --> RRD
    Stats --> Hist
    CLI -- Control Command --> Dispatch
    WebUI -- UI Command / Metric Query --> Dispatch
    WebUI -- Metric Query --> Stats
    Regression -- Test Events --> Dispatch
    Regression -- Packet Injection --> PacketIO
    SampleConfig --> ConfigMgr

    %% Click Events
    click PacketIO "https://github.com/datasoft/honeyd/blob/master/compat/libdnet/dnet.h"
    click PacketIO "https://github.com/datasoft/honeyd/tree/master/pypcap/"
    click PacketIO "https://github.com/datasoft/honeyd/tree/master/dpkt/"
    click EventLoop "https://github.com/datasoft/honeyd/blob/master/network.c"
    click EventLoop "https://github.com/datasoft/honeyd/blob/master/network.h"
    click Daemon "https://github.com/datasoft/honeyd/blob/master/honeyd.c"
    click Parser "https://github.com/datasoft/honeyd/blob/master/parse.c"
    click Parser "https://github.com/datasoft/honeyd/blob/master/parse.y"
    click Parser "https://github.com/datasoft/honeyd/blob/master/parse.h"
    click Parser "https://github.com/datasoft/honeyd/blob/master/arp.c"
    click Parser "https://github.com/datasoft/honeyd/blob/master/arp.h"
    click Parser "https://github.com/datasoft/honeyd/blob/master/ethernet.c"
    click Parser "https://github.com/datasoft/honeyd/blob/master/ethernet.h"
    click Parser "https://github.com/datasoft/honeyd/blob/master/ipfrag.c"
    click Parser "https://github.com/datasoft/honeyd/blob/master/ipfrag.h"
    click Parser "https://github.com/datasoft/honeyd/blob/master/tcp.c"
    click Parser "https://github.com/datasoft/honeyd/blob/master/tcp.h"
    click Parser "https://github.com/datasoft/honeyd/blob/master/udp.c"
    click Parser "https://github.com/datasoft/honeyd/blob/master/udp.h"
    click Dispatch "https://github.com/datasoft/honeyd/blob/master/daemon.c"
    click Personality "https://github.com/datasoft/honeyd/blob/master/personality.c"
    click Personality "https://github.com/datasoft/honeyd/blob/master/personality.h"
    click ConfigMgr "https://github.com/datasoft/honeyd/blob/master/config.c"
    click ConfigMgr "https://github.com/datasoft/honeyd/blob/master/condition.c"
    click ConfigMgr "https://github.com/datasoft/honeyd/blob/master/config.sample"
    click PluginLoader "https://github.com/datasoft/honeyd/blob/master/plugins.c"
    click PluginLoader "https://github.com/datasoft/honeyd/blob/master/plugins.h"
    click PluginLoader "https://github.com/datasoft/honeyd/blob/master/plugins_config.c"
    click PluginLoader "https://github.com/datasoft/honeyd/blob/master/plugins_config.h"
    click SubsystemIface "https://github.com/datasoft/honeyd/blob/master/subsystem.c"
    click SubsystemIface "https://github.com/datasoft/honeyd/blob/master/subsystem.h"
    click SMTP "https://github.com/datasoft/honeyd/blob/master/subsystems/smtp.c"
    click SMTP "https://github.com/datasoft/honeyd/blob/master/subsystems/smtp.h"
    click SMTP "https://github.com/datasoft/honeyd/blob/master/subsystems/smtp_main.c"
    click SMTP "https://github.com/datasoft/honeyd/blob/master/subsystems/smtp_messages.h"
    click Proxy "https://github.com/datasoft/honeyd/blob/master/subsystems/proxy.c"
    click Proxy "https://github.com/datasoft/honeyd/blob/master/subsystems/proxy.h"
    click Proxy "https://github.com/datasoft/honeyd/blob/master/subsystems/proxy_main.c"
    click Proxy "https://github.com/datasoft/honeyd/blob/master/subsystems/proxy_messages.h"
    click Logging "https://github.com/datasoft/honeyd/blob/master/log.c"
    click Logging "https://github.com/datasoft/honeyd/blob/master/log.h"
    click Stats "https://github.com/datasoft/honeyd/blob/master/stats.c"
    click Stats "https://github.com/datasoft/honeyd/blob/master/stats.h"
    click Stats "https://github.com/datasoft/honeyd/blob/master/honeydstats.c"
    click Stats "https://github.com/datasoft/honeyd/blob/master/honeydstats.h"
    click Stats "https://github.com/datasoft/honeyd/blob/master/honeydstats_main.c"
    click RRD "https://github.com/datasoft/honeyd/blob/master/rrdtool.c"
    click RRD "https://github.com/datasoft/honeyd/blob/master/rrdtool.h"
    click Hist "https://github.com/datasoft/honeyd/blob/master/histogram.c"
    click Hist "https://github.com/datasoft/honeyd/blob/master/histogram.h"
    click CLI "https://github.com/datasoft/honeyd/blob/master/honeydctl.c"
    click CLI "https://github.com/datasoft/honeyd/blob/master/hsniff.c"
    click CLI "https://github.com/datasoft/honeyd/blob/master/hsniff.h"
    click CLI "https://github.com/datasoft/honeyd/blob/master/analyze.c"
    click CLI "https://github.com/datasoft/honeyd/blob/master/analyze.h"
    click WebUI "https://github.com/datasoft/honeyd/blob/master/webserver/server.py"
    click WebUI "https://github.com/datasoft/honeyd/blob/master/webserver/support.py"
    click WebUI "https://github.com/datasoft/honeyd/blob/master/webserver/htmltmpl.py"
    click WebUI "https://github.com/datasoft/honeyd/tree/master/webserver/htdocs/"
    click Regression "https://github.com/datasoft/honeyd/tree/master/regress/"

    %% Styles
    classDef network fill:#E0F7FA,stroke:#00796B,color:#004D40
    classDef core fill:#E8F5E9,stroke:#388E3C,color:#1B5E20
    classDef interface fill:#FFF3E0,stroke:#F57C00,color:#E65100
    classDef test fill:#ECEFF1,stroke:#546E7A,color:#37474F
```
