Skip to content

Commit 4f9ea1f

Browse files
sarahsanders-dockersarahsanders-docker
committed
add ECI docs
1 parent 859343c commit 4f9ea1f

File tree

7 files changed

+672
-822
lines changed

7 files changed

+672
-822
lines changed

‎content/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/_index.md‎

Lines changed: 151 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,18 @@
22
title: Enhanced Container Isolation
33
linkTitle: Enhanced Container Isolation
44
description: Enhanced Container Isolation provides additional security for Docker Desktop by preventing malicious containers from compromising the host
5-
keywords: nhanced container isolation, container security, sysbox runtime, linux user namespaces, hardened desktop
5+
keywords: enhanced container isolation, container security, sysbox runtime, linux user namespaces, hardened desktop
66
aliases:
77
- /desktop/hardened-desktop/enhanced-container-isolation/
88
- /security/for-admins/hardened-desktop/enhanced-container-isolation/
9-
weight: 20
9+
- /security/hardened-desktop/enhanced-container-isolation/how-eci-works
10+
- /security/hardened-desktop/enhanced-container-isolation/features-benefits
11+
weight: 10
1012
---
1113

1214
{{< summary-bar feature_name="Hardened Docker Desktop" >}}
1315

14-
Enhanced Container Isolation (ECI) adds an extra layer of security to prevent malicious containers from compromising Docker Desktop or the host system. It uses advanced isolation techniques while maintaining full developer productivity.
16+
Enhanced Container Isolation (ECI) prevents malicious containers from compromising Docker Desktop or the host system. It applies advanced security techniques automatically while maintaining full developer productivity and workflow compatibility.
1517

1618
ECI strengthens container isolation and locks in security configurations created by administrators, such as [Registry Access Management policies](/manuals/enterprise/security/hardened-desktop/registry-access-management.md) and [Settings Management](../settings-management/_index.md) controls.
1719

@@ -29,121 +31,193 @@ Enhanced Container Isolation is designed for:
2931

3032
## How Enhanced Container Isolation works
3133

