Vulnerabilities API

Problem to solve

Security reports (https://docs.gitlab.com/ee/ci/yaml/#artifactsreports) are not accessible in the same way other artifacts are, and there is no API to fetch them.

This makes harder to automate flows.

A possible workaround is to set files as both regular artifacts and reports in the job definition, but this is suboptimal.

Users should be able to fetch reports easily.

Target audience

Proposal

Create API calls to fetch reports. The endpoint will be very similar of the artifacts one, allowing users to fetch different reports as JSON files.

The content is the original report content, but possibly elaborated by the backend to normalize, merge and clean up with the same process it already does before sending data to the frontend.

For example, if the pipeline has multiple jobs sending reports for sast, the endpoint will aggregate them together and will send a single vulnerability list to the caller.

If possible, cover also other report types (like codequality), but focus on security features first.

See suggested patch here: https://gitlab.com/gitlab-org/gitlab-ce/issues/49265#note_119629648

Out of Scope

This issue will NOT cover -

  1. exposing the raw reports artifacts in the job's page, like it used to work before moving to the reports syntax.
  2. exposing the raw reports artifacts to the GitLab Public API.

In Scope

It will instead focus on -

  1. exposing security reports content in a normalized and structured way (like after parsing the raw json reports in the backend and exposing clean data)

Usage metrics should be implemented as described later in this proposal.

Permissions and Security

Same as artifacts.

Documentation

What does success look like, and how can we measure that?

Number of API calls to fetch reports.

Implementation Plan

  1. add endpoint that returns all vulnerabilities for a project (from default pipline, parsing report) https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/11539
  2. change default behavior to return non-dismissed vulnerabilities only https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/12076
  3. add additional filters (report_type, confidence, severity) https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/12076
  4. support group vulnerabilities from same endpoint (follow-up issue: https://gitlab.com/gitlab-org/gitlab-ee/issues/11570)
  5. add usage ping (follow-up issue: #11569 (closed))
Edited by Philippe Lafoucrière