Skip to content

Commit b4b06ed

Browse files
craig-osterhoutcraig-osterhout
authored
ai-gov: audit log record update (#26189)
## Description Document the audit record changes in Docker Sandboxes 0.46. Sandboxes now writes a record when a user resolves a pending approval, records HTTP request evaluations separately from the network connection, and includes the enforcement mode on evaluation records. | Page | What changed | | --- | --- | | [`record-reference.md`](https://deploy-preview-26189--docsdocker.netlify.app/ai/sandboxes/governance/audit/record-reference/) | Adds the `enforcement_mode` and `approval` fields. Fixes the approval decisions to `AUDIT_DECISION_APPROVAL_ALLOW` and `AUDIT_DECISION_APPROVAL_DENY`, which replace values that don't exist in the schema. New **Enforcement modes** section. New **Approval fields** section that covers `approval_request_id`, `grant_scope`, and how a failed grant is recorded. Adds the `http_request` action type, a new **HTTP request payload** section, and a sample approved HTTP request record | ## Related issues or tickets docker/sandboxes#6656 ## Reviews - [ ] Technical review - [ ] Editorial review - [ ] Product review --------- Signed-off-by: Craig Osterhout <craig.osterhout@docker.com>
1 parent f7a20f0 commit b4b06ed

1 file changed

Lines changed: 123 additions & 24 deletions

File tree

‎content/manuals/ai/sandboxes/governance/audit/record-reference.md‎

Lines changed: 123 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,8 @@ action.
3333
| `client_name` | Source component, such as `sbx` for Docker Sandboxes. |
3434
| `hostname` | Hostname of the machine that produced the record. |
3535
| `deny_reason` | Why a denied request was blocked. Present on deny decisions. |
36+
| `enforcement_mode` | Governance mode in effect when Docker evaluated the request. See [Enforcement modes](#enforcement-modes). |
37+
| `approval` | Approval details. Present when the decision involves an approval. See [Approval fields](#approval-fields). |
3638
| `action_type` | Payload discriminator that identifies the action-specific object in the record. |
3739
| `agent` | AI agent associated with the event, when Docker knows it. |
3840

@@ -46,35 +48,97 @@ action.
4648

4749
## Decisions
4850

49-
| Decision | Description |
50-
| ---------------------------------- | ---------------------------------------------- |
51-
| `AUDIT_DECISION_ALLOW` | Docker allowed the action. |
52-
| `AUDIT_DECISION_DENY` | Docker denied the action. |
53-
| `AUDIT_DECISION_APPROVAL_REQUIRED` | Docker required consent before the action ran. |
54-
| `AUDIT_DECISION_APPROVED` | A consent request was approved. |
55-
| `AUDIT_DECISION_REJECTED` | A consent request was rejected. |
51+
| Decision | Description |
52+
| ---------------------------------- | ------------------------------------------------- |
53+
| `AUDIT_DECISION_ALLOW` | Docker allowed the action. |
54+
| `AUDIT_DECISION_DENY` | Docker denied the action. |
55+
| `AUDIT_DECISION_APPROVAL_REQUIRED` | The policy requires a user to approve the action. |
56+
| `AUDIT_DECISION_APPROVAL_ALLOW` | A user approved a pending request. |
57+
| `AUDIT_DECISION_APPROVAL_DENY` | A user denied a pending request. |
58+
59+
## Enforcement modes
60+
61+
The `enforcement_mode` field shows how governance applied to the request when
62+
Docker evaluated it.
63+
64+
| Mode | Description |
65+
| --------- | ------------------------------------------------------------------------------- |
66+
| `enforce` | Your organization's governance policy is enforced. |
67+
| `audit` | Docker records the decision for observability but doesn't enforce policy. |
68+
| `off` | Governance isn't active. Docker still writes the record to the local audit log. |
69+
70+
A record that resolves a network approval doesn't include `enforcement_mode`,
71+
and neither does the record of a declined MCP approval. An approved MCP request
72+
is evaluated again, so its record includes `enforcement_mode`.
73+
74+
## Approval fields
75+
76+
When network access requires approval, Docker blocks the request and writes an
77+
`AUDIT_DECISION_APPROVAL_REQUIRED` record. If the user approves, Docker writes
78+
a second record with `AUDIT_DECISION_APPROVAL_ALLOW`. Both records carry the
79+
same `approval.approval_request_id`, so you can join them to reconstruct the
80+
full approval. The approval applies to later requests from the sandbox. It
81+
doesn't retry the request that was blocked. If the user dismisses the request,
82+
it isn't resolved, so no second record is written and the destination is
83+
requested again the next time the sandbox reaches it. For how approval works,
84+
see [Approval-required access](../access-controls/network.md#approval-required-access).
85+
86+
For MCP approvals, an approved request is evaluated again and recorded with
87+
`AUDIT_DECISION_APPROVAL_ALLOW`, and a declined request is recorded with
88+
`AUDIT_DECISION_APPROVAL_DENY`. Neither record includes
89+
`approval.approval_request_id` or `approval.grant_scope`.
90+
91+
| Field | Description |
92+
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
93+
| `approval.reason_codes` | Policy reasons for requiring approval. Present on `AUDIT_DECISION_APPROVAL_REQUIRED` records when the policy supplies reasons, and on declined MCP approvals when reasons are available. |
94+
| `approval.approval_request_id` | ID that links an approval required record to the record that resolves it. |
95+
| `approval.grant_scope` | Scope the user accepted. Present only on `AUDIT_DECISION_APPROVAL_ALLOW` records. |
96+
| `approval.context_digest` | SHA-256 digest of the request that was resolved, which shows it matches the request that was held. Present only on declined MCP approvals. |
97+
98+
For network approvals, Docker Sandboxes records `approval.grant_scope` as
99+
`AUDIT_APPROVAL_GRANT_SCOPE_PERSISTENT`, which means that the approval applies
100+
to later requests.
101+
102+
If a user approves a request but Docker can't apply the grant, the record has
103+
an `AUDIT_DECISION_DENY` decision and includes the `approval` object.
56104

57105
## Action types
58106

59107
The `action_type` field identifies the action-specific payload in the record.
60108

61-
| Action type | Description |
62-
| ---------------------- | -------------------------------------------- |
63-
| `session` | Sandbox daemon session lifecycle event. |
64-
| `network_egress` | Network access evaluation. |
65-
| `filesystem_mount` | Filesystem mount or path access evaluation. |
66-
| `tool_invocation` | Tool invocation evaluation. |
67-
| `resource_read` | Resource read evaluation. |
68-
| `server_registration` | Server registration event. |
69-
| `prompt` | Prompt-related metadata event. |
70-
| `network_execution` | Outcome of a network action. |
71-
| `filesystem_execution` | Outcome of a filesystem action. |
72-
| `tool_execution` | Outcome of a tool invocation. |
73-
| `resource_execution` | Outcome of a resource read. |
74-
| `policy_sync` | Policy synchronization event. |
75-
| `pii_detection` | Metadata event for a data detection result. |
76-
| `c_score_report` | Metadata event for a C-score report. |
77-
| `policy_action` | Policy configuration or policy action event. |
109+
| Action type | Description |
110+
| ---------------------------- | --------------------------------------------------------------------------- |
111+
| `session` | Sandbox daemon session lifecycle event. |
112+
| `network_egress` | Network access evaluation. |
113+
| `http_request` | HTTP request evaluation. See [HTTP request payload](#http-request-payload). |
114+
| `filesystem_mount` | Filesystem mount or path access evaluation. |
115+
| `tool_invocation` | Tool invocation evaluation. |
116+
| `resource_read` | Resource read evaluation. |
117+
| `server_registration` | Server registration event. |
118+
| `prompt` | Prompt-related metadata event. |
119+
| `network_egress_execution` | Outcome of a network action. |
120+
| `filesystem_mount_execution` | Outcome of a filesystem action. |
121+
| `tool_execution` | Outcome of a tool invocation. |
122+
| `resource_read_execution` | Outcome of a resource read. |
123+
| `prompt_execution` | Outcome of a prompt request. |
124+
| `policy_sync` | Policy synchronization event. |
125+
| `pii_detection` | Metadata event for a data detection result. |
126+
| `c_score_report` | Metadata event for a C-score report. |
127+
| `policy_action` | Policy configuration or policy action event. |
128+
129+
## HTTP request payload
130+
131+
When a network policy requires each HTTP request to be authorized, Docker
132+
evaluates the request method and path in addition to the network connection.
133+
These evaluations produce records with an `action_type` of `http_request`,
134+
separate from the `network_egress` record for the connection.
135+
136+
| Field | Description |
137+
| --------------------- | --------------------------------------------------------------------------- |
138+
| `http_request.method` | HTTP method, such as `HTTP_METHOD_GET` or `HTTP_METHOD_POST`. |
139+
| `http_request.host` | Destination hostname or IP address. IPv6 addresses appear without brackets. |
140+
| `http_request.port` | Destination port. |
141+
| `http_request.path` | URL path, without the query string or fragment. |
78142

79143
## Sample record
80144

@@ -103,3 +167,38 @@ The `action_type` field identifies the action-specific payload in the record.
103167
"agent": "claude"
104168
}
105169
```
170+
171+
The following sample shows a user approving an HTTP request that required
172+
approval:
173+
174+
```json
175+
{
176+
"audit_event_id": "3c1f6a2e-8b47-4d0a-9e55-2f7b1d6c9a04",
177+
"timestamp": "2026-09-25T17:42:08.114502Z",
178+
"schema_version": "1.216.0",
179+
"category": "AUDIT_CATEGORY_EVALUATION",
180+
"decision": "AUDIT_DECISION_APPROVAL_ALLOW",
181+
"username": "jordandoe",
182+
"user_email": "jordandoe@example.com",
183+
"org_id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
184+
"org_name": "Acme Inc",
185+
"audit_session_id": "8a3bc076-79d0-4502-baf3-cc6ad35fb578",
186+
"resource_id": "api.example.com:443",
187+
"os": "macos",
188+
"app_version": "v0.46.0",
189+
"client_name": "sbx",
190+
"hostname": "host-machine",
191+
"approval": {
192+
"approval_request_id": "b7e2c9d1-4f60-4a8e-93c2-5d1e8f7a6b30",
193+
"grant_scope": "AUDIT_APPROVAL_GRANT_SCOPE_PERSISTENT"
194+
},
195+
"action_type": "http_request",
196+
"http_request": {
197+
"method": "HTTP_METHOD_POST",
198+
"host": "api.example.com",
199+
"port": "443",
200+
"path": "/v1/items"
201+
},
202+
"agent": "claude"
203+
}
204+
```

0 commit comments

Comments
 (0)