sbx: document audit logging as a governance feature #25239
+157
−30
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,124 @@ | ||
| --- | ||
| title: Audit logging | ||
| linkTitle: Audit logs | ||
| weight: 28 | ||
| description: Capture a structured, durable record of every sandbox policy decision for SIEM ingestion and compliance. | ||
| keywords: docker sandboxes, audit log, audit logging, policy decision, SIEM, compliance, jsonl, splunk, filebeat | ||
| --- | ||
|
|
||
| The sandbox daemon records a structured audit event for every policy decision | ||
| it makes. Each record captures who triggered the evaluation, when it happened, | ||
| which rule matched, and whether the resource was allowed or denied. Records are | ||
| written to disk as JSON Lines (`.jsonl`) so existing SIEM and log-shipping | ||
| tools can collect them. The records stay on the machine that produced them. | ||
| Docker doesn't collect or ingest audit data. | ||
|
dvdksn marked this conversation as resolved.
|
||
|
|
||
| > [!NOTE] | ||
|
dvdksn marked this conversation as resolved.
|
||
| > Audit logging is part of Docker AI Governance and requires a separate paid | ||
| > subscription. | ||
| > [Contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) | ||
| > to request access. | ||
|
|
||
| Audit logging is active only while your organization enforces a centralized | ||
| governance policy. The subscription alone doesn't produce records. If your | ||
| organization hasn't configured and enforced an [organization policy](org.md), | ||
| the daemon writes no audit logs. To confirm governance is active, run `sbx | ||
| policy ls` — the output begins with a `Governance: managed by <org>` header | ||
| when an organization policy is in effect. | ||
|
|
||
| Audit logging complements [monitoring](monitoring.md). Monitoring with `sbx | ||
| policy ls` and `sbx policy log` is for live, interactive debugging. Audit | ||
| logging produces a durable trail for security review and compliance. | ||
|
|
||
| ## What gets recorded | ||
|
|
||
| The daemon writes two categories of record: | ||
|
|
||
| - Evaluation records capture each policy decision: the resource, the | ||
| action, the verdict, and the reason for a denial. | ||
| - Session lifecycle records mark the start and end of each daemon run. | ||
| Evaluation records share the run's `audit_session_id`, so you can correlate | ||
| every decision back to a single daemon session. | ||
|
|
||
| A network evaluation record looks like this: | ||
|
dvdksn marked this conversation as resolved.
|
||
|
|
||
| ```json | ||
| { | ||
| "audit_event_id": "95e7257f-93c9-4f29-bde7-88830e2dae80", | ||
| "timestamp": "2026-05-28T19:15:00.728933Z", | ||
| "schema_version": "1.82.0", | ||
| "category": "AUDIT_CATEGORY_EVALUATION", | ||
| "decision": "AUDIT_DECISION_DENY", | ||
| "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": "example.com:443", | ||
| "os": "macos", | ||
| "app_version": "v0.31.0", | ||
| "client_name": "sbx", | ||
| "hostname": "host-machine", | ||
| "deny_reason": [ | ||
| "no applicable policies for op(action=net:connect:tcp, resource=net:domain:example.com:443)" | ||
| ], | ||
| "action_type": "network_egress", | ||
| "network_egress": { "protocol": "tcp" } | ||
| } | ||
| ``` | ||
|
|
||
| Common fields include: | ||
|
|
||
| | Field | Description | | ||
| | ------------------ | ------------------------------------------------------------------------------------------------------------ | | ||
| | `timestamp` | UTC time of the decision. | | ||
| | `schema_version` | Version of the record schema. Pin your SIEM field mappings to it, as the format is a stable contract. | | ||
| | `category` | `AUDIT_CATEGORY_EVALUATION` for policy decisions, `AUDIT_CATEGORY_MANAGEMENT` for session lifecycle records. | | ||
| | `audit_session_id` | Identifies the daemon run that produced the record. | | ||
| | `username` | The signed-in Docker user's Docker Hub username. | | ||
| | `user_email` | The signed-in Docker user's email address. | | ||
| | `org_id` | ID of the organization whose governance policy is in effect. | | ||
| | `org_name` | Display name of the organization whose governance policy is in effect. | | ||
| | `action_type` | The kind of access evaluated, such as `network_egress`. | | ||
| | `resource_id` | The target of the evaluation, such as a host and port. | | ||
| | `decision` | `AUDIT_DECISION_ALLOW` or `AUDIT_DECISION_DENY`. | | ||
| | `deny_reason` | Why a denied request was blocked. Present on deny decisions. | | ||
|
|
||
| Each record is attributed to the signed-in Docker user and the organization | ||
| whose governance policy is in effect. | ||
|
|
||
| ## Where records are stored | ||
|
|
||
| The daemon writes audit records, not the CLI. Running a command such as `sbx | ||
| create` sends a request to the daemon, and the daemon emits the resulting | ||
| record to its own audit directory. | ||
|
|
||
| The default location depends on your operating system: | ||
|
|
||
| | OS | Default path | | ||
| | ------- | ----------------------------------------------------------------- | | ||
| | macOS | `~/Library/Logs/com.docker.sandboxes/sandboxes/auditkit/` | | ||
| | Linux | `${XDG_STATE_HOME:-~/.local/state}/sandboxes/sandboxes/auditkit/` | | ||
|
There was a problem hiding this comment. [MEDIUM] Linux audit log path may contain a duplicated The Linux path in the OS table is: On macOS the app namespace (
Contributor
Author
There was a problem hiding this comment. this is correct I think There was a problem hiding this comment. Thanks for confirming! I misinterpreted the path structure — I assumed the double Sorry for the noise! |
||
| | Windows | `%LOCALAPPDATA%\DockerSandboxes\sandboxes\logs\auditkit\` | | ||
|
|
||
| The directory layout differs by platform because each operating system places | ||
| application logs in its own conventional location. | ||
|
|
||
| Files are named `audit-<utc-timestamp>-<process-uuid>-<seq>.jsonl`. | ||
|
|
||
| The daemon writes in-progress records to a temporary `.tmp` file and seals it | ||
| into a final `.jsonl` file by atomic rename. Sealing happens at a rotation | ||
| threshold (by default 5 minutes, 1000 events, or 50 MiB, whichever comes | ||
| first) or when the daemon shuts down cleanly. Only sealed `.jsonl` files are | ||
| complete. Treat `.tmp` files as incomplete and don't collect them. | ||
|
|
||
| Sandboxes never delete sealed files. Retention and cleanup are the | ||
| responsibility of your log shipper or your own housekeeping. | ||
|
|
||
| ## Collect records with a SIEM | ||
|
dvdksn marked this conversation as resolved.
|
||
|
|
||
| Point your log shipper at the audit directory and configure it to collect | ||
| sealed `.jsonl` files only. Tools such as the Splunk Universal Forwarder, | ||
| Filebeat, and CrowdStrike Falcon LogScale read the directory and forward each | ||
| line as an event. Because in-progress records live in `.tmp` files until they | ||
| are sealed, collectors never see partial records. | ||
|
Contributor
Author
There was a problem hiding this comment. This page was just updated because the bot is zealous and wanted to avoid vale lint errors on the term "Crowdstrike" / nothing related to audit logs. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
They also capture other important executions, such as sessions starting or ending, policy changes, etc.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Right - this PR focuses on what sandboxd emits. I'll need to open a follow-up PR to expand on the "activity log" side of things.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
added #25262 to track the follow-up