Vulnerability inventory
The vulnerability inventory answers what known vulnerabilities do our default branches depend on right now, since when, and which change brought each in? Merge Pilot keeps one for each project, follows each vulnerability from when it is first seen until it is fixed, and keeps the record afterwards as evidence.
For a short overview of what it is for, see the Vulnerability tracking & SBOM feature page.
It is read on Insights → Vulnerabilities for the whole company, and on a project's Security tab (Dependencies view) for one project. The settings that keep it up to date are on the company's Scanning tab (see Scanning → Vulnerability tracking).
What a finding is
A finding is one advisory affecting one package version on one project's default branch: for example GHSA-xxxx in lodash@4.17.20 of acme/web. The same advisory in two projects, or in two versions of a package, is two findings.
Each finding records:
- the package, its version and ecosystem, the manifests it is in, whether the project names it itself or it comes in through another package (transitive), and its dependency groups (such as
dev) when it is used only for development; - the advisory: its ID and aliases (CVE, GHSA…), summary, severity, the version that fixes it, a link, and the Malicious, Exploited (KEV) and EPSS marks;
- its status (Open or Fixed), and the exception that accepts it, if any;
- when it was first and last seen, and when it was fixed;
- what brought it in and what fixed it (below).
Severities are Critical, High, Medium, Low and Unrated (the advisory gives none).
Container images
The packages of the container images the default branch refers to (Dockerfile FROM lines, Kubernetes manifests, Helm values, Compose files) are findings too, whether or not a policy runs the container image scan, while the company's Follow the container images the default branches refer to is on (the default; see Scanning): each analysis reads those files and scans their images. Turned off, the image findings (open and fixed) are deleted and images are no longer scanned; turned on again, the next analysis is their new baseline. Their ecosystem is image/ and the package type (image/alpine, image/debian, image/python-pkg, ...), and the place they are used is the image (docker.io/library/alpine:3.21), not a manifest. They follow the same rules as dependencies, with these differences:
- the advisory check scans the images of the last analysis again (it does not read the repository): a vulnerability published for an image already in use appears without a change;
- a finding is fixed when the branch no longer refers to the image, or the image no longer has the package version; an image that could not be scanned keeps its findings;
- the first analysis that reads a project's images is their baseline, even when the project's dependencies had one before; an image that could not be scanned until now is part of that baseline once it can be.
See Container image scan → The default branch's images. The default branch's infrastructure files are followed separately: see Infrastructure check → The default branch's infrastructure.
How findings are opened
The inventory of a project starts with its first project analysis, whether a company admin ran it or a merge or a direct change started it. That first analysis is the inventory's baseline: what it finds was already on the branch, so its findings are marked Found by an analysis (a finding the merge request that started it is known to have brought is credited to it), none of them counts as new, and none is announced. From then on four things look at the default branch again:
| What | When | A new finding is marked |
|---|---|---|
| Run analysis | A company admin starts an analysis on the project's Security tab | Found by an analysis |
| A merge | A merge request that changed a dependency manifest, a file that may refer to container images or an infrastructure file (those two only while their inventory is on) merged into the default branch, while Update it when a merge request that changes a dependency manifest, a file that refers to container images or an infrastructure file merges is on. Imported past merge requests never start one | With the merge request, when that merge request added the package version or moved to it; otherwise New advisory |
| A direct change | A push without a merge request changed a dependency manifest, a file that may refer to container images or an infrastructure file (those two only while their inventory is on) on the default branch, while Refresh the vulnerability inventory when one changes a dependency manifest is on (see Direct changes) | With the direct change, when the push added the package version or moved to it; otherwise New advisory. When the company does not record direct changes, the push is still named, by its branch and commit (there is no recorded change to open) |
| The advisory check | Every Check the dependencies in use for new advisories every (hours) (24 by default). The dependencies recorded at the last analysis are looked up again; the repositories are not read | New advisory: a new advisory for a version already in use |
A merge or direct change is credited only with the package versions it brought; touching the same lockfile is not enough. A vulnerability published after the version was already in use is a New advisory, not the fault of a change.
A finding that was fixed and comes back (a downgrade, a revert) is opened again, without its fix.
New findings are announced (never those of the baseline) as one digest per round of checks, naming the projects and the worst findings first and linking to the vulnerability inventory, to the company's notification routes that take New vulnerability on a default branch (vulnerability_found; see Events), from the severity the company chooses (by default High and above). Findings already accepted by an exception are not announced. See Scanning → Vulnerability tracking.
How findings are fixed
A finding is Fixed when a run shows it is gone:
- the package version is in none of the manifests it was in, each of them read again (or gone from the branch's file list): the package was upgraded or removed, or
- the package version was looked up again in this run and the advisory no longer lists it (for example, the advisory was corrected or withdrawn).
What a run did not look at proves nothing, so a finding stays open when its manifest could not be read, was left out by a limit, or its lookup failed. The advisory check, which reads no manifests, can fix a finding only by looking its version up again.
When a merge or a direct change fixes a finding, the finding's details name it: by !42 (the merge request, linked) or fixed by direct change 1a2b3c4d (linked to the direct change when the company records direct changes). A direct change is never shown as a merge request.
Aliases
The same vulnerability often has several IDs (a GHSA and a CVE, for example), and the database can change which one it prefers. A finding is matched by its advisory ID or any of its aliases, so a change of the preferred ID neither opens a second finding nor fixes the first one.
Insights → Vulnerabilities
Insights → Vulnerabilities. The tab is shown to company admins, policy managers, auditors and platform admins; platform admins pick the company in the header first (Pick a company in the header to see its vulnerability inventory.).
Advisories affecting the default branches of the company's projects, followed from when each was first seen until it is fixed, with the merge request that brought it in.
From top to bottom:
-
Waiting changes (only with four-eyes review on and something waiting): exceptions and revocations waiting for a second person. See Vulnerability exceptions.
-
Counters:
Counter (label in the UI) Counts Open Open findings not accepted by an exception, with the count per severity New and still open, 7 days Findings first seen in the last 7 days and still open, not accepted, and not part of a project's baseline (the list's Open status with New in the last 7 days shows the same ones), with N in 30 days. A project's first analysis therefore does not make its findings look new Fixed in 30 days Findings fixed in the last 30 days Open with a fix available Open findings not accepted whose advisory names a fixed version, with in N projects: the projects that have such a finding -
Packages with the most open vulnerabilities: up to ten packages, with their worst severity and the number of open findings.
-
Inventory: the list (below).
-
Exceptions in force: see Vulnerability exceptions.
The list
The same list is on the company page (with a Project column) and on a project's Security tab, in the Dependencies view (one project, with its open, with a fix, new and still open, fixed in 30 days and accepted counts above it). There a line says what updates it, as the company set it: Merges that change a manifest, an image reference or an infrastructure file update it. or, with Update it when a merge request that changes a dependency manifest, a file that refers to container images or an infrastructure file merges off, Merges do not update it (Company → Scanning → Dependencies); running an analysis does., then the advisory check (The dependencies in use are checked for new advisories every N hours., or The check for new advisories is off (Company → Scanning → Dependencies).). It is paged by 25.
Filters
| Filter (label in the UI) | What it keeps | API parameter |
|---|---|---|
| Search (Package or advisory (CVE, GHSA)) | Packages whose name starts with the text, or the advisory whose ID or alias is exactly the text (case ignored) | q |
| Status | Open (the default: open, not accepted), Accepted by exception, Fixed, All | status: open, excepted, fixed, all |
| Minimum severity | Any severity, or Critical and above, High and above, Medium and above, Low and above | severity: critical, high, medium, low |
| Scope | Any scope, Ships with the project (used outside development groups somewhere), Development only | scope: runtime, dev |
| Manifest (Manifest path starts with) | Findings in a manifest whose path starts with the text | manifest |
| Has a fix | Findings whose advisory names a fixed version | has_fix=true |
| Exploited (KEV) | Findings in the CISA KEV catalog | kev=true |
| Brought in by a merge request | Findings credited to a merge request | from_merge=true |
| New in the last 7 days | Findings first seen in the last 7 days that were new then: not a project's baseline | since and new=true |
The API also filters by project_id, introduced_by (a merge request's ID), ecosystem, source (analysis, merge, advisory, direct), direct (true: named by the project itself; false: transitive), malicious, new (true: leaves out the baseline of each project's first analysis), and since / until (first seen, RFC 3339 times).
Columns
| Column (label in the UI) | Shows |
|---|---|
| Severity | Critical, High, Medium, Low or Unrated |
| Advisory | The advisory ID, linked to the advisory, with Malicious, Exploited (KEV) and EPSS N% badges |
| Package | package@version, the ecosystem, transitive when the project does not name the package itself, and the dependency groups (such as dev) |
| Project | The project, linked to its page (company list only) |
| EPSS | The exploitation probability, or a dash when the feed has none |
| Fixed in | The version that fixes it, or No fix yet |
| Status | Open, Accepted (an exception covers it) or Fixed |
| First seen | When it was first seen |
| Brought in by | The merge request (linked), Direct change 1a2b3c4d (linked to the direct change when it was recorded), or how it was found: Found by an analysis, Found after a merge, New advisory, Found after a direct change |
Severity, Advisory, Package, Project, EPSS, Fixed in and First seen sort the list when clicked (again to reverse). By default the worst severity comes first.
The arrow at the start of a row opens its details: the advisory's summary, Also known as (its aliases), In (the manifests), First seen …, last seen …, fixed … with the merge request or direct change that fixed it, and, for policy managers and administrators on an open finding without an exception, Accept or mark not affected (see Vulnerability exceptions).
No vulnerabilities match. when the filters leave nothing.
Download CSV
Download CSV exports the findings that match the current filters (all pages, worst first), as vulnerabilities-<date>.csv. At most 20,000 rows: a larger export holds the first 20,000 and says The file holds the first 20,000 findings only. Narrow the filters to export the rest.
Columns: Project, Advisory, Aliases, Severity, Exploited (KEV), EPSS, Ecosystem, Package, Version, Fixed in, Manifests, Direct, Scope, Status, Exception (its ID), First seen, Introduced by, Fixed at, Fixed by, Summary. Times are UTC. Text a spreadsheet would read as a formula starts with '.
KEV and EPSS
Each finding carries the Exploited (KEV) and EPSS marks of its advisory, matched by CVE (the advisory's ID or any of its CVE aliases; the highest EPSS of them). They are brought up to date whenever the finding is seen again: at the next analysis, merge, direct change or advisory check.
Above the list a line says how current they are:
| Line | When |
|---|---|
| Exploitation data: CISA KEV read <date>, FIRST EPSS read <date>. | The feeds have been read |
| Exploitation data (CISA KEV, FIRST EPSS) has not been read yet. | Not yet read since the installation started reading them |
| The last refresh failed, the earlier data is kept: … | The last refresh of a feed failed; the marks come from the earlier data |
| Exploitation data (CISA KEV, FIRST EPSS) is not read on this installation. | The installation does not read the feeds: no finding is marked |
The line ends with See EPSS at first.org/epss, the credit FIRST asks for. The feeds are CISA's Known Exploited Vulnerabilities catalog and FIRST's Exploit Prediction Scoring System; vulnerability data comes from OSV.dev.
How long findings are kept
Open and accepted findings are always kept. Fixed findings are deleted once a day after the company's Keep fixed vulnerabilities, old analyses and direct changes (days) (365 by default) have passed since they were fixed. See Scanning → Vulnerability tracking.
When a project is removed from Merge Pilot, its findings, recorded dependencies, analysis details and the exceptions made for that project alone are removed with it.
API
All paths start with /api/v1. Company admins, policy managers, auditors and platform admins may read them; other roles get 403.
| Request | What it does |
|---|---|
GET /companies/{id}/vulnerabilities | A page of findings, with the filters above, page, page_size (at most 100) and sort (severity, first_seen, package, project, fixed_in, fixed_at, advisory, epss; - in front for descending) |
GET /companies/{id}/vulnerabilities/summary | The counters: open (per severity), open_total, excepted, with_fix, new_7_days, new_30_days (open and not accepted), fixed_30_days, projects_with_fix (projects with an open, not accepted finding that has a fix), top_packages; project_id for one project |
GET /companies/{id}/vulnerabilities.csv | The CSV export, with the same filters. Headers X-Export-Truncated: true and X-Export-Limit: 20000 when it was cut |
GET /companies/{id}/vulnerabilities/feeds | Whether the KEV and EPSS feeds are read (enabled) and their status: kev_refreshed_at, epss_refreshed_at, kev_error, epss_error |
A finding has id, project_id, project_path, repo_id, vcs_connection_id, ecosystem, package, version, manifests, direct, scopes, advisory (id, aliases, summary, severity, fixed_in, url, malicious, kev, epss), has_fix, status (open, fixed), source (analysis, merge, advisory, direct), first_seen_at, last_seen_at, fixed_at, baseline (true: found by the project's first analysis, never new), introduced_by and fixed_by (id, number, title, merged_at), introduced_by_change and fixed_by_change (id, branch, after, pusher; no id when the company does not record direct changes), and exception_id.
The exceptions API is on Vulnerability exceptions.
Audit
Reading the inventory is not audited. What changes it is:
| Action | When |
|---|---|
analysis_triggered, project_analysis | An analysis was started by hand, or finished (see Project analysis) |
vuln_exception_created, vuln_exception_revoked, vuln_exception_expired | An exception changed (see Vulnerability exceptions) |
update_company | The company's vulnerability tracking settings changed |
See Audit log.
Related pages
- Project analysis: the runs that feed the inventory.
- Vulnerability exceptions.
- Scanning: how the inventory is kept and for how long.
- Dependency scan: the same lookups on merge requests.
- Jobs:
project_analysisandvuln_refresh.
Video tutorials
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →