Configuration

Sockguard supports two configuration methods: YAML config files and environment variables. Every YAML configuration file is capped at 16 MiB before parsing.

YAML Config (recommended)Copy Anchor Link

listen:
  address: 127.0.0.1:2375
  insecure_allow_plain_tcp: false
  insecure_allow_unauthenticated_clients: false
  tls:
    cert_file: /run/secrets/sockguard/server-cert.pem
    key_file: /run/secrets/sockguard/server-key.pem
    client_ca_file: /run/secrets/sockguard/client-ca.pem
    dns_names:
      - portainer.internal
    uri_sans:
      - spiffe://sockguard.test/workload/portainer

server:
  shutdown_grace: "30s" # how long to wait for in-flight requests to finish on SIGTERM/SIGINT before force-closing every listener (Go duration); default "30s"; 0 closes immediately

insecure_allow_body_blind_writes: false
insecure_allow_read_exfiltration: false
insecure_accept_opaque_buildkit_tunnels: false  # ack required to allow POST /session, POST /grpc, or a moby.buildkit.v1.Control method path

upstream:
  socket: /var/run/docker.sock
  request_timeout: "60s" # total per-request deadline (Go duration); default "60s"; set "off" (or "") to disable
  flavor: auto # which engine is behind the socket: auto | docker | podman. "auto" probes GET /version once at startup
  hijack_inactivity_timeout: "10m" # idle deadline for attach/exec-start connections (Go duration); default "10m"

  # Remote TCP endpoints with mTLS — when set, socket is ignored.
  # List endpoints in priority order; first healthy wins (active/passive failover).
  # See Remote Upstreams & Failover for the full guide.
  # endpoints:
  #   - address: tcp://dockerd-a:2376
  #     tls: { ca_file: /certs/ca.pem, cert_file: /certs/cert.pem, key_file: /certs/key.pem }
  #   - address: tcp://dockerd-b:2376
  #     tls: { ca_file: /certs/ca.pem, cert_file: /certs/cert.pem, key_file: /certs/key.pem }
  # failover:
  #   health_interval: "5s"
  #   health_timeout: "2s"

log:
  level: info        # debug, info, warn, error
  format: json       # json, text
  output: stderr
  access_log: true

response:
  deny_verbosity: minimal  # minimal (default, production) or verbose (dev/rule-authoring)
  redact_container_env: true
  redact_mount_paths: true
  redact_network_topology: true
  redact_sensitive_data: true
  redact_host_topology: false           # redact GET /info container-runtime plumbing fields (Containerd/FirewallBackend/DiscoveredDevices/NRI); opt-in
  allow_attestation_statements: false   # deny a truthy statement query unless explicitly allowed

request_body:
  container_remove:
    allow_force: false             # deny force-killing a running container (default)
    allow_remove_volumes: false    # deny deleting attached anonymous volumes, libpod `depend`, pod removal and kube down (default)
    allow_remove_links: false      # deny Docker's legacy link-removal mode (default)
  container_create:
    allow_privileged: false      # deny HostConfig.Privileged=true (default)
    allow_host_network: false    # deny HostConfig.NetworkMode=host and ns:<path> (default)
    allow_host_pid: false        # deny HostConfig.PidMode=host and ns:<path> (default)
    allow_host_ipc: false        # deny HostConfig.IpcMode=host and ns:<path> (default)
    allowed_bind_mounts:          # host paths allowed as /src:/dst bind mounts
      - /srv/containers
      - /var/lib/app-data
    allow_all_devices: false      # allow every HostConfig.Devices PathOnHost
    allowed_devices:              # HostConfig.Devices PathOnHost allowlist
      - /dev/dri
    allow_device_requests: false  # deny HostConfig.DeviceRequests by default (escape hatch: skips all inspection)
    allowed_device_requests:      # structured DeviceRequests allowlist; each entry must match driver + capabilities + count
      - driver: nvidia
        allowed_capabilities:
          - ["gpu", "compute"]
        max_count: -1             # -1 = all devices; omit to allow any count
    allow_device_cgroup_rules: false
    allowed_device_cgroup_rules:  # structured cgroup-device allowlist (empty = deny all)
      - "c 1:3 rwm"   # /dev/null (char major 1, minor 3)
      - "c 226:* rwm" # /dev/dri/* GPU class (char major 226, any minor)
    allow_tmpfs_privileged_options: false # deny privilege-escalating tmpfs Mount.TmpfsOptions.Options (dev, suid, exec) by default
    require_no_new_privileges: false      # require HostConfig.SecurityOpt to include "no-new-privileges:true"
    require_non_root_user: false          # require Config.User to be a non-zero UID / non-root name
    require_readonly_rootfs: false        # require HostConfig.ReadonlyRootfs=true
    require_drop_all_capabilities: false  # require HostConfig.CapDrop to contain "ALL"
    allow_all_capabilities: false         # opt out of the CapAdd allowlist below (default-deny CapAdd entries)
    allowed_capabilities: []              # CapAdd allowlist (CAP_ prefix stripped, case-insensitive)
    require_memory_limit: false           # require HostConfig.Memory > 0
    require_cpu_limit: false              # require one of NanoCpus, CpuQuota, CpuPeriod, CpuShares > 0
    require_cpu_limit_hard: false         # require a genuine CPU-time cap (NanoCpus or CpuQuota); CpuShares alone does not satisfy this
    require_pids_limit: false             # require HostConfig.PidsLimit > 0
    allowed_seccomp_profiles: []          # if non-empty, seccomp= profile must be in this list
    deny_unconfined_seccomp: false        # standalone toggle: deny seccomp=unconfined when no allowlist is set
    allowed_apparmor_profiles: []         # if non-empty, apparmor= profile must be in this list
    deny_unconfined_apparmor: false       # standalone toggle: deny apparmor=unconfined when no allowlist is set
    deny_selinux_disable: false           # deny label=disable / label:disable SecurityOpt (turns off SELinux confinement)
    deny_selinux_label_override: false    # deny label=user:/role:/type:/level: SELinux context overrides
    deny_unconfined_system_paths: false   # deny systempaths=unconfined AND explicit empty MaskedPaths/ReadonlyPaths
    allow_host_userns: false              # deny HostConfig.UsernsMode=host and ns:<path> (default)
    allow_host_cgroupns: false            # deny HostConfig.CgroupnsMode=host and ns:<path> (default)
    restrict_namespace_sharing: false     # gate container:<ref> NetworkMode/PidMode/IpcMode/UTSMode/UsernsMode/CgroupnsMode joins, and refuse ns:<path> on them (default: pass through unchecked)
    allowed_namespace_sharing_containers: [] # only consulted when restrict_namespace_sharing=true; empty denies every container:<ref>
    deny_namespace_path_mode: false       # deny NetworkMode=ns:<path> even with allow_host_network on
    allow_sysctls: false                  # deny a non-empty HostConfig.Sysctls map (default)
    allowed_runtimes: []                  # allowlist for non-empty HostConfig.Runtime values (e.g. ["runsc", "kata-runtime"]); an empty/unset runtime selects the daemon default and is always permitted
    required_labels: []                   # Config.Labels keys that must be present with non-empty values
    image_trust:                          # cosign signature verification (default: off)
      mode: enforce                       # off | warn | enforce
      allowed_signing_keys:              # keyed: PEM-encoded ECDSA/RSA/ed25519 public keys
        - pem: |
            -----BEGIN PUBLIC KEY-----
            MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
            -----END PUBLIC KEY-----
      allowed_keyless:                   # keyless: Fulcio cert chains with issuer + SAN matching
        - issuer: "https://token.actions.githubusercontent.com"
          subject_pattern: "^https://github.com/my-org/my-repo/.github/workflows/release\\.yml@refs/heads/main$"
      require_rekor_inclusion: true       # additionally require a Rekor transparency log entry (default: true)
      verify_timeout: 10s                 # end-to-end image-trust deadline (default: 10s)
  libpod_container_create:                # POST /libpod/containers/create — Podman's native SpecGenerator body, path-exclusive from container_create above
    allow_privileged: false      # deny top-level privileged=true (default)
    allow_host_network: false    # deny netns.nsmode=host and path (default)
    allow_host_pid: false        # deny pidns.nsmode=host and path (default)
    allow_host_ipc: false        # deny ipcns.nsmode=host and path (default)
    allow_host_userns: false     # deny userns.nsmode=host and path (default)
    allowed_bind_mounts:          # host paths allowed as mounts[] bind sources
      - /srv/containers
    allow_all_devices: false      # allow every devices[] host path
    allowed_devices:              # devices[] host path allowlist (the part before the first ":")
      - /dev/dri
    restrict_namespace_sharing: false     # gate {"nsmode":"container","value":"<ref>"} joins across netns/pidns/ipcns/userns/utsns/cgroupns, and refuse nsmode=path on them (default: pass through unchecked)
    allowed_namespace_sharing_containers: [] # only consulted when restrict_namespace_sharing=true; empty denies every container:<ref> join
    allow_all_capabilities: false         # opt out of the cap_add allowlist below (default-deny cap_add entries)
    allowed_capabilities: []              # cap_add allowlist (CAP_ prefix stripped, case-insensitive)
    allowed_seccomp_profiles: []          # if non-empty, seccomp_profile_path must be in this list ("default" covers the empty/unset default)
    deny_unconfined_seccomp: false        # standalone toggle: deny seccomp_profile_path=unconfined when no allowlist is set
    allowed_apparmor_profiles: []         # if non-empty, apparmor_profile must be in this list
    deny_unconfined_apparmor: false       # standalone toggle: deny apparmor_profile=unconfined when no allowlist is set
    deny_selinux_disable: false           # deny selinux_opts containing "disable" (turns off SELinux confinement)
    require_non_root_user: false          # require the "user" field to be a non-zero UID / non-root name
    require_readonly_rootfs: false        # require read_only_filesystem=true
    require_memory_limit: false           # require resource_limits.memory.limit > 0
    require_cpu_limit: false              # require any of resource_limits.cpu.{quota,period,shares} > 0
    require_cpu_limit_hard: false         # require a genuine CPU-time cap (cpu.quota); cpu.shares alone does not satisfy this
    require_pids_limit: false             # require resource_limits.pids.limit > 0
    allow_sysctls: false                  # deny a non-empty sysctl map (default)
    allow_systemd_mode: false             # deny systemd values other than "false" (default) — SpecGenerator itself defaults systemd to "true" even when --systemd is never passed, so this is deliberately strict
    allow_custom_id_mappings: false       # deny non-default idmappings.uidMap/gidMap or --userns=auto (default)
    image_trust:                          # cosign signature verification on the "image" field (default: off); same semantics as container_create.image_trust above
      mode: off                           # off | warn | enforce
      require_rekor_inclusion: true
  exec:
    allow_privileged: false
    allow_root_user: false
    allowed_commands:
      - ["/usr/local/bin/pre-update", "--check"]
    allowed_env_vars:
      - CALLBACK_URL
    allowed_env_values:
      - CALLBACK_URL=http://127.0.0.1:3000/callback
  image_pull:
    allow_imports: false
    allow_all_registries: false
    allow_official: true
    allowed_registries:
      - ghcr.io
  build:
    allow_remote_context: false
    allow_host_network: false
    allow_run_instructions: false
  # Mediated BuildKit gRPC policy (issue #185) — gates POST /session and
  # POST /grpc once request_body.buildkit is configured, superseding the
  # deprecated insecure_accept_opaque_buildkit_tunnels wholesale ack (the two
  # are mutually exclusive). See the Compose/BuildKit Transport section of
  # the security model docs and the *-with-mediated-build.yaml presets.
  buildkit:
    control:
      allow_info: false          # Control/Info — response filtered to the buildkit version
      allow_list_workers: false  # Control/ListWorkers — response filtered to worker id/platforms/version
      allow_status: false        # Control/Status — admitted only for a ref this session itself Solve'd
      solve:
        allow: false                       # Control/Solve — the actual build request
        allowed_cache_import_types: []      # Cache.Imports[].Type allowlist; empty = deny
        allowed_cache_export_types: []      # Cache.Exports[].Type allowlist; empty = deny
        allowed_cache_registries: []        # registry host allowlist for "registry"-typed cache entries
        allowed_exporters: []               # Exporters[].Type allowlist (e.g. image, oci, local); empty = deny
        allowed_exporter_registries: []     # registry host allowlist for an "image" exporter with push=true
    session:
      health: false  # passthrough grpc.health.v1.Health/{Check,Watch}
      auth:
        allow: false             # moby.filesync.v1.Auth (Credentials/FetchToken/GetTokenAuthority/VerifyTokenAuthority)
        allowed_registries: []   # exact registry-host allowlist
        allowed_realms: []       # exact FetchToken realm allowlist
        allowed_scopes: []       # exact FetchToken scope allowlist
      secrets:
        allow: false        # moby.buildkit.secrets.v1.Secrets/GetSecret
        allowed_ids: []     # exact secret-ID allowlist
      ssh:
        allow: false        # moby.sshforward.v1.SSH/{CheckAgent,ForwardAgent}
        allowed_ids: []     # exact SSH agent-ID allowlist
      file_sync:
        allow: false           # moby.filesync.v1.FileSync/DiffCopy — required to sync the Dockerfile/context at all
        max_files: 0           # 0 = buildkitproxy.Limits default
        max_total_bytes: 0     # 0 = buildkitproxy.Limits default
        max_path_length: 0     # 0 = buildkitproxy.Limits default
        max_file_bytes: 0      # 0 = buildkitproxy.Limits default
      file_send:
        allow: false      # moby.filesync.v1.FileSend/DiffCopy (local/tar exporter output)
        max_bytes: 0      # 0 = buildkitproxy.Limits default
      upload:
        allow: false      # moby.upload.v1.Upload/Pull (remote/stdin build context)
        max_bytes: 0      # 0 = buildkitproxy.Limits default
  service:
    allow_host_network: false
    allowed_bind_mounts:
      - /srv/services
    allow_official: true
    allowed_registries:
      - ghcr.io
    require_non_root_user: false          # require a non-root ContainerSpec.User (default off)
    require_no_new_privileges: false      # require ContainerSpec.Privileges.NoNewPrivileges (default off)
    require_readonly_rootfs: false        # require ContainerSpec.ReadOnly=true (default off)
    require_drop_all_capabilities: false  # require ContainerSpec.CapabilityDrop=["ALL"] (default off)
    deny_unconfined_seccomp: false        # deny ContainerSpec.Privileges.Seccomp.Mode=="unconfined" (default off)
    deny_custom_seccomp_profiles: false   # deny Seccomp.Mode=="custom" or a bare Profile blob (default off)
    deny_unconfined_apparmor: false       # deny ContainerSpec.Privileges.AppArmor.Mode=="disabled" (default off)
    deny_selinux_disable: false           # deny ContainerSpec.Privileges.SELinuxContext.Disable=true (default off)
    deny_selinux_label_override: false    # deny SELinuxContext.{User,Role,Type,Level} overrides (default off)
  swarm:
    allow_force_new_cluster: false
    allow_external_ca: false

clients:
  allowed_cidrs:                  # coarse TCP admission; empty means all allowed
    - 172.18.0.0/16
  container_labels:
    enabled: true                 # resolve caller by source IP, enforce labels
    label_prefix: com.sockguard.allow.

ownership:
  owner: ci-job-123               # when set, stamps owner labels and denies cross-owner access on owned resources
  label_key: com.sockguard.owner
  allow_unowned_images: true
  allow_cross_owner_namespace_sharing: false # default false (secure): deny container:<ref> namespace joins into a different owner's container

health:
  enabled: true
  path: /health
  watchdog:
    enabled: false
    interval: 5s
  readiness:
    enabled: false       # opt-in /ready probe against the Docker API
    path: /ready         # must differ from health.path, metrics.path, admin.path
    interval: 10s        # positive duration
    timeout: 5s          # positive duration; per-probe deadline

