Skip to content

v0.4.0: permissions and authorization hardening (security release)

Choose a tag to compare

@arybach arybach released this 29 Oct 17:11
· 184 commits to main since this release
b12961c

v0.4.0: permissions and authorization hardening (security release)

This release hardens the kernel permissions plane, the app execution paths, the control plane and the Agent Gateway. It contains breaking changes: read "Upgrade impact" before upgrading.

Security fixes

Six security advisories describe the fixed weaknesses. Affected versions and remediation are in each advisory.

Advisory Subject Affected Severity
GHSA-v47p-4xpf-q3g8 The tool gate did not check tools that were unmapped or unclassified as read/write >= 0.1.0, < 0.4.0 High (8.1)
GHSA-5vj4-6pfv-hm72 Row-scope values from several grants were merged instead of evaluating each grant's whole predicate >= 0.1.0, < 0.4.0 Medium (4.3)
GHSA-39v2-c45g-8jxm The tool gate discarded row filters and column masks; an empty user matched ownerless rows >= 0.1.0, < 0.4.0 Medium (6.5)
GHSA-r47r-8q4v-4r8v The grant store could fall back to plaintext or an on-box key; concurrent writers could lose a removal >= 0.1.0, < 0.4.0 Medium (4.4)
GHSA-6g57-gcrq-prc8 Control-plane read routes answered without authentication >= 0.1.0, < 0.4.0 Medium (5.3)
GHSA-jgg2-g3hf-gfm2 The Agent Gateway returned raw exception text and contained-process stderr to callers >= 0.3.1, < 0.4.0 Medium (4.3)

Upgrade impact (breaking)

  • Tool gate fails closed. An application that installs the gate now denies tools that are not mapped to a resource or not classified read, write or delete in tool_actions. There is no administrator bypass in the basic plane. Map and classify your tools before upgrading; agentic_os/tool_actions.py has the table for this repository's own apps.
  • Grants. Several grants on one resource are combined as the OR of whole predicates; column masks are decided per row; in matching is exact (no case folding). Grants with malformed identifiers stop applying: find them with agentic-os permissions audit-identifiers.
  • Grant store keys. The store refuses to start without a valid key (PERMISSIONS_KEY, or an existing owner-only key file). It no longer falls back to plaintext or generates a key silently. PERMISSIONS_ALLOW_GENERATED_KEY_DEV=1 is a development opt-in.
  • Control plane. /api/permissions/* requires PERMISSIONS_ADMIN_KEY (at least 24 characters). GET /approvals, /jobs/{id}, /api/fleet, /status and /notify/status require the fleet credential (AGENTIC_OS_API_KEY or AGENTIC_OS_CONTROL_TOKEN) or the new read-only dashboard token (AGENTIC_OS_DASHBOARD_TOKEN, header X-Dashboard-Token). With nothing configured these routes answer 503; a stock compose deployment answers 503 until a key is set. /health returns liveness only to anonymous callers and /capabilities returns names only; /docs and /redoc are removed.
  • Demo grants are opt-in. A fresh install no longer creates example grants; set AGENTIC_OS_SEED_DEMO_GRANTS=1 for a demo that needs them.
  • Agent Gateway. Clients receive a short fixed error code (capability_error, gateway_error, ...) instead of exception text. Detail goes to the agentic_os.agent_gateway server log with the request id.
  • Authorization setting. An app started with AGENTIC_OS_PERMISSIONS unset or off enforces nothing and says so at start-up and in /health (authorization: unenforced). The shipped app images set AGENTIC_OS_REQUIRE_PERMISSIONS_SETTING=1.

The full migration guide is docs/PERMISSIONS_MIGRATION.md; the operator-facing release notes are RELEASE_NOTES_security.md.

What this release does not claim

  • The reviews behind these changes were multi-stage and AI-assisted, with separate reviewer agents working from the code diff. They are not an external audit or third-party certification.
  • This release does not make the control plane as a whole protected: the module proxy (/m/<name> and /m/<name>/api/*) still forwards requests without a credential (issue #528). Do not expose the port to a network you do not control.
  • The Enterprise packages are separate and out of scope of this release and of these advisories. The public kernel release passing its checks says nothing about a deployment of those packages.
  • The root Dockerfile does not build at this tag (a missing COPY of hatch_build.py since 0.3.40). Run the control plane from a source checkout of the tag or from an image you build yourself.
  • Hosted CI does not install agent-harness, so some tool-registry tests are skipped there; they pass in a local run with it installed.
  • Making the strict permission setting the default (an unset setting refusing to start) is planned for the next compatibility-breaking release.