diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt index 6a3bd9f76f5f..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 @@ -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..fcf2a4d24c98 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/audit.md @@ -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. + +> [!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 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. + +## 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.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/` | +| 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`. + +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 + +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. 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 |