Skip to main content
Video tutorial · 1:04

Dependency sources

The Dependency sources control checks where the dependencies a merge request adds or changes are fetched from. A vulnerability scan looks at which package version is used; this control looks at where it comes from:

  • A manifest changed without its lockfile. Installs that follow the lockfile (npm ci, pnpm and yarn in CI, cargo --locked and the like) then fail, or use versions the manifest no longer names, and the versions nobody reviewed are fetched later.
  • A lockfile entry fetched from a registry that is not allowed. A package of the same name on another registry is the classic dependency confusion attack, and a hand-edited lockfile can point one package at any host. The control checks every new or changed lockfile entry, so a lockfile changed on its own is checked too.
  • Dependencies taken from a git repository, a URL or a local path, which bypass the registry and the checks that come with it.
  • pip index options that add or replace package indexes, or turn off TLS checks.

It runs inside the dependency scan, so it needs no extra job. In the policy it is the Dependency sources row of the Checks tab (API: controls.sources). The registries and choices are company settings (the company's Scanning tab → Dependencies, card Dependency sources), which a policy can override.

How it checks​

  1. The changed files of the merge request are listed (deleted files are skipped; a deleted lockfile still counts as a changed lockfile).
  2. Each changed dependency file is read at the merge base (the target branch, or the file's old path when it was renamed) and at the merge request's head commit. A new file has no base: all its entries are new.
  3. Only entries that are new or changed at the head count: an entry whose package, version, kind of source, host, address and ref are all the same as in the base is not checked again. Index options that are already in the base are not checked again either.
  4. Each new or changed entry is checked against the rules below and the settings.

The company's (or policy's) dependency scan path filters apply: a file outside the allowed paths, or inside the blocked paths, is not read (see Dependency scan).

Rules​

RuleLabel on the merge requestWhat is foundWhy it matters
lockfile-missing-updateLockfile not updatedA manifest changed, its lockfile exists at the head commit, and the lockfile did not change. A package.json or go.mod whose dependencies are the same as before is not a finding (see below). When the repository keeps no lockfile for the manifest, there is no findingThe installed versions come from the lockfile; the manifest change is either not applied or applied without review
registry-not-allowedRegistry not allowedA new or changed lockfile entry fetched from a host that is not an allowed registry for its ecosystemDependency confusion: a package of the same name on another registry, or a lockfile entry pointed at another host
source-gitGit sourceA dependency taken from a git repository (unless git dependencies are allowed)It bypasses the registry; its content is whatever the repository holds at that ref
source-urlURL sourceA dependency downloaded from an archive URL (unless URL dependencies are allowed)It bypasses the registry; the address can serve other content later
source-pathLocal pathA dependency taken from a local path or a link: a file: or link: dependency, a directory dependency, a go.mod replace whose target is a ./ or ../ directory (unless local path dependencies are allowed)The code comes from the repository or the machine running the build, not from a published package
extra-index-urlExtra indexA requirements file adds --extra-index-url for a host that is not an allowed PyPI registrypip may install a package of the same name from either index: pip's own documentation calls this unsafe, a dependency confusion risk
index-url-not-allowedIndex not allowedA requirements file's -i / --index-url / --pypi-url, or a Pipfile.lock source, points at a host that is not an allowed PyPI registryEvery package is then fetched from that index
find-linksFind-linksA requirements file's -f / --find-links points at a host that is not allowed, or at a local directory (a local directory passes when local path dependencies are allowed)pip looks for packages at that location too
trusted-hostTrusted host (no TLS check)A requirements file's --trusted-hostpip then fetches from that host "even though it does not have valid or any HTTPS": packages arrive without TLS verification. It is a finding whatever the host
source-unknown-formSource unknown (review)An entry whose source is written in a form Merge Pilot does not read (see Formats)Informational: it is listed so someone looks at it, and never fails the check. When the entry names a host that is not allowed, it is reported as registry-not-allowed instead

Packages of the same workspace (yarn workspace:, uv virtual, and npm links to a folder inside the repository) are built from the repository itself and are not findings. A local path counts only when it is new to the merge request: a version bump of the project's own crate or package is not a finding. A yarn patch: entry is a local patch over another package and is not checked.

A manifest changed without its lockfile​

A manifest is paired with the lockfiles its package managers write next to it, in the same directory:

ManifestLockfiles
package.jsonpackage-lock.json, npm-shrinkwrap.json, yarn.lock, pnpm-lock.yaml, bun.lock
pyproject.tomlpoetry.lock, uv.lock, pdm.lock
PipfilePipfile.lock
Cargo.tomlCargo.lock
GemfileGemfile.lock
composer.jsoncomposer.lock
go.modgo.sum
  • When any of the paired lockfiles changed in the merge request (or was deleted), there is no finding.
  • Otherwise each paired lockfile is looked up at the head commit. When none exists, the project keeps no lockfile and there is no finding. When some exist, the finding names them.
  • The same dependencies: for package.json, a change that leaves the dependencies, devDependencies, optionalDependencies, peerDependencies, bundleDependencies (or bundledDependencies) and overrides sections as they were (only the scripts, the version or other fields changed) is not a finding. For go.mod, a change that leaves the require, replace and exclude directives as they were (only the go or toolchain line changed) is not a finding. Other manifests count on any change.

Registries​

A registry entry is allowed when its host is on the allow-list of its ecosystem: the public registries below, plus the company's (or policy's) own, unless Only the listed registries is on.

