commit 0ae2d09b41054a40b3592dc36c9c27c751c9cec9 Author: anti Date: Sat Apr 18 06:03:38 2026 -0400 docs(wiki): add Unit 3 CLI reference page diff --git a/CLI-Reference.md b/CLI-Reference.md new file mode 100644 index 0000000..a56b37d --- /dev/null +++ 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.