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 noteQuick setup
Section titled “Quick setup”-
Run scanners somewhere. With the Helm chart, enable the scan-worker Deployment (it bundles
trivyandgrype) and a shared Trivy server:values.yaml scanning:worker:enabled: truereplicaCount: 2trivyServer:enabled: trueSee Where scans run for the alternatives.
-
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/testresource "entrepot_scanner" "trivy" {name = "trivy"type = "trivy"rescan_interval_hours = 24trivy = {server_url = "http://entrepot-trivy:4954"}}The Trivy server Service is
<release>-entrepot-trivyon port 4954; the chart’s NOTES print the exact URL. -
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"}}'PUTreplaces all mutable settings, so send the full repository definition (or edit it in the UI / Terraform).
Scanners
Section titled “Scanners”| 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).
Where scans run
Section titled “Where scans run”- In-process. The default is
scan.workers: 2inside the server pods. The default server image is distroless and has no scanner CLIs, so in-process workers only suitwebhookscanners, ortrivy/grypewith the CLIs added to the image. - Separate workers.
entrepot scan-workerruns only the pipeline. Thescannerimage (ghcr.io/entrepotproj/entrepot-scanner, Dockerfile targetscanner) bundles checksum-verifiedtrivyandgrype. The Helm chart deploys it withscanning.worker.enabled: trueand 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.
What gets scanned
Section titled “What gets scanned”| 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 |
Repository policy
Section titled “Repository policy”"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.
Quarantine
Section titled “Quarantine”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 ForbiddenX-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.
Waivers
Section titled “Waivers”A waiver accepts a vulnerability, optionally until a date.
vulnIdis an exact ID (CVE-2021-23337,GHSA-…) or*.repositoryPatternandcomponentPatternare globs (default*). The component pattern is matched againstname,name@versionorname:version.expiresAtis optional. When a waiver expires, the components it covered are re-evaluated.- A waiver of
*for everything at once is rejected.
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"}'resource "entrepot_waiver" "lodash_template" { vuln_id = "CVE-2021-23337" repository_pattern = "npm-*" component_pattern = "lodash@4.17.*" reason = "template() not used with untrusted input" expires_at = "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.
On-demand scans and results
Section titled “On-demand scans and results”curl -fsS -H "Authorization: Bearer $ENTREPOT_TOKEN" -X POST $E/api/v1/components/$ID/scan # needs writecurl -fsS -H "Authorization: Bearer $ENTREPOT_TOKEN" $E/api/v1/components/$ID/scans # findings, jobs, verdictcurl -fsS -H "Authorization: Bearer $ADMIN" "$E/api/v1/scan-jobs?status=failed" # the queuePOST …/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.
GitLab feedback
Section titled “GitLab feedback”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:runningwhile scans are outstanding; thenfailedwhen the component is quarantined or has unwaived findings at or above the threshold; otherwisesuccess. 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 issuerURLWith 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.
Limitations
Section titled “Limitations”- The vulnerability databases must be reachable from the scanners: through
the Trivy server, or
mirror.gcr.io/ ghcr for Trivy andgrype.anchore.iofor Grype. For air-gapped setups, mirror the DBs and passextraArgs(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.