anti/DECNET
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

wiki: quick start, installation, python versions

anti
2026-04-18 06:03:27 -04:00
commit 5331949184
3 changed files with 268 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
Installation.md Normal file

@@ -0,0 +1,106 @@
# Installation
Full install walkthrough. For the two-minute version see [Quick Start](Quick-Start). For interpreter support see [Requirements and Python Versions](Requirements-and-Python-Versions).
## OS prerequisites
DECNET is Linux-only. It talks directly to the kernel for MACVLAN / IPvlan setup and to the Docker daemon for container orchestration.
| Requirement | Why |
|---|---|
| Linux kernel with MACVLAN or IPvlan | Each decky gets its own MAC (MACVLAN) or unique IP on the shared host MAC (IPvlan). |
| Docker Engine 24+ | Compose v2 plugin, BuildKit, MACVLAN driver stability. |
| `iproute2` (`ip` command) | Used for interface/subnet detection and hairpin interface creation. |
| Root / `sudo` | Required for MACVLAN/IPvlan network creation and sysctl injection. |
| NIC in promiscuous mode **or** `--ipvlan` on WiFi | MACVLAN needs the NIC to accept frames for MACs it does not own; WiFi upstreams typically filter those, so IPvlan L2 is used instead. |
> WSL has MACVLAN limitations. Use bare metal or a VM for honest testing.
## Python virtualenv (recommended)
Always install into a virtualenv. ANTI's house rule: activate `.venv` before every `pip` / `pytest` call in this project.
```bash
cd DECNET
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
```
## Install DECNET
Editable install is the supported path — the CLI is under active development and `-e` keeps it tracking your checkout.
```bash
pip install -e .
```
This installs the `decnet` console script (a Typer app at `decnet/cli.py`) plus the FastAPI dashboard under `decnet/web/`.
## Optional extras
DECNET ships several optional feature groups. Install only what you need.
```bash
pip install -e ".[tracing]" # OpenTelemetry exporters for the ingest pipeline
pip install -e ".[profiling]" # py-spy / scalene hooks for the web API
pip install -e ".[dev]" # pytest, ruff, mypy
```
If an extra is not declared in `pyproject.toml`, pip will error out — check `decnet services` and the [Development and Testing](Development-and-Testing) page for the current set.
## Verifying the install
```bash
decnet --help
decnet services
decnet archetypes
decnet distros
```
- `decnet --help` should list the top-level commands: `deploy`, `status`, `teardown`, `services`, `archetypes`, `distros`, `correlate`, `web`, `api`.
- `decnet services` should print 25 service rows.
Dry-run a deploy to confirm end-to-end wiring without touching the network:
```bash
decnet deploy --mode unihost --deckies 2 --randomize-services --dry-run
```
Run the test suite (if you installed the dev extra):
```bash
python -m pytest
```
## Configuration
Runtime configuration can live in `.env.local` (preferred) or `.env` at the project root. Copy `.env.example` and edit:
```bash
cp .env.example .env.local
```
Details in [Environment Variables](Environment-Variables).
## Uninstall
```bash
pip uninstall decnet
sudo decnet teardown --all # before uninstalling, remove any live deckies
```
If teardown is unavailable (e.g. the package is already gone), remove the MACVLAN network manually:
```bash
docker network ls | grep decnet
docker network rm decnet_macvlan
ip link del decnet_macvlan0 2>/dev/null || true
```
## Next
- [Quick Start](Quick-Start)
- [Networking](Networking-MACVLAN-IPVLAN)
- [Config File](Config-File)
- [Environment Variables](Environment-Variables)

91
Quick-Start.md Normal file

