diff --git a/00-META/glossary.md b/00-META/glossary.md index 9062b7fa..1ffaa22b 100644 --- a/00-META/glossary.md +++ b/00-META/glossary.md @@ -214,6 +214,10 @@ and Health and repair. **Decided by** ADR 0100, 0126, 0176, 0181, 0207, 0221, 02 against this account's home and owned by it ([ADR 0181](../02-DECISIONS/0181-the-operator-account-is-a-node-fact-and-a-home-is-a-placement-root.md)). Not a name a manifest carries. +- **agent account** — the login every coding agent on a node runs as, when the node names one of its own; + stated on the node record at the controller's terminal, never by a verb or a setting. Empty means agents + run as the operator account. It cannot become root without a person, and the node-engine judges that on + every look ([ADR 0266](../02-DECISIONS/0266-on-the-control-node-agents-run-under-an-account-of-their-own-that-cannot-become-root-without-a-person.md)). - **account group** — a group of the machine's group database that a module puts an account in, by declaring the account with that group and nothing else of it. Several modules may each add one to the same account; the mesh takes back only an account group it added diff --git a/02-DECISIONS/0266-on-the-control-node-agents-run-under-an-account-of-their-own-that-cannot-become-root-without-a-person.md b/02-DECISIONS/0266-on-the-control-node-agents-run-under-an-account-of-their-own-that-cannot-become-root-without-a-person.md new file mode 100644 index 00000000..9a334026 --- /dev/null +++ b/02-DECISIONS/0266-on-the-control-node-agents-run-under-an-account-of-their-own-that-cannot-become-root-without-a-person.md @@ -0,0 +1,420 @@ +--- +topic: what runs on it +status: accepted +date: 2026-10-08 +deciders: jochen +reconstructed: false +extends: 02-DECISIONS/0181-the-operator-account-is-a-node-fact-and-a-home-is-a-placement-root.md +--- + +# 266. On the control node, agents run under an account of their own that cannot become root without a person + +## Context + +Every coding agent on the mesh runs as the node's operator account +([ADR 0181](0181-the-operator-account-is-a-node-fact-and-a-home-is-a-placement-root.md)). The tool runner runs +as the same account ([ADR 0175](0175-one-tool-runtime-per-node-serves-every-modules-tools-on-the-host-side.md)), +and so does the `claude-code` module that configures the agent +([to-be 36](../03-DESIGN/01-to-be/36-the-operators-agent-on-a-machine.md)). The acting tools reach root through +that account's passwordless `sudo`, which the `sudo` module declares +([to-be 42](../03-DESIGN/01-to-be/42-the-machines-modules-in-order.md)). + +On 2026-10-08 the `sudo` module's own check on the control node said what that account may do: + +- two rules grant it every command as root without a password: the module's drop-in, and a line set by hand + in the machine's main sudoers file before the module existed; +- it is in the `docker` group, which runs a container with the machine's root filesystem mounted, so it is + root without sudo at all; +- the tool runner's bus credential is owned by it, mode 0600, and carries the grants of every module the + runner serves. + +So any agent on the control node can become root without a person, and can read and use the runner's bus +credential. ADR 0259 (hq pull request 211, not yet merged) +§8, as revised after the security review of 2026-10-08, rests the router's approve warrants and a channel's +`verified-sender` on a self-check that finds **no account an agent runs as can become root without a +person**. On the control node that check fails today, and nothing measures it. + +On 2026-10-08 the operator chose one of the three remedies ADR 0259 §8 offered: **on the control node, agents +run under an account of their own, without sudo. The operator's own account keeps its sudo.** + +[Issue 333](../04-ISSUES/333-an-agent-on-the-control-node-can-become-root-without-a-person/00-report.md) records +the symptom. + +## Considered Options + +### Where the account is named + +1. **A setting of the `claude-code` module.** Rejected. Any principal granted `mesh-controller.settings` may + write a setting, agents included (the same argument ADR 0259 §7 makes for the operator's identity). An + agent could name the operator's account again. +2. **A fixed name in the module's manifest.** Rejected. A definition names no installation + ([ADR 0155](0155-a-definition-names-no-installation-and-how-that-is-checked.md)), and a fixed name would + apply on every node, including the operator's own machines, where the agent works in the operator's + desktop and files. +3. **A node fact, stated by the operator at the controller's terminal, beside the operator account.** + Chosen. No verb and no setting writes it, so no agent can change it. + +### How the operator starts a session there + +1. **`su` to the account.** Rejected. It needs a password for the account: a secret to keep, and an account + that a stolen password logs into. +2. **An ssh login as the account.** Rejected for now. It works from any terminal, but it opens a network + login into the account, needs a key placed for it, and is a second door into the account that the guard + cannot watch. +3. **`machinectl shell @`.** It gives a full login session, and needs root through polkit, so it + goes through the operator's sudo anyway. Heavier than the agent needs; the operator may still type it. +4. **The operator's own sudo, `sudo -iu claude`, as one command the module places + (`claude-agent`).** Chosen. The operator is the person whose sudo opens the account, and nothing else + can open it. + +### Which account the tool runner runs as + +1. **A service account of its own.** Rejected for now: + - the acting tools reach root through `sudo -n` as the runner's account, so a service account would need + the same passwordless sudo, and root would move rather than shrink; + - on the operator's machines the runner must be the operator's account to reach the desktop session + ([to-be 38](../03-DESIGN/01-to-be/38-building-the-operators-machine.md)); + - on the control node the operator's account is the person's and holds root anyway, so whatever can read + the credential as that account can become root regardless. + + What the security review's first finding asks is that **an agent** cannot read the runner's credential. + An agent account of its own reaches that, and the node-engine checks it (below). +2. **Keep the runner as the operator's account.** Chosen. The credential still carries every co-hosted + module's grants. Narrowing it to one credential per bundle is separate work, and ADR 0259 rule 1 already + takes the trusted parties (the router and the verified channels) out of the runner onto accounts of + their own. + +### How "cannot become root" is known + +1. **Trust the configuration**: the `sudo` module's rule names only the operator's account. Rejected. One + machine showed three ways to root on one account, and two of them were not the module's. +2. **The node-engine judges the account on every look, and the controller's self-check reads the verdict.** + Chosen. + +## Decision + +**What this record does, and what it does not.** It moves agents off the account that holds root, and it +**detects** a way to root from the agent account; it does not **prevent** one. The node-engine judges the +ways listed in §3 and nothing else. A way it does not judge is a way it does not see, and §3 names those +too. Prevention is the account having no rights to start with: no sudo, no root group, no secret of anyone +else's. The judgement says when that stops being true. + +### 1. A node may name an agent account + +**A node may name an agent account: the login every coding agent on it runs as.** The operator states it at +the controller's terminal, `mesh-controller node agent-account [home]`, and clears it with +`--clear`. It is never a verb and never a setting. **No verb reaches it.** The controller's `command` verb, +which runs the controller's own command lines for a caller, is an allow list of commands that only read. +Everything else is refused through every verb, including a command added later, until someone judges it a +read. Otherwise an agent could clear the fact, or name itself the operator account, and the next send would +write it a sudo rule (§7 lists what `command` allows). The controller +refuses root, the node's operator account as the agent account and the agent account as the operator account, +and well-known service accounts by name. It cannot read the machine's user database, so the node-engine +refuses to take over an existing account below the first login uid (1000) as one that never becomes root. **Empty means agents run as the operator account**, as before. + +The controller resolves three machine facts from it: + +- `agent-account` is the agent account, or the operator account where none is named; +- `agent-home` is that account's home; +- `agent-root` is `never` only where the node names an agent account of its own, and empty otherwise. + +The tool runner is given `MESH_AGENT_ACCOUNT` and `MESH_AGENT_HOME` beside the operator's. + +**On the control node the agent account is `agent`.** The other nodes keep their agents as the operator for +now. The operator's machines do so because the agent works in the operator's desktop and files there, under +the risk ADR 0234 accepts. A server may follow: it is moved by stating the fact. + +### 2. The account is declared and has no way to root + +The `claude-code` module declares the account as a `user` resource named `${machine:agent-account}`, with +`root: ${machine:agent-root}`. The mesh creates the account with its home, its own group and no password. +No module puts it in a group. The `sudo` module's rule names only the operator account. + +### 3. The node-engine judges `root: never` on every look + +The node-engine judges a `user` with `root: never` on every look, by reading only, with every command in +the C locale. It finds a way to root when the account: + +1. has uid 0; +2. is in a group that grants root by membership: `root`, `wheel`, `sudo`, `admin`, `docker`, `disk`, `lxd`, + `incus-admin` or `libvirt`; +3. or one of its groups has any sudo rule, as `sudo -l -U ` lists it, with or without a password + (the decision is no sudo); +4. or one of its groups has any doas rule (`/etc/doas.conf`, `/etc/opendoas.conf`). A machine without sudo + is not read as having no rules: doas and polkit are judged from their own rules; +5. or one of its groups is named by a polkit rule (`/etc/polkit-1/rules.d`, `/usr/share/polkit-1/rules.d`, + `/etc/polkit-1/localauthority`). That covers what `pkexec` and the service manager's own actions grant; +6. is covered by a polkit rule that grants every account: a `.rules` file that answers `polkit.Result.YES` + and names no user and no group, or a `.pkla` whose identity is every user or every group with a result + of yes; +7. can write a container runtime's socket (docker, podman, containerd), by owner, group, other or POSIX ACL; +8. can reach a container runtime's API on TCP port 2375 or 2376, which any local account reaches; +9. can read a secret the declaration places for another account, by owner, group, other or POSIX ACL. The + tool runner's credential is one of those; +10. could run a program no installed package owns that is setuid with owner root, or setgid with group root + whoever owns it, on any local filesystem mounted without `nosuid` (container and image layers, network + and pseudo filesystems excepted). The engine searches for these in the background, at most hourly, and + lets one search run for at most 15 minutes. Until the first search after the engine starts has finished, + the verdict is *not judged yet*. *Corrected 2026-10-09: this said the search gets two minutes; the engine's + bound on a search is 15 minutes, and it governs the whole search: mesh-host pull request 61 dropped a + two-minute limit that sat inside it. The package manager is asked about every path found in one call, and a + walk `find` ended with an error is incomplete unless every error was a file that vanished while it walked;* +11. lives on a machine whose kernel leaves hard or symbolic links to other accounts' files unprotected + (`fs.protected_hardlinks` or `fs.protected_symlinks` is 0). + +**Not judged, so not seen** (the node-engine keeps the same list beside the judge): + +- a root-run unit, timer, cron entry or script the account can write; +- a directory on root's `PATH`, or in `/etc/profile.d`, the account can write; +- root's or the operator's ssh keys or `authorized_keys` readable or writable by it; +- a file root writes or reads in a directory the account owns, other than below its home (below a home the + node-engine refuses links, §7); +- file capabilities on a program; +- a setuid program a package installed that has a flaw of its own; +- a terminal shared with a root process. `use_pty` (§7) covers sudo; it is not judged; +- a polkit rule that grants every account by logic the text does not show, or every account with an active + local session; +- a container runtime's API on another TCP port, or on a unix socket not named in 7; +- a setuid program on a filesystem not searched: a container or image layer, a network or FUSE filesystem. + +Any way found makes the declaring module's account resource unhealthy, with the reason *can become root +without a person*, followed by every way found. **A question the machine did not answer is unknown, never +healthy**: a search that ran out of time, no package manager to ask, rules that could not be read. The verdict carries `root: never`, so the controller can tell this judgement from a group check. +An engine that judges it says so in its statement (contract 3). An older engine is not sent the field, +because it parses strictly and would refuse the whole declaration. + +### 4. The controller's self-check says it, and ADR 0259 reads it + +The self-check holds an invariant: every node that names an agent account has it judged, on its engine's +newest statement, unable to become root without a person. **A verdict heard more than 15 minutes ago is not a +judgement**: an engine states its health at least every 5 minutes, so three missed statements mean it has +stopped, and an agent that stops the engine must not freeze a healthy verdict. The age is measured on the +controller's own clock. Otherwise it raises the urgent condition +`agent-can-become-root`, which says what to change. `mesh-controller.node` shows the verdict and when it was +judged. + +**This is the fact ADR 0259 §8 rule 2 reads.** On a node with an agent account of its own, a healthy verdict +means no account an agent runs as can become root without a person. The guard (§6) makes the agent account +the only one an agent works in there. On a node without an agent account, agents run as the operator +account, and the check holds only where that account cannot become root either. The rule and the code that +answers it are one function in the controller, which the router's check will call. + +### 5. The agent is configured for its own account + +The managed directory under `/etc` is unchanged and machine-wide. The licence token, the account the agent is +logged in as, an API-key licence and its key-helper, and the items registered at the home scope all go to +the agent account's home. + +The tool runner cannot enter that home. So these files are written as the agent account, by a helper: the +`claude-code` module's own binary as the managed directory carries it, root's, started through the runner +account's sudo. **The escalation goes down only.** The runner's account may become the agent's, and the +agent's may become nothing. + +When a node moves its agents, the licence follows at once. What the module placed in the operator's home +goes, as [ADR 0182](0182-inside-a-home-the-mesh-owns-what-it-places-and-holds-the-rest-as-found.md) allows +for what the mesh placed. A login the person made there stays. + +### 6. The guard refuses a session that runs as another account + +The guard on the agent's shell +([ADR 0245](0245-a-verb-says-what-it-replaces-and-the-agent-is-guarded-from-working-round-the-mesh.md)) is +asked about every tool, not only the shell and file edits. On a node with an agent account it refuses every +tool call of a session that does not run as that account: the shell, edits, reads and the mesh's tools alike. +No override lifts it. An agent started as the operator out of habit can do nothing there, and is told to use +`claude-agent`. + +Its record goes to the machine's journal, because the agent account cannot enter the module's state where +the record lives elsewhere. **The record is append-only, not authentic.** The agent account cannot remove a +line, and the module reads only the lines the journal says the guard's own binary wrote, so `logger` cannot +add one. But the agent account can run the guard's binary itself and add lines in its words. A line in the +record is the guard's words, not proof that a session was refused. + +### 7. How a session starts, and what the agent may still do + +The operator starts a session with `claude-agent`, which runs `claude` as the agent account through the +operator's own sudo. Work that needs root is the operator's, in their own shell. + +The agent may do everything the mesh MCP server serves, with the tool runner's grants, as an agent does on +any node. It may not run anything as root, use the container runtime, enter the operator's home or read the +runner's credential. + +`claude-agent` runs the agent through sudo, and the `sudo` module's drop-in sets `use_pty`, so the command +gets a terminal of its own. Otherwise the agent shares the operator's terminal and could push keystrokes into +the operator's shell after it ends (the `TIOCSTI` call). + +**The tool runner acts for any caller of the mesh MCP server, the agent included, so every tool that touches +a path is a way round this record unless it is bounded.** Four were found in review, and each is closed +here: + +- the controller's `command` verb ran any of the controller's command lines. It could set the agent account + (§1), set the operator key, issue a credential or hand out a secret. It is now an allow list of reads: + `status`, `version`, `help`, `seats`, `healers`, `hand-acts`, `durations`, `collection`, `images`, + `artifacts`, `data`, `builds`, `queue`, `plan`, `plans` but not its go, stop, close or retry, wherever the word stands in the line, `doctor` and its + probes and signals but not `doctor run`, `conditions` and its list, show and history but not silence, + `node list` and `node show`, `module list`, `settings show` and `settings preferences`, `retire list`, + `cleanup list`, `delivery plan` and `delivery walks`, `bus` alone, and `mirrors` without recording. Every + route refuses `operator`, `identity`, `broker`, `api`, `licence` and every `secret` subcommand but `rotate`, + which seals to the machine that uses the secret, never to a key the caller chooses. **The `token` verb is + refused too**, because it handed the joining token to its caller. Enrolling a machine is now done at the + controller's terminal, by the operator; +- `claude_code_add_api_key` read a caller's file as the operator, sealed it away and deleted it. It now takes + only a file under the agent's own home, reached through no symbolic link, read as the agent, at most 4 KiB, + holding an Anthropic API key. The licence manager refuses a key of another shape too; +- the node-engine, as root, changed the owner and mode of the agent's `~/.claude` by following its path. A + symbolic link put there by the agent would have pointed root at any file. Below a home it now refuses a + symbolic link in the path, opens each part without following a link (a directory as a directory), and + refuses an opened file of the wrong kind or with more than one hard link before it changes owner or mode + on it. It still unpacks an archive, and writes into an existing file, only after a check of the path, so + it refuses either below the home of any account the declaration says never becomes root, and the + catalogue's own check refuses either under `${machine:agent-home}`, so no module asks for that gap; +- the backup's restore wrote, as root, beside the live data. Beside a directory another account owns, such + as the agent's home, it now restores into its own module's state instead. + +A tool that runs a caller's command as root, or reads, writes or removes a caller's path as the operator or +as root, is a defect of that tool, found by review of its manifest and code. + +**Where the boundary stands, 2026-10-09.** *Added 2026-10-09, after review of the routes found since this +record was written; what was decided above is unchanged.* The tool runner acts for any caller of the mesh MCP +server, so the agent account's boundary is only as good as the tools that caller reaches. These routes were +found around it and are closed on the mesh's main line: + +- **The store's reader** ([issue 337](../04-ISSUES/337-the-stores-reader-can-read-the-controllers-signing-key/00-report.md)): + `mesh-store.query` could read every sealed secret and the key that signs every node's declaration, so any + caller could forge what a node applies as root. The reader now reads only what a module declares readable, + never a secret. Live on the control node and the home server since 2026-10-08. +- **A module's places and accesses, and the keys a provider serves** + ([issue 339](../04-ISSUES/339-a-verb-can-place-a-directory-at-the-machines-own/00-report.md)): a settings + call could have the node-engine, as root, hand a system directory to any account, or mount one into a + container. Those keys, every key a provider serves, every setting a trusted file asks for, and the whole + layer of a module with a trusted mergeable file are now set at the controller's terminal alone. The + node-engine refuses a placement or a mount at the machine's own trees, root's or another account's + directory below a home, and uses a directory it did not make as found. This record's own copy of that + engine guard was dropped for it; the one rule kept here is the archive and written-into file below an + agent's home (§7). +- **What every Claude Code session obeys** + ([issue 340](../04-ISSUES/340-an-agent-can-plant-a-hook-in-every-agent-session-on-the-mesh/00-report.md)): + an agent could register a hook, managed settings, a permission rule or a tool server for every node, and + have it run as the operator at the operator's next session elsewhere. Those, and shared agent text, are now + set at the controller's terminal alone. The home scope is written only into the home of an agent account + of its own, on the node serving the call, never into the operator's home. +- **The login shell's `execute` on the control node** + ([ADR 0268](0268-the-login-shells-execute-is-withheld-on-the-control-node-until-a-call-to-it-needs-a-persons-approval.md)): + it ran any command as the operator account. The control node withholds it; the setting that withholds it + is a trusted file's, so it is changed at the terminal alone. + +**What still remains, said plainly.** None of these is closed by this record or its pull requests: + +- **The login shell's `execute` on the other nodes**, and the desk's `node-terminal-emulator.open` and + `rofi_run`, run a caller's command as the operator account of their node, which has passwordless sudo + there. So an agent on the control node can still become root **on another node** through the mesh MCP + server. Whether the operator account on one of those nodes holds a key that logs into the control node + was not measured; where one does, this is also a way back to root on the control node. ADR 0268 §4 closes it + once a call to such a tool needs a person's approval (research 039); until then, withholding `execute` on + every node is the operator's choice, at the terminal. +- **Tool servers already on the bus** keep rendering until their own change lands (issue 340, "still + open"). Text written straight into the bus state needs a tool runner's credential, which the agent account + cannot read. +- **The tool runner on the control node is still the operator account** (Considered Options), so a tool + found tomorrow that reads, writes or runs a caller's path or command is a way round this record until it is + bounded. Each is a defect of that tool, found by review. +- **A build from another repository registered a module** (found in review, 2026-10-09). The controller's + `build` verb cloned any repository as given, and the outcome registered the module its `module.json` named, + from that repository: a module is registered by name and its source overwritten, and "only a commit on the + trunk is published" (ADR 0238) checked the trunk of the repository built. An agent that made a repository, + or forked the catalogue or the node-engine, and committed a `sudo` module granting itself a rule without a + password, had the next push make it root on every node. `rebuild`, `replay --register` and `assign` with + `build` reached the same take-in. Closed by mesh-controller pull request 174, once merged after pull request + 164: through any verb, an outcome registers a module only from the repository the catalogue already builds + it from — the same repository by the forge's own id, so one deleted and made again under its name is + refused — and a new module only from a repository the catalogue already builds another from (a merge adding + one); and only from the mesh's forge, where that repository's trunk refuses direct pushes, requires a status + and lets no administrator merge past one. Anything else only when the build was asked at the controller's + terminal, for that repository and path; the serving controller marks itself and everything it starts, so + none of it reads as the terminal. Through a verb, a build of a repository the catalogue builds nothing from + is not asked at all, and a failed gate puts back only a build of the module's own repository. +- **The forge's tools could change the forge's protection** (found in review, 2026-10-09). `gitea_api` sent + any call with a token minted for the forge's administrator, `write:admin` included: an agent could drop a + branch's protection or its required checks, set the merge check's status, write to the default branch, + delete and recreate a repository the mesh builds from, or merge its own pull request past the checks; and + `gitea_branch_protection_set` could weaken a rule. Closed by mesh-catalog pull request 153: `gitea_api` + reads anything but the forge's administration and writes only what an author writes, never a pull + request's base; protection is only made stronger, a rule named for a branch included; a merge goes only into + a branch whose protection requires the checks, needs every required status a success, and merges only the + head that was checked; a tool deletes only a repository of its own user that no rule guards and that had no + commit in 30 days, named in full; and the token is minted without `write:admin`. The token still belongs to + the forge's administrator; a non-admin account for the tools is a follow-up. +- **An agent can merge its own pull request.** Every mesh repository's trunk requires its checks and no + approval (0 required approvals), and the forge's merge tool merges as the forge's administrator once the + checks pass. Nothing on the forge checks that the operator said yes: the operator's approval in chat is a + habit of the session, not a rule anything enforces. A merged module is what the next push sends, so an agent + that writes a change the checks pass can deliver it without a person. Whether to require an approval on the + forge is the operator's decision, not yet taken. +- **Every node-engine restart raises `agent-can-become-root`**, and the fix proposed for it must not open a + quiet of its own. Until the engine's first search for setuid programs finishes (§3 item 10), the verdict is + *not judged yet*, and the self-check (§4) raises the urgent condition on every restart. Mesh-controller pull + request 175 (merged after 174) keeps the condition quiet while that search is within its bound, counted from + when the controller first saw it waiting, kept in its store and forgotten at the next complete verdict — + never from the engine's own time, which starts again at every restart, so an agent that restarts the engine + in a loop does not keep it quiet. The account is still not confined, `node show` still says not judged, and + the condition is raised at once when the search fails or finds a way to root. Until that pull request is + merged, every restart raises the urgent condition. +- **The self-check judges this record's account only.** ADR 0259's own root probe (mesh-controller pull + request 154) asks the same question through the `sudo` module; it must call this record's judgement, one + function, rather than keep a second answer. + +The agent account holds a forge key of its own, registered by the operator, so its pushes are its own. It +works on branches and pull requests; what it may merge is said under *What still remains*. + +## Consequences + +- The operator types `claude-agent` on the control node instead of `claude`. Typing `claude` by habit gives a + session that can do nothing and says why. +- The agent's memory and history start empty in the new home. Copying what the operator wants from their own + home is the person's act (ADR 0182). +- The agent clones into its own home and cannot write the operator's checkouts. +- **What got harder:** anything an agent did on the control node through sudo is now a verb, or the + operator's act in their own shell. A missing verb is built in the module that owns the area (ADR 0245), + never worked round. +- **Root that remains:** the operator account keeps its passwordless sudo, and its docker group, so whatever + runs as it can still become root: the tool runner and the operator's own shells. No agent runs as it. +- **Not judged, said plainly:** the ways §3 lists under *not judged*. Each is a way to root this record does not + see. None is known on the control node, and each is left for a later record. +- The tool runner's credential still carries every co-hosted module's grants. The agent cannot read it. +- ADR 0181 decided one account per node. This record adds a second, of a different kind: not a person's + login, but the one agents run as. +- ADR 0259 §8's choice is made. That record can cite this one when it is accepted. What it can rely on is a + detection, as said at the head of the Decision: a way to root §3 does not judge is not seen. + +## How it is checked + +| Rule | Checked by | +|---|---| +| The agent account is stated only at the controller's terminal, never by a verb or a setting | controller test: the `node` verb's command line is `node show` alone; `node agent-account` refuses root, the operator's account and a malformed name | +| The machine facts fall back to the operator account, and `agent-root` is `never` only for an account of its own | controller tests on machine-fact resolution and the tool runner's environment | +| An older engine is not sent `root` | controller test: a user resource's `root` is taken out for an engine whose statement says contract 2 or less | +| The node-engine judges each way §3 lists, before any session logic, in the C locale, and an unanswered question is never healthy | node-engine tests over a fake reader, for each way and for none, for doas without sudo, for a search that ran out of time; a parsing test of `sudo -l -U` | +| `command` runs only reads, and no verb sets an account, the operator key or a credential, hands out a secret or the joining token | controller tests: about 60 writing, issuing or revealing lines refused through `command` and the named verbs; about 33 reads pass | +| No archive and no file written into is placed under the agent's home | the catalogue's `checks/agenthome`, in its `merge-check.sh`; node-engine test: an archive or a written-into file below the home of a `root: never` account is refused, a whole file passes | +| Root follows no link below a home | node-engine tests: a linked `~/.claude`, a linked parent, a file that is a link, a link swapped in after the check, a hard-linked file, an opened file of the wrong kind | +| A restore beside a directory another account owns goes to the module's state | backup module test | +| `claude_code_add_api_key` takes only an API key from the agent's own home | `claude-code` tests: a path outside, `..`, a link, a file that is not a key; nothing removed, nothing repeated; licence manager test refusing a key of another shape | +| An agent account that can become root, or is not judged, raises `agent-can-become-root`; a verdict older than 15 minutes is not judged | controller self-check probe tests: pass, fail, not judged, old engine, at the bound and a second past it | +| An existing system account is not taken over as the agents' | node-engine test: a `root: never` user naming an account with uid below 1000 is refused, nothing changed | +| The agent's files are written as its account, and nothing under its home is touched as the runner's | `claude-code` tests: every operation under the agent's home goes through the helper, none outside it does; a helper that died is started again | +| The licence follows a move, and what the module placed in the operator's home goes unless a person made or changed it | `claude-code` tests: a binding applied is fetched again when the agent's home holds no token; an access-token-only file goes, a login stays, a changed home item stays | +| The guard is asked about every tool; a session not running as the agent account does nothing there, with no override; the record keeps only lines the guard's binary wrote | `claude-code` guard tests | +| End to end | on the control node, after the steps in to-be 36 §9: the self-check passes its new invariant, `claude-agent` starts a session that lists the mesh MCP server's tools and holds its licence, `sudo -n true` in it fails, and `claude` started as the operator is refused at its first command | + +## References + +- ADR 0259 (hq pull request 211, not yet merged) §8 + (hq pull request 211, revised after the security review of 2026-10-08) +- [ADR 0181](0181-the-operator-account-is-a-node-fact-and-a-home-is-a-placement-root.md) (the operator account), + [ADR 0182](0182-inside-a-home-the-mesh-owns-what-it-places-and-holds-the-rest-as-found.md) (what the mesh owns + in a home), [ADR 0175](0175-one-tool-runtime-per-node-serves-every-modules-tools-on-the-host-side.md) (the + tool runner as the operator account), [ADR 0245](0245-a-verb-says-what-it-replaces-and-the-agent-is-guarded-from-working-round-the-mesh.md) + (the guard), [ADR 0252](0252-a-module-puts-an-account-in-a-group-and-the-mesh-says-when-a-new-login-is-needed.md) + (the node-engine's account judge this extends) +- [To-be 36](../03-DESIGN/01-to-be/36-the-operators-agent-on-a-machine.md) §9, the design this amends +- [Issue 333](../04-ISSUES/333-an-agent-on-the-control-node-can-become-root-without-a-person/00-report.md) +- the `sudo` module's `sudo_check` on the control node, 2026-10-08 diff --git a/03-DESIGN/01-to-be/36-the-operators-agent-on-a-machine.md b/03-DESIGN/01-to-be/36-the-operators-agent-on-a-machine.md index d0e7f277..9d1e0ff8 100644 --- a/03-DESIGN/01-to-be/36-the-operators-agent-on-a-machine.md +++ b/03-DESIGN/01-to-be/36-the-operators-agent-on-a-machine.md @@ -2,8 +2,9 @@ layer: to-be status: in-progress code: [mesh-catalog modules/claude-code] -updated: 2026-10-07 +updated: 2026-10-09 decisions: + - 02-DECISIONS/0266-on-the-control-node-agents-run-under-an-account-of-their-own-that-cannot-become-root-without-a-person.md - 02-DECISIONS/0243-the-agent-module-removes-a-home-item-it-did-not-place-only-on-the-persons-word-and-keeps-a-copy.md - 02-DECISIONS/0245-a-verb-says-what-it-replaces-and-the-agent-is-guarded-from-working-round-the-mesh.md - 02-DECISIONS/0216-the-agents-configuration-is-registered-through-its-module-at-three-scopes-and-served-as-one-plugin.md @@ -282,6 +283,86 @@ An item and its files are one value in the state, refused above 256 KiB. own settings, and the module does not route around that refusal. A settings tool is called on the operator's word. +## 9. The account the agent runs as + +*Added 2026-10-08 by [ADR 0266](../../02-DECISIONS/0266-on-the-control-node-agents-run-under-an-account-of-their-own-that-cannot-become-root-without-a-person.md).* +Everywhere above, "the operator's home" and "the operator account" mean **the account the agent runs as**. +That is the operator account, unless the node names an **agent account** of its own. The control node does. + +**The fact.** The operator states the agent account at the controller's terminal. No verb and no setting +writes it. The controller resolves the machine facts `agent-account`, `agent-home` and `agent-root`, and gives +the tool runner the account and its home. Where the node names none, the facts name the operator account and +`agent-root` is empty, so nothing changes there. + +**What the module declares.** + +- A `user` named by `agent-account`, with `root` set from `agent-root`. Where the account is the agent's own, + the mesh creates it (home, own group, no password) and the node-engine judges on every look that it cannot + become root without a person, by the ways ADR 0266 §3 lists. It detects those ways and no others; it + prevents nothing. +- `~/.claude` under that account's home, owned by it. +- `claude-agent`, a command that starts the agent as that account through the operator's own sudo, or + directly when already run as it. + +**What the module's code does differently.** + +- The credentials file, the account file, an API-key licence with its key-helper (in a directory of the + module's under the agent's `~/.claude`), and the home-scope items go to that account's home. +- The tool runner cannot enter that home, so the code touches it through a helper running as the agent + account. The helper is the module's own binary, root's, under the managed directory, started through the + runner account's sudo. The escalation goes down only. +- A binding counts as applied only while the agent account holds its token, so a move takes the licence with + it at once. +- Once the agent's home holds the licence, and not before, what the module placed in the operator's home + goes: the access-token-only credentials file, and the + home-scope items not changed by hand. A login the person made there stays. + +**The guard.** The guard is asked about every tool. On such a node it refuses every tool call of a session not +running as the agent account, with no override. Its record goes to the machine's journal, append-only but +not authentic (ADR 0266 §6). + +**An API key comes only from the agent's home.** `claude_code_add_api_key` takes a file under the agent +account's home, reached through no symbolic link, read as that account, holding an Anthropic API key, or it +refuses and removes nothing. A caller's path anywhere else would let any caller of the mesh MCP server carry +off the tool runner's credential. + +**The self-check.** The controller holds an invariant: every node naming an agent account has it judged +unable to become root without a person. When it does not hold, it raises `agent-can-become-root`, urgent. ADR +0259 §8 reads the same judgement before the router issues an approve warrant. + +**The operator's day on the control node.** The operator works in their own login, with their own sudo, and +types `claude-agent` to start an agent. The agent runs in its own home, with its own clones and its own forge +key. It reaches the mesh through the mesh MCP server as before, and asks the operator for anything that needs +root that no verb serves. + +**Steps on the control node, in this order.** The guard refuses the operator's own Claude sessions there from +the send in step 3, so everything that needs one comes before it. The operator's own shell, and its sudo, +are never refused: the way back never needs Claude. + +0. **Before any of it**, the routes round the boundary that ADR 0266 §7 names as closed are closed and + running: the store's reader (issue 337), places, accesses and served keys at the terminal (issue 339), + what every session obeys at the terminal (issue 340), and `execute` withheld on the control node + (ADR 0268). All four ran on 2026-10-09; the tool servers already on the bus stop rendering with their + own change. What ADR 0266 §7 says still remains is the operator's to weigh before step 3. +1. The node-engine, the controller and this module are built with ADR 0266 and sent to every node, in this + order: the node-engine first, until every engine says contract 3; then the controller, its node-engine + pin moved to the engine's merged commit; then the module's code; then its manifest, which the running + controller refuses until it knows the new machine facts. Nothing changes on any node. +2. Before naming the account, the operator finishes or ends every Claude session running as themselves on the + control node; from step 3 on they can do nothing. +3. The operator states the agent account at the controller's terminal. The next send creates the account, + places `~/.claude` and `claude-agent`, fetches the licence into the agent's home, and only then removes the + token the module placed in the operator's home. The guard there starts refusing sessions as the operator. +4. The operator starts `claude-agent`, checks that the session lists the mesh's tools and holds its licence, + and that `sudo -n true` fails in it. +5. The self-check's new invariant passes, and `mesh-controller.node` shows the account judged. +6. The operator generates a forge key in the agent's home and registers it. + +**The way back**, if step 4 or 5 fails: the operator, in their own shell, clears the fact at the controller's +terminal. The next send names the operator account again: the guard lets the operator's sessions through, +and the licence is fetched into the operator's home. The agent account is kept (the node-engine never deletes +a login). + ## How it is checked | Check | Defends | @@ -297,11 +378,15 @@ operator's word. | live: a skill registered at the mesh scope is offered as `nox-mesh:` in a new session on each machine | ADR 0216 | | the module's test: the "instead of" table is generated from the controller's answers, ordered and cut; the guard refuses ssh to a mesh machine by name, domain, internal name, address, alias and jump, and the local work-arounds for a mesh name, naming the tool — and lets git to the forge, ssh beyond the mesh and a command merely mentioning ssh through; the override is honoured only from the session's start and only when recorded | ADR 0245 | | the mesh MCP server's provision resolves by co-location; a machine without the mesh MCP server refuses the module by name | ADR 0027, ADR 0152 | +| the account the agent runs as: the facts fall back to the operator account; an agent account of its own is judged unable to become root, or raises `agent-can-become-root`; its files are written only through the helper; a session as another account is refused with no override | ADR 0266 | | a new session on the assigned workstation lists the mesh MCP server's five tools under `mesh` ([ADR 0195](../../02-DECISIONS/0195-the-meshs-tools-are-found-by-address-not-announced-whole.md)) and answers "which node am I" from the instruction file | the exit of the build | ## What this does not settle -- **Several operator accounts on one node** (ADR 0181 decides one). +- **Several operator accounts on one node** (ADR 0181 decides one). ADR 0266 adds a second account of + another kind, the one agents run as, which is no person's login. +- **An agent account on the operator's machines.** They keep their agents as the operator, because the + agent works in the operator's desktop and files there (§9). - **A worker's own licence on a machine.** Every interactive session shares the node's one agent directory and its licence, however many run. A worker runs from a home of its own with an agent directory in it, bound to its own licence through the manager (to-be 39 §5); that is for when workers diff --git a/04-ISSUES/333-an-agent-on-the-control-node-can-become-root-without-a-person/00-report.md b/04-ISSUES/333-an-agent-on-the-control-node-can-become-root-without-a-person/00-report.md new file mode 100644 index 00000000..5be38fba --- /dev/null +++ b/04-ISSUES/333-an-agent-on-the-control-node-can-become-root-without-a-person/00-report.md @@ -0,0 +1,56 @@ +--- +status: located +opened: 2026-10-08 +located-in: [mesh-catalog modules/claude-code, mesh-catalog modules/sudo, mesh-controller internal/catalogue, mesh-host internal/accounts] +fixed-by: +amended-design: 03-DESIGN/01-to-be/36-the-operators-agent-on-a-machine.md +--- + +# 333. An agent on the control node can become root without a person + +## Symptom + +On 2026-10-08 the `sudo` module's `sudo_check` on the control node answered, for the account every coding agent +there runs as: + +- `passwordless: true`, decided by the module's drop-in, which grants the operator account every command as + root without a password; +- a second grant of the same, set by hand in the machine's main sudoers file before the module existed; +- the groups `docker` and the account's own. Membership of `docker` is root without sudo: a container started + with the machine's root filesystem mounted. + +So every agent session on the control node can become root without a person. It runs as the same account as +the tool runner, so it can also read the runner's bus credential, which carries the grants of every module the +runner serves. + +## Why it matters + +ADR 0259 (hq pull request 211, not yet merged) +§8, revised after the security review of 2026-10-08 (hq pull request 211), lets the router issue an approve +warrant, and honours a channel's `verified-sender`, only on a machine where the self-check finds that no account +an agent runs as can become root without a person. The router and the first channel are placed on the control +node. There the condition fails, so an agent could publish a warrant, or answer for the operator, with the +runner's credential or as root. + +## What the design let pass + +- **Nothing measured it.** The `sudo` module reports what the operator account may do. No check asks which + account an agent runs as, or whether that account can become root. +- **One account did three jobs**: the person's login, the tool runner, and every agent. ADR 0181 decided one + account per node and left several open. + +## Where it is located + +| part | owner | +|---|---| +| which account the agent runs as, and where its files go | mesh-catalog `modules/claude-code` | +| the operator account's rule | mesh-catalog `modules/sudo` | +| a node naming a second account, and the self-check's invariant | mesh-controller `internal/inventory`, `internal/catalogue`, `cmd/mesh-controller` | +| judging whether an account can become root | the node-engine, `mesh-host` `internal/accounts` | + +## The decision + +[ADR 0266](../../02-DECISIONS/0266-on-the-control-node-agents-run-under-an-account-of-their-own-that-cannot-become-root-without-a-person.md): +on the control node, agents run under an account of their own. The node-engine judges on every look that the +account cannot become root without a person, and the self-check says it urgently when it can. The operator's +account keeps its sudo.