Skip to content

Vulnerability scanning

Entrepot can scan components when they are uploaded, when a proxy first caches them, on demand, and on a schedule. Each repository decides what to do with the results: just record them (warn) or block downloads (quarantine). Builds published from GitLab CI get the results back as a commit status and an MR note.

upload / proxy fetch ──► scan_jobs (Postgres queue) ──► worker ──► trivy | grype | webhook
│
download ◄── quarantine gate ◄── verdict ◄── findings − waivers
└──► GitLab commit status + MR note
  1. Run scanners somewhere. With the Helm chart, enable the scan-worker Deployment (it bundles trivy and grype) and a shared Trivy server:

    values.yaml
    scanning:
    worker:
    enabled: true
    replicaCount: 2
    trivyServer:
    enabled: true

    See Where scans run for the alternatives.

  2. Register a scanner (UI: Security scanning → Scanners):

    Terminal window
    curl -fsS -H "Authorization: Bearer $ADMIN" -X POST $E/api/v1/scanners -d '{
    "name": "trivy", "type": "trivy", "rescanIntervalHours": 24,
    "trivy": {"serverUrl": "http://entrepot-trivy:4954"}
    }'
    curl -fsS -H "Authorization: Bearer $ADMIN" -X POST $E/api/v1/scanners/trivy/test

    The Trivy server Service is <release>-entrepot-trivy on port 4954; the chart’s NOTES print the exact URL.

  3. Turn on a policy on the repositories you care about:

    Terminal window
    curl -fsS -H "Authorization: Bearer $ADMIN" -X PUT $E/api/v1/repositories/npm-proxy -d '{
    "name": "npm-proxy", "format": "npm", "kind": "proxy", "blobStore": "default",
    "proxy": {"remoteUrl": "https://registry.npmjs.org"},
    "scan": {"scanners": ["trivy"], "mode": "quarantine", "severityThreshold": "high"}
    }'

    PUT replaces all mutable settings, so send the full repository definition (or edit it in the UI / Terraform).

Type How it runs Best for
trivy Runs the trivy CLI. With serverUrl set it uses client/server mode, so a central Trivy server keeps the vulnerability DB. most deployments
grype Runs the grype CLI. a second opinion, or when you already use Anchore
webhook POSTs a signed job to your service, which calls back with results. in-house or commercial scanners — see Webhook scanners

Settings per type:

Field Applies to Meaning
enabled all Disabled scanners queue no new jobs (default true).
rescanIntervalHours all Periodically rescan components that repositories still use, so new CVEs are found in old artifacts (0 = never).
trivy.binary / grype.binary trivy, grype Path to the CLI (default trivy / grype).
trivy.serverUrl / trivy.serverToken trivy Trivy server for client/server mode. The token is write-only.
timeoutSeconds, extraArgs trivy, grype Per-scan timeout and extra CLI arguments (e.g. --db-repository for a mirrored DB).
webhook.url / webhook.secret / webhook.timeoutSeconds webhook Endpoint, HMAC key (write-only) and callback deadline (default 900s).

Secret settings — the Trivy serverToken and the webhook secret — are encrypted at rest and never returned by the API. A scanner that a repository still uses can’t be deleted (409).

  • In-process. The default is scan.workers: 2 inside the server pods. The default server image is distroless and has no scanner CLIs, so in-process workers only suit webhook scanners, or trivy/grype with the CLIs added to the image.
  • Separate workers. entrepot scan-worker runs only the pipeline. The scanner image (ghcr.io/entrepotproj/entrepot-scanner, Dockerfile target scanner) bundles checksum-verified trivy and grype. The Helm chart deploys it with scanning.worker.enabled: true and switches the in-process workers off.

Jobs live in a Postgres table. Workers claim them with FOR UPDATE SKIP LOCKED and hold a lease, extended by a heartbeat; expired leases are reclaimed, and failures are retried with exponential backoff (up to three attempts by default). Any number of workers can run on any number of replicas.

