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 value | What it does | Effect on the merge gate |
|---|---|---|---|
| Off | off | Vulnerabilities are not looked up | None |
| Report | report | The scan runs; the result is shown on the merge request, marked (report only) | None |
| Enforce | block | The 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
- 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.
- Dependencies are compared: added, removed and version changed.
- 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"). - 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.
- 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:
| Ecosystem | Files |
|---|---|
| Go | go.mod |
| npm | package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lock, package.json |
| PyPI | requirements.txt, poetry.lock, Pipfile.lock, pdm.lock, uv.lock, pylock.toml |
| Maven | pom.xml, gradle.lockfile, buildscript-gradle.lockfile, verification-metadata.xml |
| crates.io | Cargo.lock, Cargo.toml |
| RubyGems | Gemfile.lock |
| NuGet | packages.lock.json, packages.config |
| Packagist | composer.lock |
| Pub | pubspec.lock |
| SwiftPM | Package.resolved |
| CocoaPods | Podfile.lock (read, but there is no vulnerability data for CocoaPods: its dependencies are listed under No vulnerability data for) |
| Hex | mix.lock |
| Hackage | cabal.project.freeze, stack.yaml.lock |
| ConanCenter | conan.lock |
| CRAN | renv.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):
| Condition | Message |
|---|---|
| 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 does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Mode (row Dependency scan) | See Modes | Off | Off, Report, Enforce | Policy | Policy manager, company admin, platform admin | controls.sca.mode (off, report, block) |
| Hold from severity | The lowest severity of an introduced vulnerability that holds the merge. Shown in Enforce mode | High and above | Low and above, Medium and above, High and above, Critical and above | Policy | Same | controls.sca.block_severity (low, medium, high, critical) |
| Vulnerabilities without a rating | Show, 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 mode | Show, do not hold | show, high, block | Company; policy override (shown in Enforce mode) | Company: company admin. Policy: policy manager, company admin | scanning.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 other | Count as critical | critical, show | Company; policy override (shown in Enforce mode) | Same | scanning.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 it | 0 (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 1 | Company; policy override (shown in Enforce mode) | Same | scanning.sca.epss_hold; controls.sca.overrides.epss_hold |
| When the scan cannot finish | Fail, 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 lookups | Fail, rescan by hand | manual, retry | Company; policy override | Same | scanning.sca.on_error; controls.sca.overrides.on_error |
| Allowed paths | Only manifests matching these are scanned | Empty: all | One pattern per line. A pattern without / matches a file or folder name anywhere; one with / is read from the repository root; ** spans folders | Company; policy override through the API only | Same | scanning.sca.allowed_paths; controls.sca.overrides.allowed_paths |
| Blocked paths | Manifests matching these are skipped (for example testdata, vendor, examples) | Empty | As above | Company; policy override through the API only | Same | scanning.sca.blocked_paths; controls.sca.overrides.blocked_paths |
| Max dependencies per scan | The most new or changed dependencies one merge request's scan looks up. A change with more fails the scan ("… only 500 were checked (limit)") | 500 | 0 to 20,000 (0: the default) | Company | Company admin | scanning.sca.max_dependencies |
| Max vulnerabilities stored | The most introduced vulnerabilities kept per scan, most severe first. Counts and the decision use all of them | 200 | 0 to 5,000 (0: the default) | Company | Company admin | scanning.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 lookup | 30 | 0 to 600 (0: the default) | Company | Company admin | scanning.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
scanningobject 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
| Limit | Value | When it is exceeded |
|---|---|---|
| Changed manifests per merge request | 20 | The first 20 are scanned and the scan fails ("N manifests changed; only the first 20 were scanned") |
| Size of one manifest | 5 MB | The file cannot be read; the scan fails |
| New or changed dependencies looked up | Max dependencies per scan | The scan fails |
| Introduced vulnerabilities stored | Max vulnerabilities stored | The most severe are kept; the comment says "Showing the N most severe of M" |
| Existing vulnerabilities shown | 50 | The 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}/rescanwith{"scan": "sca"}. Recorded assca_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
| Action | When |
|---|---|
sca_scan | The scan finished with a result that differs from the previous one (status, counts, highest severity, licenses, package health) |
sca_rescan | Someone started a re-scan |
vuln_exception_created, vuln_exception_revoked, vuln_exception_expired | An exception changed |
job_failed | The scan job failed after its retries |
update_company, policy_updated | The company's settings or a policy changed |
See Audit log.
API
- Policy:
controls.scawithmode,block_severityandoverrides(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_scanwithstatus(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 indecision.controls(control: "sca"). - Full result:
GET /api/v1/companies/{id}/sca-results/{result_id}(added, removed and changed dependencies, introduced and existing vulnerabilities, withexcepted_byset 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 →