Table of Contents

CLI Reference

decnet deploy
decnet redeploy
decnet teardown
decnet status
decnet api
decnet web
decnet probe
decnet collect
decnet mutate
decnet correlate
decnet services
decnet archetypes
decnet distros
decnet profiler
decnet sniffer
decnet orchestrate
decnet realism

decnet realism import-personas

decnet db-reset
Env-var summary

CLI Reference

Every decnet subcommand is a Typer command in decnet/cli.py. Flags below are verified against the source. Env-var defaults come from decnet/env.py.

Conventions used throughout:

root? — needs sudo (MACVLAN/IPVLAN, raw sockets, /var/log/decnet writes).
daemon? — supports --daemon / -d and will double-fork via _daemonize().
Related pages: INI format · Systemd · Teardown and state · Mutation.

decnet deploy

decnet/cli.py:128

Build a deception network and bring containers up. Also launches the collector, prober, profiler, sniffer, and (if --mutate-interval is set) the mutator watcher.

Usage: decnet deploy [flags]

Flags:

Flag	Type	Default	Description
`--mode`, `-m`	str	`unihost`	`unihost` or `swarm`.
`--deckies`, `-n`	int	—	Number of deckies. Required unless `--config` is used.
`--interface`, `-i`	str	auto	Host NIC. Auto-detected via `detect_interface()`.
`--subnet`	str	auto	LAN CIDR. Auto-detected via `detect_subnet()`.
`--ip-start`	str	auto	First decky IP.
`--services`	str	—	Comma-separated service slugs (`ssh,smb,rdp`).
`--randomize-services`	bool	`False`	Assign a random service mix to each decky.
`--distro`	str	—	Comma-separated distro slugs (`debian,ubuntu22,rocky9`).
`--randomize-distros`	bool	`False`	Random distro per decky.
`--log-file`	str	`$DECNET_INGEST_LOG_FILE`	Host path for RFC 5424 collector output.
`--archetype`, `-a`	str	—	Archetype slug (see `decnet archetypes`).
`--mutate-interval`	int	`30`	Minutes between auto-mutations.
`--dry-run`	bool	`False`	Generate compose file, do not start containers.
`--no-cache`	bool	`False`	Force image rebuild.
`--parallel`	bool	`False`	Concurrent BuildKit builds.
`--ipvlan`	bool	`False`	IPvlan L2 instead of MACVLAN (WiFi).
`--config`, `-c`	str	—	INI config file (see INI format).
`--api`	bool	`False`	Also start the FastAPI backend.
`--api-port`	int	`8000`	Backend API port.
`--daemon`	bool	`False`	Detach to background.

Examples:

sudo decnet deploy --mode unihost --deckies 5 --interface eth0 --randomize-services
sudo decnet deploy --mode unihost --deckies 3 --services ssh,smb --log-file /var/log/decnet/decnet.log
sudo decnet deploy --config ./fleet.ini --api --api-port 8000
decnet deploy --mode unihost --deckies 3 --randomize-services --dry-run

Notes: requires root for MACVLAN/IPVLAN attachment. On success, side-launches Collector, Prober, Profiler, Sniffer, and Mutator as detached subprocesses. See Mutation.

decnet redeploy

decnet/cli.py:439

Health-check every DECNET microservice and relaunch any that are down.

Usage: decnet redeploy [--log-file PATH]

Flags:

Flag	Type	Default	Description
`--log-file`, `-f`	str	`$DECNET_INGEST_LOG_FILE`	Path passed to relaunched workers.

Example:

sudo decnet redeploy --log-file /var/log/decnet/decnet.log

Notes: non-destructive; prints a status table and restarts only the missing services.

decnet teardown

decnet/cli.py:579

Stop and remove deckies. With --all, also kills every background DECNET service (Collector, Prober, Profiler, Sniffer, Mutator, API).

Usage: decnet teardown [--all | --id NAME]

Flags:

