Skip to main content
Video tutorial · 1:21

Dependency scan

The Dependency scan control checks the dependencies a merge request adds or upgrades for known vulnerabilities and malicious packages, using the OSV.dev vulnerability database. It reads the dependency manifests and lockfiles the change touches, compares them with the target branch, and looks up only what the change brings in. In Enforce mode a change that introduces a vulnerability at or above the policy's severity threshold cannot merge.

Whether a merge request is scanned, and from which severity it is held, is set per change policy (policy editor, Checks tab, row Dependency scan). How the scan behaves is a company setting (the company's Scanning tab → Dependencies), which a policy can override.

The same scan also reads Licenses, Package health and Dependency sources when those controls are on.

Modes​

Mode (label in the UI)API valueWhat it doesEffect on the merge gate
OffoffVulnerabilities are not looked upNone
ReportreportThe scan runs; the result is shown on the merge request, marked (report only)None
EnforceblockThe scan runs; what it finds can hold the merge (see What holds the merge)Waiting while the scan runs; Blocked when it finds something that holds, or the scan could not be completed

A new policy starts with Off.

What is scanned​

  1. The manifests among the merge request's changed files are read at the latest commit, and the same files at the point where the branch left the target branch. Deleted manifests are not read.
  2. Dependencies are compared: added, removed and version changed.
  3. Only exact versions are looked up. A dependency named by a version range (^1.2, >=2) has no version to look up; it is listed as not checked ("commit the lockfile to check the versions in use").
  4. An upgraded dependency introduces only the vulnerabilities its previous version did not have: an upgrade that keeps or fixes known vulnerabilities is not blamed for them.
  5. Vulnerabilities of unchanged dependencies are shown for context ("N existing vulnerability(ies) in unchanged dependencies (not introduced by this MR)"); they never hold the merge.

Supported manifests​

Files are recognised by name, in any folder:

EcosystemFiles
Gogo.mod
npmpackage-lock.json, yarn.lock, pnpm-lock.yaml, bun.lock, package.json
PyPIrequirements.txt, poetry.lock, Pipfile.lock, pdm.lock, uv.lock, pylock.toml
Mavenpom.xml, gradle.lockfile, buildscript-gradle.lockfile, verification-metadata.xml
crates.ioCargo.lock, Cargo.toml
RubyGemsGemfile.lock
NuGetpackages.lock.json, packages.config
Packagistcomposer.lock
Pubpubspec.lock
SwiftPMPackage.resolved
CocoaPodsPodfile.lock (read, but there is no vulnerability data for CocoaPods: its dependencies are listed under No vulnerability data for)
Hexmix.lock
Hackagecabal.project.freeze, stack.yaml.lock
ConanCenterconan.lock
CRANrenv.lock

A package.json is skipped when an npm lockfile in the same folder changed too: the lockfile says which versions are in use.

Severity, malicious packages, KEV and EPSS​

  • Each vulnerability has a severity: Critical, High, Medium, Low, or none (not rated).
  • An advisory that reports a malicious package marks the package as malicious, whatever else it says.
  • CISA KEV: vulnerabilities in the Known Exploited Vulnerabilities catalog are marked Exploited (KEV): attackers use them now.
  • EPSS: the probability, from FIRST's Exploit Prediction Scoring System, that a vulnerability is exploited in the next 30 days, shown as EPSS 12%.

Vulnerability lookups are reused for up to 24 hours; the KEV and EPSS marks are read fresh at each scan.

What holds the merge​

In Enforce mode, after vulnerabilities accepted by an exception are left out, the control fails when any of these is true (checked in this order):

ConditionMessage
The scan could not be completed"The dependency scan could not be completed: … Fix the cause and rescan."
A malicious package was added"N malicious package(s) added."
An introduced vulnerability's EPSS is at or above Hold from exploitation likelihood (EPSS)"… Exploitation likelihood (EPSS) 40% is at or above the 30% limit."
An unrated vulnerability was introduced and Vulnerabilities without a rating is Always hold"… Unrated vulnerabilities hold the change."
The highest severity reaches Hold from severity. A KEV vulnerability counts as Critical under Count as critical; an unrated one counts as High under Count as high"N new vulnerable dependenc(ies), highest severity high."

Otherwise it passes: "No new vulnerable dependencies." or "… Below the high threshold." The messages also say how many were accepted by exception and how many dependencies named by a version range were not checked. In Report mode the same result is shown as a warning and does not hold.

Settings​

The company's settings are on the company's Scanning tab → Dependencies, card Dependency vulnerability scanning and card Path filters; company admins change them there (PUT /api/v1/companies/{id} with scanning.sca). The policy editor shows its overrides under the Dependency scan row; each starts on Company setting (…).

Setting (label in the UI)What it doesDefaultAllowed valuesSet whereWho can change itAPI field
Mode (row Dependency scan)See ModesOffOff, Report, EnforcePolicyPolicy manager, company admin, platform admincontrols.sca.mode (off, report, block)
Hold from severityThe lowest severity of an introduced vulnerability that holds the merge. Shown in Enforce modeHigh and aboveLow and above, Medium and above, High and above, Critical and abovePolicySamecontrols.sca.block_severity (low, medium, high, critical)
Vulnerabilities without a ratingShow, do not hold: listed; only rated vulnerabilities at the threshold hold. Count as high: treated as high severity, held where the policy holds high. Always hold: any unrated vulnerability holds the change in Enforce modeShow, do not holdshow, high, blockCompany; policy override (shown in Enforce mode)Company: company admin. Policy: policy manager, company adminscanning.sca.unknown_severity; controls.sca.overrides.unknown_severity
Vulnerabilities exploited in the wild (CISA KEV)Count as critical: it holds the merge in Enforce mode whatever its own rating. Mark only: shown as exploited; the severity threshold decides as for any otherCount as criticalcritical, showCompany; policy override (shown in Enforce mode)Samescanning.sca.kev; controls.sca.overrides.kev
Hold from exploitation likelihood (EPSS, %) (policy editor: Hold from exploitation likelihood (EPSS))Hold the merge when an introduced vulnerability's EPSS is at least this. 0 never holds for it0 (never)Company: a percentage from 0 to 100, decimals allowed (for example 0.4). Policy editor: Never, From 10%, From 30%, From 50%, From 70%, From 90%. API: a fraction from 0 to 1Company; policy override (shown in Enforce mode)Samescanning.sca.epss_hold; controls.sca.overrides.epss_hold
When the scan cannot finishFail, rescan by hand: an unreachable OSV, an unreadable manifest or a limit fails the scan (never "clean"); someone re-scans. Fail, retry automatically: the scan fails the same way and is retried after a pause until it completes. Also applies to failed license and package lookupsFail, rescan by handmanual, retryCompany; policy overrideSamescanning.sca.on_error; controls.sca.overrides.on_error
Allowed pathsOnly manifests matching these are scannedEmpty: allOne pattern per line. A pattern without / matches a file or folder name anywhere; one with / is read from the repository root; ** spans foldersCompany; policy override through the API onlySamescanning.sca.allowed_paths; controls.sca.overrides.allowed_paths
Blocked pathsManifests matching these are skipped (for example testdata, vendor, examples)EmptyAs aboveCompany; policy override through the API onlySamescanning.sca.blocked_paths; controls.sca.overrides.blocked_paths
Max dependencies per scanThe most new or changed dependencies one merge request's scan looks up. A change with more fails the scan ("… only 500 were checked (limit)")5000 to 20,000 (0: the default)CompanyCompany adminscanning.sca.max_dependencies
Max vulnerabilities storedThe most introduced vulnerabilities kept per scan, most severe first. Counts and the decision use all of them2000 to 5,000 (0: the default)CompanyCompany adminscanning.sca.max_vulnerabilities
External call timeout (seconds)How long each call during the scan may take: reading a file from the VCS, a vulnerability or package lookup300 to 600 (0: the default)CompanyCompany adminscanning.sca.external_call_timeout

Max dependencies per project analysis, Project analysis timeout (seconds) and the Vulnerability tracking card on the same tab apply to project analyses and the vulnerability inventory, not to this control.

Notes:

  • A policy override list replaces the company's list, even when empty; leaving it out (null) keeps the company's.
  • The company's scanning object is saved as a whole: fields left out take their defaults.
  • Vulnerabilities without a rating, CISA KEV and EPSS are applied each time the merge request is evaluated, so a change to them takes effect without a new scan. The other settings take effect at the next scan (a new commit or a re-scan).

Limits​

LimitValueWhen it is exceeded
Changed manifests per merge request20The first 20 are scanned and the scan fails ("N manifests changed; only the first 20 were scanned")
Size of one manifest5 MBThe file cannot be read; the scan fails
New or changed dependencies looked upMax dependencies per scanThe scan fails
Introduced vulnerabilities storedMax vulnerabilities storedThe most severe are kept; the comment says "Showing the N most severe of M"
Existing vulnerabilities shown50The rest are left out

A scan also fails when the VCS listed only part of the changed files (a changed manifest may have been missed), a manifest cannot be read on either side, or OSV.dev cannot be asked. A failed scan is never reported as clean.

The manifest and dependency limits and a cut-short file list follow the company's When a scan cannot see everything (see Scanning); a policy can set its own. With Check the first ones up to the limit or Check what was listed, the scan checks those and names what it did not look at in the reason of the Dependency scan, Licenses, Package health and Dependency sources lines (Not looked at: …). A scan failed this way is not retried by itself.

Exceptions​

A vulnerability the company has assessed can be accepted so it no longer holds merge requests: on the Vulnerabilities page, Accept or mark not affected (why: We accept the risk for now or We are not affected (the vulnerable code is not used); where: one project or every project of the company, optionally only one package; until a date). Policy managers and company admins can create and revoke exceptions; with four-eyes review on, another policy manager or administrator must approve them, in the box of waiting changes at the top of the Vulnerabilities page.

An active exception covers the advisory by its ID or any of its aliases. The control leaves covered vulnerabilities out ("N accepted by exception."), and the merge request is evaluated again when an exception is created, revoked or expires. The scan's counts on the merge request page still include them; Show details marks them Accepted.

When it runs​

  • Once per commit. When the merge request is processed and its latest commit has not been scanned yet, the scan is queued. New commits start a new scan. A finished scan that left out a check the policy now wants (for example after the policy turned licenses on) runs again.
  • Re-scan. The Re-scan button on an open merge request's Dependency scan (SCA) card scans the latest commit again (a merged or closed merge request is not scanned again). Anyone in the company except auditors can use it. API: POST /api/v1/merge-requests/{id}/rescan with {"scan": "sca"}. Recorded as sca_rescan.
  • After a failure, with Fail, retry automatically: queued again after a pause (10 minutes by default), the next time the merge request is processed (for example by the periodic re-check).
  • A VCS rate limit is not a failure: the job waits for the limit to reset.
  • Watched repositories are scanned only while the company scans watched merge requests (company Repositories tab, Watching repositories); otherwise the control is skipped.

When the scan finishes, the merge request is evaluated again.

What the merge request shows​

The Dependency scan (SCA) card on the merge request page shows:

  • Dependency scan in progress, No vulnerabilities introduced (N manifest(s) scanned), or N vulnerability(ies) introduced with how many dependencies were added or changed, the count per severity, and Holds the merge: followed by the control's reason (see What holds the merge) when the control holds it;
  • Show details: the introduced vulnerabilities with Package, Version, Vulnerability (linked to the advisory), Summary, Severity with Exploited (KEV) and EPSS badges and Accepted for exceptions, and Fixed in;
  • when the scan failed: The scan could not be completed, so the change is not known to be safe, the reasons, and Fix the cause and rescan.;
  • banners for malicious packages and KEV vulnerabilities, the dependencies Not checked — named by a version range, and those with No vulnerability data for their ecosystem;
  • the license, package health and dependency source results, when those controls are on.

In the VCS, Merge Pilot keeps one comment, Merge Pilot: Dependency Scan, up to date on the merge request once there is something to report: the introduced vulnerabilities (package, version, advisory, severity, exploitation, fixed version), malicious packages, unchecked dependencies, licenses, package health, dependency sources, and the added, removed and changed counts. No comment is written in a watched repository.

When the result changes and vulnerabilities were introduced, the notification Vulnerable dependency introduced by a merge request goes to the company's notification routes that receive it (not for imported past merge requests).

GitLab and GitHub​

The scan is the same on both. GitHub pages and comments say pull request.

Audit​

ActionWhen
sca_scanThe scan finished with a result that differs from the previous one (status, counts, highest severity, licenses, package health)
sca_rescanSomeone started a re-scan
vuln_exception_created, vuln_exception_revoked, vuln_exception_expiredAn exception changed
job_failedThe scan job failed after its retries
update_company, policy_updatedThe company's settings or a policy changed

See Audit log.

API​

  • Policy: controls.sca with mode, block_severity and overrides (unknown_severity, kev, epss_hold, on_error, allowed_paths, blocked_paths).
  • Company: scanning.sca (allowed_paths, blocked_paths, max_dependencies, max_vulnerabilities, external_call_timeout, unknown_severity, on_error, kev, epss_hold).
  • Merge request (GET /api/v1/merge-requests/{id}): sca_scan with status (pending, clean, vulnerable, failed), head_sha, introduced_vuln_count, critical_count, high_count, medium_count, low_count, unknown_count, highest_severity, malicious_count, kev_count, max_epss, existing_vuln_count, manifests_scanned, diff_summary, unpinned, unsupported, problems, error, result_id; and the result in decision.controls (control: "sca").
  • Full result: GET /api/v1/companies/{id}/sca-results/{result_id} (added, removed and changed dependencies, introduced and existing vulnerabilities, with excepted_by set on accepted ones).
  • Exceptions: GET, POST /api/v1/companies/{id}/vulnerability-exceptions, DELETE /api/v1/companies/{id}/vulnerability-exceptions/{eid}.

Video tutorial

Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →

Block Vulnerable DependenciesYouTube ↗