Skip to content

Commit 10e4df5

Browse files
dvdksndvdksn
authored
Merge pull request #25239 from dvdksn/worktree-sbx-audit-logging-docs
sbx: document audit logging as a governance feature
1 parent c098fd1 commit 10e4df5

4 files changed

Lines changed: 157 additions & 30 deletions

File tree

‎_vale/config/vocabularies/Docker/accept.txt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ config
5050
containerd
5151
Couchbase
5252
CouchDB
53-
Crowdstrike
53+
CrowdStrike
5454
[Cc]ybersecurity
5555
datacenter
5656
datasource
@@ -93,6 +93,7 @@ Ethernet
9393
[Ff]ailover
9494
Fargate
9595
Fedora
96+
Filebeat
9697
firewalld
9798
Flink
9899
Fluentd

‎content/manuals/ai/sandboxes/governance/_index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,5 +42,7 @@ personal account.
4242
as organization members, enforced through endpoint management
4343
- [Monitoring](monitoring.md): inspect active rules and monitor sandbox
4444
network traffic with `sbx policy ls` and `sbx policy log`
45+
- [Audit logs](audit.md): capture a durable, structured record of every
46+
policy decision for SIEM ingestion and compliance
4547
- [API reference](/reference/api/ai-governance/): manage org policies
4648
programmatically via the Governance API

