Repository navigation
v0.4.0: permissions and authorization hardening (security release)
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,writeordeleteintool_actions. There is no administrator bypass in the basic plane. Map and classify your tools before upgrading;agentic_os/tool_actions.pyhas 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;
inmatching is exact (no case folding). Grants with malformed identifiers stop applying: find them withagentic-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=1is a development opt-in. - Control plane.
/api/permissions/*requiresPERMISSIONS_ADMIN_KEY(at least 24 characters).GET /approvals,/jobs/{id},/api/fleet,/statusand/notify/statusrequire the fleet credential (AGENTIC_OS_API_KEYorAGENTIC_OS_CONTROL_TOKEN) or the new read-only dashboard token (AGENTIC_OS_DASHBOARD_TOKEN, headerX-Dashboard-Token). With nothing configured these routes answer 503; a stock compose deployment answers 503 until a key is set./healthreturns liveness only to anonymous callers and/capabilitiesreturns names only;/docsand/redocare removed. - Demo grants are opt-in. A fresh install no longer creates example grants; set
AGENTIC_OS_SEED_DEMO_GRANTS=1for 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 theagentic_os.agent_gatewayserver log with the request id. - Authorization setting. An app started with
AGENTIC_OS_PERMISSIONSunset oroffenforces nothing and says so at start-up and in/health(authorization: unenforced). The shipped app images setAGENTIC_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
Dockerfiledoes not build at this tag (a missingCOPYofhatch_build.pysince0.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.