@@ -0,0 +1,91 @@
# Quick Start
Shortest path from a fresh clone to seeing attacker events roll in. For the full install walkthrough (venv, extras, uninstall) see [Installation](Installation). For supported interpreters see [Requirements and Python Versions](Requirements-and-Python-Versions).
## 1. Clone
```bash
git clone https://git.resacachile.cl/anti/DECNET
cd DECNET
```
## 2. Install
```bash
pip install -e .
```
This registers the `decnet` console script and auto-discovers all built-in honeypot service plugins.
## 3. List what is available
```bash
decnet services # all 25 registered honeypot services, with ports and images
decnet archetypes # machine identity profiles (windows-workstation, linux-server, ...)
decnet distros # OS distro profiles (debian, ubuntu22, rocky9, alpine, ...)
```
If `decnet services` prints a table, you are good to go.
## 4. Dry run — generate compose, no containers
A dry run writes the `docker-compose.yml` without starting anything. Use it to confirm the shape of the deployment before putting interfaces into MACVLAN mode.
```bash
decnet deploy --mode unihost --deckies 3 --randomize-services --dry-run
```
## 5. Full deploy
MACVLAN (and IPvlan) require root. The host NIC is auto-detected, but you can pin it with `--interface`.
```bash
sudo decnet deploy --mode unihost --deckies 5 --interface eth0 --randomize-services
```
On WiFi (or any NIC whose upstream filters unknown MACs) pass `--ipvlan`:
```bash
sudo decnet deploy --mode unihost --deckies 3 --interface wlp6s0 --ipvlan --randomize-services
```
To forward every attacker interaction off-box as RFC 5424 syslog:
```bash
sudo decnet deploy --mode unihost --deckies 3 --services ssh,smb --log-target 192.168.1.5:5140
```
See [Networking](Networking-MACVLAN-IPVLAN) for driver selection and [Environment Variables](Environment-Variables) for persistent configuration.
## 6. Check status
```bash
decnet status
```
Prints a table of every deployed decky with its IP, hostname, services, and container state.
## 7. First event
Pick any decky IP from `decnet status` and hit a service. For example:
```bash
ssh root@192.168.1.110 # will be captured by the SSH honeypot
nmap -sV 192.168.1.110 # every probed port logs a banner hit
```
If you passed `--log-target`, your syslog collector receives an RFC 5424 line for the interaction. If not, the events are captured inside each service container's stdout and (optionally) the bind-mounted log file from `--log-file`.
## 8. Tear down
```bash
sudo decnet teardown --all # remove every decky and the MACVLAN network
sudo decnet teardown --id decky-01 # stop and remove a single decky
```
## Next
- [Config File](Config-File) — pin IPs, set per-service personas, use archetype pools.
- [Services](Services) — the 25 built-in honeypots and their tunables.
- [Archetypes](Archetypes) — one-slug identities that set services + OS fingerprint.
- [OS Fingerprint Spoofing](OS-Fingerprint-Spoofing) — make `nmap -O` report the OS you want.

71
Requirements-and-Python-Versions.md Normal file

@@ -0,0 +1,71 @@
# Requirements and Python Versions
The hard requirements for running DECNET, and why the Python ceiling is pinned where it is.
## Supported Python versions
| Version | Status |
|---|---|
| 3.10 and below | Not supported. `pyproject.toml` sets `requires-python = ">=3.11"`. |
| 3.11 | Supported. Minimum version. |
| 3.12 | Supported. Recommended. |
| 3.13 | Supported. |
| 3.14 | **Not supported.** See warning below. |
### Warning: Python 3.14 breaks DECNET under load
Python 3.14's redesigned garbage collector changes finalizer and weakref ordering in ways that destabilise DECNET's concurrency model. Under sustained ingest load (multiple service containers streaming RFC 5424 syslog, the FastAPI dashboard polling the repository, the correlator running background tasks) we observed:
- Deadlocks in the ingest pipeline between the syslog UDP listener and the SQLite repository writer.
- Intermittent loss of weakref'd plugin instances registered by `decnet/services/registry.py`.
- Unbounded memory growth in long-running `decnet web` processes.
Until upstream stabilises or we ship a compat shim, DECNET keeps the ceiling below 3.14. If you manually lift `requires-python` and run under 3.14, do not open a bug report — it is expected to break.
## System packages
| Package | Minimum | Notes |
|---|---|---|
| Linux kernel | 5.x | Needs MACVLAN/IPvlan drivers. WSL has known MACVLAN limitations — prefer bare metal or a VM. |
| Docker Engine | 24.0 | Compose v2 plugin, BuildKit, stable MACVLAN driver. |
| `iproute2` | any recent | `ip link`, `ip addr`, `ip route` — used for interface/subnet detection. |
| Root / `sudo` | — | Network namespace + MACVLAN setup require privilege. |
On Debian/Ubuntu:
```bash
sudo apt install docker.io docker-compose-plugin iproute2 python3.12 python3.12-venv
```
On Fedora/Rocky:
```bash
sudo dnf install docker docker-compose-plugin iproute python3.12
```
## NIC requirements
MACVLAN needs the host NIC to accept frames for MAC addresses it does not own (effectively: promiscuous-capable and not behind a MAC-filtering upstream). WiFi access points typically filter unknown MACs, so use IPvlan L2 there:
```bash
sudo decnet deploy --interface wlp6s0 --ipvlan --deckies 3 --randomize-services
```
See [Networking](Networking-MACVLAN-IPVLAN) for driver selection guidance and troubleshooting.
## Verifying your environment
```bash
python --version # 3.11, 3.12, or 3.13
docker --version # 24+
docker compose version # v2 plugin
ip link # ensure target NIC is listed
```
If any of these fail, fix them before running `decnet deploy` — the CLI will refuse or error confusingly on a missing prerequisite.
## Next
- [Installation](Installation) — venv + extras + verification.
- [Quick Start](Quick-Start) — shortest path to a running deployment.
- [Networking](Networking-MACVLAN-IPVLAN) — MACVLAN vs IPvlan choice.