Skip to content
Drydock
ConfigurationUpdate Bouncer

Update Bouncer

Run security scanning, signature verification, and SBOM generation before applying container updates.

Update Bouncer runs security scanning in a safe-pull flow:

  1. Candidate image is scanned before update
  2. Update is blocked when CVEs match configured blocking severities
  3. Scan result is stored in container.security.scan and exposed in API/UI

Enablement

Security scanning is disabled by default. To enable it, set:

DD_SECURITY_SCANNER=grype

Grype is the recommended scanner. The image ships no scanner binaries, so with the default DD_SECURITY_BACKEND=auto Drydock runs Grype in an ephemeral, pinned worker container. That needs access to a Docker API (a socket mount or a socket proxy that allows creating and attaching containers). Leaving DD_SECURITY_SCANNER empty keeps scanning disabled, so a fresh install never starts downloading a vulnerability database.

services:
  drydock:
    image: codeswhat/drydock:1.9.0-rc.1
    environment:
      - DD_SECURITY_SCANNER=grype
      - DD_SECURITY_BLOCK_SEVERITY=CRITICAL,HIGH
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - drydock-store:/store

Variables

Env varRequiredDescriptionSupported valuesDefault value when missing
DD_SECURITY_SCANNER🔴Enable one scanner or run both and merge duplicate findings. grype is recommended.grype, trivy, bothdisabled
DD_SECURITY_BACKEND⚪Scanner execution backend. auto runs a provider as a local command when its binary resolves (DD_SECURITY_<PROVIDER>_COMMAND set, or the binary is on PATH) and in a pinned Docker worker otherwise. See Execution backends.auto, command, docker, remoteauto
DD_SECURITY_AVAILABILITY_POLICY⚪Behavior when a scan cannot complete, and whether a compose update keeps a container whose local tag moved between the pull and the recreate (Failure safety). block is fail-closed; warn records an audit warning and permits the update. Read whether or not a scanner is configured, so it still governs the moved-tag case on an install with no Update Bouncer. Detected blocking findings always block.block, warnblock
DD_SECURITY_DOCKER_SOCKET⚪Docker/Podman socket used to create scanner workers when no host is setabsolute socket path/var/run/docker.sock
DD_SECURITY_DOCKER_HOST⚪Docker API/socket-proxy host for scanner workershostname/IPempty
DD_SECURITY_DOCKER_PORT⚪Docker API/socket-proxy port1..655352375
DD_SECURITY_DOCKER_PROTOCOL⚪Docker API protocolhttp, httpshttp
DD_SECURITY_DOCKER_NETWORK⚪Docker network joined by workers. Set this to the Compose network when a remote worker must resolve a Trivy service name.Docker network namebridge
DD_SECURITY_DOCKER_CACHE_VOLUME⚪Named-volume prefix for daemon-side provider cachessafe Docker volume prefixdrydock-scanner-cache
DD_SECURITY_WORKER_MEMORY⚪Memory limit for each scanner worker container. Raise it if scans fail with Scanner worker was killed (exit 137), which usually means a large image ran Grype out of memory.integer with optional b, k, m or g suffix (512m, 1g, 1536m), at least 6m1g
DD_SECURITY_BLOCK_SEVERITY⚪Blocking severities (comma-separated). Set to NONE for advisory-only mode (scan without blocking updates)NONE, or any of UNKNOWN,LOW,MEDIUM,HIGH,CRITICALCRITICAL,HIGH
DD_SECURITY_GRYPE_COMMAND⚪Grype command. Setting it makes auto run Grype locally even if the path does not resolve.executable pathgrype
DD_SECURITY_GRYPE_TIMEOUT⚪Grype scan timeout in millisecondsinteger (>=1000)600000
DD_SECURITY_GRYPE_MAXOUTPUTBYTES⚪Largest Grype JSON output drydock will capture and parse, in bytes. Raise it if a scan fails with Grype output exceeded N bytes or Grype output is too large to parse; very large images produce tens of MB of JSON (nextcloud:30 is about 60 MB).integer (1048576 to 1073741824)134217728
DD_SECURITY_GRYPE_ARGS⚪Additional Grype arguments as a JSON string array. JSON/file output flags cannot be overridden.JSON string array[]
DD_SECURITY_GRYPE_WORKER_IMAGE⚪Digest-pinned Grype worker used when Grype runs in a workerOCI image pinned with @sha256:release-pinned Grype image
DD_SECURITY_TRIVY_SERVER⚪Trivy server URL (enables client/server mode). Use with DD_SECURITY_BACKEND=remote.URLempty
DD_SECURITY_TRIVY_COMMAND⚪Path to a Trivy binary you mounted into the container (must not contain shell metacharacters or .. path traversal). Without it, Trivy runs in the pinned worker.executable pathtrivy
DD_SECURITY_TRIVY_TIMEOUT⚪Trivy command timeout in millisecondsinteger (>=1000)600000
DD_SECURITY_TRIVY_MAXOUTPUTBYTES⚪Largest Trivy JSON or SBOM output drydock will capture and parse, in bytesinteger (1048576 to 1073741824)67108864
DD_SECURITY_TRIVY_ARGS⚪Additional Trivy arguments as a JSON string array. Output, timeout, server, scanner, and severity flags cannot be overridden.JSON string array[]
DD_SECURITY_TRIVY_IMAGE_SRC⚪Override Trivy's image source order. Any value Trivy accepts (e.g. remote, docker, or comma-separated remote,docker). When unset, Trivy uses its default source order (docker, containerd, podman, remote) and falls back to a registry pull when the local daemon is unreachable.stringempty (Trivy auto-detects)
DD_SECURITY_TRIVY_WORKER_IMAGE⚪Digest-pinned Trivy worker used when Trivy runs in a workerOCI image pinned with @sha256:release-pinned Trivy image
DD_SECURITY_FASTLANE⚪Opt every container without a dd.security.fastlane label in to the security fast lane, which lets an update that fixes critical or high vulnerabilities skip the maturity, snooze and maintenance window holds.true, falsefalse
DD_SECURITY_SCAN_CRON⚪Cron expression for scheduled background security scanscron expressiondisabled
DD_SECURITY_SCAN_JITTER⚪Random jitter delay (ms) before each scheduled scan startsinteger (>=0)60000
DD_SECURITY_SCAN_CONCURRENCY⚪Max digest scans processed in parallel during scheduled scansinteger (>=1)4
DD_SECURITY_SCAN_BATCH_TIMEOUT⚪Total scheduled scan batch timeout in milliseconds (0 disables timeout)integer (>=0)1800000
DD_SECURITY_SCAN_DIGEST_CACHE_MAX_ENTRIES⚪Max in-memory digest scan cache entries (LRU eviction -- least recently used entries are removed when the limit is reached)integer (>0)DD_DEFAULT_CACHE_MAX_ENTRIES (500)
DD_SECURITY_SCAN_NOTIFICATIONS⚪When true, findings from scheduled (cron) scans are routed through notification triggers. On-demand scans always notify.true / falsefalse
DD_SECURITY_GATE_MODE⚪Override the security gate globally. off disables the gate for all containers (audit row still fires); on enables normal gating. Per-container label dd.security.gate=off also works but only for that container.on, offon
DD_SECURITY_GATE_RELATIVE⚪When an absolute severity threshold would block a candidate, allow it only if every severity count is less than or equal to the current image's saved scan. Missing, failed, or stale current-image scans remain blocked.true / falsefalse
DD_SECURITY_PRUNE_ONBLOCK⚪Prune a pulled candidate image when Update Bouncer blocks ittrue / falsetrue