‎content/manuals/ai/sandboxes/governance/audit.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
title: Audit logging
3+
linkTitle: Audit logs
4+
weight: 28
5+
description: Capture a structured, durable record of every sandbox policy decision for SIEM ingestion and compliance.
6+
keywords: docker sandboxes, audit log, audit logging, policy decision, SIEM, compliance, jsonl, splunk, filebeat
7+
---
8+
9+
The sandbox daemon records a structured audit event for every policy decision
10+
it makes. Each record captures who triggered the evaluation, when it happened,
11+
which rule matched, and whether the resource was allowed or denied. Records are
12+
written to disk as JSON Lines (`.jsonl`) so existing SIEM and log-shipping
13+
tools can collect them. The records stay on the machine that produced them.
14+
Docker doesn't collect or ingest audit data.
15+
16+
> [!NOTE]
17+
> Audit logging is part of Docker AI Governance and requires a separate paid
18+
> subscription.
19+
> [Contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales)
20+
> to request access.
21+
22+
Audit logging is active only while your organization enforces a centralized
23+
governance policy. The subscription alone doesn't produce records. If your
24+
organization hasn't configured and enforced an [organization policy](org.md),
25+
the daemon writes no audit logs. To confirm governance is active, run `sbx
26+
policy ls` — the output begins with a `Governance: managed by <org>` header
27+
when an organization policy is in effect.
28+
29+
Audit logging complements [monitoring](monitoring.md). Monitoring with `sbx
30+
policy ls` and `sbx policy log` is for live, interactive debugging. Audit
31+
logging produces a durable trail for security review and compliance.
32+
33+
## What gets recorded
34+
35+
The daemon writes two categories of record:
36+
37+
- Evaluation records capture each policy decision: the resource, the
38+
action, the verdict, and the reason for a denial.
39+
- Session lifecycle records mark the start and end of each daemon run.
40+
Evaluation records share the run's `audit_session_id`, so you can correlate
41+
every decision back to a single daemon session.
42+
43+
A network evaluation record looks like this:
44+
45+
```json
46+
{
47+
"audit_event_id": "95e7257f-93c9-4f29-bde7-88830e2dae80",
48+
"timestamp": "2026-05-28T19:15:00.728933Z",
49+
"schema_version": "1.82.0",
50+
"category": "AUDIT_CATEGORY_EVALUATION",
51+
"decision": "AUDIT_DECISION_DENY",
52+
"username": "jordandoe",
53+
"user_email": "jordandoe@example.com",
54+
"org_id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
55+
"org_name": "Acme Inc",
56+
"audit_session_id": "8a3bc076-79d0-4502-baf3-cc6ad35fb578",
57+
"resource_id": "example.com:443",
58+
"os": "macos",
59+
"app_version": "v0.31.0",
60+
"client_name": "sbx",
61+
"hostname": "host-machine",
62+
"deny_reason": [
63+
"no applicable policies for op(action=net:connect:tcp, resource=net:domain:example.com:443)"
64+
],
65+
"action_type": "network_egress",
66+
"network_egress": { "protocol": "tcp" }
67+
}
68+
```
69+
70+
Common fields include:
71+
72+
| Field | Description |
73+
| ------------------ | ------------------------------------------------------------------------------------------------------------ |
74+
| `timestamp` | UTC time of the decision. |
75+
| `schema_version` | Version of the record schema. Pin your SIEM field mappings to it, as the format is a stable contract. |
76+
| `category` | `AUDIT_CATEGORY_EVALUATION` for policy decisions, `AUDIT_CATEGORY_MANAGEMENT` for session lifecycle records. |
77+
| `audit_session_id` | Identifies the daemon run that produced the record. |
78+
| `username` | The signed-in Docker user's Docker Hub username. |
79+
| `user_email` | The signed-in Docker user's email address. |
80+
| `org_id` | ID of the organization whose governance policy is in effect. |
81+
| `org_name` | Display name of the organization whose governance policy is in effect. |
82+
| `action_type` | The kind of access evaluated, such as `network_egress`. |
83+
| `resource_id` | The target of the evaluation, such as a host and port. |
84+
| `decision` | `AUDIT_DECISION_ALLOW` or `AUDIT_DECISION_DENY`. |
85+
| `deny_reason` | Why a denied request was blocked. Present on deny decisions. |
86+
87+
Each record is attributed to the signed-in Docker user and the organization
88+
whose governance policy is in effect.
89+
90+
## Where records are stored
91+
92+
The daemon writes audit records, not the CLI. Running a command such as `sbx
93+
create` sends a request to the daemon, and the daemon emits the resulting
94+
record to its own audit directory.
95+
96+
The default location depends on your operating system:
97+
98+
| OS | Default path |
99+
| ------- | ----------------------------------------------------------------- |
100+
| macOS | `~/Library/Logs/com.docker.sandboxes/sandboxes/auditkit/` |
101+
| Linux | `${XDG_STATE_HOME:-~/.local/state}/sandboxes/sandboxes/auditkit/` |
102+
| Windows | `%LOCALAPPDATA%\DockerSandboxes\sandboxes\logs\auditkit\` |
103+
104+
The directory layout differs by platform because each operating system places
105+
application logs in its own conventional location.
106+
107+
Files are named `audit-<utc-timestamp>-<process-uuid>-<seq>.jsonl`.
108+
109+
The daemon writes in-progress records to a temporary `.tmp` file and seals it
110+
into a final `.jsonl` file by atomic rename. Sealing happens at a rotation
111+
threshold (by default 5 minutes, 1000 events, or 50 MiB, whichever comes
112+
first) or when the daemon shuts down cleanly. Only sealed `.jsonl` files are
113+
complete. Treat `.tmp` files as incomplete and don't collect them.
114+
115+
Sandboxes never delete sealed files. Retention and cleanup are the
116+
responsibility of your log shipper or your own housekeeping.
117+
118+
## Collect records with a SIEM
119+
120+
Point your log shipper at the audit directory and configure it to collect
121+
sealed `.jsonl` files only. Tools such as the Splunk Universal Forwarder,
122+
Filebeat, and CrowdStrike Falcon LogScale read the directory and forward each
123+
line as an event. Because in-progress records live in `.tmp` files until they
124+
are sealed, collectors never see partial records.

‎content/manuals/desktop/features/networking/_index.md‎

Lines changed: 29 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ keywords: docker desktop, networking, architecture, firewall, proxies, crowdstri
44
title: Networking on Docker Desktop
55
linkTitle: Networking
66
weight: 30
7-
---
7+
---
88

99
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.
1010

@@ -17,25 +17,24 @@ Docker Desktop runs the Docker Engine inside a lightweight Linux virtual machine
1717
The backend acts as:
1818

1919
- Network proxy: Translates traffic between the host and Linux VM.
20-
- On Windows and Mac, this is handled by the `com.docker.backend` process.
21-
- On Linux, the `qemu` process performs this function.
20+
- On Windows and Mac, this is handled by the `com.docker.backend` process.
21+
- On Linux, the `qemu` process performs this function.
2222
- File server: Handles file access from containers to the host filesystem.
23-
- When using gRPC FUSE, the backend performs the file sharing.
24-
- When using `virtiofs`, `osxfs`, or `krun`, file access is handled by those respective daemons rather than the backend process.
23+
- When using gRPC FUSE, the backend performs the file sharing.
24+
- When using `virtiofs`, `osxfs`, or `krun`, file access is handled by those respective daemons rather than the backend process.
2525
- Control plane: Manages Docker API calls, port forwarding, and proxy configuration.
2626

2727
The following table summarizes typical setups in more detail:
2828

29-
| Platform | Setup | Networking handled by | File sharing handled by | Notes |
30-
| --------------- | ------------------------------------ | ------------------------ | -------------------------------------- | --------------------------------------------------------- |
31-
| Windows | Hyper-V | `com.docker.backend.exe` | `com.docker.backend.exe` | Simplest setup with full visibility to EDR/firewall tools |
32-
| Windows (WSL 2) | WSL 2 | `com.docker.backend.exe` | WSL 2 kernel (no visibility from host) | Recommended only when WSL 2 integration is needed |
33-
| Mac | Virtualization framework + gRPC FUSE | `com.docker.backend` | `com.docker.backend` | Recommended for performance and visibility |
34-
| Mac | Virtualization framework + `virtiofs`| `com.docker.backend` | Apple's Virtualization framework | Higher performance but no file access visibility from host|
35-
| Mac | Virtualization framework + `osxfs` | `com.docker.backend` | `osxfs` | Legacy setup, not recommended |
36-
| Mac | DockerVMM + `virtiofs` | `com.docker.backend` | `krun` | Currently in Beta |
37-
| Linux | Native Linux VM | `qemu` | `virtiofsd` | No `com.docker.backend` process on Linux |
38-
29+
| Platform | Setup | Networking handled by | File sharing handled by | Notes |
30+
| --------------- | ------------------------------------- | ------------------------ | -------------------------------------- | ---------------------------------------------------------- |
31+
| Windows | Hyper-V | `com.docker.backend.exe` | `com.docker.backend.exe` | Simplest setup with full visibility to EDR/firewall tools |
32+
| Windows (WSL 2) | WSL 2 | `com.docker.backend.exe` | WSL 2 kernel (no visibility from host) | Recommended only when WSL 2 integration is needed |
33+
| Mac | Virtualization framework + gRPC FUSE | `com.docker.backend` | `com.docker.backend` | Recommended for performance and visibility |
34+
| Mac | Virtualization framework + `virtiofs` | `com.docker.backend` | Apple's Virtualization framework | Higher performance but no file access visibility from host |
35+
| Mac | Virtualization framework + `osxfs` | `com.docker.backend` | `osxfs` | Legacy setup, not recommended |
36+
| Mac | DockerVMM + `virtiofs` | `com.docker.backend` | `krun` | Currently in Beta |
37+
| Linux | Native Linux VM | `qemu` | `virtiofsd` | No `com.docker.backend` process on Linux |
3938

4039
## How containers connect to the internet
4140

@@ -48,7 +47,7 @@ When a container initiates a network request, for example with `apt-get update`
4847
- 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.
4948
- 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.
5049

51-
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`.
50+
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`.
5251

5352
## How exposed ports work
5453

@@ -71,26 +70,27 @@ Docker Desktop can use your system’s default proxy settings or custom settings
7170

7271
When a proxy is enabled:
7372

74-
- The backend process forwards the network requests, for example `docker pull`, through an internal proxy at `http.docker.internal:3128`.
75-
- The internal proxy then connects either directly to the internet or through your upstream proxy, depending on your configuration and adding authentication if necessary.
73+
- The backend process forwards the network requests, for example `docker pull`, through an internal proxy at `http.docker.internal:3128`.
74+
- The internal proxy then connects either directly to the internet or through your upstream proxy, depending on your configuration and adding authentication if necessary.
7675
- Docker Desktop then downloads the requested images or data through the proxy as usual.
7776

78-
Note that:
77+
Note that:
78+
7979
- The proxy honors system or manual proxy configuration.
8080
- On Windows, Basic, NTLM, and Kerberos authentication is supported.
8181
- For Mac, NTLM/Kerberos is not supported natively. Run a local proxy on `localhost` as a workaround.
8282
- 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.
83-
84-
## Firewalls and endpoint visibility
8583

86-
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.
84+
## Firewalls and endpoint visibility
85+
86+
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.
8787

88-
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.
88+
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.
8989

90-
Crowdstrike and similar tools can observe all traffic and file access that passes through the backend process.
90+
CrowdStrike and similar tools can observe all traffic and file access that passes through the backend process.
9191

92-
| Action | Visible to host EDR? | Reason |
93-
|---------|----------------------|---------|
94-
| Container reads host files | Yes | Access handled by `com.docker.backend` |
95-
| Container writes host files | Yes | Same process performs the write |
96-
| Container accesses its own filesystem layers | No | Exists only inside the VM |
92+
| Action | Visible to host EDR? | Reason |
93+
| -------------------------------------------- | -------------------- | -------------------------------------- |
94+
| Container reads host files | Yes | Access handled by `com.docker.backend` |
95+
| Container writes host files | Yes | Same process performs the write |
96+
| Container accesses its own filesystem layers | No | Exists only inside the VM |

0 commit comments

Comments
 (0)