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
-
Devon, DevOps Engineer, https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas#devon-devops-engineer
-
Sam, Security Analyst, https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas#sam-security-analyst
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 -
- exposing the raw reports artifacts in the job's page, like it used to work before moving to the
reports
syntax. - exposing the raw reports artifacts to the GitLab Public API.
In Scope
It will instead focus on -
- 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
- add endpoint that returns all vulnerabilities for a project (from default pipline, parsing report) https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/11539
- change default behavior to return non-dismissed vulnerabilities only https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/12076
- add additional filters (report_type, confidence, severity) https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/12076
- support group vulnerabilities from same endpoint (follow-up issue: https://gitlab.com/gitlab-org/gitlab-ee/issues/11570)
- add usage ping (follow-up issue: #11569 (closed))