Appearance
0023: A dedicated NAS deploy user that can only run the deploy
Note 2026-11-06: the git host and CI moved to GitHub (
FEAW-Serv/getmy-books), ADR 0046. References below to the previous host are history; ADR 0046 says what replaces them.
Context
ADR 0019's pipeline deploy logs in to the NAS over SSH as rob, the owner's own account, which can run any command, including Docker (root-equivalent). A leaked pipeline key would hand over the NAS. The Product Owner's standing rule (2026-09-29): replace it with a dedicated deploy user, not in the docker group if that can be avoided, with a forced command in authorized_keys that only runs the deploy script, then remove the key from rob. Until that is done, deploy-nas skips with a warning (the NAS_DEPLOY_ENABLED repository variable), so main stays green.
Decision
Approved by the Product Owner on 2026-09-29, with two changes from the first draft: the deploy user unpacks the release and writes .env itself, into a folder it owns, and the root program takes no input at all; and root uses only a root-owned compose file installed from this repo, checked before every start.
A
deployuser on the NAS: a normal DSM user, not an administrator, not in thedockergroup, with its password field set to*so no password can ever match (notpasswd -l, whose!marks the account locked, which sshd may also apply to key logins), with a home folder for.sshand the releases. Its login shell must be a real shell (/bin/sh), since DSM gives non-administrators/sbin/nologinand sshd runs the forced command through the login shell.A forced command on the key. The pipeline's new key is the only line in
deploy'sauthorized_keys:restrict,from="<runner address>",command="/usr/local/bin/getmy-books-receive" ssh-ed25519 ….restrictturns off port, agent and X11 forwarding and the terminal;from=limits it to the runner; the client's own command is only read by the receive program, which accepts exactlydeploy <40-hex commit>.getmy-books-receive, running asdeploy(infra/nas/deploy/getmy-books-receive, installed root-owned at/usr/local/bin/, sodeploycan run it but not change it):- reads one gzipped tar on standard input, at most 50 MB;
- refuses anything but plain files and folders, absolute paths, paths with
.., more than 20,000 entries or more than 300 MB unpacked; - unpacks into
~/getmy-books/releases/<commit>, owned bydeploy, withinfra/nas/.envmode0600; - points
~/getmy-books/currentat it, keeps the one before aspreviousfor rollback, removes older releases; - then runs
sudo -n /usr/local/sbin/getmy-books-up, and nothing else.
getmy-books-up, the only root program (infra/nas/deploy/getmy-books-up, installed root-owned at/usr/local/sbin/): takes no input (no arguments, sudo resets the environment, standard input is closed). It:- uses only
/usr/local/etc/getmy-books/docker-compose.yml, a root-owned copy ofinfra/nas/docker-compose.ymlinstalled from this repo (-f), and refuses to start if that file isn't owned by root or is writable by anyone else; - resolves
/var/services/homes/deploy/getmy-books/current, refusing anything that is not a release folder named by a full commit id, and uses it only as the build context and env file (--project-directory <release>/infra/nas,--env-file); - runs the compose check below on
docker compose config(the file as Docker will run it, env applied), and refuses to start if it fails; - runs
docker compose up -d --build --waitand checks/healthreports that commit. Thedeployaccount therefore supplies the code and the env file, but never what the containers are allowed to do. Amended 2026-11-03 (#79): the env file is an allow-list. Before any compose command reads it,getmy-books-upruns/usr/local/sbin/getmy-books-env-checkon the release.envagainst/usr/local/etc/getmy-books/state/env-allowlist(root-owned, 0600, installed frominfra/nas/deploy/env-allowlist, which holds exactly the namesscripts/deploy-nas.shsends). Every line must beNAME=valuewith the name on the list, set once;COMPOSE_*andDOCKER_*are refused even if listed, sinceCOMPOSE_PROJECT_NAMEwould start a second project on an empty volume.uprefuses if the allowlist is not root's. Only names are printed, never values. Inert until the owner installs the checker, the allowlist and the newuptogether;upwithout the allowlist refuses every deploy. 4a. The compose check (infra/nas/deploy/getmy-books-compose-check, installed root-owned at/usr/local/sbin/) refuses:privileged; host network, pid, ipc or user namespace;cap_add;devices;security_opt;volumes_from; any bind mount; any volume other than the app's data volumepostgres-data; anddriver_optson a volume (a named volume can bind a host path that way). It prints only the reasons, never the config, which holds the resolved secrets. The host ipc, user namespace,security_optandvolumes_fromrefusals go slightly beyond the Product Owner's list, as the same kind of escape.
Amended 2026-11-03 (#80, #77): an allow-list, not a deny-list. A deny-list passes any key it has not heard of, so the check now refuses anything not on its list, still in bash and awk on the same YAML stdin, so
getmy-books-upand the sudo rule are unchanged.- Top level:
name,services,networks,volumes. - A service:
image,build,environment,env_file,restart,depends_on,healthcheck,logging,volumes,ports,networks,init,stop_grace_period,stop_signal,command,entrypoint,working_dir,profiles,labels,user,read_only,cap_drop. Any other key is refused by name. - Named refusals, besides the ones above:
userroot (or uid 0);sysctls;extra_hosts;tmpfs(as a key or a mount type);ulimits; anynetwork_mode, includingservice:<x>andcontainer:<x>; anypid,ipcoruserns_mode. imagemust be pinned by@sha256:<64 hex>(ADR 0028 decision 6, the pin half; the compose file pinspostgresand a versionedcloudflared, #77).buildtakes onlycontext,dockerfile,args,targetandlabels(no buildnetwork,entitlements,secretsorssh). Refusingbuild:itself waits for ADR 0028, when the app is pulled by digest.portsonly onpostgres, until ADR 0030 removes its LAN port.- Volumes:
postgres-dataonly, as a named volume (long syntax judged ontypeandsourcein either order); no external volume or network; networks use thebridgedriver. - Layout: two-space block YAML, as
docker compose configprints it. Tabs, flow-style YAML on any line (any value in braces or brackets but an empty{}or[], even behind an anchor or tag; a top-level section with a value, #332), other indents and a second document are refused rather than guessed at.
The check runs under gawk, mawk and busybox awk. Inert until the owner reinstalls
/usr/local/sbin/getmy-books-compose-checkon the NAS from the merged commit; the compose-check v2 and v3 rules indocs/plans/deploy-hardening.mdbecome additions to this list.- uses only
Sudo rule (
infra/nas/deploy/sudoers-getmy-books-deploy, installed as/etc/sudoers.d/getmy-books-deploy, mode0440, checked withvisudo -cffirst):deploy ALL=(root) NOPASSWD: /usr/local/sbin/getmy-books-up "", so no arguments are allowed.The pipeline (
scripts/deploy-nas.sh) sends one tar of the tracked files plus the env file (the allow-listed names from Dopplerprd, amended 2026-11-03, #79), with the commanddeploy <commit>, and reports what the NAS prints. It no longer needsNAS_DEPLOY_DIRorNAS_DEPLOY_COMPOSE.Keys and settings. A new ed25519 key pair made for this job only. In Doppler
prd:NAS_DEPLOY_USERbecomesdeployandNAS_DEPLOY_SSH_KEYthe new private key.Remove the old key from
robonce one deploy has worked throughdeploy, and check it no longer logs in.
What changes, and where
| Where | Change |
|---|---|
| NAS | Create user deploy with a home folder and /bin/sh; its ~/.ssh/authorized_keys with the one forced-command line; /usr/local/bin/getmy-books-receive; /usr/local/sbin/getmy-books-up; /usr/local/sbin/getmy-books-compose-check; /usr/local/etc/getmy-books/docker-compose.yml; /etc/sudoers.d/getmy-books-deploy; last, remove the pipeline key line from rob's authorized_keys |
Doppler prd | NAS_DEPLOY_USER=deploy; NAS_DEPLOY_SSH_KEY replaced |
| Repo | The four files under infra/nas/deploy/; scripts/deploy-nas.sh; tests/infra/ |
| Git host | Nothing: the host had no repository variables, so the NAS_DEPLOY_ENABLED gate in ci.yml is removed once the checks pass |
| Runner | Nothing |
Order, with checks
a. Merge the repo changes with NAS_DEPLOY_ENABLED still off. b. Create the user; install the three programs, the root-owned compose file and the sudoers file from main. Checks: visudo -cf passes; sudo -l -U deploy lists only /usr/local/sbin/getmy-books-up ""; the programs and the compose file are owned by root and not writable by deploy; the compose check passes on the installed file; deploy is not in the docker or administrators groups. c. Add the key. Checks, from the runner's address: ssh deploy@nas id, a shell, scp and port forwarding are all refused; a request from any other address is refused. d. Update Doppler prd; the Product Owner sets NAS_DEPLOY_ENABLED=true; the next merge deploys. Check: /health shows the commit. e. Remove the key from rob. Check: it no longer logs in.
Done on 2026-09-29
Steps b, c and d were run on the NAS by the agent, as the Product Owner asked, with every check passing. Step e follows the first deploy through deploy. The git host in use had no repository variables, so the NAS_DEPLOY_ENABLED gate was removed rather than set.
DSM 7.4.1 differs from a stock Linux host in ways the install had to follow:
- Docker is at
/usr/local/bin/docker, which is not onsudo's path.getmy-books-upsets its ownPATH, so the deploy is unaffected. - There is no
visudo. The sudoers rule is byte-identical to the onevisudoaccepted in a container dry run, andsudo -lwas checked straight after installing it. - There is no
getent; users are read from/etc/passwd. synouseris at/usr/syno/sbin/synouser;sshdat/usr/bin/sshd./usr/local/sbindid not exist and was created (root, 0755).- DSM's sudo (1.9.5p2) accepts
getmy-books-upwith no arguments, and also with a literal""argument; any other argument is refused. Harmless, sincegetmy-books-upnever reads its arguments. deploy's password field is*, not locked with!.- DSM resets a non-administrator's login shell to
/sbin/nologinwhenever it rewrites/etc/passwd(it did at 12:13 UTC on 2026-09-29, likely when another user's password changed)./sbin/nologindoes not exist on DSM, so everydeploylogin then fails with "Permission denied, please try again." and the deploy job fails loudly. The first deploy throughdeployfailed this way; the shell was set back to/bin/sh. Fixed 2026-09-30 (#69, the Product Owner chose a DSM task):infra/nas/deploy/getmy-books-deploy-shell, installed root-owned as/usr/local/sbin/getmy-books-deploy-shell, puts/bin/shback when the shell is/sbin/nologinand changes nothing otherwise. DSM Task Scheduler task 3, "GetMy Books: restore deploy shell", runs it as root every 5 minutes, all day. Tested: with the shell set to/sbin/nologin, the 09:05 run restored it. A reset can still break a deploy that starts in the 5 minutes before the next run; the job fails loudly and a rerun passes. With this in place,rob's old pipeline key (the fallback kept until now) was removed.
Consequences
- A leaked pipeline key can only send a release tar from the runner's address; it gets no shell and cannot run commands of its choosing.
- What root still takes from the
deployaccount: the code (built into the app image by the Dockerfile in the release) and the env file. A Dockerfile build runs inside Docker's build sandbox, and the compose file that decides mounts, privileges and networks is root's own, checked before every start. A change toinfra/nas/docker-compose.ymlneeds the root-owned copy reinstalled from the repo by hand; until then the NAS keeps running the old file. Later (queued): build the image in CI and pull it by digest on the NAS, so nothing is built there at all. - DSM updates can reset the login shell,
/etc/sudoers.d,/usr/local/bin,/usr/local/sbinor/usr/local/etc. After each DSM update the first deploy fails loudly rather than silently, and the files are reinstalled from this repo. - Docker access stays with root;
deployitself cannot run Docker. - Added 2026-11-03 (#78):
infra/nas/manifestlists every file underinfra/nas/with its install destination, owner, mode and SHA-256 (tests/infra/nas-manifest.test.tskeeps it current), andinfra/nas/deploy/getmy-books-drift-check, run daily as root by a DSM task, compares the installed files with it and alerts through the rootalert.envwhen any differ, naming only the files in its log. Both are inert until the owner installs them. Who owns the install (a homelab-infra Ansible role or this hand install) is still the owner's decision (#78). - Decided 2026-11-04 (#78; Decided by: Product Owner): the install manifest plus the daily drift check is the answer for one NAS. The files stay installed by hand from this repo, checked against
infra/nas/manifestevery day; no homelab-infra Ansible role is written now. Ansible is revisited if a second host appears. - Recorded 2026-11-08 (#72; decision of 2026-11-06, Decided by: Product Owner): the target state for the owner's own
robaccount, which ADR 0023 did not cover. Done so far: the pipeline key and the unusedwsl2-claude-codekey are removed (2026-09-30), and the other automation keys carryno-agent-forwarding, no-port-forwarding,no-X11-forwarding,no-pty. Still to do, by the owner on the NAS (agents never change the NAS):- replace the no-passphrase key
robad@local-machine-nopasswith a new passphrase-protected key (decided over DHCP reservations plusfrom=), proving the new key signs in before the old line is removed; - give every remaining automation key in
rob'sauthorized_keysafrom=and a forced command, or move it to its own restricted user likedeploy(thegh-actions-adviser-mcp-deployand "ppp" keys need their runner hosts identified first); - take
robout of thedockergroup once nothing under that account needs it, and check thatsudo docker psasks for a password. Target state: every key inrob'sauthorized_keysis either restricted or a passphrase-protected admin key, androbcannot rundockerwithout sudo.
- replace the no-passphrase key