metrics:
  enabled: false
  path: /metrics

admin:
  enabled: false
  path: /admin/validate
  policy_version_path: /admin/policy/version
  max_request_bytes: 524288

rules:
  - match: { method: GET, path: "/_ping" }
    action: allow
  - match: { method: HEAD, path: "/_ping" }
    action: allow

  - match: { method: GET, path: "/version" }
    action: allow

  - match: { method: GET, path: "/events" }
    action: allow

  - match: { method: GET, path: "/containers/json" }
    action: allow
  - match: { method: GET, path: "/containers/*/json" }
    action: allow

  - match: { method: "*", path: "/**" }
    action: deny
    reason: "no matching allow rule"

The default listener is loopback TCP 127.0.0.1:2375, which keeps the Docker API proxy off the network unless you explicitly choose otherwise.

• For the safest deployment, use listen.socket and share a unix socket.
• Sockguard hardens the unix socket to 0600 owner-only permissions by default. The published image and fresh named-volume directory use UID/GID 65532, so a non-root consumer must use UID 65532 too; root can also connect. For another consumer UID, run Sockguard under that matching UID with a pre-owned bind mount, or use authenticated TCP. listen.socket_mode accepts one other value: 0660, group-readable, which also requires listen.socket_gid (the group ID that should own the socket). listen.socket_uid optionally sets the socket's owning UID for either mode. Any mode other than 0600 or 0660 (with socket_gid set) is rejected at startup.
• For remote or container-network TCP, configure listen.tls so Sockguard requires mutual TLS. Sockguard's mTLS server minimum is TLS 1.3, so callers must support TLS 1.3. (The TLS 1.3 floor applies to the listener — the side your clients connect to. The upstream client side, where Sockguard dials a remote Docker daemon, floors at TLS 1.2 for daemon compatibility; see Remote Upstreams & Failover.)
• listen.tls.client_ca_file still defines the issuing trust root. To avoid trusting every cert that CA can mint, optionally narrow the accepted verified client leaf with the selectors described under mTLS Client Selectors below. Different selector fields are ANDed, while entries inside one field are ORed.
• Plaintext non-loopback TCP is rejected unless you set both listen.insecure_allow_plain_tcp: true and listen.insecure_allow_unauthenticated_clients: true. Both acknowledgments are required — one without the other is rejected — so a single fat-fingered flag cannot expose the listener. That mode is only for legacy compatibility on a private, trusted network.
• server.shutdown_grace bounds how long sockguard waits for in-flight requests to finish, on both the main listener(s) and the admin listener, after a shutdown signal (SIGTERM/SIGINT) is received, as a Go duration string (e.g. "30s"). A request still running when the grace period elapses has its listener force-closed out from under it rather than being waited on indefinitely. Defaults to "30s", unchanged from sockguard's behavior before this field existed. Unlike hijack_inactivity_timeout, 0 is a valid value — it means "close immediately" — so every value, including an empty string, must parse as a non-negative Go duration, or config load fails validation; only a negative duration or an unparseable value is rejected. The whole server.* block is immutable across hot reload — changing it requires a restart.
• health.watchdog.enabled starts an active upstream socket monitor that checks Docker every health.watchdog.interval, logs reachable/unreachable state transitions, and lets /health answer from the latest watchdog state instead of waiting for a scrape or probe to discover an outage. The watchdog dials the socket — a liveness signal that only proves the socket accepts connections.
• health.readiness.enabled adds an opt-in /ready endpoint (default path /ready) that goes one step further than the watchdog: instead of dialing the socket, it issues a real GET /containers/json?limit=1 against the upstream Docker API every health.readiness.interval (per-probe deadline health.readiness.timeout). It returns 200 only when the daemon actually answers, and 503 on any transport error or non-2xx — catching the failure mode where the socket stays connectable but request handling has wedged. Point a Kubernetes / load-balancer readiness check at /ready and a liveness check at /health. The path must start with / and must not collide with health.path, metrics.path, or admin.path; interval and timeout must be positive durations. The whole health.* block (readiness included) is immutable across hot reload — changing it requires a restart.
• upstream.endpoints is the ordered list of remote daemon addresses for TCP+mTLS or unix-socket connections. When non-empty, upstream.socket is ignored and sockguard uses the first healthy endpoint in the list (active/passive failover). endpoints and upstream.failover.* are reload-immutable — changing them requires a restart. See Remote Upstreams & Failover for the full guide including HA failover, mTLS setup, insecure opt-ins, and the DOCKER_* drop-in path.
• upstream.endpoints[].insecure_skip_tls_verify is deprecated in v2.1 and scheduled for removal in v3.0.0. Existing v2.1 configurations remain accepted and keep the same encrypted but unauthenticated wire behavior, with a startup warning naming tls.ca_file as the replacement. The Docker environment equivalent (a non-empty DOCKER_TLS while DOCKER_TLS_VERIFY is empty or unset) has the same schedule and warns with DOCKER_TLS_VERIFY=1 as its replacement. Configure the daemon's issuing CA or enable Docker TLS verification before v3.0.0.
• upstream.request_timeout bounds the total lifetime of a single proxied request as a Go duration string (e.g. "30s"); it defaults to "60s". ResponseHeaderTimeout only caps the wait for response headers; a daemon that sends headers and then hangs the body — or hangs a heavy read like GET /containers/json — can otherwise pin a request indefinitely. When active, an expired finite request aborts its upstream connection. If the deadline fires before the daemon sends response headers, the caller gets 504 Gateway Timeout (reason_code=upstream_request_timeout), distinct from the 502 an unreachable socket yields. If headers were already committed — the hung-body case above — HTTP does not allow replacing a status that has been sent, so the caller keeps the committed status (typically 200) and the response body is truncated mid-stream. The request is still aborted rather than pinned, which is the guarantee this setting provides; the 504 is not available once streaming has begun. Long-lived endpoints are exempt so the deadline never severs a legitimately long response: event streams, follow/stream logs and stats (including swarm service and task log following), truthy Podman top streams on both the native routes and Docker-compatible container route, image pull/build/push/load, image export, plugin create/pull/push/upgrade, container export, image get, container archive (docker cp, both directions), websocket attach, the BuildKit tunnel endpoints POST /session and POST /grpc, and the blocking GET /containers/{id}/wait; hijacked attach/exec-start connections already bypass it. Docker daemon top and Podman top without a truthy stream value remain finite and bounded. Set request_timeout: "off" to explicitly disable the deadline — the legacy empty string "" is also still accepted for backward compatibility. Prefer "off" when disabling via the env var: SOCKGUARD_UPSTREAM_REQUEST_TIMEOUT= (an explicitly empty value) is treated as unset and silently falls back to the 60s default, while off always works; an explicit request_timeout: "" in YAML does correctly disable it. Unlike health.*, this field is reload-mutable (upstream.socket, upstream.endpoints, and upstream.failover are immutable), so it takes effect on hot reload. Any other value must be a positive duration.
• upstream.flavor names the container engine behind the upstream: auto (the default), docker, or podman. It exists for one reason. Podman serves the Docker-compat GET /events and its own GET /libpod/events from a single handler, and that handler evaluates several values under one filter key disjunctively — Podman's own source comments it as "Filters under the same key are disjunctive while each key must match". dockerd ANDs them. Sockguard enforces a visibility policy on /events by injecting label filter values, so on Podman two or more response.visible_resource_labels selectors would become an OR and stream events the policy hides. Knowing the engine is what lets sockguard write a filter the daemon will read the way it meant it. See Podman.
  • auto issues one GET /version to the daemon at startup, before any listener binds, and classifies it from the engine component name the response carries (Podman Engine versus Engine). Nothing is probed afterwards; the result is fixed for the process.
  • An explicit docker or podman is taken as given. No GET /version flavor probe runs, so nothing in that response can move an operator's stated answer. Set it explicitly when the upstream is itself a proxy that does not serve /version. Startup still performs the mandatory upstream reachability dial before resolving the configured flavor; the explicit value removes the HTTP flavor-probe dependency, not the requirement that the upstream be reachable.
  • A probe that fails, times out (5 seconds), returns a non-200, or names an engine sockguard does not recognize fails startup with an error naming this field. There is deliberately no fallback: defaulting to docker would silently reopen the disclosure above on a Podman host, and defaulting to podman would silently start refusing /events on a Docker host that was working — and because the answer is cached for the life of the process, one transient failure at boot would carry the wrong answer until the next restart. The remedy is one config line. Either outcome is logged as upstream flavor resolved (with probed=true|false) or upstream flavor probe failed.
  • sockguard validate and every other config-only path never probe, so validation works with no daemon present.
  • Reload-immutable, alongside upstream.socket and upstream.endpoints: it describes the same daemon they address, and the resolved value is bound into the handler chain at startup.
  • The setting has to match the engine that is really behind the socket, because owner-isolation checks branch on it and a wrong value does not fail startup. For example, an image retag (POST /images/{name}/tag) under owner isolation checks one target name when the flavor is docker, and both {repo}:{tag} and localhost/{repo}:{tag} when it is podman. A Podman upstream configured as docker gets the one-name check and leaves the localhost/ name unchecked. Leave it on auto unless the upstream is a proxy that does not serve /version.