EcosystemPublic registries allowed by default
npm (npm, yarn, pnpm)registry.npmjs.org, registry.yarnpkg.com
PyPI (pip, Pipenv, Poetry, uv)pypi.org, files.pythonhosted.org
crates.iogithub.com/rust-lang/crates.io-index, index.crates.io
RubyGemsrubygems.org
Packagistrepo.packagist.org, api.github.com, github.com
  • An entry is host, host:port or host/path. The host (and port) must match exactly, ignoring case; a path, when given, must be the address's path or a parent of it. So github.com/rust-lang/crates.io-index allows that one index on github.com, not every repository there. A scheme (https://) and a trailing slash are dropped when the entry is saved; credentials, a query or wildcards are refused.
  • An entry whose lockfile names no host is fetched from the package manager's configured registry, which the lockfile does not record. It is not checked against the list: pnpm entries with only an integrity hash, yarn (berry) npm: entries, Poetry packages without a source, Pipfile.lock packages without an index, and yarn (classic) or npm (version 1) entries without a resolved address.
  • Packagist: composer.lock records a download and a repository address for every package, Packagist ones included. Both are checked as registry hosts (not as git or URL sources), which is why api.github.com and github.com are allowed by default. A path package is a local path.
  • Go has no registry check: where Go modules are downloaded from is set on the machine that builds, not in the repository. Only a replace to a local directory is checked.

Files read​

FileWhat is read
package-lock.json, npm-shrinkwrap.jsonVersion 2 and 3: each package's resolved address and link flag. Version 1: each dependency's version (git, tarball, file: sources) and resolved address. The project itself is skipped
package.jsonDependencies named by git (git+…, github:…), an http(s) tarball, file: or link:, in dependencies, devDependencies, optionalDependencies and peerDependencies. Version ranges are resolved through the registry, which only the lockfile records
yarn.lock (classic)Each entry's resolved address; file: and link: entries; offline-mirror tarballs as local paths
yarn.lock (berry)npm: (with its archive address when the lockfile has one), git #commit=, workspace:; other protocols are an unknown form
pnpm-lock.yamlEvery document of the file: integrity-only entries, tarball addresses (git-hosted ones as git), type: git, type: directory, and link: dependencies of the importers; other resolution types are an unknown form
requirements*.txtEach requirement (registry, name @ URL, git VCS URLs, archive URLs, local paths, -e) and the options -i / --index-url / --pypi-url, --extra-index-url, -f / --find-links, --trusted-host. Other VCS schemes are an unknown form. Files named with -r or -c are not followed: they are read only when they changed in the merge request too, and are named requirements*.txt
Pipfile.lockThe sources in _meta.sources, and each package's index, git, file or path
poetry.lockEach package's [package.source]: none (PyPI), legacy (a registry), git, directory, file, url
uv.lockEach package's source: registry, git, url, path, directory, editable (a local path), virtual (the workspace)
Cargo.lockEach package's source: registry+…, sparse+…, git+…. A package without a source (the project's own crates and path dependencies) counts as a local path
Gemfile.lockThe GEM, GIT and PATH sections. A PLUGIN SOURCE, or a GEM section with several remotes, is an unknown form whose hosts are still checked
composer.lockEach package's download (dist) and repository (source) addresses, and path packages
go.modreplace directives whose target is a local directory

