|
| 1 | +--- |
| 2 | +title: Trust model for Compose files |
| 3 | +weight: 70 |
| 4 | +description: Learn how Docker Compose treats Compose files as trusted input and what this means when using files you did not author. |
| 5 | +keywords: compose, security, trust model, oci, remote, registry, include, extends, supply chain, trust, best practices |
| 6 | +--- |
| 7 | + |
| 8 | +Docker Compose treats every Compose file as trusted input. When a Compose file |
| 9 | +requests elevated privileges, host filesystem access, or any other |
| 10 | +configuration, Compose applies it as written. This is the same behavior as |
| 11 | +passing flags directly to `docker run`. |
| 12 | + |
| 13 | +This means that any Compose file you run, whether it lives on your local |
| 14 | +filesystem, in a Git repository, or in an OCI registry, has full control over |
| 15 | +how containers interact with your host. The security boundary is not where the file comes from but whether you trust the author. |
| 16 | + |
| 17 | +Evaluating trust means asking: do you know who authored this file, can you verify it hasn't changed since you last reviewed it, and do you understand every privilege it requests? |
| 18 | + |
| 19 | +## The dependency chain |
| 20 | + |
| 21 | +A Compose application can be assembled from multiple sources. The |
| 22 | +[`include`](/reference/compose-file/include.md) directive imports entire Compose |
| 23 | +files, while [`extends`](/reference/compose-file/services.md#extends) inherits |
| 24 | +configuration from a specific service in another file. Both support remote |
| 25 | +references and can be chained: |
| 26 | + |
| 27 | +```text |
| 28 | +Your command |
| 29 | + └─ compose.yaml (local or remote) |
| 30 | + ├─ services, volumes, networks (direct config) |
| 31 | + ├─ include: |
| 32 | + │ └─ oci://registry.example.com/base:v2 (remote dependency) |
| 33 | + │ └─ services, volumes, networks (indirect config) |
| 34 | + └─ services: |
| 35 | + └─ app: |
| 36 | + └─ extends: |
| 37 | + └─ file: oci://registry.example.com/templates:v1 |
| 38 | + └─ service: webapp (inherited config) |
| 39 | +``` |
| 40 | + |
| 41 | +Each level has the same capabilities. The top-level file you inspect may appear |
| 42 | +safe while a nested `include` or `extends` introduces services with elevated |
| 43 | +privileges, host bind mounts, or untrusted images. These dependencies can also |
| 44 | +change independently. Risky settings can be introduced by a nested dependency that you never |
| 45 | +see unless you inspect the fully resolved output. |
| 46 | + |
| 47 | +> [!IMPORTANT] |
| 48 | +> |
| 49 | +> Compose warns you when a configuration references remote sources. Do not |
| 50 | +> accept this without understanding every reference in the chain. |
| 51 | +
|
| 52 | +## Best practices |
| 53 | + |
| 54 | +### Inspect the full configuration |
| 55 | + |
| 56 | +To see exactly what Compose applies, including all resolved `includes`, |
| 57 | +`extends`, merged overrides, and interpolated variables, use: |
| 58 | + |
| 59 | +```console |
| 60 | +$ docker compose config |
| 61 | +``` |
| 62 | + |
| 63 | +For remote references: |
| 64 | + |
| 65 | +```console |
| 66 | +$ docker compose -f oci://registry.example.com/myapp:latest config |
| 67 | +``` |
| 68 | + |
| 69 | +Review this output before running `up` or `create`, especially when the |
| 70 | +configuration comes from a source you have not audited. |
| 71 | + |
| 72 | +#### Fields to look out for |
| 73 | + |
| 74 | +A Compose configuration has broad control over how containers interact with the |
| 75 | +host. The following is a non-exhaustive list of fields that carry security |
| 76 | +implications when set by an untrusted author: |
| 77 | + |
| 78 | +| Field | Effect | |
| 79 | +|-------|--------| |
| 80 | +| `privileged` | Grants the container full access to the host | |
| 81 | +| `cap_add` | Adds Linux capabilities such as `SYS_ADMIN` or `NET_RAW` | |
| 82 | +| `security_opt` | Configures security profiles including seccomp and AppArmor | |
| 83 | +| `volumes` / bind mounts | Mounts host directories into the container | |
| 84 | +| `network_mode: host` | Shares the host network stack | |
| 85 | +| `pid: host` | Shares the host PID namespace | |
| 86 | +| `devices` | Exposes host devices to the container | |
| 87 | +| `image` | Pulls and runs an arbitrary container image | |
| 88 | + |
| 89 | +When in doubt, look up the effect of any unfamiliar field before running the configuration. |
| 90 | + |
| 91 | +### CI/CD environments |
| 92 | + |
| 93 | +Automated pipelines are particularly sensitive because they often run with |
| 94 | +access to credentials, cloud provider tokens, or Docker sockets. |
| 95 | + |
| 96 | +- Avoid referencing public or unverified Compose configurations in automated |
| 97 | + pipelines. |
| 98 | +- Gate updates behind your normal code review process. |
| 99 | +- Use read-only Docker socket mounts where possible to limit your risk. |
| 100 | + |
| 101 | +### Pin remote references to digests |
| 102 | + |
| 103 | +Tags are mutable meaning anyone with push access to a registry can overwrite a tag silently, so a reference you reviewed last week may point to different content today. |
| 104 | + |
| 105 | +Digests are immutable. Instead of referencing by tag, pin to the digest. |
| 106 | + |
| 107 | +```yaml |
| 108 | +include: |
| 109 | + - oci://registry.example.com/base@sha256:a1b2c3d4... |
| 110 | +``` |
| 111 | +
|
| 112 | +Treat any update to a pinned digest as a code change. Make sure you review the new content before updating the reference. |
| 113 | +
|
| 114 | +### Other |
| 115 | +
|
| 116 | +- Use a private registry: Host OCI artifacts on a registry your |
| 117 | + organization controls. Restrict who can push to it. |
| 118 | +- Audit transitive dependencies: Check every remote `include` and `extends` |
| 119 | + reference in the chain, not just the top-level file. |
| 120 | +- Review all Compose confirmation prompts: When loading remote Compose files, |
| 121 | + Compose displays confirmation prompts for interpolation variables, environment |
| 122 | + values, and remote includes. Review these before accepting. |
| 123 | + |
| 124 | +## Further reading |
| 125 | + |
| 126 | +- [OCI artifact applications](/manuals/compose/how-tos/oci-artifact.md) |
| 127 | +- [Use Compose in production](/manuals/compose/how-tos/production.md) |
| 128 | +- [`include` reference](/reference/compose-file/include.md) |
| 129 | +- [`extends` reference](/reference/compose-file/services.md#extends) |
| 130 | +- [Manage secrets in Compose](/manuals/compose/how-tos/use-secrets.md) |
0 commit comments