sdk/api/docker-compose

🐳 Compose

Docker Compose API Reference

Service-level configuration analysis for docker-compose.yml. Rules match service properties: privileges, mounts, capabilities, network modes, environment variables, published ports.

Canonical imports

python

from codepathfinder.container_decorators import compose_rule
from codepathfinder.container_matchers import service_has, service_missing
from codepathfinder.container_combinators import all_of, any_of, none_of  # optional

@compose_rule decorator

Declares a rule scoped to docker-compose*.yml files. Automatically sets file_pattern="**/docker-compose*.yml".

python

@compose_rule(
    id="COMPOSE-SEC-001",             # required
    name="",
    severity="MEDIUM",                # CRITICAL | HIGH | MEDIUM | LOW | INFO
    category="security",
    cwe="",
    cve="",
    tags="",
    message="",
)
def my_rule():
    return service_has(key="privileged", equals=True)

Like @dockerfile_rule, @compose_rule does not accept an owasp parameter.

service_has()

Matches services with a specific property. All constraint parameters are optional; pass only the ones you need.

python

from codepathfinder.container_matchers import service_has

# Privileged mode (container escape)
service_has(key="privileged", equals=True)

# Docker socket mounted inside container
service_has(key="volumes", contains="/var/run/docker.sock")

# Network mode = host (bypasses network isolation)
service_has(key="network_mode", equals="host")

# Dangerous Linux capabilities
service_has(
    key="cap_add",
    contains_any=["SYS_ADMIN", "NET_ADMIN", "SYS_PTRACE", "ALL"],
)

# Environment variable with secret-ish name
service_has(key="environment", env_name_regex=r"(?i).*(password|secret|token).*")

# Port published to host below a threshold (privileged ports)
service_has(key="ports", published_port_less_than=1024)

Parameters

keyrequired

str

Service property key, e.g., "privileged", "volumes", "cap_add", "network_mode", "environment", "ports", "user", "read_only".

equals

Any | None

Value must equal this literal (bool, str, int, list).

not_equals

Any | None

Value must NOT equal this literal.

contains

str | None

Stringified value must contain this substring (works for lists and strings).

not_contains

str | None

Stringified value must NOT contain substring.

contains_any

list[str] | None

Value contains at least one of the listed substrings.

regex

str | None

Regex applied to stringified value.

env_name_regex

str | None

For environment: regex on env var names.

env_value_regex

str | None

For environment: regex on env var values.

volume_type

str | None

For volumes: "bind" | "volume" | "tmpfs" | "npipe".

source_regex

str | None

For volumes: regex on source path / name.

target_regex

str | None

For volumes: regex on target mount path.

published_port_less_than

int | None

For ports: published port below threshold (privileged port detection).

service_missing()

Matches services that do NOT have a specific property. Ideal for enforcing security defaults like read_only or security_opt: no-new-privileges.

python

from codepathfinder.container_matchers import service_missing

service_missing(key="read_only")                               # filesystem isn't read-only
service_missing(key="security_opt")                            # no security_opt at all
service_missing(key="security_opt", value_contains="no-new-privileges")  # present but missing this flag

Signature

keyrequired

str

Service property key that must be absent (or present without the given value).

value_contains

str | None

When set: key may exist, but its value must NOT contain this substring.

Combinators

Same combinators as Dockerfile rules.

python

from codepathfinder.container_combinators import all_of, any_of, none_of

# Service is privileged AND mounts docker.sock
all_of(
    service_has(key="privileged", equals=True),
    service_has(key="volumes", contains="/var/run/docker.sock"),
)

# Any dangerous network setting
any_of(
    service_has(key="network_mode", equals="host"),
    service_has(key="pid", equals="host"),
    service_has(key="ipc", equals="host"),
)

Complete example: dangerous capabilities

Real rule from the registry (COMPOSE-SEC-008). Flags services that add capabilities enabling container escape.

python

from codepathfinder.container_decorators import compose_rule
from codepathfinder.container_matchers import service_has


@compose_rule(
    id="COMPOSE-SEC-008",
    name="Dangerous Capability Added",
    severity="HIGH",
    cwe="CWE-250",
    category="security",
    tags="docker-compose,compose,capabilities,cap-add,security,privilege-escalation,container-escape,linux,kernel",
    message=(
        "Service adds dangerous capability. These capabilities can be used for container escape "
        "or privilege escalation."
    )
)
def dangerous_capabilities():
    """Capabilities like SYS_ADMIN or SYS_MODULE provide near-root powers."""
    return service_has(
        key="cap_add",
        contains_any=[
            "SYS_ADMIN",
            "NET_ADMIN",
            "SYS_PTRACE",
            "SYS_MODULE",
            "DAC_READ_SEARCH",
            "ALL",
        ],
    )