bun.lock and pdm.lock count for lockfile pairing only: their sources are not read, because their format could not be verified from their publishers' documentation.

Limits​

  • At most 20 changed dependency files are checked per merge request. When more are changed, the first 20 are checked and the check fails, saying so; with the company's More … than the limits set to check the first ones, it checks those and names what it did not look at instead.
  • A file over 5 MB, or with more than 50,000 entries, fails the check; nothing is cut short.
  • A file that cannot be read or does not parse at the head commit fails the check. A base version that does not parse is read as empty: every head entry is then checked.
  • When the VCS lists only part of the changed files, the check fails: a changed dependency file may have been missed. With the company's The VCS lists only part of the changed files set to Check what was listed, it checks the files listed instead.
  • Credentials in an address (user:password@, a token) are removed before anything is stored, and the query string and fragment are dropped from the addresses shown. A finding names the host.

The 20-file limit and a cut-short file list follow the company's When a scan cannot see everything (see Scanning), as the dependency scan does; a policy can set its own. A check failed this way is final: it is not retried by itself, and says Trying again would not change this. What a check left out is named in the control's reason (Not looked at: …).

A failed check fails the control, never passes it. What happens next follows the dependency scan's When the scan cannot finish setting (see Dependency scan).

Modes​

Mode (label in the UI)API valueWhat it doesEffect on the merge gate
OffoffSources are not checkedNone
ReportreportFindings are shown on the merge request, marked (report only)None
EnforceblockFindings hold the mergeWaiting while the scan runs; Blocked on a finding (informational ones excepted) or a check that could not be completed

A new policy starts with Report. A policy saved without a mode (for example through the API) is saved with Report.

Settings​

Company admins change the company's settings on the Scanning tab, section Dependencies, card Dependency sources (PUT /api/v1/companies/{id} with scanning.sources). The policy editor shows the overrides under the Dependency sources row; each starts on Company setting (…).