Format Target
npm, PyPI a one-component CycloneDX SBOM with the package’s purl (pkg:npm/lodash@4.17.20)
Apt, Yum a deb or rpm purl plus an operating-system component from the repository’s scan.distro (debian-12, ubuntu-24.04, rocky-9)
Docker the image, exported from the blob store as an OCI layout, one per platform (up to 8), with findings merged. A proxy scans the platforms it has cached, or linux/amd64
Helm, raw reported as unsupported
"scan": {
"scanners": ["trivy"],
"mode": "quarantine",
"severityThreshold": "high",
"onUpload": true,
"onProxyFetch": true,
"blockUntilScanned": false,
"distro": "debian-12"
}
Field Default Meaning
scanners — Scanner names. Empty disables scanning for the repository.
mode warn off, warn (record only) or quarantine (block downloads).
severityThreshold high Lowest severity that quarantines: critical, high, medium, low.
onUpload true Scan components when they are uploaded.
onProxyFetch true Scan components when a proxy first caches them.
blockUntilScanned false Quarantine mode: also block components that have not been scanned yet. The download attempt queues the scan.
distro — Apt/Yum: distribution for vulnerability matching.

A component’s state is one of unscanned, pending (queued, never scanned yet), clean (no unwaived findings), vulnerable (unwaived findings), error or unsupported. It comes from the latest result of each scanner, minus active waivers.

In quarantine mode, downloads of components with an unwaived finding at or above severityThreshold get 403 with a reason and the header X-Entrepot-Quarantined: true:

403 Forbidden
X-Entrepot-Quarantined: true
CVE-2021-23337 (high) in lodash@4.17.20 — waive or fix to download
  • Metadata (packuments, indexes) is not blocked, so clients see a clear error on the file itself.
  • Docker tag and digest manifests are blocked; layers never are.
  • Switching a repository from warn to quarantine takes effect immediately, without rescanning.
  • Group repositories apply each member’s policy, not the group’s.

A waiver accepts a vulnerability, optionally until a date.

  • vulnId is an exact ID (CVE-2021-23337, GHSA-…) or *.
  • repositoryPattern and componentPattern are globs (default *). The component pattern is matched against name, name@version or name:version.
  • expiresAt is optional. When a waiver expires, the components it covered are re-evaluated.
  • A waiver of * for everything at once is rejected.
Terminal window
curl -fsS -H "Authorization: Bearer $ADMIN" -X POST $E/api/v1/waivers -d '{
"vulnId": "CVE-2021-23337", "repositoryPattern": "npm-*", "componentPattern": "lodash@4.17.*",
"reason": "template() not used with untrusted input", "expiresAt": "2027-01-31T00:00:00Z"
}'

Creating, changing or deleting a waiver re-evaluates the affected components straight away. Download-gate decisions are cached per process for up to 30 seconds, so allow that long before retrying a blocked download. In the UI, waive a finding directly from the component’s scan results, or manage waivers under Security scanning → Waivers.

Terminal window
curl -fsS -H "Authorization: Bearer $ENTREPOT_TOKEN" -X POST $E/api/v1/components/$ID/scan # needs write
curl -fsS -H "Authorization: Bearer $ENTREPOT_TOKEN" $E/api/v1/components/$ID/scans # findings, jobs, verdict
curl -fsS -H "Authorization: Bearer $ADMIN" "$E/api/v1/scan-jobs?status=failed" # the queue

POST …/scan accepts an optional body {"scanners": ["grype"]}; without it the repository’s scanners run. Find component IDs with GET /api/v1/search?q=lodash or in the UI.

When an artifact was published by a GitLab CI job (authenticated with its id_token) and that GitLab instance has an API token configured, Entrepot posts results back:

  • a commit status entrepot/scan/<repository> on the pipeline’s commit: running while scans are outstanding; then failed when the component is quarantined or has unwaived findings at or above the threshold; otherwise success. It links to the component page in the UI.
  • an MR note on each open merge request for that commit — one per repository and component, updated in place on rescans, with a findings table.
auth:
gitlab:
- name: gitlab
issuerURL: https://gitlab.example.com
api:
tokenEnv: ENTREPOT_GITLAB_TOKEN # a token with the "api" scope (or token / tokenFile)
# url: https://gitlab.example.com # defaults to issuerURL

With the Helm chart, set feedback: true on the auth.gitlab entry and store the token under gitlab-token-<name> in auth.existingSecret (or set apiToken). Feedback is best effort: errors are logged and never fail a scan.

  • The vulnerability databases must be reachable from the scanners: through the Trivy server, or mirror.gcr.io / ghcr for Trivy and grype.anchore.io for Grype. For air-gapped setups, mirror the DBs and pass extraArgs (e.g. --db-repository).
  • Group repositories apply each member’s policy, not the group’s.
  • Download-gate decisions are cached per process for up to 30 seconds after a waiver change.