Configuration

Sockguard supports two configuration methods: YAML config files and environment variables.

YAML Config (recommended)

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

insecure_allow_body_blind_writes: false
insecure_allow_read_exfiltration: false

upstream:
  socket: /var/run/docker.sock

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

request_body:
  container_create:
    allow_privileged: false      # deny HostConfig.Privileged=true (default)
    allow_host_network: false    # deny HostConfig.NetworkMode=host (default)
    allow_host_pid: false        # deny HostConfig.PidMode=host (default)
    allow_host_ipc: false        # deny HostConfig.IpcMode=host (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)
    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_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
    allow_host_userns: false              # deny HostConfig.UsernsMode=host (default)
    allow_sysctls: false                  # deny a non-empty HostConfig.Sysctls map (default)
    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: false      # additionally require a Rekor transparency log entry
      verify_timeout: 10s                 # per-verification network timeout (default: 10s)
  exec:
    allow_privileged: false
    allow_root_user: false
    allowed_commands:
      - ["/usr/local/bin/pre-update", "--check"]
  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
  service:
    allow_host_network: false
    allowed_bind_mounts:
      - /srv/services
    allow_official: true
    allowed_registries:
      - ghcr.io
  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

health:
  enabled: true
  path: /health
  watchdog:
    enabled: false
    interval: 5s

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: 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. listen.socket_mode must stay 0600; broader modes are 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.
• 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.
• 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.
• 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. When the active watchdog is enabled, metrics also include sockguard_upstream_socket_up and sockguard_upstream_watchdog_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 of policy at runtime. When on, sockguard watches the loaded config file via fsnotify (Linux inotify / macOS kqueue) and also reloads on SIGHUP. A burst of editor events (vim's chmod + write + rename + create save dance, for example) is debounced into a single reload by reload.debounce (default "250ms"). The reload pipeline parses the new file, applies the same Tecnativa-compat env expansion the startup path uses, runs the full validator + rule compiler, and atomically swaps the running handler chain on success. In-flight requests at the moment of the swap complete on the previous chain; new requests immediately route through the new one — no connections dropped. On any failure (file unreadable, YAML malformed, validator rejects, compile error) the running policy is preserved untouched. Hot reload is restricted to a reloadable subset of the config. The immutable fields — listen.*, upstream.socket, log.*, health.*, metrics.*, admin.*, and policy_bundle trust material — are bound at startup to long-lived sockets and goroutines that cannot be replaced from within a running process. A reload that would mutate any of those is refused (the running config stays in place, and the failure is logged with changed_fields=...); operators must restart sockguard to apply listener, upstream socket, log sink, health, metrics, or admin changes. Everything else — rules, clients.*, response.*, request_body.*, ownership.*, insecure_allow_* — is rebuilt and atomically applied on every successful reload. Reload outcomes are surfaced as Prometheus metrics: sockguard_config_reload_total{result="ok|reject_load|reject_validation|reject_immutable|reject_signature"} counter and a sockguard_config_reload_last_success_timestamp_seconds gauge (omitted from scrape output until the first successful reload). SIGHUP semantics change when hot reload is on: previously SIGHUP terminated sockguard (Go's default action for unhandled SIGHUP); with reload.enabled: true it triggers a reload and never terminates the process. Default is reload.enabled: false for backward compatibility — operators who script around SIGHUP-as-shutdown must update their tooling before enabling 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.
• 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), bind mount sources outside request_body.container_create.allowed_bind_mounts, 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. 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 for keyless bundles. verify_timeout controls the per-verification network timeout (default 10s); set to a low value in air-gapped environments to fail fast. Either mode is a no-op when the image reference is empty — Docker refuses to create a container without an image anyway.
• 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.
• 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.
• POST /images/create is inspected by default. Sockguard blocks fromSrc 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.
• POST /build is inspected by default. Sockguard blocks remote contexts, networkmode=host, and Dockerfiles that contain RUN instructions unless you explicitly allow those behaviors under request_body.build.*.
• 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.*.
• 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.*.
• 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, and 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.
• 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, endpoint static IP/MAC/alias/driver options, and forced disconnects unless explicitly allowed under request_body.network.*.
• 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.*.
• PUT /containers/*/archive is 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 is inspected by default. Sockguard denies image archive imports unless their manifest.json repo tags satisfy request_body.image_load.* registry policy, or untagged imports are explicitly allowed.
• 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 whether the upload arrives as a raw tar body or a multipart/form-data envelope — the multipart stream is parsed and the embedded config.json is extracted before policy evaluation.
• 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.
• insecure_allow_body_blind_writes is now reserved for the body-bearing writes Sockguard still cannot safely constrain, chiefly arbitrary exec without an allowed_commands allowlist, POST /swarm/join without request_body.swarm.allowed_join_remote_addrs, and plugin setting writes without allowed assignment prefixes.
• insecure_allow_read_exfiltration stays false by default and must be set explicitly before broad read rules can expose raw archive/export or stream-style endpoints such as 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.
• 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.

Request Body Policy Reference

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

mTLS Client Selectors

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 Profiles

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

If you are migrating from wollomatic, set clients.container_labels.label_prefix: socket-proxy.allow. to reuse existing labels. 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.

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.

• 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:

  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 Caps

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 limiting

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).

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 weighting

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 caps

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 mechanisms

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 controls

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.

Validation

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

Observability

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 Isolation

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
• 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

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 can still be pulled and inspected without relabeling. Set it to false in tighter multi-tenant setups.

Rollout Modes

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.

Pre-auth admission gates — clients.allowed_cidrs CIDR checks and identity-lookup failures — stay enforce regardless of the profile's mode. Those are unsafe to relax through rollout mode because they fire before a profile is even resolved.

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]))

Hot Reload

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 key that matches the metric label exactly, so SIEM grep against either surface produces the same set of events.

Immutable fields

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
• upstream.socket — upstream Docker socket path
• log.* — log level, format, and output sink
• health.* — health endpoint path and watchdog config
• metrics.* — metrics endpoint and path
• admin.* — admin config (including admin.listen.*)
• policy_bundle trust material — enabled, allowed_signing_keys, allowed_keyless, require_rekor_inclusion, verify_timeout

policy_bundle.signature_path is reload-mutable so an operator can re-sign the same YAML without a restart.

Everything else — rules, clients.*, response.*, request_body.*, ownership.*, insecure_allow_* — is rebuilt and atomically applied on every successful reload.

Reload outcomes

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.
• sockguard_config_reload_last_success_timestamp_seconds — gauge; omitted from scrape output until the first successful reload.

Admin Listener

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.

Signed Policy Bundles

Sockguard can refuse to start (or reload) unless the on-disk YAML config is covered by a valid cosign sigstore bundle. This is Layer 0 of the security model: even a valid YAML that passes all structural validators is rejected if it was not signed by a trusted key.

policy_bundle:
  enabled: true
  signature_path: /etc/sockguard/sockguard.yaml.bundle   # cosign bundle file
  allowed_signing_keys:                                   # keyed: PEM public keys
    - pem: |
        -----BEGIN PUBLIC KEY-----
        MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
        -----END PUBLIC KEY-----
  allowed_keyless:                                        # keyless: Fulcio + Rekor
    - 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       # require Rekor transparency log entry (keyless)
  verify_timeout: 10s                 # per-verification network timeout

Sign the config with cosign:

cosign sign-blob \
  --bundle /etc/sockguard/sockguard.yaml.bundle \
  /etc/sockguard/sockguard.yaml

Verification runs at startup before any rule compiles. A missing, malformed, or wrong-key bundle aborts the process with a wrapped policy bundle: error. On every hot reload, a signature failure rejects the reload with reason reject_signature in sockguard_config_reload_total and never touches the running policy.

The policy_bundle trust material (enabled, allowed_signing_keys, allowed_keyless, require_rekor_inclusion, verify_timeout) is reload-immutable so a SIGHUP cannot silently widen the set of accepted signers. Only signature_path is reload-mutable, so an operator can re-sign without a restart.

Two verification paths are supported and can coexist:

• Keyed — PEM-encoded ECDSA, RSA, or ed25519 public keys listed under allowed_signing_keys. Verification uses the key's algorithm directly; no network round-trip required.
• Keyless (Fulcio + Rekor) — allowed_keyless entries specify the exact OIDC issuer URL and a subject SAN regex. The signing cert's chain is verified against Fulcio; when require_rekor_inclusion: true a Rekor transparency-log entry is also required. The verify_timeout caps each network round-trip.

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.

policy_bundle.enabled: false is the default. The feature adds github.com/sigstore/sigstore-go as a dependency; it reuses the same stack already used for container image trust (request_body.container_create.image_trust).

Logging And Audit

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 Matching

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

Path Patterns

Before rule evaluation, Sockguard canonicalizes the request path: it strips any /vN.NN/ Docker API version prefix, 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.

Methods

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

Environment Variables

Every YAML field 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. See the YAML config section above for the full schema; every nested field has an env-var equivalent even when not enumerated here.

Listener and upstream

Logging

Health and observability

Response controls

Insecure opt-ins

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

Container-create body inspection

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

Other request-body inspectors

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.

Clients and ownership

response.deny_verbosity controls how much metadata Sockguard includes in its own 403 JSON deny responses:

• minimal (default): returns only the generic message. Never echoes the request method, path, or matched rule reason.
• verbose: returns message, method, path (with /secrets/* and /swarm/unlockkey paths redacted), and reason. Intended for rule authoring and dev work only — never a production default because it can leak request details to denied callers.

response.redact_container_env, response.redact_mount_paths, response.redact_network_topology, and response.redact_sensitive_data control response redaction for known protected Docker JSON response shapes. The redaction layer runs on successful body-bearing 2xx responses across request methods, not only GET 200, and fails closed with a generic 502 if a protected successful response cannot be parsed or sanitized safely. Non-success responses, HEAD responses, no-body statuses, non-protected paths, and streaming endpoints (logs, attach, events) pass through untouched. Streaming-style endpoints are gated by request-side rules and the read-side exfiltration guardrail instead. The toggles:

• redact_container_env (default true): replaces workload env arrays with empty arrays on container, service, task, and plugin reads.
• redact_mount_paths (default true): redacts mount and host-device source paths on container, volume, task, service, plugin, and /system/df reads.
• redact_network_topology (default true): redacts container, network, task, service, node, swarm, /info, and /system/df topology details such as network IDs, attached addresses, remote managers, and node reachability addresses.
• redact_sensitive_data (default true): redacts config payload material, service secret/config references, swarm join/unlock and CA material, and node/swarm TLS metadata.

Security note — the redaction toggles do not cover stream bodies. These toggles operate only on structured JSON Docker responses. Hijacked / streaming endpoints (GET /containers/*/logs, POST /containers/*/attach, GET /services/*/logs, GET /events, exec attach, image-build progress) are forwarded byte-for-byte; secrets a workload writes to its own stdout will reach an allowed caller. Gate those paths by rule, not by redaction. See the Known Limitations section in the Security guide for the full caveat.