Setting (label in the UI)What it doesDefaultAllowed valuesSet whereWho can change itAPI field
Mode (row Dependency sources)See ModesReportOff, Report, EnforcePolicyPolicy managers, company admins, platform adminscontrols.sources.mode (off, report, block)
Private registries: npm registries, PyPI registries, crates.io registries, RubyGems registries, Packagist registries (policy editor: Registries, then Company setting (…) or This policy's list)Registries your package managers use besides the public ones. A lockfile entry fetched from any other host is a findingEmpty (the public registries only)host, host:port or host/path, one per line (policy editor: separated by commas)Company; policy overrideCompany: company admins, platform admins. Policy: policy managers, company admins, platform adminsscanning.sources.registries; controls.sources.overrides.registries (a map per ecosystem: npm, PyPI, crates.io, RubyGems, Packagist)
Only the listed registries (policy editor: Public registries, Allowed / Not allowed (only the listed ones))The public registries are not allowed either, in every ecosystem: list each registry that is (for example a mirror that proxies the public one)OffOn, offCompany; policy overrideSamescanning.sources.replace_defaults; controls.sources.overrides.replace_defaults
Allow git dependencies (policy editor: Git dependencies, Flag them / Allow them)A dependency taken from a git repository is not a findingOffOn, offCompany; policy overrideSamescanning.sources.allow_git; controls.sources.overrides.allow_git
Allow URL dependencies (policy editor: URL dependencies)A dependency downloaded from an archive URL is not a findingOffOn, offCompany; policy overrideSamescanning.sources.allow_url; controls.sources.overrides.allow_url
Allow local path dependencies (policy editor: Local path dependencies)A dependency taken from a local path or link is not a finding, nor is a --find-links to a local directoryOffOn, offCompany; policy overrideSamescanning.sources.allow_path; controls.sources.overrides.allow_path
Packages left outThe check does not look at where these packages come fromEmptyPackage names, one per line (policy editor: separated by commas), * wildcards (@corp/*), matching ignores case; no spacesCompany; policy overrideSamescanning.sources.allowed_packages; controls.sources.overrides.allowed_packages

Notes:

  • A policy's Registries list replaces the company's registries as a whole (all ecosystems); the policy's own Packages left out list (even empty) replaces the company's list.
  • An ecosystem other than the five above, or an entry that is not a host, host:port or host/path, is refused when it is saved (Each line must be a host, host:port or host/path, without credentials, a query or wildcards.).
  • Packages left out applies to package entries; it does not silence lockfile-missing-update or the pip index options.
  • Settings take effect at the next scan (a new commit or a re-scan).

What the control says​

StatusMessage
PendingChecking where new dependencies come from.
PassedNew dependencies come from allowed sources. (with N entr(ies) of a form Merge Pilot cannot tell the source of; review them. when there are informational findings)
FailedN dependency source finding(s) (rule count, …)., such as 2 dependency source finding(s) (registry-not-allowed 1, source-git 1).
FailedThe dependency source check could not be completed: … Fix the cause and rescan.
FailedThe dependency scan could not be completed: … Fix the cause and rescan.

When it runs​

With the dependency scan: once per commit when the policy runs the dependency scan, licenses, package health or dependency sources; on Re-scan dependencies on the merge request page (POST /api/v1/merge-requests/{id}/rescan with {"scan": "sca"}); and after a failure when the company or policy retries automatically. A scan of the latest commit made while the control was off runs again once the policy turns it on. See Dependency scan.

What the merge request shows​

  • In the Dependency scan (SCA) card, a Dependency sources section: New dependencies come from allowed sources., Could not be checked: …, or each finding with its label, package, host, file:line and explanation. The first 100 findings are kept on the merge request (failing ones first; Showing N of M. when there are more); the full scan result keeps up to 5,000.
  • The Merge Pilot: Dependency Scan comment in the VCS gets a Dependency sources section: the number of findings (and how many are to review (source form not known)) and a table of rule, package, host, file and finding, or could not be checked: ….
  • Policy card and status comment: the Dependency sources line.
  • My Work: a merge request held by this control is listed with the reason Dependency sources failed (sources_blocked). See My Work.

GitLab and GitHub​

The check is the same on both.

Audit log​

ActionWhen
dependency_sources_detectedThe check found dependency source findings, informational ones included (written again when their number changes). Details: the repository, the merge request number, the findings that fail the check, the informational ones, the count per rule and the files checked
sca_rescanSomeone started the dependency scan again

See Audit log.

API fields​

WhereFieldMeaning
Policycontrols.sources.modeoff, report or block
Policycontrols.sources.overridesregistries, replace_defaults, allow_git, allow_url, allow_path, allowed_packages; absent or null: the company's
Companyscanning.sourcesThe same fields, the company defaults
Merge requestsca_scan.sources.statusclean (nothing that fails the check; informational findings may be listed), findings or failed
Merge requestsca_scan.sources.count, .informational, .by_ruleThe findings that fail the check, the informational ones, and the count per rule
Merge requestsca_scan.sources.findings[]file, line, package, version, ecosystem, rule, host, url, message
Merge requestsca_scan.sources.files_checked, .errorThe dependency files read; why the check could not be completed
Scan resultsource_findings[]Every finding of the scan (up to 5,000), from GET /api/v1/companies/{id}/sca-results/{resultId}
Merge requestdecision.controls[] with control: "sources"The control's status, blocking and reason

Video tutorial

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

Stop Dependency Confusion with Allowed RegistriesYouTube ↗