Initial commit: DECNET honeypot/deception network framework

Core CLI, service plugins (SSH/SMB/FTP/HTTP/RDP), Docker Compose orchestration, MACVLAN networking, and Logstash log forwarding. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-03 18:56:25 -03:00
commit 3e98c71ca4
37 changed files with 1822 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,139 @@
+# 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
+
+```bash
+pip install -e .
+```
+
+---
+
+## Usage
+
+```bash
+# 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:
+
+```ini
+[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
+```
+
+```bash
+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`.