• upstream.hijack_inactivity_timeout bounds how long a hijacked connection (docker attach, docker exec start) may sit idle — no bytes read or written in either direction — before sockguard tears it down, as a Go duration string (e.g. "10m"). Activity in either direction resets the connection-wide timer, so continuous output keeps the input side usable and vice versa. It never caps the total length of an active session, only how long a forgotten one is left open. Hijacked connections are exempt from upstream.request_timeout entirely — this is their only deadline. Defaults to "10m", unchanged from sockguard's behavior before this field existed. Unlike request_timeout there is no "off" spelling: every value, including an empty string, must parse as a positive duration, or config load fails validation. An idle teardown logs at warn ("hijack: idle connection closed after inactivity timeout"), so it is visible at the default info log level instead of only at debug. Reload-mutable, same as request_timeout.
• Bounded request-body inspectors set a 30-second body-read deadline before decoding. The access-log and metrics wrappers both preserve the response-controller interface used to set and clear it, so enabling either layer does not turn a slow body into an unlimited request. Attach and exec-start use a separate 30-second handshake deadline for the client body and upstream request/response headers; it is cleared only after a valid 101 Switching Protocols response so the upgraded stream can remain long lived.
• metrics.enabled is opt-in and serves Prometheus text metrics at metrics.path on the same listener. The endpoint is local to Sockguard, is never forwarded to Docker, bypasses Docker API allow rules like /health, and remains behind listener security plus clients.allowed_cidrs. Every scrape also exports a sockguard_build_info{version,commit,build_date,go_version} gauge and a sockguard_start_time_seconds gauge for version panels and uptime alerts. Request labels are finite: known methods keep their uppercase name, all other methods use OTHER, known route families use bounded templates, and every unknown family uses unknown. When the active watchdog is enabled, metrics also include sockguard_upstream_socket_up and sockguard_upstream_watchdog_checks_total; when the readiness probe is enabled, they also include sockguard_upstream_api_up and sockguard_upstream_readiness_checks_total.
• admin.enabled is opt-in and exposes a single POST <admin.path> endpoint (default /admin/validate) that runs the same parse + validate + compile pipeline as the offline sockguard validate command against a YAML body in the request payload. Useful as a CI gate before promoting a candidate config to production. Running policy is never mutated. The endpoint rides the main listener, so the listener's CIDR allowlist, mTLS posture, and per-profile rate-limit / concurrency caps all apply. Bodies are hard-capped at admin.max_request_bytes (default 512 KiB) via http.MaxBytesReader and return 413 on overflow. Non-POST methods return 405 with Allow: POST. The response body is a structured JSON report: {"ok": bool, "rules": int, "profiles": int, "compat_active": bool, "errors": [...]?}. A failing candidate returns 422 with the validator's per-issue error list; a passing candidate returns 200. admin.path must start with / and must not collide with health.path or metrics.path when those endpoints are also enabled.
• reload.enabled is opt-in and turns on hot reload at runtime. Sockguard watches the candidate through fsnotify and also reloads on SIGHUP; reload.debounce collapses a burst of editor events. The pipeline parses, validates, compiles, and atomically swaps the handler chain on success. In-flight requests finish on the previous chain and new requests use the new one. Any load, validation, immutable-field, signature, or signed-compatibility failure preserves the active policy. Unsigned mode applies Tecnativa rule generation normally. Signed mode verifies with pinned bootstrap trust and rejects rule-generating compatibility variables with reject_compat. Listener, upstream endpoint, log, health, metrics, and admin fields require a restart; the signed candidate's policy_bundle.signature_path remains reloadable while bootstrap trust cannot be changed in process. Reload metrics use the finite result set ok|reject_load|reject_validation|reject_immutable|reject_signature|reject_compat. Enabling reload changes SIGHUP from process termination to reload.
• W3C trace/log correlation is always on and has no config knob. Sockguard preserves valid incoming traceparent trace IDs and sampled flags, replaces the parent span with a proxy-local span ID for the forwarded request, and generates fresh local context when the caller does not send valid trace context.
• DELETE /containers/** query parameters are inspected by default, including slash-bearing names used for Docker's legacy link-removal route. A bare container removal is allowed whenever its method/path rule allows it, while force, v (anonymous-volume removal), and link each require their own explicit opt-in under request_body.container_remove. Matching follows dockerd exactly: after trimming and case-folding, only an empty value, 0, no, false, or none is false; every other value is true. force, v and link are each read once under their exact lowercase spelling. While the matching gate is closed, a request that repeats one of them or spells it in another case (Force=1, force=0&force=1) is refused with a 403, because dockerd takes the first value of the exact key while Podman matches the key in any case and takes the last, so the two would disagree about whether the removal is forced. Percent-encoded keys and values are decoded before inspection, and malformed query encoding is rejected with 400 before it can reach the daemon. Podman's DELETE /libpod/containers/** is inspected the same way, except that it reads the volumes flag from volumes and never reads link. On that path allow_force gates force, and allow_remove_volumes gates volumes, v (documented for the route, ignored by Podman 5.8.6) and depend, because removing dependents can remove a whole pod and Podman deletes a removed pod's anonymous volumes whatever volumes says. timeout and ignore aren't gated there. Podman's DELETE /libpod/pods/{name} always deletes the anonymous volumes of the containers it removes, so every pod removal needs allow_remove_volumes, and force, which stops running containers first, needs allow_force too. Kube down (DELETE /libpod/play/kube and DELETE /libpod/kube/play) stops and force-removes every pod its YAML names whatever its query says, so every kube down needs both. See the Podman guide for what each route removes.
• POST /containers/create bodies are inspected by default. Sockguard blocks HostConfig.Privileged=true, HostConfig.NetworkMode=host, HostConfig.PidMode=host, HostConfig.IpcMode=host, HostConfig.UsernsMode=host, a non-empty HostConfig.Sysctls map (unless allow_sysctls: true), a non-empty HostConfig.Runtime value not present in allowed_runtimes (an empty/unset runtime selects the daemon default and is always permitted — only callers that explicitly request an alternate OCI runtime need an entry), bind mount sources outside request_body.container_create.allowed_bind_mounts (a Mounts entry of type volume counts as a bind source when its VolumeOptions.DriverConfig asks the local driver for one, e.g. {"type":"none","o":"bind","device":"/host/path"}, because that reaches the same host path, and so does the same entry handing the local driver a real filesystem type over a /dev node, e.g. {"type":"ext4","device":"/dev/sda1"}), HostConfig.Devices host paths outside request_body.container_create.allowed_devices, HostConfig.DeviceRequests (unless explicitly allowed via allow_device_requests or allowed_device_requests), HostConfig.DeviceCgroupRules (unless explicitly allowed via allow_device_cgroup_rules or allowed_device_cgroup_rules), and any HostConfig.CapAdd entry that isn't covered by allow_all_capabilities or allowed_capabilities. Named volumes still work without allowlist entries because they are not host bind mounts. allowed_device_requests is the structured opt-in for GPU passthrough and similar device request policy — each entry must specify a driver (exact match, case-insensitive), an allowed_capabilities list of capability sets (each request capability set must be a subset of at least one allowlisted set), and an optional max_count bound (-1 means all devices; request Count: -1 is only allowed when max_count is also -1); set allow_device_requests: true only when you need unrestricted device request access. allowed_device_cgroup_rules is the structured opt-in for cgroup device policy — it accepts Docker cgroup rule strings (<type> <major>:<minor> <perms>) with * wildcards for major or minor, and denies request wildcards unless the matching allowlist entry also uses a wildcard at that position; set allow_device_cgroup_rules: true only when you need unrestricted cgroup device access. Optional opt-in rails enforce no-new-privileges, non-root Config.User, HostConfig.ReadonlyRootfs=true, HostConfig.CapDrop=["ALL"], memory / CPU / PIDs limits, allowlisted seccomp and AppArmor profiles, and required Config.Labels keys — all default to off, so a configuration that does not set them keeps prior behavior except for the CapAdd allowlist and host-userns default-deny noted above. Three further opt-in rails cover the remaining SecurityOpt directives: deny_selinux_disable denies label=disable (and the legacy label:disable colon form), which turns off SELinux confinement; deny_selinux_label_override denies label=user:/role:/type:/level: SELinux context customization; and deny_unconfined_system_paths denies systempaths=unconfined and requests that set MaskedPaths or ReadonlyPaths to an explicit empty array — the Docker CLI converts --security-opt systempaths=unconfined into MaskedPaths: [] client-side, so a direct API caller can clear the masked-path protections without ever sending the SecurityOpt string; both vectors are blocked. All three default to off (pass-through), preserving existing behavior. image_trust adds cosign-backed signature verification: set mode: enforce to deny containers whose image lacks a valid signature from one of your allowed_signing_keys (PEM public keys) or allowed_keyless identities (Fulcio cert chain matched by issuer URL and SAN regex); set mode: warn to log failures and allow the request through instead. require_rekor_inclusion: true additionally requires a Rekor transparency log entry from the supplied bundle; verification is local and does not query Rekor. verify_timeout is the end-to-end image-trust deadline (default 10s), including registry discovery. Registry deadline and cancellation errors retain their cause instead of being reported as an unsigned image. Sockguard checks cancellation before beginning and after each synchronous Sigstore verification attempt, rejects late success, and stops later signatures or signer fallbacks. Sigstore-go's local verification API cannot preempt an individual crypto call. Verification resolves the image to its registry manifest digest, fetches the cosign signatures attached to it (the classic sha256-<digest>.sig tag and OCI 1.1 referrers are both checked), and only accepts a signature whose simple-signing payload binds to that exact digest. Signature references must resolve directly to image manifests; OCI indexes are rejected instead of recursively traversed. Registry-controlled input stops at 4 MiB for every registry GET response, including redirect destinations; 32 referrer descriptors; 16 distinct signature images; 32 layers per signature manifest; 16 aggregate verification candidates; 256 KiB of aggregate annotation keys and values; 1 MiB per simple-signing payload; and 16 MiB across all payload reads for one image. Exceeding any limit aborts discovery, even when a valid sibling signature exists. In enforce mode a limit breach denies the request; in warn mode it logs the failed discovery and forwards. The registry must be reachable from the proxy, and private registries require ambient credentials (a mounted Docker config.json). Keyless verification additionally fetches the Sigstore trust root through the same bounded, no-local-cache loader used by signed policy bundles. It loads initially and refreshes about every 24 hours, so ongoing egress is required. A failed initial load fails closed; a failed background refresh is logged and retains the last valid root. TUF downloads use their own 15-second HTTP bound rather than verify_timeout. The loader works with the read-only runtime filesystem. Keyed (PEM) verification makes no TUF request. When image trust is configured, an empty image reference is denied at Sockguard before any registry request; Docker would reject it too.
• Image-trust signature payload layers with alternate URLs are rejected before blob resolution can fan out. Legal media-type parameters on direct manifests are accepted after normalization.
• POST /containers/create's HostConfig.Mounts entries are validated further: a mount whose Type is not one of bind/volume/tmpfs/image is denied fail-closed (an unrecognized mount type has no reviewed policy, so it is refused rather than passed through); VolumeOptions.Subpath and ImageOptions.Subpath (Engine API 1.45+/1.55+) must be empty or a clean relative path that does not escape the mount root via ..; and TmpfsOptions.Options entries that re-enable exec, dev, or suid on a tmpfs mount are denied unless allow_tmpfs_privileged_options: true — Docker's tmpfs default is noexec,nodev,nosuid, and these options exist specifically to override that.
• POST /containers/create also denies five HostConfig fields unconditionally — no request_body setting opts back in: VolumesFrom, UTSMode=host, a non-empty CgroupParent, GroupAdd, and ExtraHosts. Each one opens a namespace-escape or privilege-escalation path, so it is blocked regardless of policy.
• allow_host_network/allow_host_pid/allow_host_ipc/allow_host_userns/allow_host_cgroupns gate two values on HostConfig.NetworkMode/PidMode/IpcMode/UsernsMode/CgroupnsMode: the literal "host", and ns:<path>. Podman's Docker-compatible create reads ns:<path> on every one of those fields and joins whatever namespace the path names on the daemon host, so PidMode: "ns:/proc/1/ns/pid" is the host PID namespace under another name. A path needs the same gate host needs. UTSMode: "ns:<path>" is always refused, like UTSMode: host. dockerd has no ns: mode: it rejects the value on PidMode, IpcMode, UTSMode and CgroupnsMode, treats it as not-host on UsernsMode, and reads it as a network name on NetworkMode. It lets a network be named anything, so a Docker network whose name starts with ns: can't be used as NetworkMode unless allow_host_network is on. A container:<id-or-name> value (join another container's namespace) passes through the host gates unchecked, and always has. Two opt-in filter-tier knobs cover that: restrict_namespace_sharing (+ allowed_namespace_sharing_containers) denies container:<ref> joins unless the target is on the allowlist (empty allowlist = deny all), across NetworkMode, PidMode, IpcMode, UTSMode, UsernsMode and CgroupnsMode (dockerd refuses a container: value on CgroupnsMode, and Podman's Docker-compatible create joins that container's cgroup namespace), and while it's on it refuses ns:<path> on those fields too, host gate or not, because a path can name another container's namespace and no list of names can vouch for it; deny_namespace_path_mode denies a NetworkMode value with an ns:<path> prefix even when allow_host_network is on. Both default off/empty (pass-through), so enabling them is a deliberate, independent choice from the allow_host_* flags. Separately, when ownership.owner is configured, sockguard resolves every container:<ref> target on POST /containers/create and denies the request if that container belongs to a different owner — see Owner Label Isolation below; that check runs regardless of whether the filter-tier knobs above are enabled.
• POST /libpod/containers/create — Podman's native SpecGenerator create endpoint — is inspected by a separate, path-exclusive body inspector under request_body.libpod_container_create, independent from container_create above; the two never read each other's body shape (Podman's libpod API is structurally distinct from the Docker-compat API, e.g. top-level privileged/netns/mounts/volumes/devices/cap_add/user/sysctl fields instead of nested HostConfig/Config objects). Sockguard blocks privileged=true, netns/pidns/ipcns/userns objects whose nsmode is host or path (a path joins whatever namespace it names, and /proc/1/ns/pid is the host's), bind-mounted mounts[] sources outside allowed_bind_mounts (named volumes[] entries are never bind-gated — they reference a volume by name, not a host path), devices[] host paths outside allowed_devices, and any cap_add entry not covered by allow_all_capabilities/allowed_capabilities. While one of those four gates is off, its namespace only takes the modes Podman has that keep the container out of the host's, so an nsmode sockguard doesn't know, or one spelled in another case, is refused too. The Podman page lists them. {"nsmode":"container","value":"<ref>"} namespace-sharing objects (netns/pidns/ipcns/userns/utsns/cgroupns) are gated by restrict_namespace_sharing/allowed_namespace_sharing_containers, mirroring container_create's equivalent knob, and while it's on nsmode: path is refused on those fields whatever the host gates say. Optional opt-in rails require a non-root user, read_only_filesystem=true, memory/CPU/PIDs limits from resource_limits, allowlisted seccomp_profile_path/apparmor_profile values, and deny selinux_opts containing disable — all default to off. image_trust reuses the same cosign verification as container_create.image_trust, applied to the image field. Two libpod-only rails have no Docker-compat analog: allow_systemd_mode (SpecGenerator's own default for the systemd field is "true" even when --systemd is never passed on the client, so sockguard denies anything but an explicit "false" unless this is set) and allow_custom_id_mappings (denies a non-default idmappings.uidMap/gidMap or --userns=auto, independent of allow_host_userns, which only covers userns.nsmode=host).
• POST /containers/*/exec and POST /exec/*/start are inspected when request_body.exec.allowed_commands is non-empty. Sockguard denies argv vectors that match no allowlist entry — each entry is an argv template whose tokens are sockguard globs (* matches a run of non-slash characters, ** matches any sequence), and a command matches when its token count equals an entry's and every token matches the glob at that position, so an exec carrying a variable argument can be allowlisted without enumerating every literal form. It also denies privileged exec unless allow_privileged: true, denies root-user exec unless allow_root_user: true, and re-checks POST /exec/*/start against Docker's stored exec metadata before execution. Docker exposes exec inspect and exec start as separate API calls, so this start-time check has an unavoidable time-of-check/time-of-use window; keep exec allowlists and client profile assignments narrow. request_body.exec is the single config surface for exec, covering both the Docker-compat paths above and Podman's libpod-native POST /libpod/containers/*/exec and POST /libpod/exec/*/start — the two API families expose exec create/start bodies with identical field names, so there is no separate libpod_exec block; the same allowed_commands/allow_privileged/allow_root_user/env-var settings apply to a request regardless of which path family carried it, and the libpod exec-start re-check queries GET /libpod/exec/{id}/json (the libpod equivalent of the Docker-compat exec-inspect call) instead of the compat endpoint.
• POST /images/create is inspected by default. Sockguard blocks imports unless request_body.image_pull.allow_imports: true and only allows Docker Hub official images unless you set allow_all_registries: true or list explicit allowed_registries. The two checks are independent: a request that carries both fromSrc and fromImage is a pull to dockerd and to Podman, so its fromImage has to pass the registry allowlist even when imports are allowed, and fromImage and fromSrc are each read once under their exact spelling. A request that repeats either or spells it in another case is refused with a 403 while the check that reads it is enabled, because dockerd takes the first value of the exact key while Podman matches the key case-insensitively and keeps the last. Podman's native POST /libpod/images/pull shares the same request_body.image_pull block, so one registry allowlist governs both surfaces and there is no separate libpod_image_pull group to configure and forget. libpod's query shape differs and is read on its own terms: the reference arrives in reference, not fromImage/tag, Podman matches that key case-insensitively and takes the last value of a repeated key, and it accepts a docker:// transport prefix. Sockguard reads reference once under its exact spelling, refuses a request that repeats it or spells it in another case, and strips the transport prefix before matching the registry host. A libpod pull carrying no usable reference is denied rather than forwarded unless allow_all_registries: true (Podman rejects such a request itself). Native POST /libpod/images/import shares image_pull.allow_imports: every request to that route is an import, whether Podman reads its archive from the body or fetches the caller-selected URL. Body-form imports are spooled through a 512 MiB limit and return 413 Payload Too Large on overflow; URL imports retain the coarse allow_imports gate without reading a request body. Native POST /libpod/images/load likewise shares request_body.image_load with Docker's archive-load endpoint, with format-aware checks for Docker manifest.json repo tags and OCI index.json ref-name annotations.
• GET /distribution/{name}/json makes the daemon reach out to whatever registry the reference names to fetch a manifest descriptor, so it is checked against the same request_body.image_pull.allowed_registries allowlist as a pull. It reads the registry host from the path reference (allow_official still exempts Docker Hub official images). This check is gated on an explicitly configured allowlist: with no allowed_registries set, or with allow_all_registries: true, the route is left exactly as open as before, so turning on the pull inspector's default allow_official posture never starts denying distribution queries you did not opt into restricting. Credentials in an X-Registry-Auth header are not inspected here because the registry the daemon contacts is the one named in the path.
• PUT /containers/*/archive and native Podman's PUT /libpod/containers/*/archive are inspected by default through the same request_body.container_archive block, and POST /containers/*/update and native Podman's POST /libpod/containers/*/update through the same request_body.container_update block. There is no separate libpod_container_archive or libpod_container_update group to configure and forget. Podman routes both archive spellings to one compat.Archive handler, so one inspector reads the shared tar body and case-insensitive query fields. It requires one nonempty, unambiguous path; refuses relative targets when allowed_paths is configured because Podman resolves them against the container WorkingDir; and refuses a nonempty or ambiguous rename, which Podman applies after reading the tar headers. Update needs its own shape handling: libpod's body is UpdateEntities, whose embedded OCI specs.LinuxResources flattens to root-level memory/cpu/pids/blockIO/devices/unified rather than Docker's PascalCase field names, and its restart policy arrives in the restartPolicy/restartRetries query string rather than the body, so allow_restart_policy is enforced against the folded query there. devices rides allow_all_devices; the OCI resource keys, the per-device IO throttle lists and r_limits ride allow_resource_updates; health_on_failure, no_healthcheck and health_startup_retries ride allow_restart_policy. allow_privileged and allow_capabilities are inert on the libpod path because UpdateEntities carries no such field. health_cmd, health_startup_cmd, Env/UnsetEnv, and health_log_destination are denied outright. Health timing and log-retention fields can create high-frequency checks or infinite daemon logs, so they require the global insecure_allow_body_blind_writes: true acknowledgment; the outright denials remain in force even when it is set. The post-ownership require_memory_limit, require_cpu_limit, require_cpu_limit_hard, and require_pids_limit effective-state ratchets cover both update paths, applying each daemon's own merge semantics while forwarding the exact submitted body.
• POST /build and native Podman's POST /libpod/build are inspected by default through the same request_body.build policy. Sockguard blocks primary remote contexts, Podman additionalbuildcontexts backed by a URL or image, networkmode=host, and Dockerfiles that contain RUN instructions unless you explicitly allow those behaviors under request_body.build.*. networkmode, remote, dockerfile and rusagelogfile are read once under their exact spelling, and a request that repeats one or spells it in another case is refused while the check that reads it is enabled. additionalbuildcontexts and rusage may repeat under their exact spelling and every value is validated. Because their value is always validated, another spelling (/build?Rusage=1) is refused whatever the gates are, while the parameters above are refused in another spelling only while the check that reads them is enabled. The volume controls are recognized in any spelling, so without the blind-write acknowledgment below a Volume is denied just like a volume. Malformed, empty, unsupported, or duplicate additional-context definitions fail closed. Podman's volume/volumes/transientRunMounts, localpath: additional contexts, multipart local contexts, and resource-usage host-file output (rusage/rusagelogfile) have no narrower policy and require the global insecure_allow_body_blind_writes acknowledgment. Direct and version-prefixed libpod paths use the same inspector and body-sensitive startup validation. While RUN is restricted, sockguard inspects every file the engine could build, because the two engines pick it differently and a POST /build doesn't say which one will answer. With no dockerfile parameter, POST /build inspects Dockerfile and the lowercase dockerfile dockerd falls back to, and POST /libpod/build inspects Containerfile and Dockerfile, since Podman builds the first of those it finds. A build is refused when any file it inspects carries RUN or can't be read, and when the context has none of them, so a libpod build whose unused Dockerfile has a RUN is refused even though Podman would build its Containerfile. A dockerfile value is read the way Podman reads it as well as the way dockerd does: a JSON array of paths, which is how podman-remote sends -f, inspects every file in it. A value Podman would read from somewhere other than the uploaded context is refused before the body is read, on both paths: an http:// or https:// URL, an absolute path (Podman reads it from the daemon host when the host has that file), a path that climbs out of the context with ../, and a name ending in .in, which Podman runs through the C preprocessor first. podman-remote sends an absolute path for a Containerfile outside the build context, for -f -, and for a relative -f run from a symlinked directory, so those builds are refused while RUN is restricted (see Podman). A body that is neither a tar nor gzip tar but opens with a gzip, bzip2, xz or zstd header is refused as uninspectable, since the engines decompress it and sockguard doesn't. The tar scan also refuses a context that could change an inspected file after the scan read it: a second entry at the same name, an entry written through a symlink onto it, or a non-directory replacing the context root or a directory on the way to it. An inspected file that is itself a symlink or hard link is refused rather than followed.
• POST /volumes/create is inspected by default. Sockguard blocks non-local volume drivers and driver options unless you explicitly allow them under request_body.volume.*.
• PUT /volumes/{name}, the Swarm cluster-volume (CSI) update, is inspected by default through the same request_body.volume block. Its body is a single Spec object, and every field in it is denied unless you opt in. Spec.Secrets has its own flag, allow_cluster_volume_secrets, because each entry names a Swarm secret the daemon then hands to the CSI plugin, so rewriting the list points the plugin at a secret the caller was never granted. allow_cluster_volume_updates covers the rest — Availability, Group, AccessMode, CapacityRange, AccessibilityRequirements — and deliberately does not admit Spec.Secrets. A body with no Spec, or an explicitly null one, is a no-op the daemon applies nothing from and is allowed. Owner isolation covers the same request: the update runs through the owned-resource check like every other named-resource write, so a client cannot update a volume it does not own regardless of these flags. Matching follows moby's route, PUT /volumes/{name:.*}, so slash-bearing names and the create/prune spellings (which have no PUT route of their own and resolve to the update handler) are inspected too.
• POST /secrets/create and POST /configs/create are inspected by default. Sockguard blocks custom and template drivers unless you explicitly allow them under request_body.secret.* and request_body.config.*. Driver is read as the {"Name", "Options"} object both engines take, and Driver.Options needs allow_custom_drivers the same as a driver name does. On this route every driver name is custom, file included, because dockerd resolves any name as a secrets plugin. A client that wants the built-in store, or Podman's file default, leaves Driver out, which is what the Docker CLI does.
• POST /services/create and POST /services/*/update are inspected by default. Sockguard blocks services that attach the host network, blocks bind mounts outside request_body.service.allowed_bind_mounts (a ContainerSpec mount of type volume counts as a bind source when its VolumeOptions.DriverConfig asks the local driver for one, e.g. {"type":"none","o":"bind","device":"/host/path"}, exactly as it does on POST /containers/create), constrains service images to Docker Hub official images unless you set request_body.service.allow_all_registries: true or list explicit request_body.service.allowed_registries, enforces the same allow_all_capabilities / allowed_capabilities capability allowlist and allow_sysctls gate as container-create, and applies image_trust cosign verification to the service's ContainerSpec image. Opt-in hardening rails mirror the container-create knobs onto the swarm ContainerSpec: require_non_root_user (denies a root or empty ContainerSpec.User), require_no_new_privileges (requires ContainerSpec.Privileges.NoNewPrivileges: true), require_readonly_rootfs (requires ContainerSpec.ReadOnly: true), and require_drop_all_capabilities (requires ContainerSpec.CapabilityDrop to include ALL) — all default off, so services that do not set them keep prior behavior. Confinement-mode rails complete the parity: deny_unconfined_seccomp denies ContainerSpec.Privileges.Seccomp.Mode: "unconfined", deny_custom_seccomp_profiles denies Mode: "custom" and the fail-closed case of a Seccomp object carrying a Profile blob with no Mode (an inline profile the proxy cannot vet), and deny_unconfined_apparmor denies ContainerSpec.Privileges.AppArmor.Mode: "disabled" (swarm's equivalent of unconfined AppArmor). Note that a custom seccomp profile can encode an allow-everything policy, so operators setting deny_unconfined_seccomp should usually set deny_custom_seccomp_profiles as well. SELinux rails complete the parity with container-create: deny_selinux_disable denies ContainerSpec.Privileges.SELinuxContext.Disable: true (the swarm equivalent of the container-create label=disable), and deny_selinux_label_override denies any SELinuxContext.{User,Role,Type,Level} context customization — both default off. (Swarm has no privileged mode, no per-service namespace sharing, and no runtime/device knobs, so those container-create rails have no service equivalent; swarm's seccomp/AppArmor settings are mode enums, so the named-profile allowlists from container-create do not apply.)
• POST /swarm/init, POST /swarm/join, and POST /swarm/update are inspected by default. Sockguard blocks ForceNewCluster, external CA configuration, non-allowlisted join targets, token rotations, manager unlock-key rotations, manager autolock, and signing-CA updates unless you explicitly allow them under request_body.swarm.*.
• POST /networks/create, POST /networks/*/connect, and POST /networks/*/disconnect are inspected by default. Sockguard blocks custom drivers, swarm/ingress/attachable/config-only controls, custom IPAM, driver options, and forced disconnects unless explicitly allowed under request_body.network.*. allow_endpoint_config additionally gates endpoint static IP, MAC address, links, driver options, and GwPriority (Engine API 1.45+, which network provides the default route when a container is attached to more than one) — enforced on both POST /networks/*/connect and POST /containers/create's NetworkingConfig.EndpointsConfig (see the container_create row below), since the two carry the identical attack surface. Endpoint Aliases are always allowed at both, independent of this flag. POST /networks/create also denies an explicit EnableIPv4: false (Engine API 1.48+; the field defaults to true when absent) unless allow_disable_ipv4: true — disabling IPv4 on a network is a deliberate topology choice, not a bypass, but it changes how the network's traffic can be observed and is gated the same as other network-shape controls.
• endpoint_config narrows allow_endpoint_config into independent per-field gates (#186). allow_endpoint_config: true (default false) remains the whole-object escape hatch and, when set, keeps admitting every EndpointSettings field exactly as before — the granular block below is not consulted at all in that case, and a config that sets both is rejected at load time (pick one). That rejection applies per group: request_body.network and request_body.libpod_network each carry the block and each are checked on their own, so writing both keys under either one fails startup with a message naming that group. When allow_endpoint_config is left at its default false, request_body.network.endpoint_config gates each field independently: allow_static_addressing (IPAMConfig.IPv4Address/IPv6Address and the deprecated top-level Gateway/IPAddress/IPPrefixLen/IPv6Gateway/GlobalIPv6Address/GlobalIPv6PrefixLen fields), allow_link_local_ips (IPAMConfig.LinkLocalIPs, independent of static addressing), allow_mac_pinning (MacAddress, shared with container_create's deprecated top-level MacAddress field), and allow_gw_priority (GwPriority) all default false. allow_aliases defaults true, reproducing allow_endpoint_config's long-standing unconditional-allow behavior for Aliases — set it to false explicitly to deny Aliases under the granular form (there is no equivalent opt-out under allow_endpoint_config: true). Links and DriverOpts have no granular field of their own: under the granular form they are always denied, fail-closed, regardless of the other settings — only allow_endpoint_config: true can admit them. Denial reasons name the specific offending field (e.g. "endpoint link-local IP addresses are not allowed"). Applies identically wherever allow_endpoint_config applies today — POST /networks/*/connect and POST /containers/create's NetworkingConfig.EndpointsConfig/legacy MacAddress field — and, under the libpod_network key, to Podman's native POST /libpod/networks/{name}/connect, whose top-level static_ips/static_mac/aliases/options fields map onto the same gates (allow_link_local_ips and allow_gw_priority have no libpod analog and never fire there). See the Podman guide for the libpod wire shape.
• POST /containers/*/update is inspected by default. Sockguard blocks restart-policy changes, resource controls, privileged mode, device changes, and capability/security-profile fields unless explicitly allowed under request_body.container_update.*.
• POST /containers/*/update, native POST /libpod/containers/*/update, and POST /services/create/POST /services/*/update additionally carry an opt-in resource-limit guard (request_body.container_update.require_memory_limit/require_cpu_limit/require_cpu_limit_hard/require_pids_limit, request_body.service.require_cpu_limit/require_cpu_limit_hard) that runs as its own policy layer after ownership, not inside the inspectors above. All six default false. For container update, the guard fetches current state from the daemon and applies the target endpoint's merge semantics before validating the effective post-update state: Docker-compatible updates treat omitted or zero scalar HostConfig fields as unchanged while pointer PidsLimit values including 0/-1 clear; native updates overlay lowercase memory.limit, cpu.{shares,quota,period}, and pids.limit, where an explicit zero clears the submitted native field. require_cpu_limit_hard accepts only a positive CPU quota/cap; shares alone do not satisfy it. Container-update require_* flags are enforced only when allow_resource_updates: true is also set; sockguard warns when a require_* flag is set while that gate stays off. For services, ServiceSpec is a full replacement rather than a merge, so an ordinary create/update is validated directly against the submitted body; POST /services/*/update?rollback=previous is instead validated against the daemon's stored PreviousSpec, with a 409 resource_limit_policy_state_changed if the inspected version no longer matches the caller's version query; an automatic-rollback-capable update additionally validates the current Spec. The original body is forwarded byte-for-byte after a successful check on both container API spellings.
• The resource-limit guard fails closed: a malformed request body (400 resource_limit_request_invalid), a failed or malformed daemon lookup (502 resource_limit_policy_lookup_failed), and a rollback version mismatch (409 resource_limit_policy_state_changed) are hard errors in every rollout mode, including warn/audit profiles — only a genuine policy violation (403 resource_limit_policy_denied) honors the profile's rollout mode. Denial messages are static and parameter-free (e.g. "container update denied: a memory limit is required") and never echo submitted values, container/service IDs, or daemon response content.
• Migration note (the "ratchet" edge): because the guard validates effective state, enabling a require_* flag against a container or service that already carries a legacy, non-compliant resource configuration blocks that resource's next guarded write — even one that doesn't touch resources at all — until a compliant patch supplies the missing limit. Roll a require_* flag out under warn or audit before switching it to enforce fleet-wide, and expect to remediate long-lived legacy containers/services with one compliant update before enabling it in enforce mode.
• PUT /containers/*/archive and native PUT /libpod/containers/*/archive are inspected by default. Sockguard blocks unsafe target paths, tar traversal, setuid/setgid entries, device nodes, and escaping symlinks/hardlinks unless explicitly allowed under request_body.container_archive.*.
• POST /images/load and native Podman's POST /libpod/images/load are inspected by default through the same policy. Docker archives are checked through manifest.json repo tags; OCI archives are checked through the byte-exact effective index.json name, with io.containerd.image.name taking precedence over org.opencontainers.image.ref.name exactly as it does in Podman. On the native route, bare names are normalized to localhost. SHA-256, SHA-384, and SHA-512 OCI graphs are supported. Tagged references must satisfy request_body.image_load.* even when allow_untagged is enabled, and every Docker manifest member is checked separately for an untagged image. Podman's permissive handling of advisory layout, index schema-version, and descriptor media-type metadata is mirrored. Mixed OCI and Docker archives require both reference sets to be inspectable and pass policy because Podman can reject OCI config or layer content after metadata inspection and then fall back to Docker. The exception is an OCI half no daemon selects a single image from. A multi-manifest index.json loads with the manifest.json repo tags and every index annotation name checked together, since Podman falls back to the Docker archive while a containerd-store dockerd imports each descriptor and records the name it carries; a missing or undecodable index.json carries no names, so those archives are judged on the manifest.json set alone. Either way the multi-image tarball docker save a:1 b:2 writes on Docker's containerd image store still loads. Canonically duplicate controls, malformed mixed-format controls, and outer archive symlink or hardlink entries fail closed. An archive with a top-level repositories file and no manifest.json is refused on POST /images/load unless allow_all_registries is set. Docker's classic image store, before Docker 29, loads that shape in its pre-1.10 layout and takes the image names from repositories whatever else the archive holds, and Sockguard does not read that file, so its names would skip the allowlist. Every docker save since 1.10 writes a manifest.json and is unaffected, and Podman never reads the file, so its native route is left alone.
• POST /swarm/unlock and POST /nodes/*/update are inspected by default. Swarm unlock is denied unless request_body.swarm.allow_unlock: true; node updates block role, availability, name, and unapproved label mutations unless allowed under request_body.node.*.
• POST /plugins/pull, POST /plugins/*/upgrade, POST /plugins/*/set, and POST /plugins/create are inspected by default. Sockguard constrains plugin registries, privileges, assignment prefixes, local tar config.json, host mounts, device exposure, and capabilities unless you explicitly allow them under request_body.plugin.*. POST /plugins/create is inspected as the raw tar upload Docker reads. A multipart/form-data upload is refused with request_form_body_refused before it gets that far, because Docker ignores the framing and untars the raw body.
• POST /images/create (pull), POST /libpod/images/pull, and POST /images/*/push all decode the base64 X-Registry-Auth header (standard, URL-safe, and unpadded variants all accepted) under the same 8 KiB bound as other inspectors; an oversized, non-base64, or non-JSON header is denied fail-closed. The image_pull.allowed_registries cross-check against the decoded serveraddress applies to the two pull paths only — POST /images/*/push is not inspected against it, so a client with push access can push to any registry its own credentials reach, gated only by insecure_allow_read_exfiltration. POST /build decodes the analogous X-Registry-Config multi-registry header the same bounded way but does not cross-check hosts against a build-time allowlist. Decoded credential fields (username/password/identity token) are never inspected, logged, or reflected in a deny reason.
• POST /libpod/pods/create (Podman's libpod-native pod creation) is inspected by default under request_body.libpod_pod_create. Sockguard denies a pod-level host network namespace (netns: {nsmode: "host"}), a network namespace joined by path (netns: {nsmode: "path"}) and a netns mode it doesn't know unless allow_host_network: true, denies a shared PID namespace ("pid" present in shared_namespaces) unless allow_shared_pid_namespace: true, and denies an infra image whose registry isn't in allowed_infra_image_registries — reusing the same registry-allowlist shape as image_pull.allowed_registries — whenever infra_image is set explicitly. When ownership.owner is configured, cross-owner pod membership is also denied on both sides of the relationship (#148): POST /libpod/pods/create joining another owner's host namespaces, and POST /libpod/containers/create targeting another owner's pod — reusing the same container:<ref> namespace-sharing checks POST /containers/create already applies. See Owner Label Isolation below for the full picture.
• POST /libpod/volumes/create, POST /libpod/networks/create, POST /libpod/networks/{name}/connect, POST /libpod/networks/{name}/disconnect, POST /libpod/networks/{name}/update, and POST /libpod/secrets/create (Podman's libpod-native equivalents of POST /volumes/create/POST /networks/create/POST /networks/*/connect/POST /networks/*/disconnect/POST /secrets/create) are inspected by default under request_body.libpod_volume, request_body.libpod_network, and request_body.libpod_secret respectively — these reuse the same volume/network/secret config fields documented above rather than introducing separate knobs, since the policy question (custom drivers? driver options? custom IPAM/subnets?) is identical even though libpod's wire shapes differ from the Docker-compat API: volume driver options live under a top-level Options key (not DriverOpts), network options are snake_case (ipam_options, subnets) with no swarm/ingress/attachable/config-only fields (libpod has no swarm mode), and secret creation reads driver from the query string rather than a JSON body, so the libpod secret inspector never touches r.Body at all. On that route driver=file, the containers.conf default podman-remote sends on every create, counts as the default driver, and any driveropts needs allow_custom_drivers too: the file driver's path option is the directory on the daemon host the secret data is written to, so choosing it is the same step as choosing a driver.
• POST /libpod/containers/*/restore, POST /libpod/play/kube (and its identically-handled POST /libpod/kube/play alias), POST /libpod/kube/apply, and POST/PUT /libpod/manifests/* have no request-body inspector. Admitting any of them requires insecure_allow_body_blind_writes: true exactly like uninspected exec. Treat play/kube with particular care: a single request can carry a multi-container (or multi-pod) Kubernetes manifest, so one allowed call can provision an arbitrary number of privileged containers from a document sockguard never parses, a materially larger blast radius than the single-container blind writes this flag otherwise covers. With ?import=1, restore creates a container from an opaque CRIU checkpoint archive whose spec never passes through either container-create inspector.
• Oversized bodies on bounded JSON/tar inspectors are rejected with 413 Payload Too Large before the inspector decodes them, so a misbehaving or hostile client cannot tie up the filter or the Docker daemon with oversized payloads. Under warn or audit the filter still reads no more than the limit, but the body is forwarded whole, so the daemon does see it.
• insecure_allow_body_blind_writes is now reserved for body-bearing controls Sockguard still cannot safely constrain, chiefly arbitrary exec without an allowed_commands allowlist, POST /swarm/join without request_body.swarm.allowed_join_remote_addrs, plugin setting writes without allowed assignment prefixes, Podman build host/local/multipart or resource-usage host-file controls, the daemon-host POST /libpod/local/build and POST /libpod/local/images/load routes, the SSH image transfer POST /libpod/images/scp/*, POST /libpod/containers/*/restore, and the uninspected libpod play/kube/kube/apply/manifest surface described above. For exec and Podman build, setting it changes request-time behavior, not just startup validation: an exec with no allowed_commands is admitted instead of denied, and Podman's host volume/local/multipart controls or rusage/rusagelogfile output is admitted. The remaining exec and build checks still apply. The native libpod image load and import routes are inspected and do not use this acknowledgment. For the daemon-host local routes, the SSH image transfer, container restore, and the play/kube/kube/apply/manifest writes there is no equivalent partial protection, so setting the flag admits the request with no body inspection at all. POST /libpod/images/scp/* needs both acknowledgments, one per direction: this one for the image it creates from an archive fetched off a caller-named SSH host, outside image_pull.allowed_registries, and insecure_allow_read_exfiltration for the copy it sends to one. Scope any allow rule for these paths as narrowly as possible.
• insecure_allow_read_exfiltration stays false by default and must be set explicitly before broad read rules can expose process-list, raw archive/export, or stream-style endpoints such as GET /containers/*/top, GET /containers/*/archive, GET /containers/*/export, GET /containers/*/logs, GET /containers/*/attach/ws, POST /containers/*/attach, GET /services/*/logs, GET /tasks/*/logs, GET /images/get, or GET /images/*/get — as well as their libpod-native counterparts GET /libpod/containers/*/top, GET /libpod/pods/*/top, GET /libpod/containers/*/archive, GET /libpod/containers/*/export, GET /libpod/containers/*/logs, POST /libpod/containers/*/attach, POST /libpod/containers/*/checkpoint, POST /libpod/containers/*/mount, GET /libpod/containers/showmounted, GET /libpod/images/export, GET /libpod/images/*/get, POST /libpod/images/*/push, POST /libpod/images/scp/* (an image copy to a caller-named SSH host, which also takes insecure_allow_body_blind_writes for the ingest half), POST /libpod/manifests/*/registry/*, POST /libpod/manifests/*/push, and GET /libpod/generate/kube (a read despite the "generate" name: Podman serves it as a GET that dumps an existing pod's or container's definition to YAML, which can include environment variables and other resource data). Two entries in that list are gated twice over: GET /images/get and GET /images/*/get are refused by owner isolation and by visibility policy regardless of this flag, so setting the acknowledgment does not make either reachable for a caller that either layer applies to (see Owner Label Isolation). The libpod-native GET /libpod/images/export and GET /libpod/images/*/get stay available under isolation, each behind its own owner and visibility preflight. Container and pod top are not redacted metadata reads: Docker-compatible caller-selected ps_args choose the daemon host's ps output, including process command lines and arguments, while both native Podman routes expose the same process-list class and support streaming responses. Version prefixes normalize away before rule matching and before the request-time gate alike. Image names in Podman's {name:.*}/push route may contain slashes; startup validation audits the whole dynamic route language, including constrained wildcard rules below any literal name prefix rather than only one representative path. Setting the acknowledgment does not make the risk go quiet: sockguard logs a warning naming the exfiltration endpoints the current rules actually admit, once per process, on the first filter-chain build (startup or hot-reload). Startup validation audits the authored rule literals against the catalog's whole route language, so an exact-name process-list allow and an ordered deny that shadows the representative path are both refused at load time without the acknowledgment. With the acknowledgment set, the warning names an evaluator-confirmed concrete path where it has one, and otherwise the catalog spelling as a conservative stand-in for an endpoint whose concrete path could not be confirmed. The top-level rules and each named client profile are reported separately, since the acknowledgment is global and a profile can be the only reason it has to be set. The fields name one reachable path per cataloged endpoint rather than every path the rules admit, so two empty lists mean no cataloged endpoint is reachable and the flag is buying nothing.
• insecure_accept_opaque_buildkit_tunnels stays false by default and must be set explicitly before startup validation will accept a rule that admits POST /session or POST /grpc — the opaque BuildKit session/gRPC tunnel Compose uses for docker compose build/up --build by default (Engine API 1.53 deprecated both, but current Buildx still uses them). (A rule naming a literal moby.buildkit.v1.Control method path is held to the same startup acknowledgment, but that path stays denied at runtime regardless — there is no hijack-capable h2c tunnel there for any mediator to terminate, so it is never actually reachable end-to-end.) Unlike POST /build's single inspectable JSON body, this transport carries secrets, SSH agent forwarding, and file sync as an ongoing binary conversation. This flag is now deprecated: request_body.buildkit (issue #185) mediates the same two endpoints with full per-message policy instead of admitting the tunnel wholesale, and setting the flag to true now logs a startup deprecation warning steering operators toward that surface; it will be removed in a future major release. The flag and request_body.buildkit are mutually exclusive — mediation supersedes the acknowledgment — so a config cannot set both, and the deprecation warning never fires alongside that validation error. Tecnativa's GRPC=1/SESSION=1 compat env vars still auto-set this flag with their own compat-specific deprecation warning so existing drop-in configs keep working, unless request_body.buildkit is configured at the top level or on any client profile: the two are mutually exclusive and compat runs before validation, so there it leaves the flag alone. With a top-level policy the compat /grpc and /session rules are then admitted under mediation and startup succeeds. With a policy on a client profile only, startup still refuses, because those compat rules are top-level and a profile's policy cannot mediate them; the refusal names the env vars that generated the rules and the top-level cure. See the Compose/BuildKit Transport section of the security model docs, Migration for the step-by-step move off this flag, and the drydock-with-build.yaml/portwing-with-build.yaml (classic DOCKER_BUILDKIT=0 builder) or drydock-with-mediated-build.yaml/portwing-with-mediated-build.yaml (mediated BuildKit) presets for fully-inspectable alternatives.
• request_body.buildkit (issue #185) configures per-gRPC-message mediation of POST /session/POST /grpc, gating the same two endpoints insecure_accept_opaque_buildkit_tunnels admits wholesale. control.solve.allow gates the Control/Solve RPC — the actual build request — with security.insecure always denied (no enabling knob), network.host requiring request_body.build.allow_host_network, a remote build context requiring request_body.build.allow_remote_context, and RUN-instruction inspection on the Dockerfile synced over session.file_sync requiring request_body.build.allow_run_instructions (the same three sibling request_body.build flags used for classic /build, reused verbatim rather than duplicated). control.solve's five allowlists (allowed_cache_import_types, allowed_cache_export_types, allowed_cache_registries, allowed_exporters, allowed_exporter_registries) gate cache import/export types, the registry host of a registry-typed cache entry, exporter types, and the destination registry of an image-typed exporter that sets push: true — each empty by default (deny). control.allow_info/allow_list_workers gate two worker/version metadata RPCs whose requests carry no policy-relevant field but whose responses are rewritten before relay — a worker record reaches the client with only its id, platforms and buildkit version, never the daemon host's labels, garbage-collection policy or CDI device inventory; control.allow_status gates Control/Status, admitted only for a ref this same client/profile actually Solved. Under session, auth (exact registry/realm/scope match for the moby.filesync.v1.Auth credential RPCs), secrets/ssh (exact-ID allowlists), file_sync/file_send (byte/file/path caps, file_sync.allow required to sync any Dockerfile or build context at all), and upload (a one-use token bound to an admitted Solve) each stay denied until their own allow/allowlist fields are set — see the Request Body Policy Reference table below for the full field list.
• response.allow_attestation_statements stays false by default. A truthy statement query returns the full in-toto attestation payload, which may have been generated by a different and less-trusted pipeline than the image itself, so it is denied unless explicitly allowed. Empty, 0, no, false, and none are false after trimming and case-folding; every other non-empty value is true. A request without a truthy statement value still lists available attestation manifests.
• response.redact_container_env, response.redact_mount_paths, response.redact_network_topology, and response.redact_sensitive_data default to true. Sockguard redacts workload env arrays across container/service/task/plugin reads, redacts host-path-bearing mount and device metadata across container/volume/task/service/plugin/system-usage reads, strips container/network/swarm/node topology from container/network/service/task/node/swarm/info/system-usage responses, and redacts higher-risk payload material such as config Spec.Data, service secret/config references, swarm join/unlock material, and swarm/node TLS metadata. Disable them only for trusted admin clients that truly need Docker's raw metadata.
• response.redact_host_topology defaults to false (opt-in): when enabled, Sockguard redacts container-runtime plumbing fields on GET /info — Containerd (socket path and namespace layout), FirewallBackend, DiscoveredDevices, and NRI — independent of Swarm mode (the redaction runs whether or not the daemon has a Swarm section in its response). Enable it when /info reads are exposed to a caller that should be able to confirm the daemon is reachable without learning host build details.

Multiple ListenersCopy Anchor Link

listeners: runs more than one main (Docker-API) listener from a single Sockguard process, each with its own bind target and its own admission scope, instead of requiring one process per audience.

listeners:
  - name: ci
    socket: /var/run/sockguard-ci.sock
    socket_mode: "0600"
    allowed_profiles: [ci]

  - name: ops
    socket: /var/run/sockguard-ops.sock
    socket_mode: "0600"
    allowed_profiles: [ops]

• listeners: and the legacy top-level listen: block are mutually exclusive — set one or the other, never both. Migrating means moving the listen: block's fields into a single-entry listeners: list.
• Each entry's name identifies the listener for logs, metrics, health, audit, and reload diagnostics. It must be unique within listeners, match the listener-name pattern, and cannot be admin (reserved for the admin listener).
• allowed_profiles scopes a listener to a subset of clients.profiles and is required and non-empty on every explicit entry. A client that resolves (via mTLS cert, unix peer UID, or source IP) to a profile outside a listener's allowed_profiles is denied with listener_profile_not_allowed, even if the base policy would otherwise allow it — the listener boundary is evaluated after normal profile resolution and never falls back to a weaker selector. The single-element list ["*"] preserves legacy behavior: every resolved profile, plus the unprofiled/default-policy path, is admitted.
• Each entry otherwise takes the same fields as the top-level listen: block (socket/address, socket_mode, tls, and so on) — see the listener bullets above for what each field does. Unlike the legacy listen: block, an explicit listeners[*] unix-socket entry does not default socket_mode; set it explicitly on every entry.
• admin.mount_on names the single listener that carries /admin/* traffic when in-band admin (admin.enabled: true with no dedicated admin.listen) runs alongside two or more effective listeners. It is required in that case — startup validation rejects a config with 2+ listeners, in-band admin enabled, and no admin.mount_on — and the admin endpoints are unreachable from any other listener. Configuring a dedicated admin.listen instead sidesteps mount_on entirely.

See configs/multi-listener.yaml for a complete working example, including a TCP+mTLS variant and disjoint per-listener client profiles.

Request Body Policy ReferenceCopy Anchor Link

All request-inspection policy fields under request_body default to the safest value unless noted. List fields default to empty lists.

mTLS Client SelectorsCopy Anchor Link

listen.tls.client_ca_file is the issuing trust root. To avoid trusting every leaf that CA can mint, narrow admission with one or more of the selector fields below. Different fields are ANDed; entries inside one field are ORed. An empty selector means "any verified client certificate issued by the configured CA is accepted".

listen:
  tls:
    client_ca_file: /run/secrets/sockguard/client-ca.pem
    common_names: ["portainer"]
    dns_names: ["portainer.internal"]
    ip_addresses: ["10.0.5.12"]
    uri_sans: ["spiffe://sockguard.test/workload/portainer"]
    public_key_sha256_pins:
      - 3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b

Malformed selectors (invalid IPs, malformed URIs, non-hex SPKI pins, pins that are not 32 bytes) are rejected at startup. The TLS handshake fails closed with no upstream connection when a CA-issued client certificate does not match the configured allowlist.

Per-Client ACLs And ProfilesCopy Anchor Link

clients.allowed_cidrs is a coarse TCP-client gate evaluated before the global rule set. Requests whose source IP is outside every configured CIDR are denied with 403 and never reach the health handler or the rule evaluator.

When clients.container_labels.enabled is true, Sockguard resolves bridge-network callers by source IP through the Docker API and looks for per-client allow labels on the calling container. Each clients.container_labels.label_prefix + <method> label is interpreted as a comma-separated Sockguard glob allowlist for that HTTP method:

com.sockguard.allow.get=/containers/json,/containers/*/json,/events
com.sockguard.allow.post=/containers/*/restart

Every comma-separated path in a label must start with /, exactly as a rule's match.path must. Label values are globs, not regexes, and the same dialect applies: * stops at a /, ** spans any number of segments, and /** is the catch-all. A path without the leading slash is refused rather than compiled, because the two families it splits into are both wrong and only one of them is obviously so. A rootless single-star path such as containers/* matches nothing at all, so the grant silently does nothing. A rootless path carrying ** does the opposite: ** alone spans every segment including the leading slash, so a label reading com.sockguard.allow.get=** would hand that client every GET the global policy allows instead of the narrow grant it looks like. Sockguard refuses the whole label set for that container, logs the offending label and path at error level, and answers 502 for its requests until the label is fixed. This is the same fail-closed path a label whose pattern cannot be compiled already takes; labels never pass through config validation, so it is the only place the shape is checked.

If you are migrating from wollomatic, set clients.container_labels.label_prefix: socket-proxy.allow. to keep the existing label namespace. Only the key prefix carries over: wollomatic label values are regexes, Sockguard reads them as globs, and every value has to be rewritten as a rooted glob starting with /. A leftover value like socket-proxy.allow.get=.* is not a glob Sockguard treats as a catch-all; it compiles to a literal match on the string .* and is refused for missing the leading slash, so requests from that container 502 until the label is rewritten. Callers that cannot be resolved by IP (for example, because they share the host network) fall through to the global rule set unchanged.

Security note — IP-based identity is soft isolation. IP-keyed admission (clients.allowed_cidrs, clients.container_labels.enabled, and profile match.source_cidrs) is adequate against configuration drift but not hard isolation against an attacker who can influence container-to-IP mapping on a shared bridge. For caller identity in the security boundary, prefer a unix socket with clients.unix_peer_profiles and uids/gids — SO_PEERCRED cannot be spoofed. See the Known Limitations section in the Security guide for the full caveat.

Security note — label grants assume sockguard is the only socket consumer. Allow labels are read from the calling container, and any workload that can reach the raw Docker socket directly can create a container carrying arbitrary label_prefix permission labels — self-granting access the policy never approved. Label ACLs are only trustworthy when every Docker API consumer goes through sockguard; the proxy cannot detect other socket consumers, so it logs a warning stating this invariant — once per process, on the first policy build (startup or hot-reload) that has clients.container_labels.enabled set.

Named client profiles turn one Sockguard instance into a shared control plane for multiple consumers. Root-level rules and request_body remain the fallback policy unless clients.default_profile points at a named profile:

clients:
  default_profile: readonly
  source_ip_profiles:
    - profile: watchtower
      cidrs:
        - 172.18.0.0/16
  client_certificate_profiles:
    - profile: portainer
      dns_names:
        - portainer.internal
      spiffe_ids:
        - spiffe://sockguard.test/workload/portainer
      public_key_sha256_pins:
        - 3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b
  unix_peer_profiles:
    - profile: readonly
      uids:
        - 501
  profiles:
    - name: readonly
      response:
        visible_resource_labels:
          - com.sockguard.visible=true
      rules:
        - match: { method: GET, path: "/containers/json" }
          action: allow
        - match: { method: GET, path: "/containers/*/json" }
          action: allow
        - match: { method: GET, path: "/events" }
          action: allow
        - match: { method: "*", path: "/**" }
          action: deny
    - name: watchtower
      response:
        visible_resource_labels:
          - com.sockguard.client=watchtower
      request_body:
        image_pull:
          allow_all_registries: true
        exec:
          allowed_commands:
            - ["/usr/local/bin/pre-update"]
      rules:
        - match: { method: GET, path: "/containers/json" }
          action: allow
        - match: { method: GET, path: "/containers/*/json" }
          action: allow
        - match: { method: POST, path: "/containers/*/exec" }
          action: allow
        - match: { method: POST, path: "/exec/*/start" }
          action: allow
        - match: { method: POST, path: "/images/create" }
          action: allow
        - match: { method: "*", path: "/**" }
          action: deny

• clients.source_ip_profiles matches the caller's remote IP against CIDRs in config order.
• clients.client_certificate_profiles matches the verified mTLS leaf certificate in config order. Each assignment can match common_names, dns_names, ip_addresses, uri_sans, spiffe_ids, and public_key_sha256_pins; different selector fields on the same assignment are ANDed, while entries inside one field are ORed.
• clients.unix_peer_profiles matches unix-socket callers by peer uids, gids, and pids. Different selector fields on the same assignment are ANDed, while entries inside one field are ORed.
• clients.default_profile is the fallback when no specific assignment matches.
• Each profile has its own rules and request_body policy, so one proxy can safely host a read-only dashboard, a container updater, and an admin UI at the same time.
• clients.client_certificate_profiles requires listen.tls mutual TLS.
• clients.unix_peer_profiles requires listen.socket.
• response.visible_resource_labels and clients.profiles[].response.visible_resource_labels enforce read-side visibility on labeled list/events/inspect paths plus selected service/task log paths. Selectors use Docker label syntax (key or key=value), are ANDed together, and profile selectors are additive with the root response selectors. When ownership.owner is configured, a selector may not use the ownership label key: both layers write the same label filter upstream, that key is proxy-enforced, and Docker's Swarm control-plane lists collapse repeated keys nondeterministically. Sockguard refuses to start on that combination. Podman's GET /events is stricter: because its handler ORs repeated label values, a request under both owner isolation and any visibility label selector is refused with 403 (reason_code=owner_visibility_podman_events_unscopeable) rather than forwarded with a wider scope.
• response.name_patterns and response.image_patterns add glob-based selector axes that operate alongside label selectors (AND semantics across all axes). Within each axis, at least one pattern must match (OR semantics). name_patterns is matched against Names[0] with the leading / stripped for containers, and against each RepoTags short name (the part after the last /) for images. image_patterns is matched against the container's Image field and against each full RepoTags reference for images. Patterns use the same glob dialect as rule path patterns (* = no slash, ** = any depth). Both knobs are supported at the per-profile level via clients.profiles[*].response.name_patterns / image_patterns. Pattern filtering buffers the upstream list response in memory under an 8 MiB cap; a larger response is rejected with a 502 rather than buffered unbounded. Example — expose only traefik containers and images from a private registry to a specific client profile:

The resolved caller identity also scopes mediated BuildKit state. Sockguard uses the verified client certificate on mTLS, kernel-supplied Unix peer credentials on a Unix listener, or the normalized remote host for unauthenticated TCP. It pairs that principal with the selected profile and BuildKit's session ID, so /grpc and /session connections from one build correlate even when TCP source ports differ, while simultaneous builds and unrelated Unix peers remain isolated. Session, ref, and upload identifiers have a 256-byte persistence bound, each control tunnel can admit at most 256 distinct BuildKit session IDs, and unconsumed upload grants expire after one hour.

For a single container or image read that combines label selectors with name or image patterns, Sockguard decodes both axes from one bounded upstream inspect response. It does not cache that result across requests. Visibility path matching treats write-only action words such as create and prune as valid resource names on GET and HEAD, so a resource cannot escape a hidden view because its name resembles a collection operation.

response:
  name_patterns:
    - "traefik"
clients:
  profiles:
    - name: registry-reader
      response:
        image_patterns:
          - "ghcr.io/myorg/**"

• Hidden resources disappear from GET /containers/json, /images/json, /networks, /volumes, /services, /tasks, /secrets, /configs, /nodes, and GET /events, while hidden inspect/log-style targets such as GET /services/*, GET /services/*/logs, GET /tasks/*, GET /tasks/*/logs, GET /secrets/*, GET /configs/*, GET /nodes/*, and GET /swarm return 404 instead of exposing a policy-specific deny body.

Rate Limiting and Concurrency CapsCopy Anchor Link

Each named profile can carry a limits block that enforces two independent mechanisms. Both are per-profile and disabled by default — omitting limits entirely (or omitting either sub-block) leaves that profile unthrottled.

Token-bucket rate limitingCopy Anchor Link

limits.rate enforces a maximum sustained request rate using a token bucket. The bucket refills continuously at tokens_per_second; its capacity is burst (peak burst size). When the bucket is empty a request is denied immediately with 429 Too Many Requests, a JSON body containing retry_after_seconds, and a Retry-After header.

• tokens_per_second (required): refill rate; must be > 0.
• burst (optional, default = tokens_per_second): bucket capacity. Must be >= tokens_per_second when explicitly set. Set to 0 to accept the default (no burst allowance beyond one token per interval). Upper bound: 65535 — the validator rejects larger values (the token bucket packs its state into a single atomic word with a 16-bit integer token field). Since burst >= tokens_per_second, the refill rate is implicitly bounded at 65535 tokens/second as well.

clients:
  profiles:
    - name: interactive-operator
      limits:
        rate:
          tokens_per_second: 8
          burst: 16          # allow short bursts; sustain at 8 req/s
      rules:
        - match: { method: GET, path: "/containers/**" }
          action: allow
        - match: { method: "*", path: "/**" }
          action: deny

    - name: ci-agent
      limits:
        rate:
          tokens_per_second: 100
          burst: 200         # CI workflows issue large list calls at startup
      rules:
        - match: { method: "*", path: "/**" }
          action: allow

Guidance on starting values:

Endpoint cost weightingCopy Anchor Link

By default every request withdraws one token from the bucket. limits.rate.endpoint_costs lets you assign a higher per-request cost to expensive Docker operations (build, image pull, exec) so they consume the budget proportionally to the work they actually do. The base rate stays comfortable for normal traffic while abusive POST /build floods are bounded.

Each entry has:

• path (required): glob matched against the normalized request path (Docker API version prefix is stripped). Same dialect as filter rules.
• methods (optional): list of HTTP methods to restrict the rule to. Case-insensitive. Empty matches all methods.
• cost (required): number of tokens withdrawn on match. Must be >= 1 and <= effective burst (a cost greater than burst can never be satisfied; startup fails closed if you misconfigure it).

Rules are evaluated in declaration order; first match wins. Unmatched requests fall back to the default cost of 1.

clients:
  profiles:
    - name: ci-agent
      limits:
        rate:
          tokens_per_second: 100
          burst: 200
          endpoint_costs:
            # Image pull is the single most expensive operation Docker exposes;
            # registry round-trips can pin upstream for minutes.
            - path: /images/create
              methods: [POST]
              cost: 20
            # Build context uploads + multi-stage assembly are similarly heavy.
            - path: /build
              methods: [POST]
              cost: 10
            # Exec creation is cheap but exec start spawns a process — tax it.
            - path: /containers/*/exec
              methods: [POST]
              cost: 5
      rules:
        - match: { method: "*", path: "/**" }
          action: allow

When a request is throttled because of its weighted cost, the structured audit record (sampled once per (client, reason) per second) carries the cost attribute alongside the existing rate-limit fields so operators can distinguish expensive-endpoint denials from base-rate denials.

Concurrency capsCopy Anchor Link

limits.concurrency.max_inflight caps the number of simultaneously in-flight requests per client. Once the cap is reached, additional requests are denied immediately with 429 Too Many Requests and a {"reason":"concurrency_cap"} body (no Retry-After, since release timing depends on concurrent traffic). The cap is decremented when the response completes or the connection is hijacked/closed — a request that is denied as rate-limited or by policy never counts against the cap.

clients:
  profiles:
    - name: streaming-client
      limits:
        concurrency:
          max_inflight: 16   # allow up to 16 simultaneous streaming connections
      rules:
        - match: { method: GET, path: "/events" }
          action: allow
        - match: { method: "*", path: "/**" }
          action: deny

Combining both mechanismsCopy Anchor Link

Rate limiting and concurrency caps can coexist on the same profile. The rate check runs first; a request that passes the rate check but hits the concurrency cap is denied with a concurrency reason (not a rate reason). A request denied by either mechanism is never counted as in-flight.

limits:
  rate:
    tokens_per_second: 50
    burst: 100
  concurrency:
    max_inflight: 32

Priority / fairness controlsCopy Anchor Link

A noisy low-priority client can saturate the per-profile concurrency cap on its own profile, but it should not be able to starve unrelated higher-priority profiles. The system-wide priority-aware fairness gate solves this.

Enable it by setting a global cap and tagging each profile with a priority tier:

clients:
  global_concurrency:
    max_inflight: 100        # system-wide ceiling, shared across all profiles
  profiles:
    - name: admin
      limits:
        priority: high       # admits up to 100% of the global cap
        concurrency:
          max_inflight: 50
    - name: ci
      limits:
        priority: normal     # admits up to 80% of the global cap (default)
        concurrency:
          max_inflight: 30
    - name: scraper
      limits:
        priority: low        # admits up to 50% of the global cap
        concurrency:
          max_inflight: 20

Each priority tier has a hardcoded share of the global cap:

When total in-flight crosses the floor for a request's priority, the request is denied with 429 Too Many Requests and {"reason":"priority_floor"}. Per-profile concurrency caps still apply on top — a low profile with max_inflight: 20 is bounded by both its own cap and the 50% global floor.

The gate is checked before the per-profile concurrency cap, so a low-priority request that hits the global floor never occupies a per-profile slot. Profiles configured without limits.priority or without any limits block default to normal, so a single client cannot evade the gate by skipping per-profile configuration. priority is only honored when clients.global_concurrency is set; otherwise it has no effect.

Reload resets limiter stateCopy Anchor Link

A hot reload rebuilds the rate-limit and concurrency machinery from scratch, even when the change had nothing to do with limits or global_concurrency. The replacement chain starts empty: every client's consumed token-bucket quota and every in-flight concurrency count begin at zero, so a bucket that was nearly drained comes back full and a profile sitting at its max_inflight cap opens back up to new requests.

Only the new chain starts empty. Requests already admitted when the swap lands keep running on the old chain and hold its concurrency slot until they finish, so the old and new caps overlap for the length of that drain window: a profile capped at max_inflight: 20 can have up to 20 pre-swap requests still draining while the new chain admits another 20. The same goes for clients.global_concurrency. The overlap clears on its own as the old requests return.

State is not carried across the old and new chains, and there is no way to preserve it, since a profile can change shape between reloads and there is no principled way to remap old counters onto a different limit. Sockguard logs a warning when a reload replaces a chain that actually held counters (a token bucket, a per-profile concurrency cap, or the global one), so this shows up as an expected reload side effect rather than an unexplained gap in your throttling data. A profile that sets only limits.priority has no counters to discard, so reloading it stays quiet.

ValidationCopy Anchor Link

Sockguard fails at startup with a clear error if any of these invariants are violated (fail-closed, never silent-disable):

• limits.rate.tokens_per_second must be > 0
• limits.rate.burst must be >= tokens_per_second or 0 (default)
• limits.rate.endpoint_costs[].path must be non-empty and compile as a valid glob
• limits.rate.endpoint_costs[].cost must be >= 1 and <= effective burst
• limits.rate.endpoint_costs[].methods[] must not contain empty strings
• limits.concurrency.max_inflight must be > 0
• clients.global_concurrency.max_inflight must be > 0 when set
• limits.priority must be one of low, normal, or high

ObservabilityCopy Anchor Link

When Prometheus metrics are enabled (metrics.enabled: true), two additional series appear:

• sockguard_throttle_requests_total{profile, reason_code, mode} — counter incremented on every denial by this subsystem. reason_code is one of rate_limit_exceeded, concurrency_cap, or priority_floor.
• sockguard_inflight_requests{profile} — gauge tracking the current in-flight count for profiles that have max_inflight configured.

Audit log events for throttle denials are sampled to the first occurrence of each (client, reason) pair per second to avoid log-volume blowout under load. The Prometheus counters are not sampled. priority_floor audit records additionally carry priority, current_global_inflight, priority_threshold, and global_max_inflight so operators can attribute denials to specific tiers.

Owner Label IsolationCopy Anchor Link

Setting ownership.owner turns on per-proxy resource ownership isolation. Sockguard will:

• Add ownership.label_key=ownership.owner to POST /containers/create, /networks/create, /volumes/create, /services/create, /services/*/update, /secrets/create, /configs/create, /nodes/*/update, and /swarm/update
• Stamp service writes at both Labels and TaskTemplate.ContainerSpec.Labels so downstream tasks inherit the same owner identity
• Add the same label to POST /build via the labels query parameter so build-produced images can carry the owner identity too. A Podman build cannot shed that stamp: a request whose unsetlabel names the owner key is refused (Podman's builder applies unsetlabel after the label it sets, so it would strip the stamp), and a Labels sent in any other letter case is collapsed into the single lowercase labels the proxy writes, so a case variant cannot race the stamp on a Podman upstream that reads the key case-insensitively
• Inject label=<owner> filters into list, prune, and events requests, including /services, /tasks, /secrets, /configs, and /nodes (node.label=<owner> there), so responses only reveal resources owned by this proxy instance
• Inspect target resources on individual GET, POST, PUT, and DELETE paths and deny cross-owner access to owned containers, images, networks, volumes, services, tasks, secrets, configs, nodes, and swarm state
• Resolve every container:<ref> namespace-sharing target on POST /containers/create (HostConfig.NetworkMode/PidMode/IpcMode/UTSMode/UsernsMode/CgroupnsMode) and deny the request if that container belongs to a different owner
• Authorize resources embedded in workload payloads before forwarding them: container Image, named HostConfig.Binds/volume mounts, custom NetworkMode, and every NetworkingConfig.EndpointsConfig network; plus service ContainerSpec.Image, named volume mounts, secrets, configs, and attached networks

Ownership authorization always performs a fresh Docker inspect. It deliberately does not reuse the short-lived visibility cache because Docker names and image tags are mutable: after a delete/recreate or retag, a cached positive label result could otherwise authorize a different resource. Repeated references inside one payload are deduplicated before inspection.

Docker reuses words such as create, prune, and json for collection actions, but those words are also legal resource names. Ownership path classification is method-aware and reserves a word only for the exact method and path that performs the collection action. A resource action such as POST /containers/create/start still treats create as the container identifier and applies the normal owner check.

Unlabeled nodes and swarm state are denied on reads once ownership is enabled. They can still be claimed through POST /nodes/*/update and POST /swarm/update, where Sockguard stamps the current owner label into the outgoing update body before forwarding it to Docker.

allow_unowned_images defaults to true so shared base images that Docker can inspect but that lack the ownership label can still be referenced by a container or service. A labeled image owned by somebody else is always denied, and an image reference that Docker cannot resolve is not treated as “unlabeled.” Set the option to false in tighter multi-tenant setups. The option also covers the reference an image retag creates: POST /images/{name}/tag and POST /libpod/images/{name}/tag are denied when repo and tag name a reference another owner's image holds, and a reference held by an unlabeled image can be repointed only while this option is true. The same holds for every other route that names an image: a commit's repo and tag, a build's t, an import, a load and a pull. With the option false, an owner cannot build, load or pull over a tag an unlabeled image currently holds, which includes refreshing an image it pulled earlier unless that image carries its owner label. Unlabeled or unresolved volumes, networks, secrets, and configs remain untrusted; create those resources through their owner-stamping endpoints before referencing them from a workload.

allow_cross_owner_namespace_sharing defaults to false. Joining another container's network/PID/IPC namespace via container:<id> shares that container's sockets, process visibility, and /dev/shm — a full cross-tenant compromise, strictly worse than the access ownership already gates on every other endpoint. As of v1.5, sockguard denies a container:<ref> target that belongs to a different owner by default whenever ownership.owner is set; same-owner refs still pass, but an unlabeled target is treated as untrusted and denied too — consistent with every other container-targeting ownership check — so only a same-owner join is allowed by default. This is a genuine behavior change for the narrow case of an ownership.owner deployment that was already relying on cross-owner container: sharing — set allow_cross_owner_namespace_sharing: true to restore the old unchecked behavior. This check is independent of the filter-tier restrict_namespace_sharing knob described above: it runs whenever ownership.owner is configured, regardless of whether restrict_namespace_sharing is enabled.

Owner isolation and visibility policy also cover the libpod (Podman-native) surface (#148). POST /libpod/containers/create, /pods/create, /networks/create, and /volumes/create get the owner label stamped into their labels field (libpod's own lowercase convention, except /libpod/volumes/create which serializes Labels capitalized — Podman's VolumeCreateOptions carries no JSON tag on that field); /libpod/secrets/create has no JSON body (the body is the raw secret payload), so the label is stamped into its labels query parameter instead, a JSON-encoded map, the same way a build's labels is. Pods have no Docker-compat equivalent, so they get a dedicated KindLibpodPod resource kind with its own list/inspect owner-filtering and visibility coverage; every other libpod list and inspect/action path (containers, networks, volumes, secrets) is owner-filtered and visibility-filtered too, so switching a client from Docker-compat to libpod-native paths is not a way around isolation. Cross-owner pod membership is denied on both sides of the relationship: POST /libpod/pods/create joining another owner's host namespaces, and POST /libpod/containers/create targeting another owner's pod (SpecGenerator.pod) — reusing the same container:<ref> namespace-sharing and embedded-resource-reference checks described above, extended to libpod's {"nsmode":"container","value":"<ref>"} namespace shape. Denial reasons for libpod-family requests are prefixed libpod , matching the convention the libpod body inspectors already use.

Admission MutationsCopy Anchor Link

mutations.rules[] declaratively injects fixed labels or remaps an image reference on a matched request body before the corresponding container_create/service body inspection above runs, image-trust verification, and owner-label stamping — so the mutated bytes get the exact same downstream policy scrutiny a client-authored body would. It is a fail-closed, deliberately narrow DSL: exactly two operations (inject_labels, remap_image), no JSON-patch, no arbitrary field paths, no templating.

Unlike request_body.* and rules, mutations is not part of clients.profiles — there is a single, global mutation authority applied identically regardless of which client profile matched the request. This is a deliberate v1 scope decision, not an oversight: per-profile mutation overrides introduce a merge-order question (which profile's rule wins when both match?) that the feature does not need to answer yet.

mutations:
  rules:
    - id: tag-managed-by
      mode: enforce                      # enforce | warn | audit
      surfaces: [container_create, service_create]
      inject_labels:
        labels:
          com.sockguard.managed-by: "sockguard"

    - id: pin-internal-registry
      mode: warn                         # observe would_apply before enforcing
      surfaces: [container_create, service_create, service_update]
      remap_image:
        match: prefix                    # exact | prefix
        from: "docker.io/"
        to: "registry.internal.example.com/"

    - id: pin-internal-registry-unqualified-alpine
      mode: warn
      surfaces: [container_create, service_create, service_update]
      remap_image:
        match: exact                     # unqualified refs need one exact rule each
        from: "alpine:3.21"
        to: "registry.internal.example.com/alpine:3.21"

remap_image matches the literal image string a client sent, byte for byte — it never expands Docker's own unqualified-reference conventions (no implicit docker.io/library/ prefix, no case folding). The pin-internal-registry rule above only catches requests that already spell out docker.io/...; a request for alpine:3.21 or nginx:1.27 does not start with that prefix and passes through unmodified. To also pin unqualified references, add one match: exact rule per expected bare image, as shown in the second rule above.

Exactly one of inject_labels/remap_image is required per rule — never both, never neither. A rule that unconditionally injects the ownership label key (when ownership.owner is configured) is rejected at config load, since that key must stay under sockguard's exclusive control. Two rules that could both match the same label key or overlapping image from pattern on the same surface are also rejected at config load — which rule would win is otherwise silently order-dependent.

The mutations block uses a stricter config decode than the rest of this schema: unknown keys and YAML type-coercion (e.g. an unquoted id: 0 silently becoming the string "0") are both load-time errors here, not silently accepted.

Rollout ModesCopy Anchor Link

Each named profile can set a mode field that controls how Sockguard applies denials from that profile's rules, request-body inspectors, ownership isolation, visibility checks, client-ACL label policy, and rate-limit / concurrency throttle gates:

warn and audit exist for staged rollouts: add a tighter rule to a profile in warn or audit mode, observe would_deny in dashboards and logs until you are confident the deny rate is correct, then flip to enforce.

A request a body inspector refuses, for what the body holds or for its size, is forwarded with every byte the client sent. Sockguard still reads no more of it than the inspector's byte limit, but under warn and audit that limit doesn't stop an oversized body reaching the daemon.

Pre-auth admission gates — clients.allowed_cidrs CIDR checks and identity-lookup failures — stay enforce regardless of the profile's mode. Unacknowledged Docker-compatible and native libpod process-list reads also stay enforce; warn and audit cannot replace the global insecure_allow_read_exfiltration: true acknowledgment. These gates are unsafe to relax through rollout mode.

clients:
  profiles:
    - name: ci-agent
      mode: warn          # observe would_deny before enforcing
      rules:
        - match: { method: GET, path: "/containers/**" }
          action: allow
        - match: { method: POST, path: "/containers/*/exec" }
          action: allow
        - match: { method: "*", path: "/**" }
          action: deny

Once the would-deny rate in dashboards matches expectations, set mode: enforce (or remove the field — enforce is the default).

The mode label on deny/throttle counters lets you compare blocked vs. would-have-been-blocked volume side by side:

sum by (mode) (rate(sockguard_http_denied_requests_total[5m]))

Policy Discovery WorkflowCopy Anchor Link

mode: audit has a second use beyond staging a tighter rule on an existing profile: bootstrapping a policy for a client you don't already have rules for. Point a deny-everything profile at the real client, run its normal traffic through it, and every profile denial comes back as a would_deny record carrying the exact method and normalized path — the answer to "what does this thing actually call" without reading its source or guessing from vendor docs. Pre-auth admission failures, including allowed-CIDR and identity lookup failures, remain enforced and are not converted to would_deny.

1. Prerequisites. Access and audit records both carry would_deny and normalized_path, but the dedicated audit log is off by default (log.audit.enabled defaults to false — see Logging And Audit). The discovery.yaml preset in app/configs/ turns it on for you: a discovery profile in mode: audit with a single deny-all rule, applied to every caller of a dedicated owner-only unix socket via clients.default_profile, with the audit stream on stdout (separate from the operational log, which stays on its stderr default) so it's trivial to capture on its own.

2. Start with the discovery preset.

sockguard serve --config app/configs/discovery.yaml

The preset binds /var/run/sockguard-discovery.sock with mode 0600 instead of relying on Sockguard's default TCP listener. Mount that dedicated socket only into the client being observed. If the client must use authenticated TCP or unix-peer identity instead, copy the production listener settings into a private discovery config and keep that listener equally isolated; do not put the discovery profile on a shared listener.

3. Exercise the client normally. Let it run through its actual startup and steady-state behavior: list, inspect, create, whatever it does on a normal day. mode: audit forwards requests denied by the resolved profile; pre-auth admission gates still enforce. The observed client therefore has unfiltered Docker API access through the dedicated discovery listener while the preset is active, so give that socket only to a client you already trust with the daemon. Every profile denial that was forwarded is logged as would_deny.

4. Harvest the events. Every audit event the client's traffic produced carries decision: "would_deny", plus the request's method and normalized_path. A denied POST /v1.51/containers/create looks like:

{"event_type":"http_request","timestamp":"2026-08-29T14:32:07.118453Z","request_id":"a1b2c3d4e5f67890","client_request_id":"","trace_id":"4bf92f3577b34da6a3ce929d0e0e4736","trace_parent_id":"00f067aa0ba902b7","trace_span_id":"7f1a3c9e2b6d4f80","trace_sampled":true,"method":"POST","raw_path":"/v1.51/containers/create","normalized_path":"/containers/create","decision":"would_deny","reason_code":"matched_deny_rule","reason":"discovery preset — logged only, not enforced","matched_rule":0,"selected_profile":"discovery","rollout_mode":"audit","status":201,"actor_remote_addr":"@","actor_source_ip":"","transport_listener":"unix","transport_scheme":"http","transport_protocol":"HTTP/1.1","listener_name":"discovery","ownership":{"enabled":false,"owner":"","label_key":""}}

trace_id, trace_span_id, trace_parent_id, and trace_sampled ride every audit event (and every access log line and upstream-error log — see Logging And Audit) with no omitempty, so a real event always carries all four; trace_sampled renders false rather than vanishing when the incoming request carried no sampled trace context.

status: 201 is the daemon's real response — the request was actually forwarded and actually succeeded; would_deny only describes what the profile would have done. Pull the distinct method/path pairs out of the stream with jq:

docker logs sockguard 2>/dev/null \
  | jq -r 'select(.decision == "would_deny") | "\(.method) \(.normalized_path)"' \
  | sort -u

A morning of traffic from, say, a Traefik-style consumer might come back as:

GET /_ping
GET /containers/4f8a1c2e9b7d/json
GET /containers/json
GET /events
GET /version
POST /containers/4f8a1c2e9b7d/start

5. Turn that into rules. normalized_path carries the real resource ID from the traffic that happened to run, not a wildcard — generalize per- resource segments (4f8a1c2e9b7d) to * by hand before writing the rule, the same way every other preset in app/configs/ does. The harvested output above becomes:

clients:
  default_profile: traefik-live
  profiles:
    - name: traefik-live
      rules:
        - match: { method: GET, path: "/_ping" }
          action: allow
        - match: { method: GET, path: "/version" }
          action: allow
        - match: { method: GET, path: "/events" }
          action: allow
        - match: { method: GET, path: "/containers/json" }
          action: allow
        - match: { method: GET, path: "/containers/*/json" }
          action: allow
        - match: { method: POST, path: "/containers/*/start" }
          action: allow
        - match: { method: "*", path: "/**" }
          action: deny

Note the new profile has no mode field — that's step 6, not this one. Leaving discovery.yaml's own deny-all rule in mode: audit while you edit is fine; nothing is enforced either way until you switch.

6. Switch off shadow mode and verify. Replace the discovery config with the rules you just wrote — mode: audit omitted (or set to enforce, which is the same thing) so denials are real again — restart sockguard, and run the client through the same paths one more time. Confirm two things: the client still works exactly as it did in step 3, with no new errors; and the audit log shows no decision: "deny" events for it (would_deny itself can't appear anymore — that decision only exists under warn/audit). If you see a real deny, you missed a rule; add it and repeat this step before calling the profile done.

Hot ReloadCopy Anchor Link

Sockguard can reload policy at runtime without dropping connections.

reload:
  enabled: true            # default false; opt-in
  debounce: 250ms          # collapse burst of fs events into one reload (default "250ms")
  poll_interval: ""        # "" = off; opt-in stat fallback for inotify-unreliable backends

When reload.enabled: true:

• fsnotify file watch — Sockguard watches the loaded config file via Linux inotify / macOS kqueue. A burst of editor-save events (vim's chmod + write + rename + create sequence, for example) is debounced by reload.debounce into a single reload.
• SIGHUP — sending SIGHUP triggers a reload. Without reload.enabled, SIGHUP terminates the process (Go's default); with reload on, SIGHUP never terminates. On Synology / DSM and other btrfs bind-mount backends, SIGHUP is the canonical reload trigger — inotify events on the host filesystem don't always propagate into the container, so the fsnotify watch may miss otherwise-valid edits.
• Stat-based poll fallback — set reload.poll_interval (typical 5s–15s) to have Sockguard periodically re-stat the config file and fire a reload when its size, modification time, or inode have moved. Use this on filesystems where fsnotify drops events (Synology btrfs bind-mounts, some FUSE backends, NFS). The poll is off by default because regular Linux inotify and macOS kqueue cover the common cases reliably.
• Atomic swap — on success, the running handler chain is replaced atomically. In-flight requests at the swap moment complete on the previous chain; new requests immediately route through the new one. No connections are dropped.
• Rollback on failure — if the new file is unreadable, the YAML is malformed, the validator rejects the config, or a signature check fails, the running policy is preserved untouched. The failure is logged with a structured result=reject_load|reject_validation|reject_immutable|reject_signature|reject_compat key that matches the metric label exactly, so SIEM grep against either surface produces the same set of events.

Immutable fieldsCopy Anchor Link

Some config fields are bound to long-lived sockets and goroutines that cannot be replaced from within a running process. A reload that would mutate any of these is refused — the running policy stays in place and the failure is logged with changed_fields=...:

• listen.* — listener address, TLS material, and socket path
• server.* — currently just shutdown_grace, read once at startup into the seam shutdownServers consults; a reload has no way to make a changed value take effect before the next shutdown
• upstream.socket — upstream Docker socket path
• upstream.endpoints and upstream.failover — remote endpoint list and health-probe loop parameters (bound to the long-lived Resolver at startup)
• upstream.flavor — which engine the upstream is (the auto probe runs once at startup and the resolved value is bound into the handler chain)
• log.* — log level, format, and output sink
• health.* — health endpoint path, watchdog, and readiness probe config
• metrics.* — metrics endpoint and path
• admin.* — admin config (including admin.listen.*)
• signed-policy trust material selected by --policy-bundle-trust-config is pinned outside the candidate and cannot be changed by hot reload

The signed candidate's policy_bundle.signature_path is reload-mutable so an operator can re-sign the same YAML without a restart. Any candidate copies of enabled, allowed_signing_keys, allowed_keyless, require_rekor_inclusion, or verify_timeout are ignored and replaced by the pinned bootstrap values.

Everything else — rules, clients.*, response.*, request_body.*, ownership.*, insecure_allow_*, and upstream.request_timeout / upstream.hijack_inactivity_timeout (of the upstream block, only those two fields are mutable; socket, endpoints, failover, and flavor are pinned) — is rebuilt and atomically applied on every successful reload.

Reload outcomesCopy Anchor Link

When metrics.enabled: true, two series track reload outcomes:

• sockguard_config_reload_total{result} — counter with labels ok, reject_load, reject_validation, reject_immutable, reject_signature, reject_compat.
• sockguard_config_reload_last_success_timestamp_seconds — gauge; omitted from scrape output until the first successful reload.

Admin ListenerCopy Anchor Link

The admin endpoints (POST /admin/validate and GET /admin/policy/version) can run on a separate listener, keeping admin traffic entirely off the main Docker-API data plane.

admin:
  enabled: true
  listen:
    socket: /var/run/sockguard-admin/admin.sock   # operator-only perms

Or loopback TCP:

admin:
  enabled: true
  listen:
    address: 127.0.0.1:2376
    tls:
      cert_file: /run/secrets/sockguard/admin-cert.pem
      key_file:  /run/secrets/sockguard/admin-key.pem
      client_ca_file: /run/secrets/sockguard/admin-ca.pem

When admin.listen is unset, admin endpoints are served on the main listener and inherit its CIDR allowlist, mTLS posture, and per-profile rate-limit / concurrency caps. When set, Docker-API traffic and admin traffic are fully isolated. See the Admin API page for the full endpoint reference and recommended posture.

The admin.* block including admin.listen.* is immutable across hot reload — restart is required to change the listener binding.

Security note — a wide-open admin listener is rejected at startup. A non-loopback plaintext admin.listen.address with no clients.allowed_cidrs would let any host that can reach the port submit candidate YAML and read policy metadata with no authentication and no IP backstop — unlike the main listener, whose unauthenticated requests still face the full policy filter chain, the admin surface is gated only by CIDRs. Validation therefore rejects that combination. Resolve it by setting clients.allowed_cidrs, configuring admin.listen.tls (mutual TLS), or — only on a private, trusted network — explicitly acknowledging the exposure with admin.listen.insecure_allow_wide_open: true.

Signed Policy BundlesCopy Anchor Link

Signed-policy mode has two files with separate jobs:

1. The bootstrap trust config defines whether signature verification is enabled, who may sign, whether Rekor inclusion is required, and the verification timeout. It is selected out of band with the required serve --policy-bundle-trust-config <path> flag.
2. The signed candidate contains the operational policy plus policy_bundle.signature_path, which points to the cosign bundle covering that candidate's exact bytes.

The candidate and bootstrap YAML files inherit the 16 MiB configuration cap. The referenced Sigstore bundle JSON is capped at 4 MiB. Startup and reload fail closed on any oversized file before parsing or verification. Only regular files are accepted; inputs are opened nonblocking and FIFOs, devices, directories, and other non-regular paths are rejected.

The bootstrap file reuses the existing policy_bundle schema:

policy_bundle:
  enabled: true
  allowed_signing_keys:
    - pem: |
        -----BEGIN PUBLIC KEY-----
        MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
        -----END PUBLIC KEY-----
  allowed_keyless:
    - issuer: "https://token.actions.githubusercontent.com"
      subject_pattern: "^https://github.com/my-org/my-repo/.github/workflows/release\\.yml@refs/heads/main$"
  require_rekor_inclusion: true
  verify_timeout: 10s

The signed policy carries the mutable bundle location, not its own trust decision:

policy_bundle:
  signature_path: /etc/sockguard/sockguard.yaml.bundle

rules:
  # ...the signed policy...

For the keyed entry above, sign the candidate on a trusted workstation with the matching private key, deploy only the candidate and bundle, and start Sockguard with the runtime paths. Never mount or deploy the private signing key with the proxy:

cosign sign-blob --key ./policy-signing.key --bundle ./sockguard.yaml.bundle ./sockguard.yaml
sockguard serve --config /etc/sockguard/sockguard.yaml --policy-bundle-trust-config /etc/sockguard/policy-bundle-trust.yaml

For the keyless entry, omit --key so cosign uses its OIDC identity:

cosign sign-blob --yes --bundle ./sockguard.yaml.bundle ./sockguard.yaml

For the GitHub Actions issuer and subject shown above, the signing job also needs permissions: id-token: write so cosign can obtain the OIDC identity. Keyless trust loads the public Sigstore root initially and refreshes it about every 24 hours through a process-wide memoized TUF client, so ongoing outbound access is required. It does not use a local TUF cache and bounds each TUF HTTP request to 15 seconds. An initial load failure aborts startup before a listener opens; a failed background refresh is logged and retains the last valid root. Read-only container filesystems need no cache volume. A keyed-only bootstrap does not load TUF material and needs no policy-bundle network access.

The Helm chart exposes the same separation without copying either external object into the chart-generated candidate ConfigMap. Configure policyBundleTrust and policyBundleSignature together, using either a Secret or ConfigMap reference for each. The signature object is mounted at /etc/sockguard-policy-bundle-signature/signature.json, so the candidate must use that exact policy_bundle.signature_path. The trust reference cannot name the chart-generated candidate ConfigMap or the same Secret/ConfigMap that holds the rotatable signature bundle. Kubernetes authorization applies to the whole object, not individual keys, so co-locating them would give signature rotators authority over trust. Rotate either external object by updating it and restarting the DaemonSet; bootstrap trust is process-immutable.

policyBundleTrust:
  secretRef:
    name: sockguard-policy-trust
    key: trust.yaml
policyBundleSignature:
  secretRef:
    name: sockguard-policy-signature
    key: signature.json

config: |
  listen:
    address: ":2375"
    insecure_allow_plain_tcp: true
    insecure_allow_unauthenticated_clients: true
  policy_bundle:
    signature_path: /etc/sockguard-policy-bundle-signature/signature.json
  # ...the rest of the signed policy...

Signed mode intentionally ignores every SOCKGUARD_* environment overlay. Keep listener and other operational settings in the signed config value, as the chart defaults do, so verification cannot silently replace them with built-in defaults.

The candidate and bootstrap trust config must resolve to different files. Sockguard rejects the same path, two symlinks to the same file, and hardlinks to the same inode. A candidate cannot authenticate itself: setting policy_bundle.enabled: true without --policy-bundle-trust-config is a startup error. Copies of bootstrap fields placed in the candidate are ignored and replaced with the pinned bootstrap values.

Verification runs before the operational logger is constructed, before any rule compiles, and before a listener opens. Early diagnostics use a fixed stderr bootstrap logger, so an unverified log.output path is never opened. A missing, malformed, or wrong-key bundle aborts startup with a wrapped policy bundle: error. On hot reload, a signature failure records reject_signature and leaves the running policy untouched.

Two verification paths are supported and can coexist:

• Keyed: PEM-encoded ECDSA, RSA, or ed25519 public keys under allowed_signing_keys. Verification uses the key's algorithm directly and needs no network round trip.
• Keyless (Fulcio + Rekor): allowed_keyless entries specify the exact OIDC issuer URL and a subject SAN regex. The signing certificate chain is verified against Fulcio. When require_rekor_inclusion: true, a Rekor transparency-log entry is also required. Startup loads the public Sigstore trust root through a memoized TUF client and fails closed if it cannot. verify_timeout supplies a cooperative deadline for local verification. Sockguard checks it before beginning and after each synchronous Sigstore verification attempt, rejects late success, and stops later signer fallbacks. Sigstore-go cannot preempt an individual crypto call. Rekor proof verification is local; TUF root downloads use the separate 15-second HTTP bound described below.

The verified signer fingerprint (keyed:<spki-fingerprint> or keyless:<issuer>:<san>) and the YAML's SHA-256 digest are stamped onto the policy-version snapshot returned by GET /admin/policy/version in the bundle_signer, bundle_digest, and bundle_source fields.

Signed mode rejects the presence of every rule-generating Tecnativa variable, even if its value is false. That includes section variables, POST, GRPC/SESSION, and granular ALLOW_* variables. Startup fails before rule compilation. If one appears after startup, the next reload records reject_compat and keeps the active policy. Convert compatibility grants to YAML rules before signing. Unsigned compatibility mode remains available.

The feature uses github.com/sigstore/sigstore-go, the same verification stack as container image trust (request_body.container_create.image_trust).

Logging And AuditCopy Anchor Link

Sockguard has two operator-facing logging streams:

• log.access_log (default true) controls the structured request log written through the normal logger output.
• log.audit.enabled (default false) enables a dedicated JSON audit stream with a stable schema: request ID, client request ID, trace ID, trace parent/span IDs, sampled flag, raw and normalized path, decision, reason_code, reason, matched rule, selected profile, flattened actor and transport identity fields, ownership context, and final HTTP status.

Access logs intentionally carry both path and normalized_path. path is the raw client URL path as received, including any Docker API version prefix, percent-encoded separators, or other client-controlled shape; keep it for forensic replay. normalized_path is the canonical path after Sockguard's policy normalization and is the field to use for SIEM grouping, alerting, rule dashboards, and allow/deny analysis. Audit events use the same split as raw_path and normalized_path.

Every request also carries trace correlation fields. If a caller sends a valid W3C traceparent, Sockguard preserves trace_id and trace_sampled, records the incoming parent as trace_parent_id, forwards a new proxy-local trace_span_id, and emits the same fields in access logs, audit events, and upstream reverse-proxy error logs. Invalid or absent trace context starts a fresh local trace and drops stale tracestate.

Audit logs use a separate sink from the access logger:

• log.audit.format: currently only json is accepted.
• log.audit.output: same sink options as the main logger (stderr, stdout, or file:/absolute/path).

Every audit event includes an ownership object with enabled, owner, and label_key. When ownership.owner is set, that owner identifier appears in every audit event, including requests that do not touch owned resources. Treat it as an operator-visible tenant or workload identifier, not a secret.

Audit events intentionally preserve both the proxy-generated canonical request_id and any caller-supplied client_request_id. Upstream proxy failures rewrite the audit reason_code to bounded terminal values such as upstream_socket_unreachable or upstream_response_rejected_by_policy so the final outcome is explicit even after a request was policy-allowed.

Rule MatchingCopy Anchor Link

Rules are evaluated in order. First match wins. If no rule matches, the request is denied.

Path PatternsCopy Anchor Link

Every pattern must start with /. Config validation rejects one that does not, naming the rule and the rooted spelling to write instead. The two ways a rootless pattern goes wrong are why it is the shape that is refused rather than the outcome. A rootless single-star pattern (containers/*, */json, a bare *) matches nothing: request paths are always rooted and * stops at a /, so the rule silently never fires. A rootless pattern carrying ** goes the other way, because ** spans any sequence including the leading slash: ** on its own is a catch-all, **/json matches /containers/json, and */** matches everything. Neither is what the spelling suggests. Use /**, not **, for a catch-all. The same rule and the same reasoning apply to container-label ACL paths, which are refused in clientacl because they never reach config validation.

A trailing slash is a real, empty final segment, not punctuation: a pattern matches only a path with exactly as many /-separated segments as the pattern spends, so /containers/* matches /containers/abc but not /containers/abc/, and /*/*/* matches /a/b/. On every Docker route this is invisible, because canonicalization strips the trailing slash before matching. The one place it shows is Podman's image-SCP route, where Sockguard matches the path gorilla/mux actually routes on, trailing slash included — see the Podman guide. ** is unaffected either way, since it already spans any number of segments including an empty one.

Before rule evaluation, Sockguard canonicalizes the request path: it strips any /vN.NN/ Docker API version prefix (Podman's own /vN.N.N[-suffix]/ semver prefixes included), percent-decodes the path (so %2F, %2E, and mixed-case escapes cannot smuggle separators past a literal allowlist), and resolves . / .. segments via path.Clean. A request for /v1.45/containers/%2e%2e/images/json therefore matches as /images/json. Because the path is decoded before matching, a rule whose match.path contains a literal % could never match a real request — such a pattern is rejected at config validation rather than silently never firing. The same applies to a match.path that itself begins with a version prefix (e.g. /v1.45/containers/json): it can never match the already-stripped request path, so config validation rejects it too, naming the offending rule and pattern — write the pattern without the /vN... prefix.

MethodsCopy Anchor Link

• Exact: GET, POST, PUT, DELETE, HEAD
• Wildcard: * matches any method

Environment VariablesCopy Anchor Link

Most YAML fields can be set via env var by prefixing with SOCKGUARD_ and replacing dots with underscores (metrics.enabled → SOCKGUARD_METRICS_ENABLED). List-typed values accept comma-separated entries. Precedence is CLI flags > env vars > YAML > built-in defaults.

The table below covers the most commonly used variables. Scalar and list-of-string fields at any nesting depth have an env-var equivalent even when they aren't enumerated here. Four things don't:

• The rules: block. It's populated after unmarshal rather than from a default, so there is no SOCKGUARD_RULES.
• clients.global_concurrency, and a profile's limits.rate and limits.concurrency. These are pointer blocks that stay absent unless the YAML declares them, and binding them would turn "absent" into "present but empty".
• listen.socket_uid and listen.socket_gid, and the admin listener's copies of them. They're pointer ints so that an omitted value is distinguishable from UID or GID 0, and the same absent-vs-empty rule applies. Set them in YAML.
• Anything inside a list entry, because the list itself is the leaf. That covers clients.profiles[], listeners[], upstream.endpoints[], mutations.rules[], request_body.container_create.allowed_device_requests[], and the image_trust.allowed_signing_keys / allowed_keyless lists.

Rows marked (YAML-only) below are those cases.

A SOCKGUARD_* variable that binds to no config key is read by nothing, and without a warning that silence looks exactly like a setting that took effect. sockguard serve and sockguard validate both check the environment at startup and log one line per unrecognized variable, naming it and, when the spelling is within a couple of characters of a real one, the variable you probably meant:

level=WARN msg="ignoring unrecognized SOCKGUARD_* environment variable: it maps to no configuration key, so the setting it looks like it carries is still at its config-file or default value" var=SOCKGUARD_LISTEN_SOCKT did_you_mean=SOCKGUARD_LISTEN_SOCKET

Only the name is logged, never the value, since a typo lands on a variable holding a credential as easily as on one holding a socket path. The warning is advisory and never fails startup: a variable nothing reads cannot make a config invalid.

Recognized means your configuration could actually bind it, which is the schema plus whatever your YAML declares, rather than a fixed list. So a variable for one of the four YAML-only cases above is reported unless the file declares the block it sits in, because declaring it is what puts the key where an env var can reach it. Tecnativa compatibility variables (CONTAINERS, POST, ALLOW_START, SOCKET_PATH, LOG_LEVEL) carry no SOCKGUARD_ prefix and are never flagged.

Listener and upstreamCopy Anchor Link

LoggingCopy Anchor Link

Health and observabilityCopy Anchor Link

Response controlsCopy Anchor Link

Insecure opt-insCopy Anchor Link

These flags loosen Sockguard's defaults. Do not enable them without an explicit operational reason and a plan to revisit.

Container-create body inspectionCopy Anchor Link

POST /containers/create is inspected by default; bodies that violate any of the gates below are denied before the request reaches Docker.

libpod_container_createCopy Anchor Link

Podman's native POST /libpod/containers/create counterpart to container_create above — see Request Body Policy Reference for the full field-by-field mapping to libpod's SpecGenerator body shape.

Other request-body inspectorsCopy Anchor Link

Comma-separated list values (ALLOWED_*, ALLOWED_BIND_MOUNTS, etc.) accept multiple entries via the env var; e.g. SOCKGUARD_REQUEST_BODY_IMAGE_PULL_ALLOWED_REGISTRIES=ghcr.io,quay.io.