mirror of
https://github.com/docker/docs.git
synced 2026-11-04 10:01:00 +00:00
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 https://github.com/docker/sandboxes/pull/6656 ## Reviews - [ ] Technical review - [ ] Editorial review - [ ] Product review --------- Signed-off-by: Craig Osterhout <craig.osterhout@docker.com>
This commit is contained in:
Craig Osterhout authored and 
GitHub committed
1 parent
f7a20f07a8
commit
b4b06ed783
1 file changed
+123
-24
@@ -33,6 +33,8 @@ action.
|
||||
| `client_name` | Source component, such as `sbx` for Docker Sandboxes. |
|
||||
| `hostname` | Hostname of the machine that produced the record. |
|
||||
| `deny_reason` | Why a denied request was blocked. Present on deny decisions. |
|
||||
| `enforcement_mode` | Governance mode in effect when Docker evaluated the request. See [Enforcement modes](#enforcement-modes). |
|
||||
| `approval` | Approval details. Present when the decision involves an approval. See [Approval fields](#approval-fields). |
|
||||
| `action_type` | Payload discriminator that identifies the action-specific object in the record. |
|
||||
| `agent` | AI agent associated with the event, when Docker knows it. |
|
||||
|
||||
@@ -46,35 +48,97 @@ action.
|
||||
|
||||
## Decisions
|
||||
|
||||
| Decision | Description |
|
||||
| ---------------------------------- | ---------------------------------------------- |
|
||||
| `AUDIT_DECISION_ALLOW` | Docker allowed the action. |
|
||||
| `AUDIT_DECISION_DENY` | Docker denied the action. |
|
||||
| `AUDIT_DECISION_APPROVAL_REQUIRED` | Docker required consent before the action ran. |
|
||||
| `AUDIT_DECISION_APPROVED` | A consent request was approved. |
|
||||
| `AUDIT_DECISION_REJECTED` | A consent request was rejected. |
|
||||
| Decision | Description |
|
||||
| ---------------------------------- | ------------------------------------------------- |
|
||||
| `AUDIT_DECISION_ALLOW` | Docker allowed the action. |
|
||||
| `AUDIT_DECISION_DENY` | Docker denied the action. |
|
||||
| `AUDIT_DECISION_APPROVAL_REQUIRED` | The policy requires a user to approve the action. |
|
||||
| `AUDIT_DECISION_APPROVAL_ALLOW` | A user approved a pending request. |
|
||||
| `AUDIT_DECISION_APPROVAL_DENY` | A user denied a pending request. |
|
||||
|
||||
## Enforcement modes
|
||||
|
||||
The `enforcement_mode` field shows how governance applied to the request when
|
||||
Docker evaluated it.
|
||||
|
||||
| Mode | Description |
|
||||
| --------- | ------------------------------------------------------------------------------- |
|
||||
| `enforce` | Your organization's governance policy is enforced. |
|
||||
| `audit` | Docker records the decision for observability but doesn't enforce policy. |
|
||||
| `off` | Governance isn't active. Docker still writes the record to the local audit log. |
|
||||
|
||||
A record that resolves a network approval doesn't include `enforcement_mode`,
|
||||
and neither does the record of a declined MCP approval. An approved MCP request
|
||||
is evaluated again, so its record includes `enforcement_mode`.
|
||||
|
||||
## Approval fields
|
||||
|
||||
When network access requires approval, Docker blocks the request and writes an
|
||||
`AUDIT_DECISION_APPROVAL_REQUIRED` record. If the user approves, Docker writes
|
||||
a second record with `AUDIT_DECISION_APPROVAL_ALLOW`. Both records carry the
|
||||
same `approval.approval_request_id`, so you can join them to reconstruct the
|
||||
full approval. The approval applies to later requests from the sandbox. It
|
||||
doesn't retry the request that was blocked. If the user dismisses the request,
|
||||
it isn't resolved, so no second record is written and the destination is
|
||||
requested again the next time the sandbox reaches it. For how approval works,
|
||||
see [Approval-required access](../access-controls/network.md#approval-required-access).
|
||||
|
||||
For MCP approvals, an approved request is evaluated again and recorded with
|
||||
`AUDIT_DECISION_APPROVAL_ALLOW`, and a declined request is recorded with
|
||||
`AUDIT_DECISION_APPROVAL_DENY`. Neither record includes
|
||||
`approval.approval_request_id` or `approval.grant_scope`.
|
||||
|
||||
| Field | Description |
|
||||
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `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. |
|
||||
| `approval.approval_request_id` | ID that links an approval required record to the record that resolves it. |
|
||||
| `approval.grant_scope` | Scope the user accepted. Present only on `AUDIT_DECISION_APPROVAL_ALLOW` records. |
|
||||
| `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. |
|
||||
|
||||
For network approvals, Docker Sandboxes records `approval.grant_scope` as
|
||||
`AUDIT_APPROVAL_GRANT_SCOPE_PERSISTENT`, which means that the approval applies
|
||||
to later requests.
|
||||
|
||||
If a user approves a request but Docker can't apply the grant, the record has
|
||||
an `AUDIT_DECISION_DENY` decision and includes the `approval` object.
|
||||
|
||||
## Action types
|
||||
|
||||
The `action_type` field identifies the action-specific payload in the record.
|
||||
|
||||
| Action type | Description |
|
||||
| ---------------------- | -------------------------------------------- |
|
||||
| `session` | Sandbox daemon session lifecycle event. |
|
||||
| `network_egress` | Network access evaluation. |
|
||||
| `filesystem_mount` | Filesystem mount or path access evaluation. |
|
||||
| `tool_invocation` | Tool invocation evaluation. |
|
||||
| `resource_read` | Resource read evaluation. |
|
||||
| `server_registration` | Server registration event. |
|
||||
| `prompt` | Prompt-related metadata event. |
|
||||
| `network_execution` | Outcome of a network action. |
|
||||
| `filesystem_execution` | Outcome of a filesystem action. |
|
||||
| `tool_execution` | Outcome of a tool invocation. |
|
||||
| `resource_execution` | Outcome of a resource read. |
|
||||
| `policy_sync` | Policy synchronization event. |
|
||||
| `pii_detection` | Metadata event for a data detection result. |
|
||||
| `c_score_report` | Metadata event for a C-score report. |
|
||||
| `policy_action` | Policy configuration or policy action event. |
|
||||
| Action type | Description |
|
||||
| ---------------------------- | --------------------------------------------------------------------------- |
|
||||
| `session` | Sandbox daemon session lifecycle event. |
|
||||
| `network_egress` | Network access evaluation. |
|
||||
| `http_request` | HTTP request evaluation. See [HTTP request payload](#http-request-payload). |
|
||||
| `filesystem_mount` | Filesystem mount or path access evaluation. |
|
||||
| `tool_invocation` | Tool invocation evaluation. |
|
||||
| `resource_read` | Resource read evaluation. |
|
||||
| `server_registration` | Server registration event. |
|
||||
| `prompt` | Prompt-related metadata event. |
|
||||
| `network_egress_execution` | Outcome of a network action. |
|
||||
| `filesystem_mount_execution` | Outcome of a filesystem action. |
|
||||
| `tool_execution` | Outcome of a tool invocation. |
|
||||
| `resource_read_execution` | Outcome of a resource read. |
|
||||
| `prompt_execution` | Outcome of a prompt request. |
|
||||
| `policy_sync` | Policy synchronization event. |
|
||||
| `pii_detection` | Metadata event for a data detection result. |
|
||||
| `c_score_report` | Metadata event for a C-score report. |
|
||||
| `policy_action` | Policy configuration or policy action event. |
|
||||
|
||||
## HTTP request payload
|
||||
|
||||
When a network policy requires each HTTP request to be authorized, Docker
|
||||
evaluates the request method and path in addition to the network connection.
|
||||
These evaluations produce records with an `action_type` of `http_request`,
|
||||
separate from the `network_egress` record for the connection.
|
||||
|
||||
| Field | Description |
|
||||
| --------------------- | --------------------------------------------------------------------------- |
|
||||
| `http_request.method` | HTTP method, such as `HTTP_METHOD_GET` or `HTTP_METHOD_POST`. |
|
||||
| `http_request.host` | Destination hostname or IP address. IPv6 addresses appear without brackets. |
|
||||
| `http_request.port` | Destination port. |
|
||||
| `http_request.path` | URL path, without the query string or fragment. |
|
||||
|
||||
## Sample record
|
||||
|
||||
@@ -103,3 +167,38 @@ The `action_type` field identifies the action-specific payload in the record.
|
||||
"agent": "claude"
|
||||
}
|
||||
```
|
||||
|
||||
The following sample shows a user approving an HTTP request that required
|
||||
approval:
|
||||
|
||||
```json
|
||||
{
|
||||
"audit_event_id": "3c1f6a2e-8b47-4d0a-9e55-2f7b1d6c9a04",
|
||||
"timestamp": "2026-09-25T17:42:08.114502Z",
|
||||
"schema_version": "1.216.0",
|
||||
"category": "AUDIT_CATEGORY_EVALUATION",
|
||||
"decision": "AUDIT_DECISION_APPROVAL_ALLOW",
|
||||
"username": "jordandoe",
|
||||
"user_email": "jordandoe@example.com",
|
||||
"org_id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
|
||||
"org_name": "Acme Inc",
|
||||
"audit_session_id": "8a3bc076-79d0-4502-baf3-cc6ad35fb578",
|
||||
"resource_id": "api.example.com:443",
|
||||
"os": "macos",
|
||||
"app_version": "v0.46.0",
|
||||
"client_name": "sbx",
|
||||
"hostname": "host-machine",
|
||||
"approval": {
|
||||
"approval_request_id": "b7e2c9d1-4f60-4a8e-93c2-5d1e8f7a6b30",
|
||||
"grant_scope": "AUDIT_APPROVAL_GRANT_SCOPE_PERSISTENT"
|
||||
},
|
||||
"action_type": "http_request",
|
||||
"http_request": {
|
||||
"method": "HTTP_METHOD_POST",
|
||||
"host": "api.example.com",
|
||||
"port": "443",
|
||||
"path": "/v1/items"
|
||||
},
|
||||
"agent": "claude"
|
||||
}
|
||||
```
|
||||
Reference in new issue
Block a user