Configure Docker socket exceptions and advanced settings

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

This page shows you how to configure Docker socket exceptions and other advanced settings for Enhanced Container Isolation (ECI). These configurations enable trusted tools like Testcontainers to work with ECI while maintaining security.

Docker socket mount permissions

By default, Enhanced Container Isolation blocks containers from mounting the Docker socket to prevent malicious access to Docker Engine. However, some tools require Docker socket access.

Common scenarios requiring Docker socket access include:

• Testing frameworks: Testcontainers, which manages test containers
• Build tools: Paketo buildpacks that create ephemeral build containers
• CI/CD tools: Tools that manage containers as part of deployment pipelines
• Development utilities: Docker CLI containers for container management

Configure socket exceptions

Configure Docker socket exceptions using Settings Management:

{{< tabs >}} {{< tab name="Admin Console" >}}

1. Sign in to Docker Home and select your organization from the top-left account drop-down.
2. Go to Admin Console > Desktop Settings Management.
3. Create or edit a setting policy.
4. Find Enhanced Container Isolation settings.
5. Configure Docker socket access control with your trusted images and command restrictions.

{{< /tab >}} {{< tab name="JSON file" >}}

Create an admin-settings.json file and add:

{
  "configurationFileVersion": 2,
  "enhancedContainerIsolation": {
    "locked": true,
    "value": true,
    "dockerSocketMount": {
      "imageList": {
        "images": [
          "docker.io/localstack/localstack:*",
          "docker.io/testcontainers/ryuk:*",
          "docker:cli"
        ],
        "allowDerivedImages": true
      },
      "commandList": {
        "type": "deny",
        "commands": ["push", "build"]
      }
    }
  }
}

{{< /tab >}} {{< /tabs >}}

Image allowlist configuration

The imageList defines which container images can mount the Docker socket.

Image reference formats

Example configurations

Basic allowlist for testing tools:

"imageList": {
  "images": [
    "docker.io/testcontainers/ryuk:*",
    "docker:cli",
    "alpine:latest"
  ]
}

Wildcard allowlist (Docker Desktop 4.36 and later):

"imageList": {
  "images": ["*"]
}

[!WARNING]

Using "*" allows all containers to mount the Docker socket, which reduces security. Only use this when explicitly listing allowed images isn't feasible.

Security validation

Docker Desktop validates allowed images by:

1. Downloading image digests from registries for allowed images
2. Comparing container image digests against the allowlist when containers start
3. Blocking containers whose digests don't match allowed images

This prevents bypassing restrictions by re-tagging unauthorized images:

$ docker tag malicious-image docker:cli
$ docker run -v /var/run/docker.sock:/var/run/docker.sock docker:cli
# This fails because the digest doesn't match the real docker:cli image

Derived images support

For tools like Paketo buildpacks that create ephemeral local images, you can allow images derived from trusted base images.

Enable derived images

"imageList": {
  "images": [
    "paketobuildpacks/builder:base"
  ],
  "allowDerivedImages": true
}

When allowDerivedImages is true, local images built from allowed base images (using FROM in Dockerfile) also gain Docker socket access.

Derived images requirements

• Local images only: Derived images must not exist in remote registries
• Base image available: The parent image must be pulled locally first
• Performance impact: Adds up to 1 second to container startup for validation
• Version compatibility: Full wildcard support requires Docker Desktop 4.36+

Command restrictions

Deny list (recommended)

Blocks specified commands while allowing all others:

"commandList": {
  "type": "deny",
  "commands": ["push", "build", "image*"]
}

Allow list

Only allows specified commands while blocking all others:

"commandList": {
  "type": "allow",
  "commands": ["ps", "container*", "volume*"]
}

Command wildcards

Command blocking example

When a blocked command is executed:

/ # docker push myimage
Error response from daemon: enhanced container isolation: docker command "/v1.43/images/myimage/push?tag=latest" is blocked; if you wish to allow it, configure the docker socket command list in the Docker Desktop settings.

Common configuration examples

Testcontainers setup

For Java/Python testing with Testcontainers:

"dockerSocketMount": {
  "imageList": {
    "images": [
      "docker.io/testcontainers/ryuk:*",
      "testcontainers/*:*"
    ]
  },
  "commandList": {
    "type": "deny",
    "commands": ["push", "build"]
  }
}

CI/CD pipeline tools

For controlled CI/CD container management:

"dockerSocketMount": {
  "imageList": {
    "images": [
      "docker:cli",
      "your-registry.com/ci-tools/*:*"
    ]
  },
  "commandList": {
    "type": "allow",
    "commands": ["ps", "container*", "image*"]
  }
}

Development environments

For local development with Docker-in-Docker:

"dockerSocketMount": {
  "imageList": {
    "images": [
      "docker:dind",
      "docker:cli"
    ]
  },
  "commandList": {
    "type": "deny",
    "commands": ["system*"]
  }
}

Security recommendations

Image allowlist best practices

• Be restrictive: Only allow images you absolutely trust and need
• Use wildcards carefully: Tag wildcards (*) are convenient but less secure than specific tags
• Regular reviews: Periodically review and update your allowlist
• Digest pinning: Use digest references for maximum security in critical environments

Command restrictions

• Default to deny: Start with a deny list blocking dangerous commands like push and build
• Principle of least privilege: Only allow commands your tools actually need
• Monitor usage: Track which commands are being blocked to refine your configuration

Monitoring and maintenance

• Regular validation: Test your configuration after Docker Desktop updates, as image digests may change.
• Handle digest mismatches: If allowed images are unexpectedly blocked:
  consoleCopy

  $ docker image rm <image>
  $ docker pull <image>
  

This resolves digest mismatches when upstream images are updated.

Next steps

• Review Enhanced Container Isolation limitations.
• Review Enhanced Container Isolation FAQs.