DECNET

A honeypot/deception network framework. Deploys fake machines (deckies) with realistic services (SSH, SMB, RDP, FTP, HTTP) that appear as real LAN hosts — complete with their own MACs and IPs — to lure, detect, and profile attackers. All interactions are forwarded to an isolated logging pipeline (ELK / SIEM).

attacker ──► decoy network (deckies)
                   │
                   └──► log forwarder ──► isolated SIEM (ELK)

---

Requirements

• Python ≥ 3.11
• Docker + Docker Compose
• Root / sudo for MACVLAN networking (bare metal or VM recommended; WSL has known limitations)

---

Install

pip install -e .

---

Usage

# List available honeypot service plugins
decnet services

# Dry-run — generate compose file, no containers started
decnet deploy --mode unihost --deckies 3 --randomize-services --dry-run

# Deploy 5 deckies with random services
sudo decnet deploy --mode unihost --deckies 5 --interface eth0 --randomize-services

# Deploy with specific services and log forwarding
sudo decnet deploy --mode unihost --deckies 3 --services ssh,smb --log-target 192.168.1.5:5140

# Deploy from an INI config file
sudo decnet deploy --config decnet.ini

# Status
decnet status

# Teardown
sudo decnet teardown --all
sudo decnet teardown --id decky-01

Key flags

Flag	Description
--mode	unihost (single host) or swarm (multi-host)
--deckies N	Number of fake machines to spin up
--interface	Host NIC (auto-detected if omitted)
--subnet	LAN subnet CIDR (auto-detected if omitted)
--ip-start	First decky IP (auto if omitted)
--services	Comma-separated list: ssh,smb,rdp,ftp,http
--randomize-services	Assign random service mix to each decky
--log-target	Forward logs to ip:port (e.g. Logstash)
--dry-run	Generate compose file without starting containers
--no-cache	Force rebuild all images
--config	Path to INI config file

---

Deployment Modes

UNIHOST — one real host spins up n deckies via Docker Compose. Simplest setup, single machine.

SWARM (MULTIHOST) — n real hosts each running deckies. Orchestrated via Ansible or similar tooling.

---

Architecture

• Containers: Docker Compose with debian:bookworm-slim as the default base image. Mixing Ubuntu, CentOS, and other distros is encouraged to make the decoy network look heterogeneous.
• Networking: MACVLAN/IPVLAN — each decky gets its own MAC and IP, appearing as a distinct real machine on the LAN.
• Log pipeline: Logstash → ELK stack → SIEM on an isolated network unreachable from the decoy network.
• Services: Plugin-based registry (decnet/services/). Each plugin declares its ports, default image, and container config.

decnet/
├── cli.py            # Typer CLI — deploy, status, teardown, services
├── config.py         # Pydantic models (DecnetConfig, DeckyConfig)
├── composer.py       # Docker Compose YAML generator
├── deployer.py       # Container lifecycle management
├── network.py        # IP allocation, interface/subnet detection
├── ini_loader.py     # INI config file support
├── logging/
│   └── forwarder.py  # Log target probe + forwarding
└── services/
    ├── registry.py   # Plugin registry
    ├── ssh.py
    ├── smb.py
    ├── rdp.py
    ├── ftp.py
    └── http.py

---

INI Config

You can describe a fully custom decoy fleet in an INI file instead of CLI flags:

[global]
interface = eth0
log_target = 192.168.1.5:5140

[decky-01]
services = ssh,smb
base_image = debian:bookworm-slim
hostname = DESKTOP-A1B2C3

[decky-02]
services = rdp,http
base_image = ubuntu:22.04
hostname = WIN-SERVER-02

sudo decnet deploy --config decnet.ini

---

Adding a Service Plugin

1. Create decnet/services/yourservice.py implementing the BaseService interface.
2. Register it in decnet/services/registry.py.
3. Verify with decnet services.