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

Draft
craig-osterhout wants to merge 1 commit into
base: main
Choose a base branch
from
+110 −24
Draft

ai-gov: audit log record update #26189

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
134 changes: 110 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,84 @@ 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` | Docker held the action until a user approves or denies it. |
| `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. |

Approval resolution records don't include `enforcement_mode`.

## Approval fields

When a policy requires approval, Docker writes an
`AUDIT_DECISION_APPROVAL_REQUIRED` record while the request waits. When a user
approves or denies the request, Docker writes a second record with
`AUDIT_DECISION_APPROVAL_ALLOW` or `AUDIT_DECISION_APPROVAL_DENY`. Both records
carry the same `approval.approval_request_id`, so you can join them to
reconstruct the full approval.

| Field | Description |
| ------------------------------ | --------------------------------------------------------------------------------- |
| `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. |

Docker Sandboxes records an approved request's `approval.grant_scope` as
`AUDIT_APPROVAL_GRANT_SCOPE_PERSISTENT`, which means that the approval persists
beyond the request that was approved.

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_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. |

## 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 +154,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"
}
```
Loading