README
¶
sudo-broker
sudo-broker lets an authenticated local agent request and run one exact, operator-approved command as another Unix user. Commands come from a root-owned catalog. It does not accept shell strings, arbitrary executables, interactive shells, TTYs, stdin, or caller-controlled environment variables.
The runtime has two processes:
sudo-brokeris an unprivileged HTTP frontend using BrokerKit policy, grants, Operator V1, and Telegram approval.sudo-broker-execis a root helper reachable only through a private Unix socket by the dedicated frontend account.
Install
Install the latest checksummed release on Linux or macOS:
curl -fsSL https://raw.githubusercontent.com/osolmaz/brokerkit/main/brokers/sudo/install.sh | sh
The frontend is installed in the selected binary directory. The helper is
installed in the adjacent libexec directory and is not added to ordinary
user command paths.
Configure On Linux
Start from catalog.example.json and policy.example.json, then run:
sudo sudo-broker setup systemd \
--catalog-file ./catalog.json \
--policy-file ./policy.json
Setup generates independent client and operator secrets, installs a root helper
unit and an unprivileged frontend unit, and starts them in dependency order.
Use --no-start to write the configuration without enabling or starting it,
or --dry-run to validate and print the unit shape without changing the host.
Write a client config for an agent account:
sudo sudo-broker setup client \
--client bob \
--url http://127.0.0.1:8084 \
--secret-file /etc/sudo-broker/secrets \
--home-dir /home/bob
Verify host isolation and helper readiness:
sudo sudo-broker doctor host --agent bob
Use
sudo-broker run nginx-reload \
--as root \
--reason "Apply reviewed nginx configuration" \
--operation-id nginx-reload-20260713
run submits one Agent V1 operation, waits for approval, and executes the exact
cataloged command through the privileged helper. For typed catalog slots,
repeat --arg-json NAME=JSON. Reuse a stable --operation-id when retrying;
never retry an ambiguous execution under a new id.
See the threat model for the security boundary and platform-specific guarantees.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
sudo-broker
command
|
|
|
sudo-broker-exec
command
|
|
|
internal
|
|
|
catalog
Package catalog validates and resolves the root-owned sudo command catalog.
|
Package catalog validates and resolves the root-owned sudo command catalog. |
|
executorclient
Package executorclient connects the unprivileged frontend to the Unix helper.
|
Package executorclient connects the unprivileged frontend to the Unix helper. |
|
executorprotocol
Package executorprotocol defines the bounded frontend-to-helper wire protocol.
|
Package executorprotocol defines the bounded frontend-to-helper wire protocol. |
|
executorserver
Package executorserver validates and executes one-shot sudo plans.
|
Package executorserver validates and executes one-shot sudo plans. |
|
hostcheck
Package hostcheck validates privileged filesystem facts.
|
Package hostcheck validates privileged filesystem facts. |
|
plan
Package plan owns immutable sudo execution plans and activation validation.
|
Package plan owns immutable sudo execution plans and activation validation. |
|
presenter
Package presenter renders bounded sudo command approval details.
|
Package presenter renders bounded sudo command approval details. |
|
privexec
Package privexec performs the final no-shell Unix privilege transition.
|
Package privexec performs the final no-shell Unix privilege transition. |
|
routes
Package routes assembles sudo-broker's unprivileged HTTP frontend.
|
Package routes assembles sudo-broker's unprivileged HTTP frontend. |
|
sudopolicy
Package sudopolicy defines sudo-broker's provider-owned policy vocabulary.
|
Package sudopolicy defines sudo-broker's provider-owned policy vocabulary. |