From 9d0e4dbc83de60ff1bb0bfbbde9ad55ea75c6fe1 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 2 Jun 2026 12:56:14 +0200 Subject: [PATCH 1/8] sbx: document audit logging as a governance feature Add a governance page describing how sandboxd records a structured audit event for every policy decision, where the JSONL records land on disk, how to collect them with a SIEM, and how to override the storage location. Link it from the governance index and add Filebeat to the Vale vocabulary. Co-Authored-By: Claude Opus 4.8 (1M context) --- _vale/config/vocabularies/Docker/accept.txt | 1 + .../manuals/ai/sandboxes/governance/_index.md | 2 + .../manuals/ai/sandboxes/governance/audit.md | 120 ++++++++++++++++++ 3 files changed, 123 insertions(+) create mode 100644 content/manuals/ai/sandboxes/governance/audit.md diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt index 6a3bd9f76f5f..55fa9732b61c 100644 --- a/_vale/config/vocabularies/Docker/accept.txt +++ b/_vale/config/vocabularies/Docker/accept.txt @@ -92,6 +92,7 @@ Ethernet [Ff]ailover Fargate Fedora +Filebeat firewalld Flink Fluentd diff --git a/content/manuals/ai/sandboxes/governance/_index.md b/content/manuals/ai/sandboxes/governance/_index.md index 599cba0d153b..aa48d21dc515 100644 --- a/content/manuals/ai/sandboxes/governance/_index.md +++ b/content/manuals/ai/sandboxes/governance/_index.md @@ -34,5 +34,7 @@ rules are no longer evaluated. See [Organization policy](org.md). your organization from the Admin Console - [Monitoring](monitoring.md): inspect active rules and monitor sandbox network traffic with `sbx policy ls` and `sbx policy log` +- [Audit logs](audit.md): capture a durable, structured record of every + policy decision for SIEM ingestion and compliance - [API reference](/reference/api/ai-governance/): manage org policies programmatically via the Governance API diff --git a/content/manuals/ai/sandboxes/governance/audit.md b/content/manuals/ai/sandboxes/governance/audit.md new file mode 100644 index 000000000000..5a7804c99182 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/audit.md @@ -0,0 +1,120 @@ +--- +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. + +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: + +```json +{ + "audit_event_id": "95e7257f-93c9-4f29-bde7-88830e2dae80", + "timestamp": "2026-05-28T19:15:00.728933Z", + "schema_version": "1.80.0", + "category": "AUDIT_CATEGORY_EVALUATION", + "audit_session_id": "8a3bc076-79d0-4502-baf3-cc6ad35fb578", + "username": "5f3e3556-ed49-4431-bdd8-24958cdc4340", + "user_email": "jordan@example.com", + "action_type": "network_egress", + "resource_id": "example.com", + "decision": "AUDIT_DECISION_DENY", + "deny_reason": [ + "no applicable policies for op(action=net:connect:tcp, resource=net:domain:example.com)" + ], + "network_egress": { "protocol": "tcp" }, + "os": "macos", + "hostname": "host-machine", + "client_name": "sbx", + "app_version": "v0.30.0" +} +``` + +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 account UUID. | +| `user_email` | The signed-in Docker user's email address. | +| `action_type` | The kind of access evaluated, such as `network_egress`. | +| `resource_id` | The target of the evaluation, such as a hostname. | +| `decision` | `AUDIT_DECISION_ALLOW` or `AUDIT_DECISION_DENY`. | +| `deny_reason` | Why a denied request was blocked. Present on deny decisions. | + +Identity is resolved from the signed-in Docker user at daemon startup. If no +user is signed in when the daemon starts, records still ship, but with empty +`username` and `user_email` fields. + +## 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}/com.docker.sandboxes/logs/sandboxes/auditkit/` | +| Windows | `%LOCALAPPDATA%\com.docker.sandboxes\logs\sandboxes\auditkit\` | + +Files are named `audit---.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 do not 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 + +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. + +## Override the storage location + +Two environment variables change where records are written. Set them on the +daemon process, not the CLI. + +| Variable | Effect | +| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | +| `SANDBOXES_STORAGE_ROOT=` | Override the base storage directory. The audit path becomes `/logs/com.docker.sandboxes/sandboxes/auditkit/`. | +| `DOCKER_SANDBOXES_APP_NAME=` | Append a suffix to the app name (`sandboxes` becomes `sandboxes-`). Useful for running multiple daemon instances side by side. | + +The CLI starts the daemon automatically when none is running, so exporting +either variable in your shell propagates to the daemon it spawns. If a daemon +is already running, stop it first with `sbx daemon stop` so the next `sbx` +command starts a daemon that picks up the new value. From 1913666bbb6c01337c103b1f0dffd086611d2d5a Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 2 Jun 2026 14:46:08 +0200 Subject: [PATCH 2/8] sbx: address review feedback on audit logging docs - Remove bold from concept names in the record-categories list - Replace semicolons with separate sentences - Correct the Linux and Windows default audit paths to match the storagekit platform namespaces (verified against the implementation) and generalize the storage-root override description - Use the correct CrowdStrike brand casing; update the Vale vocabulary and existing networking doc to match Co-Authored-By: Claude Opus 4.8 (1M context) --- _vale/config/vocabularies/Docker/accept.txt | 2 +- .../manuals/ai/sandboxes/governance/audit.md | 31 +++++----- .../desktop/features/networking/_index.md | 58 +++++++++---------- 3 files changed, 47 insertions(+), 44 deletions(-) diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt index 55fa9732b61c..a00d1a94036e 100644 --- a/_vale/config/vocabularies/Docker/accept.txt +++ b/_vale/config/vocabularies/Docker/accept.txt @@ -49,7 +49,7 @@ config containerd Couchbase CouchDB -Crowdstrike +CrowdStrike [Cc]ybersecurity datacenter datasource diff --git a/content/manuals/ai/sandboxes/governance/audit.md b/content/manuals/ai/sandboxes/governance/audit.md index 5a7804c99182..5973ba505ca0 100644 --- a/content/manuals/ai/sandboxes/governance/audit.md +++ b/content/manuals/ai/sandboxes/governance/audit.md @@ -14,16 +14,16 @@ tools can collect them. The records stay on the machine that produced them. Docker doesn't collect or ingest audit data. Audit logging complements [monitoring](monitoring.md). Monitoring with `sbx -policy ls` and `sbx policy log` is for live, interactive debugging; audit +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 +- 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. +- 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. @@ -79,11 +79,14 @@ 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}/com.docker.sandboxes/logs/sandboxes/auditkit/` | -| Windows | `%LOCALAPPDATA%\com.docker.sandboxes\logs\sandboxes\auditkit\` | +| OS | Default path | +| ------- | ----------------------------------------------------------------- | +| macOS | `~/Library/Logs/com.docker.sandboxes/sandboxes/auditkit/` | +| Linux | `${XDG_STATE_HOME:-~/.local/state}/sandboxes/sandboxes/auditkit/` | +| 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---.jsonl`. @@ -91,7 +94,7 @@ 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 do not collect them. +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. @@ -100,7 +103,7 @@ responsibility of your log shipper or your own housekeeping. 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 +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. @@ -109,10 +112,10 @@ are sealed, collectors never see partial records. Two environment variables change where records are written. Set them on the daemon process, not the CLI. -| Variable | Effect | -| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | -| `SANDBOXES_STORAGE_ROOT=` | Override the base storage directory. The audit path becomes `/logs/com.docker.sandboxes/sandboxes/auditkit/`. | -| `DOCKER_SANDBOXES_APP_NAME=` | Append a suffix to the app name (`sandboxes` becomes `sandboxes-`). Useful for running multiple daemon instances side by side. | +| Variable | Effect | +| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| `SANDBOXES_STORAGE_ROOT=` | Override the base storage directory. Audit records move under `/logs/`, keeping the same platform-specific namespace as the default paths. | +| `DOCKER_SANDBOXES_APP_NAME=` | Append a suffix to the app name (`sandboxes` becomes `sandboxes-`). Useful for running multiple daemon instances side by side. | The CLI starts the daemon automatically when none is running, so exporting either variable in your shell propagates to the daemon it spawns. If a daemon diff --git a/content/manuals/desktop/features/networking/_index.md b/content/manuals/desktop/features/networking/_index.md index 515dbc91f7c9..b0554e0361ee 100644 --- a/content/manuals/desktop/features/networking/_index.md +++ b/content/manuals/desktop/features/networking/_index.md @@ -4,7 +4,7 @@ keywords: docker desktop, networking, architecture, firewall, proxies, crowdstri title: Networking on Docker Desktop linkTitle: Networking weight: 30 ---- +--- This page explains how Docker Desktop routes network traffic and file I/O between containers, the VM, and the host, and how this behavior is visible to firewalls and endpoint protection tools. @@ -17,25 +17,24 @@ Docker Desktop runs the Docker Engine inside a lightweight Linux virtual machine The backend acts as: - Network proxy: Translates traffic between the host and Linux VM. - - On Windows and Mac, this is handled by the `com.docker.backend` process. - - On Linux, the `qemu` process performs this function. + - On Windows and Mac, this is handled by the `com.docker.backend` process. + - On Linux, the `qemu` process performs this function. - File server: Handles file access from containers to the host filesystem. - - When using gRPC FUSE, the backend performs the file sharing. - - When using `virtiofs`, `osxfs`, or `krun`, file access is handled by those respective daemons rather than the backend process. + - When using gRPC FUSE, the backend performs the file sharing. + - When using `virtiofs`, `osxfs`, or `krun`, file access is handled by those respective daemons rather than the backend process. - Control plane: Manages Docker API calls, port forwarding, and proxy configuration. The following table summarizes typical setups in more detail: -| Platform | Setup | Networking handled by | File sharing handled by | Notes | -| --------------- | ------------------------------------ | ------------------------ | -------------------------------------- | --------------------------------------------------------- | -| Windows | Hyper-V | `com.docker.backend.exe` | `com.docker.backend.exe` | Simplest setup with full visibility to EDR/firewall tools | -| Windows (WSL 2) | WSL 2 | `com.docker.backend.exe` | WSL 2 kernel (no visibility from host) | Recommended only when WSL 2 integration is needed | -| Mac | Virtualization framework + gRPC FUSE | `com.docker.backend` | `com.docker.backend` | Recommended for performance and visibility | -| Mac | Virtualization framework + `virtiofs`| `com.docker.backend` | Apple's Virtualization framework | Higher performance but no file access visibility from host| -| Mac | Virtualization framework + `osxfs` | `com.docker.backend` | `osxfs` | Legacy setup, not recommended | -| Mac | DockerVMM + `virtiofs` | `com.docker.backend` | `krun` | Currently in Beta | -| Linux | Native Linux VM | `qemu` | `virtiofsd` | No `com.docker.backend` process on Linux | - +| Platform | Setup | Networking handled by | File sharing handled by | Notes | +| --------------- | ------------------------------------- | ------------------------ | -------------------------------------- | ---------------------------------------------------------- | +| Windows | Hyper-V | `com.docker.backend.exe` | `com.docker.backend.exe` | Simplest setup with full visibility to EDR/firewall tools | +| Windows (WSL 2) | WSL 2 | `com.docker.backend.exe` | WSL 2 kernel (no visibility from host) | Recommended only when WSL 2 integration is needed | +| Mac | Virtualization framework + gRPC FUSE | `com.docker.backend` | `com.docker.backend` | Recommended for performance and visibility | +| Mac | Virtualization framework + `virtiofs` | `com.docker.backend` | Apple's Virtualization framework | Higher performance but no file access visibility from host | +| Mac | Virtualization framework + `osxfs` | `com.docker.backend` | `osxfs` | Legacy setup, not recommended | +| Mac | DockerVMM + `virtiofs` | `com.docker.backend` | `krun` | Currently in Beta | +| Linux | Native Linux VM | `qemu` | `virtiofsd` | No `com.docker.backend` process on Linux | ## How containers connect to the internet @@ -48,7 +47,7 @@ When a container initiates a network request, for example with `apt-get update` - The traffic is transferred to the host system over a shared-memory channel rather than through a traditional virtual network interface. This approach ensures reliable communication and avoids conflicts with host-level network adapters or firewall configurations. - On the host, Docker Desktop’s backend process receives the traffic and creates standard TCP/IP connections using the same networking APIs as other applications. -All outbound container network traffic originates from the `com.docker.backend` process. Firewalls, VPNs, and security tools, like Crowdstrike, see traffic coming from this process — not from a VM or unknown source so firewall and endpoint security software can apply rules directly to `com.docker.backend`. +All outbound container network traffic originates from the `com.docker.backend` process. Firewalls, VPNs, and security tools, like CrowdStrike, see traffic coming from this process — not from a VM or unknown source so firewall and endpoint security software can apply rules directly to `com.docker.backend`. ## How exposed ports work @@ -71,26 +70,27 @@ Docker Desktop can use your system’s default proxy settings or custom settings When a proxy is enabled: -- The backend process forwards the network requests, for example `docker pull`, through an internal proxy at `http.docker.internal:3128`. -- The internal proxy then connects either directly to the internet or through your upstream proxy, depending on your configuration and adding authentication if necessary. +- The backend process forwards the network requests, for example `docker pull`, through an internal proxy at `http.docker.internal:3128`. +- The internal proxy then connects either directly to the internet or through your upstream proxy, depending on your configuration and adding authentication if necessary. - Docker Desktop then downloads the requested images or data through the proxy as usual. -Note that: +Note that: + - The proxy honors system or manual proxy configuration. - On Windows, Basic, NTLM, and Kerberos authentication is supported. - For Mac, NTLM/Kerberos is not supported natively. Run a local proxy on `localhost` as a workaround. - CLI plugins and other tools that use the Docker API directly must be configured separately with the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables. - -## Firewalls and endpoint visibility -To restrict VM or container networking apply rules to `com.docker.backend.exe` (Windows) `com.docker.backend` (Mac) or `qemu` (Linux) as all VM networking is funneled through these processes. +## Firewalls and endpoint visibility + +To restrict VM or container networking apply rules to `com.docker.backend.exe` (Windows) `com.docker.backend` (Mac) or `qemu` (Linux) as all VM networking is funneled through these processes. -Use Windows Defender Firewall or enterprise endpoint firewalls for control. This enables traffic inspection and restriction at the host level without modifying the Docker Engine. +Use Windows Defender Firewall or enterprise endpoint firewalls for control. This enables traffic inspection and restriction at the host level without modifying the Docker Engine. -Crowdstrike and similar tools can observe all traffic and file access that passes through the backend process. +CrowdStrike and similar tools can observe all traffic and file access that passes through the backend process. -| Action | Visible to host EDR? | Reason | -|---------|----------------------|---------| -| Container reads host files | Yes | Access handled by `com.docker.backend` | -| Container writes host files | Yes | Same process performs the write | -| Container accesses its own filesystem layers | No | Exists only inside the VM | +| Action | Visible to host EDR? | Reason | +| -------------------------------------------- | -------------------- | -------------------------------------- | +| Container reads host files | Yes | Access handled by `com.docker.backend` | +| Container writes host files | Yes | Same process performs the write | +| Container accesses its own filesystem layers | No | Exists only inside the VM | From 6e3120cab5a947acf8a55203579ba10ef6ede2f4 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 3 Jun 2026 08:28:05 +0200 Subject: [PATCH 3/8] sbx: gate audit logging on an AI Governance subscription Add the paid-subscription note used across the governance section so the audit logging page states that the feature requires Docker AI Governance. Co-Authored-By: Claude Opus 4.8 (1M context) --- content/manuals/ai/sandboxes/governance/audit.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/content/manuals/ai/sandboxes/governance/audit.md b/content/manuals/ai/sandboxes/governance/audit.md index 5973ba505ca0..b457a46f12ba 100644 --- a/content/manuals/ai/sandboxes/governance/audit.md +++ b/content/manuals/ai/sandboxes/governance/audit.md @@ -13,6 +13,12 @@ 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. +> [!NOTE] +> 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 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. From 672781d58e6eb89f2f337684725aaac7dccaa3f7 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 3 Jun 2026 11:09:27 +0200 Subject: [PATCH 4/8] sbx: drop undocumented storage-override env vars from audit logging SANDBOXES_STORAGE_ROOT and DOCKER_SANDBOXES_APP_NAME are undocumented internals and out of scope for the audit logging page. Remove the override section; it can be documented separately in a follow-up if needed. Co-Authored-By: Claude Opus 4.8 (1M context) --- content/manuals/ai/sandboxes/governance/audit.md | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/content/manuals/ai/sandboxes/governance/audit.md b/content/manuals/ai/sandboxes/governance/audit.md index b457a46f12ba..e550317ddb82 100644 --- a/content/manuals/ai/sandboxes/governance/audit.md +++ b/content/manuals/ai/sandboxes/governance/audit.md @@ -112,18 +112,3 @@ 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. - -## Override the storage location - -Two environment variables change where records are written. Set them on the -daemon process, not the CLI. - -| Variable | Effect | -| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| `SANDBOXES_STORAGE_ROOT=` | Override the base storage directory. Audit records move under `/logs/`, keeping the same platform-specific namespace as the default paths. | -| `DOCKER_SANDBOXES_APP_NAME=` | Append a suffix to the app name (`sandboxes` becomes `sandboxes-`). Useful for running multiple daemon instances side by side. | - -The CLI starts the daemon automatically when none is running, so exporting -either variable in your shell propagates to the daemon it spawns. If a daemon -is already running, stop it first with `sbx daemon stop` so the next `sbx` -command starts a daemon that picks up the new value. From 1affb6c192bbdc2b45515b58ffdd6f4cd881d9a8 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 3 Jun 2026 11:13:23 +0200 Subject: [PATCH 5/8] sbx: simplify audit record attribution wording Drop the unattributed-records caveat. In the licensed, signed-in flow, every record is attributed to the signed-in Docker user; empty attribution is an abnormal state, not expected behavior. Co-Authored-By: Claude Opus 4.8 (1M context) --- content/manuals/ai/sandboxes/governance/audit.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/content/manuals/ai/sandboxes/governance/audit.md b/content/manuals/ai/sandboxes/governance/audit.md index e550317ddb82..a5b0a9c47f92 100644 --- a/content/manuals/ai/sandboxes/governance/audit.md +++ b/content/manuals/ai/sandboxes/governance/audit.md @@ -73,9 +73,7 @@ Common fields include: | `decision` | `AUDIT_DECISION_ALLOW` or `AUDIT_DECISION_DENY`. | | `deny_reason` | Why a denied request was blocked. Present on deny decisions. | -Identity is resolved from the signed-in Docker user at daemon startup. If no -user is signed in when the daemon starts, records still ship, but with empty -`username` and `user_email` fields. +Each record is attributed to the signed-in Docker user. ## Where records are stored From c82b89bd373128b81aff286a3fe8b3abb9e067e5 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 3 Jun 2026 11:21:23 +0200 Subject: [PATCH 6/8] sbx: align audit record example with real sample output Verified the field table and example against real records from a running daemon. Bump schema_version to 1.82.0, include the port in resource_id (host:port), and match the field order of actual output. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../manuals/ai/sandboxes/governance/audit.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/content/manuals/ai/sandboxes/governance/audit.md b/content/manuals/ai/sandboxes/governance/audit.md index a5b0a9c47f92..fff81c20eda0 100644 --- a/content/manuals/ai/sandboxes/governance/audit.md +++ b/content/manuals/ai/sandboxes/governance/audit.md @@ -39,22 +39,22 @@ A network evaluation record looks like this: { "audit_event_id": "95e7257f-93c9-4f29-bde7-88830e2dae80", "timestamp": "2026-05-28T19:15:00.728933Z", - "schema_version": "1.80.0", + "schema_version": "1.82.0", "category": "AUDIT_CATEGORY_EVALUATION", - "audit_session_id": "8a3bc076-79d0-4502-baf3-cc6ad35fb578", + "decision": "AUDIT_DECISION_DENY", "username": "5f3e3556-ed49-4431-bdd8-24958cdc4340", "user_email": "jordan@example.com", - "action_type": "network_egress", - "resource_id": "example.com", - "decision": "AUDIT_DECISION_DENY", - "deny_reason": [ - "no applicable policies for op(action=net:connect:tcp, resource=net:domain:example.com)" - ], - "network_egress": { "protocol": "tcp" }, + "audit_session_id": "8a3bc076-79d0-4502-baf3-cc6ad35fb578", + "resource_id": "example.com:443", "os": "macos", - "hostname": "host-machine", + "app_version": "v0.31.0", "client_name": "sbx", - "app_version": "v0.30.0" + "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" } } ``` @@ -69,7 +69,7 @@ Common fields include: | `username` | The signed-in Docker user's account UUID. | | `user_email` | The signed-in Docker user's email address. | | `action_type` | The kind of access evaluated, such as `network_egress`. | -| `resource_id` | The target of the evaluation, such as a hostname. | +| `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. | From 6b9cae059d0d1727bdcc4be226f1305c6aed4f2b Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 3 Jun 2026 11:59:22 +0200 Subject: [PATCH 7/8] sbx: clarify audit logging activates only under org governance Address PM feedback: make explicit that audit logs are written only while an organization enforces a centralized governance policy. A subscription alone produces no records. Add an sbx policy ls check so testers can confirm governance is active instead of hunting for absent log files. Co-Authored-By: Claude Opus 4.8 (1M context) --- content/manuals/ai/sandboxes/governance/audit.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/content/manuals/ai/sandboxes/governance/audit.md b/content/manuals/ai/sandboxes/governance/audit.md index fff81c20eda0..e9bf54e34b4f 100644 --- a/content/manuals/ai/sandboxes/governance/audit.md +++ b/content/manuals/ai/sandboxes/governance/audit.md @@ -19,6 +19,13 @@ Docker doesn't collect or ingest audit data. > [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 ` 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. From f7988d1f604a541cd251eedcd7317b0c018a4d02 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 4 Jun 2026 08:55:35 +0200 Subject: [PATCH 8/8] sbx: update audit fields for user + org attribution (sandboxes#3281) PR docker/sandboxes#3281 (merged 2026-06-03) changes audit attribution: username now carries the Docker Hub handle (not the UUID, which is no longer emitted), and records include org_id and org_name resolved from the active governance organization. Update the example, field table, and attribution sentence to match. Co-Authored-By: Claude Opus 4.8 (1M context) --- content/manuals/ai/sandboxes/governance/audit.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/content/manuals/ai/sandboxes/governance/audit.md b/content/manuals/ai/sandboxes/governance/audit.md index e9bf54e34b4f..fcf2a4d24c98 100644 --- a/content/manuals/ai/sandboxes/governance/audit.md +++ b/content/manuals/ai/sandboxes/governance/audit.md @@ -49,8 +49,10 @@ A network evaluation record looks like this: "schema_version": "1.82.0", "category": "AUDIT_CATEGORY_EVALUATION", "decision": "AUDIT_DECISION_DENY", - "username": "5f3e3556-ed49-4431-bdd8-24958cdc4340", - "user_email": "jordan@example.com", + "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", @@ -73,14 +75,17 @@ Common fields include: | `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 account UUID. | +| `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. +Each record is attributed to the signed-in Docker user and the organization +whose governance policy is in effect. ## Where records are stored