NixDaemon

2026-10-08-pentest-toolkit-design.md (18796B)

---

 # Pentest toolkit for NixDaemon — design
 
 **Date:** 2026-10-08
 **Status:** awaiting review
 **Author:** daemon-sec, with Claude
 
 ## Intent
 
 Turn this laptop into a Kali-equivalent offensive workstation, declaratively,
 for **HackTheBox CPTS prep**. Everything comes from the flake: no `curl | bash`,
 no tools living outside the store except the ones that must be mutable
 (VPN profiles, loot).
 
 Success criteria:
 
 1. `nh os switch` is the only install step. A fresh machine reaches the same kit.
 2. Tools are grouped into independently toggleable modules (`daemon.pentest.*`),
    so a category can be dropped in one line.
 3. Tools are reachable with no ceremony: `nxc`, `ffuf`, `secretsdump` work in any
    terminal, including under `sudo`.
 4. Windows/Linux/macOS agent binaries and offensive payloads are staged in one
    predictable tree, servable to a target in one command.
 5. The HTB loop — connect VPN, set target, fix clock skew, enumerate — is
    driven by a handful of commands that share state across terminals.
 
 Non-goals: C2 infrastructure beyond what ships in nixpkgs; anything targeting
 hosts outside HTB/authorised labs; Kali's full 600-package catalogue (curated
 instead); a second non-NixOS VM.
 
 ## Decisions
 
 These were delegated to me with "whatever is best for NixOS". Recorded with
 reasoning so they can be revisited.
 
 ### D1 — Tools install to `environment.systemPackages`, not `home.packages`
 
 **The single most important NixOS-specific decision.** Half this toolkit needs
 root: `nmap -sS` (raw sockets), `responder`, `mitm6`, `bettercap`, `tcpdump`,
 `masscan`. home-manager packages are on the *user's* PATH only, so
 `sudo nmap -sS` would fail with `command not found` — the classic
 Kali-refugee-on-NixOS trap. System packages behave like Kali's `/usr/bin`.
 
 Consequence: modules live in `modules/features/pentest/` as
 `flake.nixosModules.pentest-*`. Only genuinely user-scoped things (the `htb*`
 commands, the cheat card, shell integration) are home modules.
 
 ### D2 — Everything on PATH, per-category toggles, devshells as a bonus
 
 Friction matters more than PATH tidiness during CPTS. 1.8TB free, and the kit
 comes from the binary cache rather than compiling. Toggles are the escape hatch.
 
 `perSystem.devShells.pentest` (plus one per category) is declared anyway — ~10
 lines, and it makes the kit portable: `nix develop github:…#pentest` on any
 machine with Nix.
 
 ### D3 — Missing tools become pinned Nix derivations; a script re-pins them
 
 ~20 tools aren't in nixpkgs. Each gets a derivation in `_pkgs/` with a pinned
 `rev`/`hash`, so the toolkit rolls back with the system generation.
 `pentest-update` re-pins to latest on demand.
 
 Where a tool declares Windows support in nixpkgs, build it **from source** with
 `pkgsCross.mingwW64` rather than downloading a release blob. Verified available
 for `mimikatz`, `ligolo-ng`, `netexec`. Genuine provenance, no trusting strangers.
 
 Prebuilt .NET binaries (SharpCollection, Ghostpack, potato family) are the
 exception: building .NET offline in Nix is brittle, so those are pinned release
 assets with recorded hashes.
 
 ### D4 — Defaults: CPTS core + heavy GUI on; the rest written but off
 
 On: `recon ad bloodhound web pivot crack shells wordlists payloads python gui`.
 Off: `dfir reversing wireless cloud osint mobile`.
 Keeps the first build finishable in one sitting; each is one line to enable.
 
 ### D5 — Native NixOS options over bare packages, wherever they exist
 
 Not cosmetic — on NixOS the package alone is often *unusable*:
 
 | Option | Why the package alone is not enough |
 |---|---|
 | `programs.wireshark.enable` | Creates the `wireshark` group and the `dumpcap` capability wrapper. Without it you cannot capture without full root. |
 | `programs.proxychains.enable` | Manages `/etc/proxychains.conf`. `/etc` is read-only on NixOS, so the Kali habit of editing that file by hand simply fails. This module is what makes `proxychains` work at all. |
 | `security.wrappers` | Capabilities (`cap_net_raw`) instead of setuid, for raw-socket tools. |
 | `services.neo4j` + `services.postgresql` | BloodHound CE needs both; there is no `services.bloodhound` in nixpkgs, so this is wired by hand. |
 
 `rockyou.txt` ships gzipped in the store, so `wordlists.nix` produces a
 decompressed derivation and exports `$WORDLISTS`.
 
 ## Architecture
 
 Dendritic, matching the existing repo: every file under `modules/` is a
 flake-parts module declaring the outputs it owns, cross-referenced by **name**
 through `self`, never by path. Switches live in one `options.nix`; each category
 is gated with `lib.mkIf`.
 
 ```text
 modules/features/pentest/
 ├── options.nix       daemon.pentest.{enable,<cat>.enable} + assertions
 ├── core.nix          always-on base + $PAYLOADS/$WORDLISTS env + /etc/hosts helper
 ├── python.nix        the combined offensive Python env + suffix-free aliases
 ├── recon.nix         ad.nix  bloodhound.nix  web.nix  pivot.nix  crack.nix
 ├── shells.nix        wordlists.nix  payloads.nix  gui.nix
 ├── dfir.nix          reversing.nix  wireless.nix  cloud.nix  osint.nix  mobile.nix
 ├── vpn.nix           htbvpn@.service template + scoped sudo rule
 ├── time.nix          htb-time privileged helper + scoped sudo rule
 ├── devshells.nix     perSystem.devShells.pentest and per-category
 └── _pkgs/            ~20 pinned derivations (paths with /_ are skipped by import-tree)
 
 modules/home/
 ├── htb.nix           htbtarget htbvpn htbtime htbip htb new — the user-facing CLI
 ├── htb-shell.nix     zsh precmd integration: $TARGET/$BOX live in every terminal
 └── cheats/pentest.md `pentest-cheat`, in the existing cheat-card style
 ```
 
 ### Option tree
 
 ```nix
 daemon.pentest = {
   enable = mkEnableOption "the offensive toolkit";   # master switch, default false
   <category>.enable = ... ;                          # per D4 defaults
   payloads.windowsArches = [ "amd64" "x86" ];        # which .exe variants to build
   htb.vpnDir = "~/.config/htb/vpn";                  # where .ovpn profiles live
   htb.promptTarget = true;                           # show $TARGET in the prompt
 };
 ```
 
 Every category also implies `core`, so `$PAYLOADS`/`$WORDLISTS` always exist.
 An assertion fires if a category is enabled while `daemon.pentest.enable` is false.
 
 ## Components
 
 ### C1 — Tool modules
 
 Curated from what was verified present in the pinned nixpkgs (2026-10-08).
 
 - **recon** — nmap masscan rustscan naabu fscan nbtscan enum4linux-ng snmpcheck
   onesixtyone thc-ipv6 dnsrecon subfinder amass httpx dnsx katana gowitness
   eyewitness whatweb
 - **ad** — netexec impacket certipy bloodhound-py kerbrute responder mitm6
   coercer donpapi adidnsdump ldapdomaindump smbmap evil-winrm pypykatz bloodyad
   lsassy dploot masky pywerview krb5 openldap samba(smbclient) sshpass
   · custom: krbrelayx sprayhound
 - **bloodhound** — bloodhound-ce with neo4j + postgresql wired up
 - **web** — ffuf gobuster feroxbuster dirb nikto sqlmap commix wfuzz nuclei
   nuclei-templates wpscan joomscan dalfox arjun jwt-cli jwt-hack mitmproxy
   burpsuite zap
 - **pivot** — ligolo-ng chisel socat proxychains-ng(native opt) sshuttle gost
   frp iodine pingtunnel stunnel wireguard-tools openvpn
 - **crack** — hashcat hashcat-utils john hydra medusa crowbar crunch cewl hashid
   name-that-hash
 - **shells** — metasploit msfpc powershell pwncat rlwrap updog miniserve
   freerdp remmina rdesktop upx
 - **wordlists** — seclists wordlists rockyou(decompressed) exploitdb
 - **dfir** — volatility3 sleuthkit autopsy yara capa chainsaw hayabusa exiftool
   foremost testdisk chntpw binwalk · custom: velociraptor
 - **reversing** — ghidra radare2 rizin cutter gef pwntools one_gadget pwninit
   checksec flare-floss retdec patchelf
 - **wireless** — aircrack-ng hcxtools bettercap wireshark(native opt) termshark tcpdump
 - **cloud** — awscli2 azure-cli google-cloud-sdk kubectl trivy kube-hunter pacu
 - **osint** — theharvester recon-ng sherlock maigret holehe
 - **mobile** — apktool jadx dex2jar frida-tools objection scrcpy
 
 ### C2 — The Python toolkit (`python.nix`)
 
 Answers "a script built into the nixos config that can set up all the python tools".
 
 Three parts:
 
 1. **One combined interpreter.** `pentest-python` = `python3.withPackages` with
    every offensive library: impacket certipy pywerview dploot masky bloodhound
    ldapdomaindump pypykatz bloodyad lsassy minikerberos aiowinreg ldap3 dnspython
    scapy pwntools pycryptodomex requests rich. Any offensive script you download
    runs with `pentest-python foo.py` and its imports already resolve — no venv,
    no `pip install`.
 
    *Risk:* a version conflict inside one env (impacket is built against
    python3.14 here). Mitigation: if `withPackages` fails to resolve, fall back to
    per-tool standalone packages and a slimmer shared env. Decided at build time,
    not guessed.
 
 2. **Suffix-free aliases.** impacket installs 70 scripts as `secretsdump.py`,
    `psexec.py`, `GetUserSPNs.py`. A `mkSuffixFreeAliases` helper globs a package's
    `bin/*.py` and symlinks `secretsdump` → `secretsdump.py`, so both spellings
    work. Applied to impacket and any other `.py`-suffixed toolkit.
 
 3. **A discovery command.** `impacket` with no arguments lists all 70 scripts
    with fzf selection and `--help` preview; `impacket <name>` runs one. Same for
    `pentest-python --list`.
 
 ### C3 — Payload tree (`payloads.nix`)
 
 A derivation of symlinks at a stable path, exported as `$PAYLOADS`:
 
 ```text
 $PAYLOADS/
 ├── windows/{amd64,x86}/
 │   ├── privesc/potato/    JuicyPotato JuicyPotatoNG RoguePotato SweetPotato
 │   │                      GodPotato PrintSpoofer SharpEfsPotato EfsPotato
 │   │                      LocalPotato DeadPotato
 │   ├── privesc/printer/   SpoolSample SharpPrintNightmare PrintSpoofer
 │   ├── privesc/           winPEASx64 winPEASx86 Seatbelt SharpUp
 │   ├── ad/                Rubeus SharpHound Certify Whisker SharpView
 │   │                      ADCSPwn StandIn
 │   ├── creds/             mimikatz-2.2.0 mimikatz-2.1.1 LaZagne SharpDPAPI
 │   ├── agents/            ligolo-agent chisel nc
 │   └── misc/              SharpCollection (the full upstream set)
 ├── linux/{amd64,arm64}/   ligolo-agent chisel linpeas pspy socat nc
 ├── macos/{amd64,arm64}/   ligolo-agent chisel
 └── scripts/
     ├── ad/                PowerView PowerUp SharpView.ps1 Invoke-Mimikatz
     │                      PowerSploit nishang Invoke-Kerberoast
     ├── printer/           printerbug.py CVE-2021-1675.py Invoke-Nightmare.ps1
     └── privesc/           linux-smart-enumeration linux-exploit-suggester
                            PowerUp.ps1 Sherlock.ps1
 ```
 
 Multi-arch comes from `pkgsCross.mingwW64` (Windows) and `pkgsCross.aarch64-multiplatform`
 (Linux arm64) over the same source. Versioned duplicates live here as distinct
 filenames (`mimikatz-2.2.0.exe`, `mimikatz-2.1.1.exe`) rather than contending
 for one PATH name — the reason payloads are files, not commands.
 
 `payload-serve [port]` HTTP-serves the tree bound to `tun0`;
 `payload-serve --smb` runs the impacket `smbserver` equivalent;
 `payload-serve --list` prints the tree.
 
 ### C4 — Shared target state (`htbtarget`)
 
 The requirement is a target IP visible **across terminals**. Environment
 variables cannot be pushed into already-running processes, so:
 
 - **State** lives in `$XDG_STATE_HOME/htb/` (`target`, `name`, `vpn`), surviving
   reboots so a box can be resumed next day.
 - **Propagation** is a zsh `precmd` hook that re-reads the state file and exports
   `$TARGET`, `$RHOST`, `$IP`, `$BOX`. Every terminal picks up a change made in
   any other terminal **at its next prompt**.
 
 ```sh
 htbtarget 10.10.11.5 vintage.htb   # set IP (+ optional FQDN)
 htbtarget                          # print current
 htbtarget clear
 ```
 
 With a FQDN, it also manages a marked block in `/etc/hosts` through a privileged
 helper — necessary because Kerberos in CPTS AD boxes needs working name
 resolution, and `/etc` is read-only on NixOS.
 
 **Honest limitation, to be documented in the cheat card:** a shell that is
 mid-command when the target changes keeps the old value until its next prompt.
 Interactive use is unaffected.
 
 ### C5 — VPN control (`htbvpn`)
 
 Implemented as a **systemd service template** `htbvpn@.service`, not a
 backgrounded process — it survives closing the terminal, logs to the journal,
 and `down` reliably kills it.
 
 ```sh
 htbvpn list            # profiles in ~/.config/htb/vpn, active one marked
 htbvpn up lab_eu_free  # sudo systemctl start htbvpn@lab_eu_free
 htbvpn down            # stop whatever is up
 htbvpn status          # unit state + tun0 address
 htbip                  # just the tun0 IP, for pasting into payloads
 ```
 
 Profiles are **not** Nix-managed: they are per-account files that rotate, and
 `~/.config/htb/vpn/` is created for them. A sops-encrypted variant is available
 later if wanted. A scoped `NOPASSWD` sudo rule covers only
 `systemctl {start,stop,restart} htbvpn@*`.
 
 ### C6 — Clock skew control (`htbtime`)
 
 The Kerberos-skew problem: AD authentication rejects a clock more than ~5
 minutes off the DC, and on NixOS `systemd-timesyncd` is enabled by default and
 will **undo** any manual adjustment.
 
 `htbtime $TARGET`:
 1. Record prior state (is `timesyncd` active? what does `timedatectl` report for
    NTP? are `chrony`/`ntpd` running?) into `/var/lib/htb-time/state`.
 2. Disable the conflicts: `timedatectl set-ntp false`, stop `chrony`/`ntpd` if up.
 3. Sync to the target: `ntpdate -u <target>` (from `pkgs.ntp`, confirmed to ship
    `ntpdate` and `sntp`), falling back to `chronyd -q` if the DC refuses NTP.
 4. Report the resulting offset.
 
 `htbtime off` reads the state file and restores **exactly** what was there, then
 re-syncs to real time. `htbtime status` shows the current offset and mode.
 
 Two safeguards:
 
 - **A skew warning.** A large offset breaks TLS certificate validation, so `nix`,
   `git` and HTTPS may fail while skewed. `htbtime` says so explicitly rather than
   letting it become a confusing debugging session.
 - **Self-healing.** State lives in `/var/lib`, but a reboot re-applies the NixOS
   default anyway, so a forgotten `htbtime off` cannot permanently break the clock.
 
 Root side is `htb-time`, a fixed store script with a scoped `NOPASSWD` rule for
 `wheel` — mirroring the existing `fan-ec` / `fan` split in
 `modules/hosts/laptop/fan-cli.nix` and `modules/home/fan.nix`.
 
 ### C7 — Engagement scaffolding and cheat card
 
 ```sh
 htb new escape    # ~/htb/escape/{nmap,loot,creds,www,exploit}/ + notes.md template,
                   # sets the target if given, cds in
 htb ls            # boxes worked, newest first
 pentest-cheat     # recon | ad | pivot | transfer | crack | web | dfir | htb
 ```
 
 `pentest-cheat` follows the existing card mechanism exactly
 (`modules/home/cheats/*.md` + `cheat-render`), so it joins `nix-cheat`,
 `gpg-cheat` and `niri-cheat` with no new machinery.
 
 ### C8 — `pentest-update`
 
 Re-pins every `_pkgs/` derivation to its latest upstream `rev`/`hash` using
 `nix-prefetch-url`/`nurl`, rewrites the hashes in place, and prints a diff for
 review. Never auto-commits and never runs during a rebuild — pinning stays
 deliberate.
 
 ## Error handling
 
 - **Missing VPN profile** — `htbvpn up` lists what is available and exits 2.
 - **No target set** — any command needing `$TARGET` says which command sets it.
 - **`htbtime` without a reachable DC** — reports the failure and leaves NTP
   *disabled* with a clear warning plus the `htbtime off` hint, rather than
   silently half-applying.
 - **Unbuildable `_pkgs` entry** (upstream retagged, asset renamed) — that one
   derivation fails with the URL that broke; it must not take the rebuild down, so
   payload entries are assembled so a single failure is diagnosable in isolation.
 - **Python env conflict** — falls back to standalone packages (C2).
 
 ## Testing
 
 No unit-test framework applies to a package set, so verification is build- and
 behaviour-based, **per module as it lands**, not in one pass at the end:
 
 1. `nix flake check` and `nix build .#nixosConfigurations.nixos.config.system.build.toplevel`
    after each module — eval errors and missing attributes surface immediately.
 2. **Smoke test per category**: one `--version`/`--help` per tool, scripted, so a
    package that installs but cannot run is caught.
 3. **Payload tree**: assert every declared path exists and Windows artefacts
    report as PE binaries (`file`), Linux ELF ones as ELF.
 4. **`htbtarget` cross-terminal**: set in terminal A, confirm `$TARGET` appears in
    terminal B at its next prompt.
 5. **`htbvpn`**: unit starts, `tun0` gains an address, `down` removes it.
 6. **`htbtime`**: capture `timedatectl` before, run `htbtime` against a test NTP
    source, confirm NTP disabled and offset applied, run `htbtime off`, confirm
    `timedatectl` matches the original state byte for byte. This round-trip is the
    one that must not be hand-waved.
 7. `sudo nmap -sS` and `sudo responder -h` — the D1 guarantee, explicitly tested.
 
 ## Risks
 
 | Risk | Mitigation |
 |---|---|
 | First build is 40–60GB / a couple of hours | Mostly cache downloads. Phased: core + AD first, GUI last. |
 | Upstream release assets move, breaking `_pkgs` | Hashes pinned; `pentest-update` re-pins; failures isolated per derivation. |
 | `pkgsCross.mingwW64` fails for a given tool | Verified for mimikatz/ligolo-ng/netexec. Anything else falls back to a pinned release asset. |
 | Combined Python env conflicts | C2 fallback to standalone packages. |
 | Clock skew breaks TLS mid-engagement | Explicit warning + reboot self-heal (C6). |
 | 200 new names shadow an existing command | Smoke test diffs `PATH` collisions against the pre-change profile and reports them. |
 
 ## Phasing
 
 Each phase ends with a working, committed system.
 
 1. **Foundation** — `options.nix`, `core.nix`, `wordlists.nix`, `python.nix`. Proves the pattern.
 2. **CPTS core** — `recon`, `ad`, `web`, `pivot`, `crack`, `shells`.
 3. **HTB workflow** — `vpn.nix`, `time.nix`, `htb.nix`, `htb-shell.nix`. The commands.
 4. **Payloads** — `_pkgs/` derivations, cross-builds, the staging tree, `payload-serve`.
 5. **Heavy and optional** — `bloodhound`, `gui`, then `dfir`/`reversing`/`wireless`/`cloud`/`osint`/`mobile` (off by default).
 6. **Polish** — `pentest-cheat`, `pentest-update`, `devshells.nix`, README.
 
 ## Scope note
 
 Written for authorised lab use: HackTheBox CPTS preparation. The toolkit is
 ordinary defensive-security coursework equipment; it carries no targeting
 configuration and nothing here points at infrastructure the operator does not
 own or have explicit permission to test.