lifeich1/nixcf / .agents/skills/nixcf-service-firewall
nixcf-service-firewall
VerifiedAdd, review, or refactor network-facing NixOS and Home Manager services in the nixcf repository while preserving service state and assigning each firewall rule to one owner. Use for firewall policy, listen addresses, ports, service users, systemd hardening, OCI containers, and service options involving Gitea, Attic, Hobob, Syncthing, vlmcsd, Bilibili Live Recorder, VirtualBox or desktop networking, Xray, OpenSSH, and KDE Connect.
Nixcf Service and Firewall
Change service and network boundaries from current evidence. Keep local configuration work separate from live firewall changes, restarts, deployment, and data migration.
Guardrails
- Treat source and
flake.lockas current truth. Treat README files as navigation and dated refactor plans as historical recommendations to revalidate. - Never inspect, decrypt, print, copy, or synthesize secret values. Read Agenix declarations and runtime paths only.
- Treat the credential candidates identified by the Agenix reference as opaque while
.agents/skills/nixcf-secrets-agenix/scripts/check-nix-source-safety.shfails. Do not open them directly or use a content-producing search. - Run that source-safety gate before every repo-consuming Nix evaluation, build, check, lock, activation, or deployment command. Stop on a nonzero result; a narrower attribute does not bypass the risk of copying tracked source into
/nix/store. - Never deploy, restart or stop a service, migrate or delete data, alter a live firewall, pull a live container image, update inputs, commit, or tag unless the user explicitly authorizes that exact action.
- Do not edit
hardware-configuration.nix,system.stateVersion, orhome.stateVersionfor a service change. - For review or diagnosis requests, remain read-only. Implement only when the user requests a change.
- Do not claim a listener, migration, backup, deployment, or recovery path was verified from Nix evaluation alone.
Read the minimum context
- Read the repository
README.mdandflake.nix. - Identify every affected host and Home Manager profile. Read their
readme.mdand entry module. - Read the service directory's
readme.md, implementation, parentos/readme.mdorfool/readme.md, and relevant aggregator. - Read
os/firewall, upstream option usage in source, and any direct host firewall rules that overlap. - Read Agenix declarations without opening
.agepayloads when the service consumes credentials. Run the source-safety gate before following any route through a reported credential candidate. - Read references/source-routing.md for repository-specific routing and links. Open only the dated plans relevant to the requested change and only sources the gate permits.
Use rg and rg --files to locate options and consumers. Do not scan unrelated modules.
Stop for material decisions
Ask the user interactively before selecting among materially different outcomes when any of these remain ambiguous:
- whether a listener is loopback-only, LAN-accessible, or reachable from wider networks, including the allowed client sources;
- whether existing state must move, which backup and restore test is acceptable, or whether a format upgrade can occur;
- whether a service truly requires root, a privileged port, host networking, device access, or Linux capabilities;
- which immutable container digest is approved and whether it is available for every enabled architecture, especially
aarch64-linuxon Pi; - which independent recovery route is available before tightening SSH or firewall access on a remote host.
Present the current evidence, the recommended choice, and its impact. Continue safe source inspection while waiting, but do not encode an arbitrary answer.
Workflow
1. Establish scope and current behavior
Build a host/service matrix containing:
- configuration name, architecture, user, Home profile, and enablement source;
- service module, package or image, state paths, service identity, and secret runtime path;
- declared bind address, TCP/UDP port, port mapping, and current firewall owner;
- dependencies on proxy, cache, DNS name, LAN address, or another service.
Distinguish configured intent from live fact. Before tightening exposure, require an actual listener inventory from user-provided evidence or an explicitly authorized read-only check. Record at least protocol, local address, port, process/unit, expected clients, and whether the listener is temporary. Do not record payloads or credentials.
2. Choose ownership
- Put reusable NixOS service implementation in
os/<service>/; keephost/<hostname>/to imports, enablement, and host-specific values. - Put reusable Home Manager container or user-service implementation in
fool/<service>/; keephome/<profile>/to enablement and personal values. - Let the service module own its bind, typed port, and firewall rule. Prefer an upstream NixOS option when it already provides the rule, as with OpenSSH, Syncthing, or KDE Connect.
- Ensure exactly one owner for each rule. Remove duplicated host or generic-firewall rules only after the replacement evaluates equivalently.
- Do not make a Home Manager module silently own the system firewall. For a user container, expose bind/host-port/access intent in the user module and route any required NixOS firewall rule through one explicit system owner.
- Keep broad firewall policy separate from application-named options. Do not introduce generic switches such as
serve-<application>.
3. Design typed, safe options
Use typed options for every configurable boundary:
- use
lib.types.portfor host and service ports; - expose a listen or bind address separately from a port;
- use
openFirewallas an explicit boolean, normally defaulting to false; - type package, path, enum, list, and attribute options rather than accepting arbitrary strings;
- assert invalid combinations such as opening a port for a loopback-only listener or enabling a service without its required user/data path.
Generate port-mapping strings inside the module. Do not use the presence of a port mapping as proof that the firewall should be open. Keep endpoint, migration proxy, SOCKS proxy, and cache roles distinct even when they currently share a host.
4. Migrate firewall ownership without lockout
- Inventory current declared rules, evaluated rules, and actual listeners.
- Add service-owned rules while preserving the existing broad rule.
- Compare the evaluated TCP/UDP ports and ranges before and after ownership migration.
- Remove duplicate application or host rules in a behavior-preserving change.
- Tighten broad ranges in a separate change only after the user decides exposure and recovery paths.
- Stage live rollout by host: preserve a prior generation, change one host, test access and application health, then continue only after success.
Never combine a default-deny transition with unrelated option renames, image changes, or state migration. A local patch may prepare these stages, but live execution needs separate authority.
5. Minimize service privilege
- Prefer a dedicated system user/group or a compatible
DynamicUserdesign. - Declare state, cache, runtime, log, and configuration directories through NixOS/systemd facilities where possible; set ownership deliberately.
- Use
lib.getExeor an explicit packaged executable and declare network ordering only when the program needs it. - Add systemd hardening incrementally after checking program behavior. Consider
NoNewPrivileges, filesystem protections, private temporary storage, device restrictions, capability bounds, and writable path allowlists. - Do not guess away root or add broad capabilities. Ask for evidence when the program needs privileged ports, devices, arbitrary paths, or host networking, then grant only the minimum.
6. Wire secrets at runtime
- Use Agenix runtime files or systemd credentials; do not interpolate secret content into Nix strings, derivations, generated environment files, documentation, logs, or commands.
- Match owner, group, and mode to the service identity. Verify that the service receives the runtime path, not a copied store path.
- When changing Attic, check the coupled substituter, public key, netrc, client, and server configuration without exposing credentials.
- Route credential rotation or recipient changes through the repository's Agenix skill and corresponding dated credential plan.
7. Preserve state and containers
For Gitea, Attic, Hobob, Syncthing, recorders, and any other stateful service:
- Identify current data, database, repository, LFS, cache, configuration, and recording paths from source and authorized runtime evidence.
- Keep paths, users, folder IDs, sync direction, retention, chunking, and formats unchanged during structural refactors.
- Define a backup, integrity check, restore test, cutover, and rollback before any migration.
- Require explicit authority before stopping writers or copying data. Retain the old data read-only until acceptance; never let old and new units write it simultaneously.
For containers, expose image, digest, bind/listen address, host/container ports, data directory, restart policy, and access policy. Require an immutable approved digest, inspect manifest architecture support, and validate Pi images on aarch64-linux. Separate image changes from data-format or directory migrations.
8. Apply service-specific checks
- Attic: Preserve existing storage and chunking unless explicitly changing them; coordinate runtime credentials, cache endpoint, retention, and firewall ownership.
- Gitea: Preserve database, repository, LFS, domain, registration, and clone behavior;
keep migration proxy separate from public serving. The former
mailer.SENDMAIL_PATH = "/fix-merged-wait-deploy"workaround was removed (evaluated 2025-09-07: the upstream module owns that option and derives a safe default while mailer is disabled) — do not reintroduce placeholder values; re-evaluate upstream options before adding or retaining workarounds. - Hobob: The live resource root is
/home/pi/hub/hobob(2025-09-07 inventory:/opt/hobobonly holds symlinks to it plus a writable.cache; the service ran as root). Target a dedicatedhobobsystem user, explicitdataDirat/home/pi/hub/hobob(never move resources to/var/lib/hobob),StateDirectory=hobobfor writable state, and verify which paths the program actually writes before adding hardening or dropping root. Require a decision for any remaining root or capability need. - Syncthing: Use the upstream
services.syncthing.openDefaultPortsoption (TCP/UDP 22000 + UDP 21027 discovery) through the wrapper'sfool.syncthing.openFirewallpassthrough. Personal folders/devices topology lives inos/syncthing/topology.nix, imported explicitly by GTR7/XPS13 hosts. Preserve device IDs, folder IDs, paths, receive-only direction, and override semantics while separating reusable wrapper from personal topology. - vlmcsd and recorders: vlmcsd uses the NixOS OCI container declaration only (the
cmdbranch andinvokeTypewere removed); the module owns itsopenFirewallrule. Generate mappings from typed ports, pin images by digest, verify architecture, and keep image and data changes separate. Validate on the actual runtime host: vlmcsd on Pi (aarch64-linux), bililiverecorder on GTR7 (x86_64-linux, Home Manager) — do not merge the two verification paths into one "Pi/aarch64" step. - VirtualBox and desktop networking:
fool.virtualbox.usersderivesvboxusersmembership in the module; hosts no longer hand-write that group. Desktop stacks are composablefool.collectionsprofiles —desktop,audio,pro-audio— and both GTR7 and XPS13 enable pro-audio (JACK + realtime loginLimits; 2025-09-07 decision). Review bridge/host-only interfaces, user groups, devices, KDE Connect, professional-audio ports, and application ownership independently; do not infer exposure merely from enablement. - Xray: Determine listener/firewall needs from safe runtime inventory or sanitized configuration facts; never open the encrypted configuration. Loopback-only listeners need no inbound rule.
- OpenSSH and KDE Connect: Prefer upstream firewall controls and verify their evaluated
port/range effects. KDE Connect has no separate firewall option: enabling
programs.kdeconnectautomatically opens TCP/UDP 1714-1764, owned solely by that upstream module via the plasma/desktop collection. Require a recovery route before restricting remote SSH access.
9. Validate local configuration
- Update the affected module or directory
readme.mdso options, ownership, and enablement match source. - Run
git diff --check. - Before any Nix command, run
.agents/skills/nixcf-secrets-agenix/scripts/check-nix-source-safety.sh; if blocked, skip Nix validation and report the path/category-only result. - For Nix changes, run
just chkonly after the gate succeeds. - Evaluate or build each affected host, including
nixos-pi4bforaarch64-linuxchanges, only after the gate succeeds. - Inspect final evaluated
allowedTCPPorts,allowedUDPPorts, and ranges to detect duplicates or unexpected broad access. - Report any live inventory, architecture manifest, backup/restore, service health, or connectivity check that remains unverified.
Do not run deployment recipes as validation. Hand deployment to the dedicated deployment workflow only after explicit authorization.
Report the result
Lead with the ownership and exposure outcome. List affected hosts, decisions made, state/secret safeguards, files changed, validation performed, and unresolved live checks. Clearly distinguish source evaluation from live verification and give a staged rollback plan for any future rollout.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |