Skip to main content
2 video tutorials

Scanning

The company's Scanning tab holds the company defaults of every scan Merge Pilot runs on merge requests, and the settings of the vulnerability inventory that follows each project's default branch. Company defaults for the scans; whether a merge request is scanned, and whether a finding holds it, is set per change policy.

A scan runs only where a change policy turns its control on (Report or Enforce); see Controls. Some of the settings below can be taken over by a policy for the changes it covers (Company settings and policy overrides).

Where to find it​

Administration → Company (platform admins: Administration → Companies → the company), tab Scanning. The company page opens for company admins and platform admins only.

The tab has seven sections, chosen with the buttons at the top: Secrets, Dependencies, CI configuration, Container images, Infrastructure, Commits and When a scan cannot see everything.

The settings are saved with Save changes in the bar at the bottom of the company page, together with the other tabs (PUT /api/v1/companies/{id}): the scan settings as the scanning object, the vulnerability inventory settings as the vulnerabilities object. Each object is saved as a whole: a field left out takes its default.

Whether watched repositories are scanned at all is set on the Repositories tab (Scan watched merge requests for secrets, vulnerable dependencies and licenses); see Repositories settings.

File patterns on this tab are read the same way everywhere: One per line. A pattern without "/" matches a file or folder name anywhere ("*.test.go", "testdata"); one with "/" is read from the repository root ("docs/**", "/scripts"). "**" spans folders.

Secrets​

The company defaults of the Secret scan control. Every field is documented in Secret scan → Settings.

CardSettings
Detection settingsEnable custom detection rules, Max findings per scan (default 50), External call timeout (seconds) (default 30)
BehaviourFiles the VCS sends no diff for, "gitleaks:allow" comments, When the scan cannot finish, Lowest severity that holds a merge (default Low (every finding): findings below it are listed on the merge request but do not hold it), Scan commit messages and the merge request description, Decoding depth (default 5)
Allowed pathsFiles that are not scanned
Allowed rulesRules that are not run, listed as Custom rules (mp-) and built-in rules, with a search and Select all / Deselect all. Custom rules can be ticked only while Enable custom detection rules is on

API: scanning.secrets.

Dependencies​

Six cards: Dependency vulnerability scanning, Vulnerability tracking, Path filters, Licenses, Package health and Dependency sources.

Dependency vulnerability scanning​

Scan merge request dependencies for known vulnerabilities using OSV.dev. The company defaults of the Dependency scan control: Vulnerabilities without a rating, When the scan cannot finish, Vulnerabilities exploited in the wild (CISA KEV), Hold from exploitation likelihood (EPSS, %), Max dependencies per scan, Max vulnerabilities stored and External call timeout (seconds) are documented in Dependency scan → Settings.