32-
For an overview of how ECI works, see [How Enhanced Container Isolation works](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/how-eci-works.md).
34+
Docker implements ECI using the [Sysbox container runtime](https://github.com/nestybox/sysbox), a
35+
security-enhanced fork of the standard OCI runc runtime. When ECI is turned on, containers created through `docker run` or `docker create` automatically use Sysbox instead of runc without requiring any changes to developer workflows.
3336

34-
## Enable Enhanced Container Isolation
37+
> [!NOTE]
38+
>
39+
> When ECI is turned on, the Docker CLI `--runtime` flag is ignored.
40+
Docker's default runtime remains `runc`, but all user containers
41+
implicitly launch with Sysbox.
3542

36-
### For developers
43+
Even containers using the `--privileged` flag run securely with Enhanced Container Isolation, preventing them from breaching the Docker Desktop virtual machine or other containers.
3744

38-
To turn on ECI:
45+
## Key security features
3946

40-
1. Verify your organization has a Docker Business subscription.
41-
1. Sign in to your organization in Docker Desktop to access ECI features.
42-
1. Stop and remove all existing containers:
47+
### Linux user namespace isolation
4348

44-
```console
45-
$ docker stop $(docker ps -q)
46-
$ docker rm $(docker ps -aq)
47-
```
49+
With Enhanced Container Isolation, all containers leverage Linux user namespaces for stronger isolation. Container root users map to unprivileged users in the Docker Desktop VM:
4850

49-
1. In Docker Desktop, go to **Settings** > **General**.
50-
1. Select the **Use Enhanced Container Isolation** checkbox.
51-
1. Select **Apply and restart**.
51+
```console
52+
$ docker run -it --rm --name=first alpine
53+
/ # cat /proc/self/uid_map
54+
0 100000 65536
55+
```
5256

53-
> [!IMPORTANT]
54-
>
55-
> ECI doesn't protect containers created before turning on the feature. Remove existing containers before turning on ECI.
57+
This output shows that container root (0) maps to unprivileged user 100000 in the VM, with a range of 64K user IDs. Each container gets exclusive mappings:
5658

57-
### For administrators
59+
```console
60+
$ docker run -it --rm --name=second alpine
61+
/ # cat /proc/self/uid_map
62+
0 165536 65536
63+
```
5864

59-
Before you begin, [enforce sign-in](/manuals/enterprise/security/enforce-sign-in) so users authenticate with your organization
60-
when signing into Docker Desktop.
65+
Without Enhanced Container Isolation, containers run as true root:
6166

62-
You can configure Enhanced Container Isolation for your organization using
63-
Settings Management.
67+
```console
68+
$ docker run -it --rm alpine
69+
/ # cat /proc/self/uid_map
70+
0 0 4294967295
71+
```
6472

65-
{{< tabs >}}
66-
{{< tab name="Admin Console" >}}
73+
By using Linux user namespaces, ECI ensures container processes never run with valid user IDs in the Linux VM, constraining their capabilities to resources within the container only.
6774

68-
1. Sign in to [Docker Home](https:app.docker.com) and select your organization.
69-
1. Go to **Admin Console** > **Desktop Settings Management**.
70-
1. [Create or edit a settings policy](/manuals/enterprise/security/hardened-desktop/settings-management/configure-admin-console.md).
71-
1. Set **Enhanced Container Isolation** to **Always enabled**.
75+
### Secured privileged containers
7276

73-
{{< /tab >}}
74-
{{< tab name="`admin-settings.json` file" >}}
77+
Privileged containers (`docker run --privileged`) normally pose significant security risks because they provide unrestricted access to the Linux kernel. Without ECI, privileged containers can:
7578

76-
Create an [`admin-settings.json`](/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md) file with:
79+
- Run as true root with all capabilities
80+
- Bypass seccomp and AppArmor restrictions
81+
- Access all hardware devices
82+
- Modify global kernel settings
7783

78-
```json
79-
{
80-
"configurationFileVersion": 2,
81-
"enhancedContainerIsolation": {
82-
"value": true,
83-
"locked": true
84-
}
85-
}
86-
```
84+
Organizations securing developer environments face challenges with privileged containers because they can gain control of the Docker Desktop VM and alter security settings like registry access management and network proxies.
8785

88-
Configuration options:
89-
- `"value": true`: Turns on ECI by default
90-
- `"locked": true`: Prevents developers from turning off ECI
91-
- `"locked": false`: Allows developers to control the setting
86+
Enhanced Container Isolation transforms privileged containers by ensuring they can only access resources within their container boundary. For example, privileged containers can't access Docker Desktop's network configuration:
9287

93-
{{< /tab >}}
94-
{{< /tabs >}}
88+
```console
89+
$ docker run --privileged djs55/bpftool map show
90+
Error: can't get next map: Operation not permitted
91+
```
9592

96-
#### Apply the configuration
93+
Without ECI, privileged containers can easily access and modify these settings:
9794

98-
To apply the updated Enhanced Container Isolation setting for your organization:
95+
```console
96+
$ docker run --privileged djs55/bpftool map show
97+
17: ringbuf name blocked_packets flags 0x0
98+
key 0B value 0B max_entries 16777216 memlock 0B
99+
18: hash name allowed_map flags 0x0
100+
key 4B value 4B max_entries 10000 memlock 81920B
101+
```
99102

100-
- New installations: Users launch Docker Desktop and sign in
101-
- Existing installations: Users must fully quit Docker Desktop and relaunch
103+
Advanced container workloads like Docker-in-Docker and Kubernetes-in-Docker still work with ECI but run much more securely.
102104

103-
> [!IMPORTANT]
105+
> [!NOTE]
104106
>
105-
> Restarting from the Docker Desktop menu isn't sufficient. Users must completely quit and reopen Docker Desktop.
107+
> ECI doesn't prevent users from running privileged containers, but makes them secure by containing their access. Privileged workloads that modify global kernel settings (loading kernel modules, changing Berkeley Packet Filter settings) receive "permission denied" errors.
108+
109+
### Namespace isolation enforcement
110+
111+
Enhanced Container Isolation prevents containers from sharing Linux namespaces with the Docker Desktop VM, maintaining isolation boundaries:
112+
113+
**PID namespace sharing blocked:**
114+
115+
```console
116+
$ docker run -it --rm --pid=host alpine
117+
docker: Error response from daemon: failed to create shim task: OCI runtime create failed: error in the container spec: invalid or unsupported container spec: sysbox containers can't share namespaces [pid] with the host (because they use the linux user-namespace for isolation): unknown.
118+
```
119+
120+
**Network namespace sharing blocked:**
121+
122+
```console
123+
$ docker run -it --rm --network=host alpine
124+
docker: Error response from daemon: failed to create shim task: OCI runtime create failed: error in the container spec: invalid or unsupported container spec: sysbox containers can't share a network namespace with the host (because they use the linux user-namespace for isolation): unknown.
125+
```
126+
127+
**User namespace override ignored:**
106128

107-
You can also configure Docker socket mount permissions for trusted images that need Docker API access.
129+
```console
130+
$ docker run -it --rm --userns=host alpine
131+
/ # cat /proc/self/uid_map
132+
0 100000 65536
133+
```
108134

109-
## Verify Enhanced Container Isolation is active
135+
Docker build operations using `--network-host` and Docker buildx entitlements (`network.host`,
136+
`security.insecure`) are also blocked.
110137

111-
When ECI is turned on, users can verify it's working by checking the user
112-
namespace mapping:
138+
### Protected bind mounts
139+
140+
Enhanced Container Isolation maintains support for standard file sharing while preventing access to sensitive VM directories:
141+
142+
**Host directory mounts continue to work:**
113143

114144
```console
115-
$ docker run --rm alpine cat /proc/self/uid_map
145+
$ docker run -it --rm -v $HOME:/mnt alpine
146+
/ # ls /mnt
147+
# Successfully lists home directory contents
116148
```
117149

118-
When ECI is turned on:
150+
**VM configuration mounts are blocked:**
151+
152+
```console
153+
$ docker run -it --rm -v /etc/docker/daemon.json:/mnt/daemon.json alpine
154+
docker: Error response from daemon: failed to create shim task: OCI runtime create failed: error in the container spec: can't mount /etc/docker/daemon.json because it's configured as a restricted host mount: unknown
155+
```
156+
157+
This prevents containers from reading or modifying Docker Engine configurations, registry access management settings, proxy configurations, and other security-related VM files.
158+
159+
> [!NOTE]
160+
>
161+
> By default, ECI blocks bind mounting the Docker Engine socket (/var/run/docker.sock) as this would grant containers control over Docker Engine. Administrators can create exceptions for trusted container images.
162+
163+
### Advanced system call protection
164+
165+
Enhanced Container Isolation intercepts sensitive system calls to prevent containers from using legitimate capabilities maliciously:
119166

120-
```text
121-
0 100000 65536
167+
```console
168+
$ docker run -it --rm --cap-add SYS_ADMIN -v $HOME:/mnt:ro alpine
169+
/ # mount -o remount,rw /mnt /mnt
170+
mount: permission denied (are you root?)
122171
```
123172

124-
This shows the container's root user (0) maps to an unprivileged user (100000) in the Docker Desktop VM, with a range of 64K user IDs. Each container gets an exclusive user ID range for isolation.
173+
Even with `CAP_SYS_ADMIN` capability, containers can't change read-only bind mounts to read-write, ensuring they can't breach container boundaries.
125174

126-
When ECI is turned off:
175+
Containers can still create internal mounts within their filesystem:
127176

128-
```text
129-
0 0 4294967295
177+
```console
178+
/ # mkdir /root/tmpfs
179+
/ # mount -t tmpfs tmpfs /root/tmpfs
180+
/ # mount -o remount,ro /root/tmpfs /root/tmpfs
181+
/ # findmnt | grep tmpfs
182+
├─/root/tmpfs tmpfs tmpfs ro,relatime,uid=100000,gid=100000
130183
```
131184

132-
This shows the container root user (0) maps directly to the VM root user (0), providing less isolation.
185+
ECI performs system call filtering efficiently by intercepting only control-path system calls (rarely used) while leaving data-path system calls unaffected, maintaining container performance.
186+
187+
### Automatic filesystem user ID mapping
188+
189+
Enhanced Container Isolation solves file sharing challenges between containers with different user ID ranges through automatic filesystem mapping.
190+
191+
Each container gets exclusive user ID mappings, but Sysbox uses filesystem user ID remapping via Linux kernel ID-mapped mounts (added in 2021) or alternative shiftsfs module. This maps filesystem accesses from containers' real user IDs to standard ranges, enabling:
133192

134-
You can also check the container runtime:
193+
- Volume sharing across containers with different user ID ranges
194+
- Consistent file ownership regardless of container user ID mappings
195+
- Transparent file access without user intervention
196+
197+
### Information hiding through filesystem emulation
198+
199+
ECI emulates portions of `/proc` and `/sys` filesystems within containers to hide sensitive host information and provide per-container views of kernel resources:
135200

136201
```console
137-
$ docker inspect --format='{{.HostConfig.Runtime}}' <container_name>
202+
$ docker run -it --rm alpine
203+
/ # cat /proc/uptime
204+
5.86 5.86
138205
```
139206

140-
With ECI, it returns `sysbox-runc`. Without ECI it returns `runc`.
207+
This shows container uptime instead of Docker Desktop VM uptime, preventing system information from leaking into containers.
208+
209+
Several `/proc/sys` resources that aren't namespaced by the Linux kernel are emulated per-container, with Sysbox coordinating values when programming kernel settings. This enables container workloads that normally require privileged access to run securely.
141210

142-
## What developers see with enforced ECI
211+
## Performance and compatibility
143212

144-
When administrators enforce Enhanced Container Isolation:
213+
Enhanced Container Isolation maintains excellent performance and full compatibility:
145214

146-
- The Use Enhanced Container Isolation setting appears turned on in Docker Desktop settings
147-
- The setting is locked and can't be changed if `"locked": true` was configured
148-
- All new containers automatically use Linux user namespaces
149-
- Existing development workflows continue to work without modification
215+
- No performance impact: System call filtering targets only control-path calls, leaving data-path operations unaffected
216+
- Full workflow compatibility: Existing development processes, tools, and container images work unchanged
217+
- Advanced workload support: Docker-in-Docker, Kubernetes-in-Docker, and other complex scenarios work securely
218+
- Automatic management: User ID mappings, filesystem access, and security policies are handled automatically
219+
- Standard image support: No special container images or modifications required
220+
221+
> [!IMPORTANT]
222+
>
223+
> ECI protection varies by Docker Desktop version and doesn't yet protect extension containers. Docker builds and Kubernetes in Docker Desktop have varying protection levels depending on the version. For details, see [Enhanced Container Isolation limitations](/manuals/enterprise/security/hardened-desktop/enhanced-container-isolation/limitations.md).

0 commit comments

Comments
 (0)