Covers how it works, requirements, installation, quick start, full CLI
reference, archetypes table, services table, OS fingerprint spoofing,
distro profiles, INI config file format with field reference, logging,
network drivers (MACVLAN vs IPvlan), architecture overview, plugin
authoring guide, and test suite summary.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- ini_loader.py: DeckySpec gains nmap_os field; load_ini parses nmap_os=
(also accepts nmap-os= hyphen alias) and propagates it to amount-expanded deckies
- cli.py: _build_deckies_from_ini resolves nmap_os with priority:
explicit INI key > archetype default > "linux"
- test-full.ini: every decky now carries nmap_os=; [windows-workstation]
gains archetype= so its OS family is set correctly; decky-winbox/fileserv/
ldapdc → windows, decky-iot → embedded, decky-legacy → bsd, rest → linux
- tests/test_ini_loader.py: 7 new tests covering nmap_os parsing, defaults,
hyphen alias, and amount= expansion propagation
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Each decky base container now receives a set of Linux kernel sysctls
(net.ipv4.ip_default_ttl, net.ipv4.tcp_syn_retries, etc.) tuned to
match the claimed OS family, making nmap OS detection return the
expected OS rather than the Linux host.
- decnet/os_fingerprint.py: OS profile table (linux/windows/bsd/embedded/cisco)
keyed by TTL and TCP tuning knobs
- decnet/archetypes.py: Archetype gains nmap_os field; windows-* → "windows",
printer/iot/industrial → "embedded", rest → "linux"
- decnet/config.py: DeckyConfig gains nmap_os field (default "linux")
- decnet/cli.py: nmap_os resolved from archetype → DeckyConfig in both CLI
and INI build paths
- decnet/composer.py: base container gets sysctls + cap_add: [NET_ADMIN];
service containers inherit via shared network namespace
- tests/test_os_fingerprint.py: 48 new tests covering profiles, compose
injection, archetype coverage, and CLI propagation
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Introduces archetype profiles (windows-workstation, linux-server,
domain-controller, printer, iot-device, etc.) so users get a realistic
service+distro combination without knowing which services to pick.
Adds amount= to INI config (and CLI --archetype) so a single section
can spawn N identical deckies without copy-paste. Per-service subsections
(e.g. [group.ssh]) propagate to all expanded instances automatically.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
MACVLAN assigns unique MACs per container; WiFi APs typically reject
frames from unregistered MACs, making deckies unreachable from other
LAN devices. IPvlan L2 shares the host's MAC, so all traffic passes
through the AP normally.
- network.py: add create_ipvlan_network, setup_host_ipvlan,
teardown_host_ipvlan, HOST_IPVLAN_IFACE
- config.py: add ipvlan: bool = False to DecnetConfig (persisted to
state so teardown uses the right driver)
- deployer.py: branch on config.ipvlan for create/setup/teardown
- cli.py: add --ipvlan flag, wire into DecnetConfig
- tests/test_network.py: new test module covering ips_to_range,
create_macvlan/ipvlan, setup/teardown for both drivers
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Subtraction underestimates the required prefix when IPs span a CIDR
boundary (e.g. .110–.119 gave /28 covering only .96–.111, leaving
deckies at .112+ unreachable from the host macvlan route).
XOR correctly finds the highest differing bit, yielding /27 (.96–.127).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
deployer.py status lookup used f"{decky.name}-{svc}" verbatim, so
docker_api (underscore) resolved to "decky-devops-docker_api" while the
actual container is named "decky-devops-docker-api" (hyphen). Status
would always report it absent/degraded even when running.
Fix: normalize underscores to hyphens in the container name lookup,
consistent with how all service plugins name their containers.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
dict[str, Any] and X | Y union syntax require Python 3.10+. Containers
running centos7/ubuntu20/rocky9 base images ship Python 3.6-3.9 and
crashed on import. Adding the __future__ import makes all annotations
lazy strings, compatible back to Python 3.7.
Affected: templates/decnet_logging.py (+ all 22 template copies),
decnet/logging/syslog_formatter.py, decnet/logging/file_handler.py
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Previously --log-file only set DECNET_LOG_FILE inside containers with no
volume mount, so logs were lost on container restart and never visible on
the host. Now generate_compose binds the host log dir to
/var/log/decnet inside every service container so the file appears on
the host as expected.
- composer.py: _resolve_log_file() maps host path → container path;
generate_compose() mkdir's host dir and injects volume + DECNET_LOG_FILE
- tests/test_log_file_mount.py: 9 new tests covering mount format,
env injection, dir creation, and dedup
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- HTTP: configurable server_header, response_code, fake_app presets
(apache/nginx/wordpress/phpmyadmin/iis), extra_headers, custom_body,
static files directory mount
- SSH/Cowrie: configurable kernel_version, hardware_platform, ssh_banner,
and users/passwords via COWRIE_USERDB_ENTRIES; switched to build mode
so cowrie.cfg.j2 persona fields and userdb.txt generation work
- SMTP: configurable banner and MTA hostname
- MySQL: configurable version string in protocol greeting
- Redis: configurable redis_version and os string in INFO response
- BYOS: [custom-*] INI sections define bring-your-own Docker services
- Stealth: rename all *_honeypot.py → server.py; replace HONEYPOT_NAME
env var with NODE_NAME across all 22+ service templates and plugins;
strip "honeypot" from all in-container file content
- Config: DeckyConfig.service_config dict; INI [decky-N.svc] subsections;
composer passes service_cfg to compose_fragment
- 350 tests passing (100%)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
dtagdevsec/mailoney and dtagdevsec/elasticpot are unavailable on Docker Hub
("manifest unknown"), causing the entire deployment to abort and cascade-
interrupt all other image pulls.
- Convert smtp and elasticsearch to build services with custom Python
honeypots: smtp emulates Postfix ESMTP (EHLO/AUTH/MAIL/RCPT logging),
elasticsearch emulates ES 7.17 HTTP API (logs recon probes like /_cat/,
/_cluster/, /_nodes/, /_security/)
- Both use ARG BASE_IMAGE so they participate in per-decky distro variation
- Add _compose_with_retry() to deployer: 3 attempts with exponential backoff
(5s → 10s → 20s) for transient network failures; permanent errors
("manifest unknown", "pull access denied") are detected and not retried
- Update test_services.py and test_composer.py: smtp/elasticsearch moved
from UPSTREAM_SERVICES to BUILD_SERVICES (314 tests passing)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
b"\x00" * 10 inside an implicit bytes-literal concatenation block is a
multiplication expression, not a literal. Python's greedy concatenation
absorbs the b"\x00" into the preceding chain, applies * 10 to the whole
thing, then finds the following b"\x21..." literal stranded after an
expression without a comma — SyntaxError.
Fix: inline the 10 null bytes as a literal.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
--break-system-packages was added in pip 23 (Debian Bookworm). Ubuntu 22.04
ships pip 22 which rejects the flag with exit code 2. Switch to the
PIP_BREAK_SYSTEM_PACKAGES env var instead: recognized by pip>=23, silently
ignored by pip<23 where PEP 668 is not enforced anyway.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Replace hardcoded ALL_SERVICE_NAMES=[5 services] in cli.py with
_all_service_names() pulling dynamically from the plugin registry;
randomize-services now draws from all 25 registered honeypots
- Add build_base field to DistroProfile: apt-compatible image for service
Dockerfiles (ubuntu22/ubuntu20/kali get their own; others fall back to
debian:bookworm-slim since Dockerfiles use apt-get)
- Add build_base to DeckyConfig; propagate from distro in _build_deckies
and _build_deckies_from_ini
- Inject BASE_IMAGE build arg in composer.py for every build-based service
so each decky's containers reflect its assigned distro
- Update all 21 service Dockerfiles: FROM debian:bookworm-slim →
ARG BASE_IMAGE=debian:bookworm-slim / FROM ${BASE_IMAGE}
- Add tests/test_cli_service_pool.py and tests/test_composer.py (306 total)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