Tecnativa Compatibility

For drop-in migration, sockguard accepts Tecnativa-style env vars:

CONTAINERS=1      # Allow /containers/** (GET/HEAD when POST=0)
IMAGES=1          # Allow /images/** (GET/HEAD when POST=0)
SERVICES=1        # Allow /services/** (GET/HEAD when POST=0)
SECRETS=0         # Deny /secrets/**
EVENTS=1          # Allow /events (default)
PING=1            # Allow /_ping (default)
VERSION=1         # Allow /version (default)
POST=0            # Read-only mode for section vars (default)
SOCKET_PATH=/var/run/docker.sock
LOG_LEVEL=warning

Compat env vars only generate rules when no explicit rules: are configured. If rules: is present in YAML, those rules take precedence even when they are identical to Sockguard's built-in defaults.

Broad compat reads such as CONTAINERS=1, IMAGES=1, or POST=0 with section-wide GET access require SOCKGUARD_INSECURE_ALLOW_READ_EXFILTRATION=true if you intentionally want raw archive/export or log/attach streaming parity. Safer YAML configs should allow only the list/inspect endpoints a client needs.

Granular Operations (LinuxServer compatible)

Granular container-write flags still work even when POST=0:

ALLOW_START=1      # Allow POST /containers/{id}/start
ALLOW_STOP=1       # Allow POST /containers/{id}/stop
ALLOW_RESTARTS=1   # Allow POST /containers/{id}/stop|restart|kill
ALLOW_CREATE=0     # Deny POST /containers/create (default)
ALLOW_EXEC=0       # Deny POST /containers/{id}/exec (default)

Sockguard also accepts the legacy singular ALLOW_RESTART=1 alias, but ALLOW_RESTARTS is the upstream Tecnativa/LinuxServer name.

Precedence

CLI flags > environment variables > config file > defaults