Skip to content

Commit 87bb373

Browse files
giodl73-repogiodl73-repo
committed
feat(policy): add tool posture conformance
1 parent 391f29b commit 87bb373

7 files changed

Lines changed: 1412 additions & 12 deletions

File tree

‎docs/cli/policy.md‎

Lines changed: 35 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,21 @@ posture, and tool metadata looks like this:
120120
},
121121
"tools": {
122122
"requireMetadata": ["risk", "sensitivity", "owner"],
123+
"profiles": {
124+
"allow": ["messaging", "minimal"],
125+
},
126+
"fs": {
127+
"requireWorkspaceOnly": true,
128+
},
129+
"exec": {
130+
"allowSecurity": ["deny", "allowlist"],
131+
"requireAsk": ["always"],
132+
"allowHosts": ["sandbox"],
133+
},
134+
"elevated": {
135+
"allow": false,
136+
},
137+
"denyTools": ["group:runtime", "group:fs"],
123138
},
124139
}
125140
```
@@ -129,16 +144,23 @@ when a concrete rule is present. OpenClaw reads current `channels.*` settings
129144
`mcp.servers.*`, `models.providers.*`, selected agent model refs, network SSRF
130145
settings, Gateway bind/auth/Control UI/Tailscale/remote/HTTP posture, OpenClaw
131146
config agent sandbox workspace access and tool deny posture, config secret
132-
provider and SecretRef provenance, config auth profile metadata, and `TOOLS.md`
133-
declarations as evidence, then reports observed state that does not conform. If
134-
a policy denies non-loopback Gateway binds, omit `gateway.bind` only when you
147+
provider and SecretRef provenance, config auth profile metadata, configured
148+
global/per-agent tool posture, and `TOOLS.md` declarations as evidence, then
149+
reports observed state that does not conform. If a policy denies non-loopback
150+
Gateway binds, omit `gateway.bind` only when you
135151
are willing to review the runtime default; set `gateway.bind=loopback` for
136152
strict config conformance. For read-only agent posture, configure sandbox mode
137153
on the applicable defaults or agent and set `workspaceAccess` to `none` or
138154
`ro`; omitted or `off` sandbox mode does not satisfy a read-only/no-write
139155
policy. `agents.workspace.denyTools` supports `exec`, `process`, `write`,
140156
`edit`, and `apply_patch`; OpenClaw config `group:fs` covers file mutation tools
141-
and `group:runtime` covers shell/process tools. Secret evidence records
157+
and `group:runtime` covers shell/process tools. Tool posture policy observes
158+
`tools.profile`, `tools.allow`, `tools.deny`, `tools.fs.workspaceOnly`,
159+
`tools.exec.security`, `tools.exec.ask`, `tools.exec.host`,
160+
`tools.elevated.enabled`, and the same per-agent `agents.list[].tools.*`
161+
overrides. It does not read runtime/operator approval state such as
162+
exec-approvals.json, and it does not enforce tool calls at runtime. Secret
163+
evidence records
142164
provider/source posture and SecretRef metadata, never raw secret values. Policy
143165
does not read or attest per-agent credential stores such as `auth-profiles.json`;
144166
those stores remain owned by the existing auth and credential flows.
@@ -378,6 +400,8 @@ only `expectedAttestationHash` usually changes.
378400
Enabling or upgrading `agents.workspace` rules adds `agentWorkspace` evidence to
379401
the workspace hash and attestation hash. Operators should review the new
380402
evidence and refresh accepted attestation hashes after enabling these rules.
403+
Enabling or upgrading tool posture rules adds `toolPosture` evidence in the
404+
same way.
381405

382406
`openclaw policy watch` runs the same check repeatedly and reports when the
383407
current evidence no longer matches `expectedAttestationHash`:
@@ -416,6 +440,13 @@ Policy currently verifies:
416440
| `policy/gateway-http-url-fetch-unrestricted` | Gateway HTTP URL-fetch input lacks a required URL allowlist. |
417441
| `policy/agents-workspace-access-denied` | Agent sandbox mode or workspace access is outside the policy allowlist. |
418442
| `policy/agents-tool-not-denied` | An agent or default config does not deny a tool required by policy. |
443+
| `policy/tools-profile-unapproved` | A configured global or per-agent tool profile is outside the allowlist. |
444+
| `policy/tools-fs-workspace-only-required` | Filesystem tools are not configured with workspace-only path posture. |
445+
| `policy/tools-exec-security-unapproved` | Exec security mode is outside the policy allowlist. |
446+
| `policy/tools-exec-ask-unapproved` | Exec ask mode is outside the policy allowlist. |
447+
| `policy/tools-exec-host-unapproved` | Exec host routing is outside the policy allowlist. |
448+
| `policy/tools-elevated-enabled` | Elevated tool mode is enabled when policy denies it. |
449+
| `policy/tools-required-deny-missing` | A global or per-agent tool deny list does not include a required denied tool. |
419450
| `policy/secrets-unmanaged-provider` | A config SecretRef references a provider not declared under `secrets.providers`. |
420451
| `policy/secrets-denied-provider-source` | A config secret provider or SecretRef uses a source denied by policy. |
421452
| `policy/secrets-insecure-provider` | A secret provider opts into insecure posture when policy denies it. |

‎docs/plugins/reference/policy.md‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,27 @@ Adds policy-backed doctor checks for workspace conformance.
1616

1717
## Surface
1818

19-
plugin
19+
plugin; CLI command: [`openclaw policy`](/cli/policy)
20+
21+
## Behavior
22+
23+
The Policy plugin contributes doctor health checks for policy-managed OpenClaw
24+
settings and governed workspace declarations. Policy currently covers channel
25+
conformance, governed tool metadata, MCP server posture, model-provider posture,
26+
private-network access posture, Gateway exposure posture, agent workspace/tool
27+
posture, configured global/per-agent tool posture, and OpenClaw config secret
28+
provider/auth profile posture.
29+
30+
Policy stores authored requirements in `policy.jsonc`, observes existing
31+
OpenClaw settings and workspace declarations as evidence, and reports drift
32+
through `openclaw policy check` and `openclaw doctor --lint`. A clean policy
33+
check emits policy, evidence, findings, and attestation hashes that operators
34+
can record for audit.
35+
36+
Tool posture rules can require approved profiles, workspace-only filesystem
37+
tools, bounded exec security/ask/host settings, disabled elevated mode, and
38+
required tool deny entries. These checks observe config conformance only; they
39+
do not read runtime approval state or add runtime enforcement.
2040

2141
## Related docs
2242

0 commit comments

Comments
 (0)