Update Bouncer

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=trivy

Variables

Trivy modes

Client mode (local CLI)

Use this mode when the trivy binary is available inside the drydock runtime.

services:
  drydock:
    image: codeswhat/drydock:latest
    environment:
      - DD_SECURITY_SCANNER=trivy
      - DD_SECURITY_BLOCK_SEVERITY=CRITICAL,HIGH
      - DD_SECURITY_TRIVY_COMMAND=trivy
      - DD_SECURITY_TRIVY_TIMEOUT=120000

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:latest
    depends_on:
      - trivy
    environment:
      - DD_SECURITY_SCANNER=trivy
      - DD_SECURITY_BLOCK_SEVERITY=CRITICAL,HIGH
      - DD_SECURITY_TRIVY_SERVER=http://trivy:4954
      - DD_SECURITY_TRIVY_TIMEOUT=120000

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.

services:
  drydock:
    image: codeswhat/drydock:latest
    environment:
      - DD_SECURITY_SCANNER=trivy
      - DD_SECURITY_BLOCK_SEVERITY=NONE

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.

Key-based verification

services:
  drydock:
    image: codeswhat/drydock:latest
    environment:
      - DD_SECURITY_SCANNER=trivy
      - 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:latest
    environment:
      - DD_SECURITY_SCANNER=trivy
      - 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 generates Software Bill of Materials (SBOM) documents for candidate images during the Update Bouncer flow. SBOMs are persisted in container.security.sbom and available via the API.

services:
  drydock:
    image: codeswhat/drydock:latest
    environment:
      - DD_SECURITY_SCANNER=trivy
      - DD_SECURITY_SBOM_ENABLED=true
      - DD_SECURITY_SBOM_FORMATS=spdx-json,cyclonedx-json
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

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 Trivy 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:latest
    environment:
      - DD_SECURITY_SCANNER=trivy
      - 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.

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.

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:

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

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:

Full example (scanning + signatures + SBOM)

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

  drydock:
    image: codeswhat/drydock:latest
    depends_on:
      - trivy
    environment:
      - DD_SECURITY_SCANNER=trivy
      - DD_SECURITY_BLOCK_SEVERITY=CRITICAL,HIGH
      - DD_SECURITY_TRIVY_SERVER=http://trivy:4954
      - 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