Skip to content

ai-gov: audit log record update #26189

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
craig-osterhout merged 3 commits into from
Sep 30, 2026
Merged

ai-gov: audit log record update #26189

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4eb0ab9
ai-gov: audit log record update
craig-osterhout Sep 25, 2026
b1c5610
reword
craig-osterhout Sep 30, 2026
eac0862
fix user-facing
craig-osterhout Sep 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
147 changes: 123 additions & 24 deletions content/manuals/ai/sandboxes/governance/audit/record-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. |

Expand All @@ -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

Expand Down Expand Up @@ -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"
}
```