Two more fields on this card do not affect merge requests. They bound the project analysis (Run analysis on a project's Security tab, and the analyses run after a merge or a direct change touches a dependency manifest of the default branch) and the advisory check of the vulnerability inventory (below):

Setting (label in the UI)What it doesDefaultAllowed valuesSet whereWho can change itAPI field
Max dependencies per project analysisHow many dependencies one project analysis, and one advisory check, looks up. The number is shared evenly among the project's manifests. An analysis that finds more checks only this many and is marked incomplete (max_deps_exceeded, with the number of dependencies not checked)20,0000 to 20,000 (0: the default)CompanyCompany admins, platform adminsscanning.sca.analysis_max_dependencies
Project analysis timeout (seconds)How long each lookup of a project analysis and of the advisory check may take (vulnerability and license lookups). They ask about many more packages than a merge request's scan900 to 600 (0: the default)CompanyCompany admins, platform adminsscanning.sca.analysis_timeout_seconds

Vulnerability tracking​

Each registered project's default branch has a vulnerability inventory (Insights → Vulnerabilities): what affects it, since when, and which merge request brought it in. The inventory of a project starts with its first project analysis; this card sets how it is kept up to date and how long its history is kept.

Setting (label in the UI)What it doesDefaultAllowed valuesSet whereWho can change itAPI field
Update it when a merge request that changes a dependency manifest, a file that refers to container images or an infrastructure file mergesAfter a merge into the default branch that changed such a file (image and infrastructure files only while their inventory below is on), the project's default branch is analysed again (job vuln_refresh), and new findings are attributed to that merge request. Imported past merge requests never start oneOnOn, offCompanyCompany admins, platform adminsvulnerabilities.analyse_on_merge
Follow the container images the default branches refer toEach analysis and advisory check scans the images in Dockerfiles, Kubernetes manifests, Helm values and Compose files. Their vulnerable packages are findings in the inventory (see Vulnerability inventory), whether or not a policy runs the container image scan on merge requests. Turned off and saved, the image findings (open and fixed: that inventory's history) and what was read of the images are deleted (audit vulnerability_inventory_cleared), and analyses, advisory checks, merges and direct changes no longer scan images. Turned on again, the next analysis starts a new baseline: what it finds is not announcedOnOn, offCompanyCompany admins, platform adminsvulnerabilities.image_inventory
Follow the default branches' infrastructure filesEach analysis checks Terraform, Dockerfiles, Kubernetes and Helm files for misconfigurations. They are kept as infrastructure findings, whether or not a policy runs the infrastructure check on merge requests. Turned off and saved, the infrastructure findings (open and fixed) and what was read of the files are deleted (audit vulnerability_inventory_cleared), and analyses, merges and direct changes no longer check them. Turned on again, the next analysis starts a new baselineOnOn, offCompanyCompany admins, platform adminsvulnerabilities.iac_inventory
Check the dependencies in use for new advisories every (hours)Without reading the repositories: only the advisory database is asked. Each project with a known dependency list has its dependencies looked up again when its last check is older than this; a new advisory for a version in use becomes a finding. 0 turns it off240 to 720CompanyCompany admins, platform adminsvulnerabilities.advisory_check_hours
Longest exception (days)An accepted or not-affected vulnerability is held for review again after at most this many days. A vulnerability exception (on the Vulnerabilities page) cannot end later than the end of the day that is this many days from today, in the company's time zone (an exception lasts at most N days: the latest expiry is the end of <date> (<time zone>)); when it ends, the vulnerability counts again901 to 730 (API: 0 takes the default)CompanyCompany admins, platform adminsvulnerabilities.exception_max_days
Keep fixed vulnerabilities, old analyses and direct changes (days)Once a day, fixed vulnerabilities, ended or revoked exceptions and the details of older analyses (their summaries stay; the latest completed analysis of each project keeps its details, the SBOM's source) are deleted after this many days. Open and accepted vulnerabilities are always kept. Direct changes older than this are removed too. See How long direct changes are kept36530 to 3,650 (API: 0 takes the default)CompanyCompany admins, platform adminsvulnerabilities.retention_days

The advisory check runs in the background, at most 200 projects per company per round, the oldest checked first. It does not run for an inactive company; that company's exceptions still expire. It needs no VCS calls. When a lookup fails, nothing is concluded and the next round tries again.

Who is told about new vulnerabilities on default branches is set on the company's Notifications tab, What is announced → New vulnerabilities on default branches: Critical only, High and above (the default), Medium and above, Low and above, Every severity, unrated too or Never (API vulnerabilities.notify_min_severity: critical, high, medium, low, unknown, none). They are announced as the vulnerability_found event: one message for each round of checks, naming the projects and the worst findings first, linked to the vulnerability inventory (see Events).

A direct change to a dependency manifest on the default branch can also refresh the inventory: see Refresh the vulnerability inventory when one changes a dependency manifest in Repositories settings.

Path filters​

Allowed paths and Blocked paths: which dependency manifests the dependency scan reads. See Dependency scan → Settings. API: scanning.sca.allowed_paths, scanning.sca.blocked_paths.

Licenses​

Denied licenses, Allow only the licenses below, Allowed licenses and Licenses that cannot be checked: the company defaults of the Licenses control. See Licenses → Settings. API: scanning.licenses.

Package health​

Minimum version age (days) and Flag deprecated versions: the company defaults of the Package health control. See Package health → Settings. API: scanning.packages.

Dependency sources​

Where the dependencies a change adds may come from: the registries allowed per ecosystem, and whether git, URL and local path dependencies are allowed. Checked in the dependency scan when a policy turns dependency sources on. The company defaults of the Dependency sources control:

  • Private registries: one list per ecosystem (npm registries, PyPI registries, crates.io registries, RubyGems registries, Packagist registries), each showing the public registries allowed by default. Add the registries your package managers use besides the public ones: a host, host:port or host/path per line.
  • Only the listed registries: the public registries are not allowed either, in every ecosystem.
  • Allow git dependencies, Allow URL dependencies, Allow local path dependencies (all off by default).
  • Packages left out: package names, * wildcards, whose sources are not checked.

See Dependency sources → Settings. API: scanning.sources.

CI configuration​

Card CI configuration: What the CI configuration check (a policy control) accepts in changed GitHub Actions workflows and GitLab CI configuration. Three settings: Actions that need not be pinned (GitHub; default actions/* and github/*), GitLab includes that need not be pinned (empty by default) and Images allowed without a digest (GitLab; empty by default). See CI configuration check → Company default. API: scanning.workflows.

Container images​

Card Container images: what the container image scan (a policy control) does with the images a change starts referring to. Settings: Hold for vulnerabilities without a fix (off by default), Image references that cannot be resolved (Fail the scan by default, or List only), Vulnerabilities without a rating (Listed, never held by default, Count them as high, or Always hold), Images not scanned, Platform (linux/amd64), Max new images per change (20) and Internal hosts. See Container image scan → Company default. API: scanning.images.

Container registries​

Card Container registries: the sign-ins the container image scan uses to pull images from private registries. Public images need none. Add registry adds one:

Field (label in the UI)What it is
NameA name for the registry
HostThe registry's address, host or host:port, no path: ghcr.io, registry.gitlab.example.com, 123456789012.dkr.ecr.eu-west-1.amazonaws.com, europe-docker.pkg.dev, docker.io (Docker Hub, under any of its names). One sign-in per host
Sign-inUser name and password or token; Amazon ECR (access key): an access key ID and secret access key, turned into an ECR token for each scan, with an optional Region (taken from the host when empty); Google Artifact Registry (service account key): a service account key (JSON), turned into an access token for each scan
CA certificateA PEM certificate trusted besides the system CAs, for a registry with a private CA
Skip TLS verificationThe registry's certificate is not checked. Prefer adding its CA certificate

Use a token that can only read the registry: on GitLab a deploy token or access token with read_registry, on GitHub a token with read:packages, on Google a service account with Artifact Registry Reader. The password, key or token is stored encrypted and never shown again (Configured); it is kept when the field is left empty, as long as the host, sign-in kind and user name stay the same: a stored secret is never sent to another registry. Test signs in to the registry as a scan would and says whether it worked (audited as registry_test). A sign-in is used for its own registry only.

API: registries in PUT /api/v1/companies/{id} (the list replaces the stored one); POST /api/v1/companies/{id}/test-registry tests one.

Infrastructure​

Card Infrastructure: what the infrastructure check (a policy control) looks at. Settings: File types checked (all by default), Changed files that cannot be checked (Fail the check by default, or List only), Checks left out, Files not checked and Max infrastructure files per change (50). See Infrastructure check → Company default. API: scanning.iac.

When a scan cannot see everything​

Section When a scan cannot see everything: what the dependency, license, package health, source, CI configuration, image and infrastructure scans do when they cannot look at all of a change. The secret scan has its own choices (Behaviour card). A policy can set its own for each.

Setting (label in the UI)What it doesDefaultAllowed valuesAPI field
The VCS lists only part of the changed filesA change too large for the VCS to list whole. The scans fail: held wherever a scan holds; a rescan does not change it, so it is not retried by itself. Check what was listed and say what was not: the scans check the files the VCS listed and say that others may have been missedThe scans failfail, notescanning.coverage.incomplete
More images, infrastructure files or dependencies than the limitsThe scan fails (not retried by itself). Check the first ones up to the limit and say how many were left out. Also covers the image scan's limit of 100 files that may name images and the CI configuration check's limit of 50 changed CI configuration filesThe scan failsfail, notescanning.coverage.over_limit
An image, infrastructure or CI configuration scan could not completeWait for a rescan, or Try again after a pause. A scan failed by a limit or a cut-short file list is never retriedWait for a rescanmanual, retryscanning.coverage.on_error
Risk of a change the VCS listed only in partIts size and paths are not fully known. Unknown: held wherever risk holds, or counted as a risk level (low, medium, high, critical). The merge request says which. During a change freeze that raises the risk, the change stays critical whatever is chosen hereUnknownhold, low, medium, high, criticalscanning.coverage.unreadable_risk

The dependency source check follows The VCS lists only part of the changed files and More … than the limits as the dependency scan does. A scan failed only by a cut-short file list or a limit says Trying again would not change this: change the merge request or the company's scan settings, then use rescan, instead of saying that Merge Pilot tries again. With Check what was listed or Check the first ones up to the limit, what the scan left out is named in the control's reason (Not looked at: …).

Commits​

Card Signed commits: Who the signed-commits check (a policy control) leaves out. One setting, Authors that need not sign (empty by default). See Signed commits → Company default. API: scanning.signatures.exempt_authors.

Validation​

Saving is refused, with the reason, when:

  • a limit or timeout is negative or above its maximum (… must be between 0 (the default) and …);
  • Decoding depth is not 0 to 10, or Minimum version age (days) not 0 to 365;
  • a license entry is not an SPDX license id, or an allowed license uses a wildcard;
  • an Actions that need not be pinned entry is not owner/* or owner/repo, a GitLab includes that need not be pinned entry has no / or holds a space or @, or an Images allowed without a digest entry is empty or holds a space;
  • a registry entry is not a host, host:port or host/path (Each line must be a host, host:port or host/path, without credentials, a query or wildcards.), or a Packages left out entry holds a space;
  • a file pattern is not valid;
  • Platform is not os/arch or os/arch/variant, an Internal hosts entry is not a host or host:port, Max new images per change is not 0 to 100 or Max infrastructure files per change not 0 to 500;
  • a container registry has no name or host, a host with a path, a host another registry already has, no user name or access key ID where its sign-in needs one, a CA certificate that is not PEM, or no password, key or token (also when its host, sign-in kind or user name changed: the stored one is not kept then);
  • Check the dependencies in use for new advisories every (hours) is not 0 to 720, Longest exception (days) not 1 to 730, or Keep fixed vulnerabilities, old analyses and direct changes (days) not 30 to 3,650.

When changes take effect​

  • Scan settings: at the next scan of a merge request (a new commit or a re-scan); a few are applied at the next evaluation without a new scan. Each control's page says which.
  • Max dependencies per project analysis and Project analysis timeout (seconds): at the next project analysis or advisory check.
  • Check the dependencies in use for new advisories every (hours): at the next round of the background check.
  • Longest exception (days): for exceptions made afterwards; existing exceptions keep their end date.
  • Keep fixed vulnerabilities, old analyses and direct changes (days): at the next daily clean-up.

API fields​

FieldValues
scanning.secretsSee Secret scan
scanning.scaSee Dependency scan; also analysis_max_dependencies (0 to 20,000) and analysis_timeout_seconds (0 to 600)
scanning.licensesSee Licenses
scanning.packagesSee Package health
scanning.sourcesregistries, replace_defaults, allow_git, allow_url, allow_path, allowed_packages. See Dependency sources
scanning.workflowspin_allowed, include_allowed, image_allowed. See CI configuration check
scanning.coverageincomplete, over_limit (fail, note), on_error (manual, retry), unreadable_risk (hold, low, medium, high, critical). See When a scan cannot see everything
scanning.imagesblock_unfixed, unresolved (fail, note), unknown_severity (show, high, block), skipped_images, platform, max_images (0 to 100), internal_hosts. See Container image scan
scanning.iactypes, unchecked (fail, note), skipped_checks, skipped_paths, max_files (0 to 500). See Infrastructure check
registriesSee Container registries
scanning.signatures.exempt_authorsSee Signed commits
vulnerabilities.analyse_on_mergetrue (default), false
vulnerabilities.image_inventory, vulnerabilities.iac_inventorytrue (default), false
vulnerabilities.advisory_check_hours0 to 720 (default 24; 0: off)
vulnerabilities.notify_min_severitycritical, high (default), medium, low, unknown, none
vulnerabilities.exception_max_days1 to 730 (default 90)
vulnerabilities.retention_days30 to 3,650 (default 365)

Video tutorials

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

Keep Unwanted Licenses OutYouTube ↗
Keep Deprecated Packages OutYouTube ↗