Flag	Type	Default	Description
`--all`	bool	`False`	Tear down all deckies and remove the network.
`--id`	str	—	Tear down a specific decky by name.

Examples:

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

Notes: root. Exits 1 if neither flag is passed. See Teardown and state.

decnet status

decnet/cli.py:556

Print running deckies plus the UP/DOWN status of the six DECNET microservices.

Usage: decnet status

Flags: none.

Example:

decnet status

decnet api

decnet/cli.py:81

Run the FastAPI backend (serves /api/v1/* and mounts the web dashboard if built).

Usage: decnet api [flags]

Flags:

Flag	Type	Default	Description
`--port`	int	`$DECNET_API_PORT`	API listen port.
`--host`	str	`$DECNET_API_HOST`	API bind IP.
`--log-file`	str	`$DECNET_INGEST_LOG_FILE`	Log file to tail.
`--daemon`, `-d`	bool	`False`	Detach to background.
`--workers`, `-w`	int	`1`	Uvicorn worker count (min 1).

Examples:

decnet api --port 8000 --workers 2
decnet api --daemon --log-file /var/log/decnet/decnet.log

Notes: workers run in their own process group so Ctrl+C tears the whole tree down. Env alternatives: DECNET_API_HOST, DECNET_API_PORT, DECNET_INGEST_LOG_FILE.

decnet web

decnet/cli.py:701 (command name: web)

Serve the Vite-built frontend and reverse-proxy /api/* to the backend.

Usage: decnet web [flags]

Flags:

Flag	Type	Default	Description
`--web-port`	int	`$DECNET_WEB_PORT`	Frontend HTTP port.
`--host`	str	`$DECNET_WEB_HOST`	Bind IP.
`--api-port`	int	`$DECNET_API_PORT`	Upstream API port to proxy.
`--daemon`, `-d`	bool	`False`	Detach to background.

Examples:

decnet web --web-port 5173 --api-port 8000
decnet web --daemon

Notes: exits with an error if decnet_web/dist is missing — run npm run build first. Handles SSE streams with disabled socket timeout.

decnet probe

decnet/cli.py:481

Fingerprint attackers discovered in the log stream (JARM + HASSH + TCP/IP stack).

Usage: decnet probe [flags]

Flags:

Flag	Type	Default	Description
`--log-file`, `-f`	str	`$DECNET_INGEST_LOG_FILE`	Reads attackers from `.json` sibling, writes results to both.
`--interval`, `-i`	int	`300`	Seconds between probe cycles.
`--timeout`	float	`5.0`	Per-probe TCP timeout.
`--daemon`, `-d`	bool	`False`	Detach to background.

Examples:

decnet probe --interval 60 --timeout 3
sudo decnet probe --daemon --log-file /var/log/decnet/decnet.log

Notes: auto-launched by decnet deploy. Runs prober_worker under asyncio.

decnet collect

decnet/cli.py:508

Stream Docker logs from every decky service container into a single RFC 5424 syslog file plus a .json index.

Usage: decnet collect [flags]

Flags:

Flag	Type	Default	Description
`--log-file`, `-f`	str	`$DECNET_INGEST_LOG_FILE`	Output path.
`--daemon`, `-d`	bool	`False`	Detach to background.

Example:

decnet collect --log-file /var/log/decnet/decnet.log --daemon

decnet mutate

decnet/cli.py:526

Manually trigger, force, or continuously watch for decky mutation. See Mutation.

Usage: decnet mutate [flags]

Flags:

Flag	Type	Default	Description
`--watch`, `-w`	bool	`False`	Run the watch loop forever.
`--decky`	str	—	Force mutate a specific decky now.
`--all`	bool	`False`	Force mutate every decky now.
`--daemon`, `-d`	bool	`False`	Detach to background.

Examples:

decnet mutate --watch
decnet mutate --decky decky-03
decnet mutate --all

Notes: --watch is the mode auto-launched by deploy. With no flags, runs mutate_all(force=False) once.

decnet correlate

decnet/cli.py:623

Analyse a syslog file (or stdin) and print cross-decky attacker traversals.

Usage: decnet correlate [flags]

Flags:

Flag	Type	Default	Description
`--log-file`, `-f`	str	—	Syslog file to ingest.
`--min-deckies`, `-m`	int	`2`	Minimum deckies an IP must touch to be reported.
`--output`, `-o`	str	`table`	`table`, `json`, or `syslog`.
`--emit-syslog`	bool	`False`	Also print RFC 5424 traversal events.
`--daemon`, `-d`	bool	`False`	Detach to background.

Examples:

decnet correlate -f /var/log/decnet/decnet.log -m 3
cat /var/log/decnet/decnet.log | decnet correlate --output json

Notes: exits 1 if neither --log-file nor piped stdin is provided.

decnet services

decnet/cli.py:598 (command name: services)

List every registered honeypot service plugin, with ports and default image.

Usage: decnet services

Example:

decnet services

decnet archetypes

decnet/cli.py:683

List machine archetypes (service bundles + fingerprints).

Usage: decnet archetypes

Example:

decnet archetypes

decnet distros

decnet/cli.py:611

List available OS distro profiles for deckies.

Usage: decnet distros

Example:

decnet distros

decnet profiler

decnet/cli.py:817

Run the attacker profiler as a standalone microservice (rebuilds behaviour profiles from indexed events).

Usage: decnet profiler [flags]

Flags:

Flag	Type	Default	Description
`--interval`, `-i`	int	`30`	Seconds between rebuild cycles.
`--daemon`, `-d`	bool	`False`	Detach to background.

Examples:

decnet profiler --interval 15
decnet profiler --daemon

Notes: initialises the shared repo via DI (web.dependencies.repo).

decnet sniffer

decnet/cli.py:844

Run the passive network sniffer as a standalone microservice.

Usage: decnet sniffer [flags]

Flags:

Flag	Type	Default	Description
`--log-file`, `-f`	str	`$DECNET_INGEST_LOG_FILE`	Output syslog + JSON path.
`--daemon`, `-d`	bool	`False`	Detach to background.

Examples:

sudo decnet sniffer --log-file /var/log/decnet/decnet.log
sudo decnet sniffer --daemon

Notes: needs root (raw sockets via scapy). Probes the ipvlan/macvlan host interface automatically.

decnet orchestrate

decnet/cli/orchestrator.py:10

Run the orchestrator worker — the long-lived loop that injects synthetic life into the running fleet (inter-decky SSH traffic, file plants and edits, fake corporate email drops). After the realism migration this single command covers what decnet orchestrate and decnet emailgen run did separately; both decnet-emailgen.service and the standalone CLI are gone.

Usage: decnet orchestrate [flags]

Flags:

Flag	Type	Default	Description
`--interval`, `-i`	int (seconds)	`60`	Time between ticks. Each tick rolls one action across the weighted set `traffic` (45%) / `file` (45%) / `email` (10%).
`--daemon`, `-d`	bool	`False`	Detach to background. Skip under systemd; the unit supervises directly.
`--llm` / `--no-llm`	bool	env-driven	Enable or disable LLM enrichment of user-class file bodies. Default reads `$DECNET_REALISM_LLM` (any non-empty / non-`off` value enables). When the LLM is unreachable, a process-local circuit breaker trips after 3 consecutive failures and the worker falls back to deterministic templates for 60 s.

Examples:

decnet orchestrate                       # 60s tick, env decides LLM
decnet orchestrate --interval 30         # double the rate
decnet orchestrate --no-llm              # force template-only, ignore env
DECNET_REALISM_LLM=ollama decnet orchestrate

See Realism for content classes, the persona pool, and how canary cultivation hooks into the same planner.

decnet realism

decnet/cli/realism.py:25

Maintenance commands for the realism content engine. The only sub-command currently is import-personas. There is no decnet realism run — the long-lived worker is decnet orchestrate.

decnet realism import-personas

Validate and install a JSON file as the host-wide global persona pool. Used for fleet (MACVLAN/IPVLAN) and SWARM-shard deckies that have no parent topology row. MazeNET-topology deckies use Topology.email_personas instead.

Usage: decnet realism import-personas <PATH> [--output PATH]

Flags:

Flag	Type	Default	Description
`--output`, `-o`	path	resolved global pool	Override the destination. Defaults to `$DECNET_REALISM_PERSONAS`, then `/etc/decnet/email_personas.json`, then `~/.decnet/email_personas.json`.

Examples:

decnet realism import-personas ./personas.json
decnet realism import-personas ./personas.json -o ~/.decnet/email_personas.json

The validator parses every entry into the EmailPersona schema (decnet/realism/personas.py), drops invalid entries with a warning, refuses to write when no entries are valid, and warns when fewer than two entries land (the email path needs at least two for sender/recipient pairs). Master-only — gated by DECNET_MODE=master.

decnet db-reset

decnet/cli.py:930

Destructive MySQL wipe. Refuses to run on SQLite. Dry-run by default.

Usage: decnet db-reset [flags]

Flags:

Flag	Type	Default	Description
`--i-know-what-im-doing`	bool	`False`	Required to actually commit the wipe.
`--mode`	str	`truncate`	`truncate` (keep schema) or `drop-tables`.
`--url`	str	—	Override `DECNET_DB_URL` for this invocation.

Examples:

decnet db-reset                                   # dry-run, shows row counts
decnet db-reset --mode drop-tables --i-know-what-im-doing
DECNET_DB_URL=mysql+asyncmy://... decnet db-reset --i-know-what-im-doing

Notes: requires DECNET_DB_TYPE=mysql. Tables wiped in FK-safe order: attacker_behavior, attackers, logs, bounty, state, users. Falls back to build_mysql_url() from DECNET_DB_HOST/PORT/NAME/USER/PASSWORD when no DSN is given.

Env-var summary

Var	Used by	Purpose
`DECNET_API_HOST`	`api`, `deploy --api`	API bind host.
`DECNET_API_PORT`	`api`, `web`, `deploy --api`	API port.
`DECNET_WEB_HOST`	`web`	Dashboard bind host.
`DECNET_WEB_PORT`	`web`	Dashboard port.
`DECNET_INGEST_LOG_FILE`	`deploy`, `collect`, `probe`, `sniffer`, `api`, `redeploy`	Collector output path.
`DECNET_DB_TYPE`	`db-reset`	`mysql` or `sqlite`.
`DECNET_DB_URL`	`db-reset`	Full async DSN.
`DECNET_DB_HOST/PORT/NAME/USER/PASSWORD`	`db-reset`	Fallback DSN components.
`DECNET_REALISM_LLM`	`orchestrate`	LLM backend selector (`ollama` / `fake` / `off`). Default: empty (LLM disabled, templates only).
`DECNET_REALISM_MODEL`	`orchestrate`	Model name for the Ollama backend. Default: `llama3.1`.
`DECNET_REALISM_TIMEOUT`	`orchestrate`	Per-call wall-clock cap. Default: `60`.
`DECNET_REALISM_PERSONAS`	`orchestrate`, `realism import-personas`	Global persona pool path override.
`DECNET_CANARY_HTTP_BASE`	`orchestrate` (canary cultivator), `canary` worker	HTTP callback base URL for cultivated canary artifacts.
`DECNET_CANARY_DNS_ZONE`	`orchestrate` (canary cultivator), `canary` worker	DNS zone for callback subdomains.

See env.config.example at the repo root for full defaults.

DECNET

Home

User docs

Developer docs

Project meta

DECNET — honeypot deception-network framework. Pre-1.0, active development — use with caution. See Sponsors to support the project. Contact: samuel@securejump.cl