Execution backends

DD_SECURITY_BACKEND decides how each provider (Grype, Syft, Trivy, cosign) runs. The Drydock image ships none of them.

BackendBehavior
auto (default)Per provider: a local command when DD_SECURITY_<PROVIDER>_COMMAND is set or the binary is on PATH, otherwise an ephemeral Docker worker from a pinned image.
commandAlways a local command. Needs the binary mounted or installed in a custom image. Trivy is the exception: with no Trivy binary it falls back to the pinned worker (see Trivy).
dockerAlways an ephemeral Docker worker.
remoteTrivy only. Runs the Trivy client in a worker against DD_SECURITY_TRIVY_SERVER.

Each worker runs with a read-only root filesystem, all Linux capabilities dropped, no-new-privileges, bounded memory, PIDs and output, no Docker socket inside the worker, a provider-only cache mount, and an environment allowlist per provider (only that provider's registry credentials reach it). Worker images are pinned by digest and refreshed with each release.

services:
  drydock:
    image: codeswhat/drydock:1.9.0-rc.1
    environment:
      - DD_SECURITY_SCANNER=grype
      - DD_SECURITY_AVAILABILITY_POLICY=block
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - drydock-store:/store

The Security toolbar shows each worker's digest and version and offers touch-friendly Pull and Warm actions. The equivalent API is POST /api/v1/server/security/assets/{provider}/{operation}, with provider=trivy|grype|syft|cosign and operation=pull|warm. Pull/warm start, success, and failure are written to the audit log.

Trivy

The Trivy binary is no longer bundled in the image (removed in v1.8.0). DD_SECURITY_SCANNER=trivy and both still work, but Trivy now runs in the pinned Trivy worker. Drydock logs one warning per process and shows the change in the deprecation banner. Recommended: switch to DD_SECURITY_SCANNER=grype. See DEPRECATIONS.

If Docker refuses to create or attach the worker (for example a socket proxy that blocks container creation), the scan fails with an error naming the three setups that work:

  1. DD_SECURITY_SCANNER=grype (recommended).
  2. DD_SECURITY_BACKEND=remote with DD_SECURITY_TRIVY_SERVER.
  3. A Trivy binary you mount yourself, set with DD_SECURITY_TRIVY_COMMAND.

Mounted binary (local CLI)

Use this when you supply a trivy binary inside the Drydock container.

No Docker socket required for the scan itself. Trivy uses its default source order (docker, containerd, podman, remote) and falls back to a registry pull when no local daemon is available. If you know your setup is socket-less and want to skip the probe steps, set DD_SECURITY_TRIVY_IMAGE_SRC=remote.
services:
  drydock:
    image: codeswhat/drydock:1.9.0-rc.1
    environment:
      - DD_SECURITY_SCANNER=trivy
      - DD_SECURITY_BLOCK_SEVERITY=CRITICAL,HIGH
      - DD_SECURITY_TRIVY_COMMAND=/opt/trivy/trivy
      - DD_SECURITY_TRIVY_TIMEOUT=600000
    volumes:
      - ./trivy:/opt/trivy/trivy:ro

The 10-minute scan budget accommodates large-image analysis. In local mode, drydock separately performs a best-effort vulnerability-database warm-up before the first scan, so a successful database download does not consume this scan-command budget. If scans still regularly approach the limit, use DD_SECURITY_TRIVY_SERVER so a dedicated Trivy server owns and caches the vulnerability database.

If a scan fails with Trivy output is too large to parse or Trivy output exceeded N bytes, the image's report is bigger than the output limit. Raise DD_SECURITY_TRIVY_MAXOUTPUTBYTES to scan it.

Server mode (Trivy server)

Use this mode when running a separate Trivy server and letting drydock call it.

services:
  trivy:
    image: aquasec/trivy:latest
    command: server --listen 0.0.0.0:4954

  drydock:
    image: codeswhat/drydock:1.9.0-rc.1
    depends_on:
      - trivy
    environment:
      - DD_SECURITY_SCANNER=trivy
      - DD_SECURITY_BACKEND=remote
      - DD_SECURITY_BLOCK_SEVERITY=CRITICAL,HIGH
      - DD_SECURITY_TRIVY_SERVER=http://trivy:4954
      - DD_SECURITY_TRIVY_TIMEOUT=600000

remote is a Trivy-only backend. Drydock still needs a Trivy client to prepare and submit image data, so it runs that client in the pinned ephemeral Docker worker instead of pretending the server is a direct image-scan HTTP API. The worker requires access to the local Docker API, while the Trivy server owns the vulnerability database.

Advisory-Only Mode

Set DD_SECURITY_BLOCK_SEVERITY=NONE to run vulnerability scans without blocking updates. Scan results remain visible in the Security view and audit log, but no update is ever rejected due to detected vulnerabilities. This setting only covers findings. A scan that errors instead of finishing follows DD_SECURITY_AVAILABILITY_POLICY, which defaults to block; set it to warn to let the update proceed.

services:
  drydock:
    image: codeswhat/drydock:1.9.0-rc.1
    environment:
      - DD_SECURITY_SCANNER=grype
      - DD_SECURITY_BLOCK_SEVERITY=NONE

No-worse-than-current gate

Set DD_SECURITY_GATE_RELATIVE=true to keep the absolute severity threshold while allowing a candidate that does not worsen the running image's vulnerability profile. Drydock compares CRITICAL, HIGH, MEDIUM, LOW, and UNKNOWN independently; every candidate count must be less than or equal to the corresponding current-image count.

services:
  drydock:
    environment:
      - DD_SECURITY_SCANNER=grype
      - DD_SECURITY_BLOCK_SEVERITY=CRITICAL,HIGH
      - DD_SECURITY_GATE_RELATIVE=true

The comparison is fail-closed. A relative pass requires a successful saved scan for the exact running image. If that scan is missing, failed, belongs to an older image, or any severity count increased, the normal absolute block remains in force. The candidate scan is persisted with relativeGate.decision, relativeGate.reason, and the current summary used for a successful comparison, so API clients and audit logs can explain why the update passed.

Blocked candidate cleanup

When Update Bouncer blocks an update after pulling the candidate image, drydock prunes that candidate image by default (DD_SECURITY_PRUNE_ONBLOCK=true). This cleanup is best-effort: if Docker refuses the prune, the update still fails with the original security-block reason and the prune failure is logged as a warning for operators to review.

Signature Verification (cosign)

When enabled, candidate images are verified with cosign before the update proceeds. Updates are blocked if signatures are missing, invalid, or verification fails.

Env varRequiredDescriptionSupported valuesDefault value when missing
DD_SECURITY_VERIFY_SIGNATURES⚪Enable signature verification gatetrue / falsefalse
DD_SECURITY_COSIGN_KEY⚪Path to cosign public key filefile pathempty (keyless / Sigstore)
DD_SECURITY_COSIGN_COMMAND⚪Cosign command path. Setting it makes auto run cosign locally even if the path does not resolve.executable pathcosign
DD_SECURITY_COSIGN_WORKER_IMAGE⚪Digest-pinned cosign worker used when cosign runs in a workerOCI image pinned with @sha256:release-pinned cosign image
DD_SECURITY_COSIGN_TIMEOUT⚪Cosign command timeout in millisecondsinteger (>=1000)60000
DD_SECURITY_COSIGN_IDENTITY⚪Certificate identity for keyless verificationstringempty
DD_SECURITY_COSIGN_ISSUER⚪OIDC issuer for keyless verificationstringempty
The image no longer bundles cosign. With the default auto backend, cosign runs in a pinned worker container with the same hardening as the scanner workers (read-only root filesystem, all capabilities dropped, no Docker socket, environment allowlist). The target image's registry credentials are passed to the worker the same way they are for Grype. A DD_SECURITY_COSIGN_KEY file is read by Drydock and handed to the worker by value, so it does not need to be mounted into the worker. Set DD_SECURITY_COSIGN_COMMAND to keep using a binary you mount yourself.
When DD_SECURITY_COSIGN_KEY is empty, cosign runs in keyless mode using Sigstore's public transparency log. Set DD_SECURITY_COSIGN_IDENTITY and DD_SECURITY_COSIGN_ISSUER to constrain keyless verification to a specific signer.
The examples below use a direct Docker socket mount for brevity. For production deployments, use a socket proxy instead — all security features work identically with proxy-based connections.

Key-based verification

services:
  drydock:
    image: codeswhat/drydock:1.9.0-rc.1
    environment:
      - DD_SECURITY_SCANNER=grype
      - DD_SECURITY_VERIFY_SIGNATURES=true
      - DD_SECURITY_COSIGN_KEY=/keys/cosign.pub
    volumes:
      - ./cosign.pub:/keys/cosign.pub:ro
      - /var/run/docker.sock:/var/run/docker.sock

Keyless verification (Sigstore)

services:
  drydock:
    image: codeswhat/drydock:1.9.0-rc.1
    environment:
      - DD_SECURITY_SCANNER=grype
      - DD_SECURITY_VERIFY_SIGNATURES=true
      - DD_SECURITY_COSIGN_IDENTITY=https://github.com/CodesWhat/drydock/.github/workflows/release-cut.yml@refs/heads/main
      - DD_SECURITY_COSIGN_ISSUER=https://token.actions.githubusercontent.com
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

SBOM Generation

When enabled, Trivy or Syft generates Software Bill of Materials (SBOM) documents for candidate images during the Update Bouncer flow. auto uses Syft when Grype is the only scanner and Trivy otherwise.

Env varRequiredDescriptionSupported valuesDefault value when missing
DD_SECURITY_SBOM_ENABLED⚪Enable SBOM generationtrue / falsefalse
DD_SECURITY_SBOM_FORMATS⚪Comma-separated list of SBOM formatsspdx-json, cyclonedx-jsonspdx-json
DD_SECURITY_SBOM_GENERATOR⚪Provider-neutral SBOM generatorauto, trivy, syftauto
DD_SECURITY_SYFT_COMMAND⚪Syft command. Setting it makes auto run Syft locally even if the path does not resolve.executable pathsyft
DD_SECURITY_SYFT_TIMEOUT⚪Syft generation timeout in millisecondsinteger (>=1000)600000
DD_SECURITY_SYFT_ARGS⚪Additional Syft arguments as a JSON string array. Output/file flags cannot be overridden.JSON string array[]
DD_SECURITY_SYFT_WORKER_IMAGE⚪Digest-pinned Syft worker used when Syft runs in a workerOCI image pinned with @sha256:release-pinned Syft image
services:
  drydock:
    image: codeswhat/drydock:1.9.0-rc.1
    environment:
      - DD_SECURITY_SCANNER=grype
      - DD_SECURITY_SBOM_ENABLED=true
      - DD_SECURITY_SBOM_FORMATS=spdx-json,cyclonedx-json
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
SBOM documents are retrievable per-container via GET /api/v1/containers/:id/sbom?format={format} where format is one of spdx-json or cyclonedx-json.

SBOM bodies are stored off-heap at /store/sbom/<digest-key>/<document-sha>/<format>.json; container records retain only validated checksum/size references. Identical canonical documents for the same image digest share a blob, while divergent regenerations remain independently readable. On startup, Drydock atomically migrates legacy inline current/update SBOM records and preserves the original row for retry if any write fails.

Scheduled scanning

Set DD_SECURITY_SCAN_CRON to automatically scan all watched containers on a schedule. A random jitter delay (DD_SECURITY_SCAN_JITTER, default 60 seconds) is applied before each cycle to spread load. You can tune parallelism with DD_SECURITY_SCAN_CONCURRENCY (default 4) and cap total batch runtime with DD_SECURITY_SCAN_BATCH_TIMEOUT (default 1800000, set 0 to disable).

By default, scheduled scans update the Security view and audit log but do not fire notification triggers. Set DD_SECURITY_SCAN_NOTIFICATIONS=true to opt in to cron-driven alerts. On-demand scans (UI, single-container API, or the bulk POST /api/v1/containers/scan-all endpoint) always emit notifications.

Digest-level scan dedup caching uses an interval derived from the cron schedule:

  • drydock parses DD_SECURITY_SCAN_CRON and uses the shortest upcoming gap between scheduled runs as cache TTL.
  • For irregular schedules (for example 0 3,9 * * *), cache TTL is based on the shortest gap (6h in this case), not a fixed daily fallback.
  • If interval derivation fails, drydock falls back to 24h.

Transient scanner failures (daemon timeout, registry outage) no longer overwrite previously-stored scan results. The existing result is preserved for up to 7 days; error retries are floored at 15 minutes per digest regardless of cron frequency.

services:
  drydock:
    image: codeswhat/drydock:1.9.0-rc.1
    environment:
      - DD_SECURITY_SCANNER=grype
      - DD_SECURITY_SCAN_CRON=0 3 * * *   # every day at 3 AM
      - DD_SECURITY_SCAN_JITTER=60000      # up to 60s random delay
      - DD_SECURITY_SCAN_CONCURRENCY=4     # scan up to 4 digests in parallel
      - DD_SECURITY_SCAN_BATCH_TIMEOUT=1800000 # abort remaining digest queue after 30m
      - DD_SECURITY_SCAN_NOTIFICATIONS=true    # opt in to cron-driven notifications

On-demand scanning

You can trigger a security scan without waiting for the next scheduled cycle.

  • Single container — UI: Click the shield button on a container row.
  • Single container — API: POST /api/v1/containers/:id/scan runs vulnerability scanning, signature verification (if configured), and SBOM generation (if configured). Rate-limited to 30 requests per minute.
  • All containers — UI: Click Scan All in the Security view toolbar. Issues one server-side bulk scan — produces a single scan cycle rather than N per-container requests.
  • All containers — API: POST /api/v1/containers/scan-all scans all watched containers in one bulk operation. Rate-limited to 1 request per 60 seconds per IP (admin bypass available). Streams progress over SSE and respects client-disconnect aborts.

Real-time progress is broadcast via SSE events dd:scan-started and dd:scan-completed. Each scan cycle (cron, on-demand single, or bulk) carries a stable cycleId (UUID v7). When the cycle finishes, a dd:security-scan-cycle-complete event is emitted with { cycleId, scannedCount, alertCount, startedAt, completedAt }.

The cycleId is used by digest-mode notification triggers to group all findings from one scan cycle into a single summary notification instead of one per container.

Long-running scans

Scanner and cosign commands that run longer than 30 seconds log a progress line every 30 seconds, for example Trivy: still scanning registry.example.com/app:1.2.3 (60s). The line stops as soon as the command exits, fails or times out.

While a scan of a container runs, Drydock marks it with securityScanState: "scanning" and sends a dd:container-updated SSE event, so the container list shows a Scanning chip on the row. The flag is held in memory only. It clears when the scan finishes, fails or times out, and it is gone after a restart. The same flag shows up in GET /api/v1/containers for a scan that is running when the page loads. This covers scheduled, on-demand and bulk scans. The pre-update scan of a candidate image does not mark the running container, because that scan describes the new image and the update has its own progress phase.

Security view update button

When a newer image is available for a container shown in the Security view, an inline Update button appears directly next to the vulnerability data. This lets you apply the update without leaving the security context.

The update button respects eligibility blockers. If a security-scan-blocked blocker is active (either the running image scan or the candidate image scan returned blocked-severity vulnerabilities), the button is locked. Use the force-update path to override.

The Security view uses the same release-notes and source-project controls as the Containers view. When Drydock knows the current image's release notes, they are shown even if no update is pending; when source metadata is available, the View project link points at the resolved source repository.

security-scan-blocked eligibility blocker

The security-scan-blocked hard blocker is raised when:

  • The candidate update image scan (container.security.updateScan) has status blocked, or
  • The current running image scan (container.security.scan) has status blocked

Either condition prevents a manual update and causes POST /api/v1/containers/:id/update to return 409. Use the force-update path if you need to proceed anyway.

Dual-slot scanning

When a container has an available update, clicking Scan Now (or calling POST /api/v1/containers/:id/scan) scans both the current running image and the available update image in a single operation.

  • Results for the current image are stored in container.security.scan
  • Results for the update image are stored in container.security.updateScan
  • The UI shows delta comparison badges indicating how vulnerabilities change between versions (e.g. +3 fixed, -1 new)

This differs from the pre-update Update Bouncer flow, which only scans the candidate image as a gate before applying an update. Dual-slot scanning is informational and does not block updates.

Vulnerability report export

The Security detail panel includes an Export section for downloading vulnerability scan results in CSV or JSON format — useful for sharing with upstream image maintainers or importing into issue trackers.

UI export

  1. Open the Security detail panel for a container (click any container row in the Security view)
  2. Select a format from the Export vulnerabilities dropdown: CSV or JSON
  3. Click Download Report

CSV format

The CSV includes one row per vulnerability with these columns:

ColumnDescription
IDCVE or advisory identifier (e.g. CVE-2024-1234)
SeverityCRITICAL, HIGH, MEDIUM, LOW, or UNKNOWN
PackageAffected package name
VersionInstalled version
Fixed InVersion that resolves the vulnerability (empty if no fix available)
TitleShort vulnerability description
TargetScan target (e.g. OS package db, language lockfile)
URLLink to the advisory
CSV fields are sanitized against formula injection — values starting with =, +, -, or @ are automatically escaped so the file is safe to open in spreadsheet applications.

JSON format

The JSON export is an array of objects with the same fields as the CSV (id, severity, package, version, fixedIn, title, target, url).

API

Vulnerability data is also available programmatically:

  • Single container: GET /api/v1/containers/:id/vulnerabilities
  • All containers (paginated): GET /api/v1/containers/security/vulnerabilities?limit=100&offset=0

SBOM download

SBOM documents can be downloaded from the Security detail panel or via the API:

  • UI: Open the Security detail panel → click Download SBOM (works regardless of whether the SBOM viewer toggle is active)
  • API: GET /api/v1/containers/:id/sbom?format={format} where format is spdx-json or cyclonedx-json
When the security scanner is disabled or misconfigured, GET /api/v1/containers/:id/sbom returns 503 Service Unavailable with the message "Security scanner is not configured". This distinguishes "feature intentionally off" from a real server error.

Security digest notifications

On large inventories, a single scheduled scan can surface many vulnerable containers. By default each one would send a separate notification. Use SECURITYMODE=digest on a notification trigger to receive one summary per scan cycle instead of one per container.

environment:
  - DD_SECURITY_SCAN_CRON=0 3 * * *
  - DD_SECURITY_SCAN_NOTIFICATIONS=true

  - DD_NOTIFICATION_SMTP_ALERTS_FROM=drydock@example.com
  - DD_NOTIFICATION_SMTP_ALERTS_TO=security@example.com
  - DD_NOTIFICATION_SMTP_ALERTS_SECURITYMODE=digest
  # Optional: customize digest subject/body
  # - DD_NOTIFICATION_SMTP_ALERTS_SECURITYDIGESTTITLE=Security scan complete: ${scan.alertCount} ${scan.containerNoun} with findings
  # - DD_NOTIFICATION_SMTP_ALERTS_SECURITYDIGESTBODY=Found ${scan.alertCount} of ${scan.scannedCount} containers with alerts

The digest fires once per cycleId, grouped by severity. Cycles with zero findings never emit. The SECURITYMODE setting is independent of the update-notification MODE — a trigger can combine MODE=batch (update emails) with SECURITYMODE=digest (security emails) simultaneously.

Digest templates use the same safe ${…} interpolation as every other trigger template — they are not evaluated as JavaScript, so arbitrary expressions (arrow functions, array methods, arithmetic) resolve to an empty string rather than running code. The following scan.* variables are available:

VariableDescription
scan.alertCountContainers with at least one finding
scan.scannedCountContainers scanned in the cycle
scan.containerNouncontainer when alertCount is 1, otherwise containers
scan.criticalCount / scan.highCount / scan.mediumCount / scan.lowCount / scan.unknownCountContainer counts whose top severity is that level
scan.criticalList / scan.highListPre-formatted, newline-joined - name: … lists for the critical and high tiers
scan.startedAt / scan.completedAtCycle start/finish ISO timestamps
scan.cycleIdThe cycle's UUID v7

Full example (scanning + signatures + SBOM)

services:
  drydock:
    image: codeswhat/drydock:1.9.0-rc.1
    environment:
      - DD_SECURITY_SCANNER=grype
      - DD_SECURITY_BLOCK_SEVERITY=CRITICAL,HIGH
      - DD_SECURITY_VERIFY_SIGNATURES=true
      - DD_SECURITY_COSIGN_IDENTITY=https://github.com/CodesWhat/drydock/.github/workflows/release-cut.yml@refs/heads/main
      - DD_SECURITY_COSIGN_ISSUER=https://token.actions.githubusercontent.com
      - DD_SECURITY_SBOM_ENABLED=true
      - DD_SECURITY_SBOM_FORMATS=spdx-json,cyclonedx-json
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock