fix(web): reload Caddy without setuid sudo

[defangdevs]

Summary

• authorize configured agent users through polkit for exactly reload on caddy.service
• remove the built-in Caddy command from the sudo allowlist on both NixOS and native Ubuntu renderers
• update the shipped guide and Caddyfile instructions to use systemctl reload caddy.service directly
• remove the now-redundant Caddy sudo grant from the example host configurations

Fixes #726.

Security effect

The new policy matches the caller against the configured agent-user list and matches both polkit details: unit == caddy.service and verb == reload. It does not authorize stop, restart, daemon-reload, or actions on any other unit. Avoiding a setuid transition makes the supported reload path usable from Codex command namespaces where sudo appears owned by nobody:nogroup.

Testing

• python3 tests/test_agentbox.py — 151 tests pass, 1 environment-dependent skip
• python3 scripts/check_backend_parity.py — pass
• nix build -L .#checks.x86_64-linux.module-generated-up-to-date .#checks.x86_64-linux.golden-snapshot .#checks.x86_64-linux.one-spec-both-backends .#checks.x86_64-linux.backend-parity .#checks.x86_64-linux.assemble-module-escaping — pass
• nix build -L .#checks.x86_64-linux.web-surface — pass

The booted VM test exercises the literal user flow: write a new ~/sites/*.caddy vhost, reload without sudo from the agent's mount namespace, and fetch the new host. It also confirms that the same caller is denied stop caddy.service, restart caddy.service, and reload fail2ban.service.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: f296d59f-185e-4e43-86da-d83e1f464bc7

📥 Commits

Reviewing files that changed from the base of the PR and between ffb41ef and a87fad9.

📒 Files selected for processing (26)

• README.md
• bin/agentbox
• flake.nix
• hosts/bare-metal.nix
• hosts/vm.nix
• modules/agent-box.nix
• modules/agent-box.nix.in
• modules/src/caddyfile-header.caddy
• modules/src/caddyfile-sites.caddy
• modules/src/default-agents.md
• tests/golden/vm/etc/agent-box-guides/AGENTS.agent.md
• tests/golden/vm/etc/sudoers
• tests/golden/web/etc/agent-box-guides/AGENTS.agent.md
• tests/golden/web/etc/caddy/caddy_config
• tests/golden/web/etc/sudoers
• tests/native/config.json
• tests/native/config.yaml
• tests/native/expected-modes.json
• tests/native/expected/etc/agent-box-guides/AGENTS.agent.md
• tests/native/expected/etc/agent-box-guides/AGENTS.robot.md
• tests/native/expected/etc/agent-box/Caddyfile
• tests/native/expected/etc/polkit-1/rules.d/50-agent-box-caddy-reload.rules
• tests/native/expected/etc/sudoers.d/agent-box
• tests/spec.nix
• tests/test_agentbox.py
• tests/web-surface.nix

💤 Files with no reviewable changes (3)

• tests/golden/vm/etc/sudoers
• hosts/vm.nix
• hosts/bare-metal.nix

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The pull request replaces Caddy reload authorization through setuid sudo with a narrow polkit rule. The rule permits configured agent users to reload only caddy.service. Rendering, documentation, host configuration, generated outputs, and tests are updated.

Changes

Caddy reload authorization

Layer / File(s)	Summary
Policy rendering and lifecycle bin/agentbox, modules/agent-box.nix, modules/agent-box.nix.in	The renderer creates and removes a polkit rules file. The rule allows configured users to reload caddy.service only. The Caddy reload is removed from the sudo command list.
Module integration and guidance modules/agent-box.nix, modules/agent-box.nix.in, modules/src/*, README.md, hosts/*, flake.nix	Web-enabled configurations enable the polkit rule. Documentation and generated guidance use direct systemctl reload caddy.service commands. Host sudo allowlists no longer include the Caddy reload.
Generated outputs and authorization tests tests/golden/*, tests/native/*, tests/test_agentbox.py, tests/web-surface.nix, tests/spec.nix	Expected outputs and tests verify the policy contents, removed sudo permissions, policy cleanup, successful reloads, and denied stop, restart, and unrelated-unit operations.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant Agent
  participant systemctl
  participant systemd
  participant Polkit
  Agent->>systemctl: Request reload caddy.service
  systemctl->>systemd: Send manage-units request
  systemd->>Polkit: Evaluate caddy.service and reload
  Polkit-->>systemd: Allow configured agent user
  systemd-->>Agent: Reload Caddy

Loading

Suggested reviewers: lionello

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description clearly explains the polkit authorization change, sudo removal, documentation updates, security scope, issue reference, and test results. It directly matches the changeset.
Title check	✅ Passed	The title accurately and concisely identifies the main change: reloading Caddy without setuid sudo.
Linked Issues check	✅ Passed	Issue #726 requires a safe Caddy reload path that works when setuid sudo fails. The PR removes the Caddy reload sudo grant and adds a polkit rule for configured agent users. The rule permits only `rel…
Out of Scope Changes check	✅ Passed	The changes stay within issue #726. Renderer updates, NixOS and native configuration updates, generated golden files, documentation, and negative authorization tests support the replacement reload pat…
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 1 files. (22 skipped: 2…

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}