Vulnerability exceptions
Not every known vulnerability can be fixed at once, and some do not apply: the vulnerable function is never called, or no fix exists yet and the risk has been weighed. A vulnerability exception records that decision, with the reason, for a limited time. While it is in force:
- merge requests that introduce the vulnerability are not held for it by the Dependency scan control;
- the vulnerability inventory shows the findings it covers as Accepted instead of Open, and they leave the open counts.
When it ends (expires or is revoked), the vulnerability counts again everywhere.
Who may
| Action | Who |
|---|---|
| Accept a vulnerability, revoke an exception | Policy managers, company admins, platform admins |
| See the exceptions | The same, and auditors |
Other roles do not see the Vulnerabilities page. With four-eyes review on, accepting and revoking wait for a second person (below).
Accepting a secret, a license or a package finding
On a merge request, a policy manager, company admin or platform admin can accept one finding with Accept:
- a secret finding (the Secret scan card): it is accepted by its fingerprint, a hash of its rule and value (the value is never kept), so the same value found again is the same finding;
- a dependency's license (the Licenses list of the dependency scan): the package, with that license. Every denied license of a dependency is kept on the merge request, so each can be accepted;
- a package health finding (the Package health list): the package, in that version.
The dialog Accept <what> asks This repository or In every project of the company, For how many days (30 by default, at most the company's Longest exception (days); like a vulnerability exception it ends at the end of the last day in the company's time zone, UTC when it has none) and Why is it acceptable?. For a secret, In every project of the company warns: A secret is accepted by its value: for every project, the same value is accepted in any repository and file of the company. Prefer this repository unless the value is a known test fixture. Merge requests are no longer held for the finding until the exception ends. Four-eyes review, the list of exceptions in force, revoking and the audit work as for vulnerabilities below.
API: POST /api/v1/companies/{id}/vulnerability-exceptions with kind (secret and fingerprint; license, package and optionally license; package, package and optionally version), project_id, reason, expires_at, and optionally state (accepted when left out). These kinds take no advisory_id; such a request is refused (advisory_id is for advisory exceptions only), as is one without its fingerprint or package (a secret exception needs the finding's fingerprint, a license exception needs the package, a package exception needs the package).
Accepting a vulnerability
- Open the finding: Insights → Vulnerabilities, or the project's Security tab → Dependencies view.
- Open its row with the arrow at the start, and choose Accept or mark not affected. The button is shown on open findings that no exception covers yet.
- Fill in the dialog Accept <advisory>: Merge requests that introduce it are no longer held for it, and it shows as accepted, until the date you choose.
- Accept.
| Field (label in the UI) | What it does | Default | Allowed values | API field |
|---|---|---|---|---|
| Why | The kind of decision. We accept the risk for now (listed as Risk accepted): the vulnerability applies, and the risk is accepted until the date. We are not affected (the vulnerable code is not used) (listed as Not affected). Both have the same effect; the choice is the record | We accept the risk for now | accepted, not_affected | state |
| Where | In <project> only: the finding's project. In every project of the company: every project, now and later | In <project> only | A project of the company, or none for every project | project_id (left out: every project) |
| Only for <package> | Ticked: only this package (in its ecosystem) is covered. Unticked: the advisory is covered in any package | Ticked | — | package, ecosystem (an ecosystem needs a package) |
| Reason | What makes this acceptable, and what happens next. Required | Empty | Up to 2,000 characters | reason |
| Until | The last day the exception is in force; it ends at the end of that day | 30 days from today, or the company's longest exception when that is shorter | From today to the day that is the company's Longest exception (days) (90 by default) from today, both counted in the company's time zone (UTC when it has none): At most N days: until the end of <date> (<time zone>) at the latest (Company → Scanning → Dependencies). The exception ends at the end of the chosen day in that time zone | expires_at (a time; must be in the future, and at most the end of that last day in the company's time zone, or UTC when it has none) |
The advisory is the finding's advisory ID (advisory_id). An exception covers that advisory by its ID or any of its aliases, so an exception made for a GHSA also covers the same vulnerability listed under its CVE.
After Accept: Accepted, or, with four-eyes review on, Sent for review: another administrator or policy manager must approve it.
What happens at once
- Every open finding the exception covers (in its project or in every project, in its package or in any) is marked Accepted.
- Every open merge request whose dependency scan found the advisory (in the covered project, at most 500) is evaluated again, so a merge held only for it can go ahead. Its scan's counts still include the accepted vulnerability; Show details marks it Accepted (see Dependency scan → Exceptions).
- New findings of the advisory, found later in a covered project, start as Accepted.
Refused
The exception is refused, with the reason, when the advisory or the reason is missing (say why), the reason is longer than 2,000 characters, the date is not in the future, the date is later than the end of the day that is the company's longest exception 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>)), an ecosystem is given without a package, or the project is not the company's.
Exceptions in force
The Exceptions in force card at the bottom of Insights → Vulnerabilities lists every exception in force now, newest first: what it accepts (the advisory; for the other kinds Secret finding <fingerprint>, License <license> of <package> or Licenses of <package>, Package health of <package> with its version when it names one), the package (when it names one), Risk accepted or Not affected, the project's name (a link to its page) or Every project, the reason, and until the end of <day> (<the company's time zone>), by <who asked for it>: the last day the exception is in force, as it was given, whatever the viewer's own time zone. No exception is in force. when there is none.
Ended and revoked exceptions are not listed there; the API returns them (active=false).
Four-eyes review
When the company reviews control changes (company Governance tab, Review control changes; see Governance tab), accepting and revoking are not applied when asked for. They wait in a box at the top of Insights → Vulnerabilities (1 change waits for a second person), as Accept <advisory> or Revoke an exception.
- Another policy manager, company admin or platform admin decides it with Approve or Reject, from a signed-in session. Nobody decides their own request (see Who may decide).
- The request is checked when it is made: one that would be refused is refused at once and nothing waits.
- Approve creates (or revokes) the exception as it was asked for. The exception is recorded as made by the person who asked; the audit entry names both.
- A waiting request does not expire, and the exception's dates are not moved: approve a request before the date it asks for, or it is refused when applied.
When an exception ends
| How | What happens |
|---|---|
| It expires | At the end of its last day Merge Pilot ends it, at its next background round. The audit log records vuln_exception_expired (by Merge Pilot) |
| It is revoked | Revoke on its line in Exceptions in force asks first (Revoke the exception for <advisory>? The findings it covers count as open again., Cancel or Revoke), then ends it at once (with four-eyes review: once a second person approves; the page shows Sent for review: another administrator or policy manager must approve it) |
Either way, each finding it covered is checked against the other exceptions in force: one that another exception covers stays Accepted under that one; the others are Open again. Open merge requests that introduce the advisory are evaluated again and can be held once more. Exceptions of inactive companies expire too.
An exception cannot be changed. To extend one, make a new exception (the old one can be revoked or left to expire).
Ended and revoked exceptions are deleted once a day after the company's Keep fixed vulnerabilities, old analyses and direct changes (days) have passed since they ended (see Scanning).
API
All paths start with /api/v1.
| Request | Who | What it does |
|---|---|---|
GET /companies/{id}/vulnerability-exceptions | Policy managers, company admins, auditors, platform admins | The company's exceptions, newest first (at most 1,000). active=true: in force now; active=false: ended or revoked |
POST /companies/{id}/vulnerability-exceptions | Policy managers, company admins, platform admins | Creates one: advisory_id, state (accepted, not_affected), reason, expires_at, and optionally project_id, package, ecosystem. 201 with the exception; 202 with {"pending": true, "change": {…}} when it waits for review; 400 when refused |
DELETE /companies/{id}/vulnerability-exceptions/{eid} | The same | Revokes it. 200 with the exception; 202 when it waits for review; 404 exception not found or already ended: an exception that expired or was revoked cannot be revoked, and nothing is recorded |
An exception has id, company_id, project_id (absent: every project), kind (absent for an advisory), advisory_id, fingerprint, license, version, ecosystem, package, state, reason, expires_at, created_by, created_at, revoked_at and revoked_by. A finding the exception covers carries its exception_id.
Waiting requests are decided through the config-changes API with the kinds vuln_exception_create and vuln_exception_revoke (see Governance tab → API).
Audit
| Action | When | Who is recorded |
|---|---|---|
vuln_exception_created | An exception was created, or a reviewed one was approved (then with requested_by and approved_by) | The person who made it, or the approver |
vuln_exception_revoked | An exception was revoked, or a reviewed revocation was approved | The same |
vuln_exception_expired | An exception expired | Merge Pilot |
config_change_requested, config_change_approved, config_change_rejected | A request waited for review, and was decided | The requester, the decider |
The entries hold the advisory, package, state, reason, end date and, for one project, the project. See Audit log.
Related pages
- Vulnerability inventory.
- Dependency scan → Exceptions.
- Scanning → Vulnerability tracking: Longest exception (days).
- Governance tab.
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →