docs(wiki): add Unit 3 CLI reference page

2026-04-18 06:03:38 -04:00
commit 0ae2d09b41
1 changed files with 434 additions and 0 deletions
--- a/CLI-Reference.md
+++ b/CLI-Reference.md
@@ -0,0 +1,434 @@
+# CLI Reference
+
+Every `decnet` subcommand is a Typer command in [`decnet/cli.py`](https://git.resacachile.cl/anti/DECNET/src/branch/main/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](INI-Config-Format) · [Systemd](Systemd-Setup) · [Teardown and state](Teardown-and-State) · [Mutation](Mutation-and-Randomization).
+
+---
+
+## 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](INI-Config-Format)). |
+| `--api` | bool | `False` | Also start the FastAPI backend. |
+| `--api-port` | int | `8000` | Backend API port. |
+| `--daemon` | bool | `False` | Detach to background. |
+
+**Examples:**
+
+```bash
+sudo decnet deploy --mode unihost --deckies 5 --interface eth0 --randomize-services
+sudo decnet deploy --mode unihost --deckies 3 --services ssh,smb --log-target 192.168.1.5:5140
+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](Mutation-and-Randomization).
+
+---
+
+## 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:**
+
+```bash
+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:**
+
+```bash
+sudo decnet teardown --all
+sudo decnet teardown --id decky-01
+```
+
+**Notes:** root. Exits `1` if neither flag is passed. See [Teardown and state](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:**
+
+```bash
+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:**
+
+```bash
+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:**
+
+```bash
+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:**
+
+```bash
+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:**
+
+```bash
+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](Mutation-and-Randomization).
+
+**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:**
+
+```bash
+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:**
+
+```bash
+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:**
+
+```bash
+decnet services
+```
+
+---
+
+## decnet archetypes
+
+`decnet/cli.py:683`
+
+List machine archetypes (service bundles + fingerprints).
+
+**Usage:** `decnet archetypes`
+
+**Example:**
+
+```bash
+decnet archetypes
+```
+
+---
+
+## decnet distros
+
+`decnet/cli.py:611`
+
+List available OS distro profiles for deckies.
+
+**Usage:** `decnet distros`
+
+**Example:**
+
+```bash
+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:**
+
+```bash
+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:**
+
+```bash
+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 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:**
+
+```bash
+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. |
+
+See `env.config.example` at the repo root for full defaults.