Update Guard

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

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

Candidate image is scanned before update
Update is blocked when CVEs match configured blocking severities
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

Env var	Required	Description	Supported values	Default value when missing
`DD_SECURITY_SCANNER`	🔴	Enable scanner provider	`trivy`	disabled
`DD_SECURITY_BLOCK_SEVERITY`	⚪	Blocking severities (comma-separated)	Any of `UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL`	`CRITICAL,HIGH`
`DD_SECURITY_TRIVY_SERVER`	⚪	Trivy server URL (enables client/server mode)	URL	empty (local CLI mode)
`DD_SECURITY_TRIVY_COMMAND`	⚪	Trivy command path for local CLI mode	executable path	`trivy`
`DD_SECURITY_TRIVY_TIMEOUT`	⚪	Trivy command timeout in milliseconds	integer (`>=1000`)	`120000`

Trivy modes

Client mode (local CLI)

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

As of v1.3.0, the official drydock image includes both trivy and cosign. No custom image is needed for local CLI mode.

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

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 var	Required	Description	Supported values	Default value when missing
`DD_SECURITY_VERIFY_SIGNATURES`	⚪	Enable signature verification gate	`true` / `false`	`false`
`DD_SECURITY_COSIGN_KEY`	⚪	Path to cosign public key file	file path	empty (keyless / Sigstore)
`DD_SECURITY_COSIGN_COMMAND`	⚪	Cosign command path	executable path	`cosign`
`DD_SECURITY_COSIGN_TIMEOUT`	⚪	Cosign command timeout in milliseconds	integer (`>=1000`)	`60000`
`DD_SECURITY_COSIGN_IDENTITY`	⚪	Certificate identity for keyless verification	string	empty
`DD_SECURITY_COSIGN_ISSUER`	⚪	OIDC issuer for keyless verification	string	empty

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.

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.yml@refs/tags/*
      - 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 Guard flow. SBOMs are persisted in container.security.sbom and available via the API.

Env var	Required	Description	Supported values	Default value when missing
`DD_SECURITY_SBOM_ENABLED`	⚪	Enable SBOM generation	`true` / `false`	`false`
`DD_SECURITY_SBOM_FORMATS`	⚪	Comma-separated list of SBOM formats	`spdx-json`, `cyclonedx-json`	`spdx-json`

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

SBOM documents are retrievable per-container via GET /api/containers/:id/sbom?format=\{format\} where format is one of spdx-json or cyclonedx-json.

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.yml@refs/tags/*
      - 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

Update Guard

On this page