Skip to main content
Video tutorial · 1:19

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​

ActionWho
Accept a vulnerability, revoke an exceptionPolicy managers, company admins, platform admins
See the exceptionsThe 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​

  1. Open the finding: Insights → Vulnerabilities, or the project's Security tab → Dependencies view.
  2. 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.
  3. 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.
  4. Accept.
Field (label in the UI)What it doesDefaultAllowed valuesAPI field
WhyThe 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 recordWe accept the risk for nowaccepted, not_affectedstate
WhereIn <project> only: the finding's project. In every project of the company: every project, now and laterIn <project> onlyA project of the company, or none for every projectproject_id (left out: every project)
Only for <package>Ticked: only this package (in its ecosystem) is covered. Unticked: the advisory is covered in any packageTicked—package, ecosystem (an ecosystem needs a package)
ReasonWhat makes this acceptable, and what happens next. RequiredEmptyUp to 2,000 charactersreason
UntilThe last day the exception is in force; it ends at the end of that day30 days from today, or the company's longest exception when that is shorterFrom 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 zoneexpires_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​

HowWhat happens
It expiresAt 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 revokedRevoke 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.

RequestWhoWhat it does
GET /companies/{id}/vulnerability-exceptionsPolicy managers, company admins, auditors, platform adminsThe company's exceptions, newest first (at most 1,000). active=true: in force now; active=false: ended or revoked
POST /companies/{id}/vulnerability-exceptionsPolicy managers, company admins, platform adminsCreates 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 sameRevokes 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​

ActionWhenWho is recorded
vuln_exception_createdAn 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_revokedAn exception was revoked, or a reviewed revocation was approvedThe same
vuln_exception_expiredAn exception expiredMerge Pilot
config_change_requested, config_change_approved, config_change_rejectedA request waited for review, and was decidedThe requester, the decider

The entries hold the advisory, package, state, reason, end date and, for one project, the project. See Audit log.

Video tutorial

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

Accept a Finding with a ReasonYouTube ↗