2020-09-11 21:08:44 +00:00
---
stage: Secure
group: Threat Insights
2020-11-26 06:09:20 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-09-11 21:08:44 +00:00
---
2019-10-30 09:27:58 +00:00
# Vulnerability Findings API **(ULTIMATE)**
2021-09-07 12:11:26 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/19029) in GitLab 12.5.
2019-10-30 09:27:58 +00:00
2020-12-04 21:09:29 +00:00
NOTE:
2019-10-30 09:27:58 +00:00
This API resource is renamed from Vulnerabilities to Vulnerability Findings because the Vulnerabilities are reserved
2020-08-13 18:10:36 +00:00
for serving [Vulnerability objects ](https://gitlab.com/gitlab-org/gitlab/-/issues/13561 ).
2019-10-30 09:27:58 +00:00
To fix any broken integrations with the former Vulnerabilities API, change the `vulnerabilities` URL part to be
2020-03-13 18:09:39 +00:00
`vulnerability_findings` .
2019-10-30 09:27:58 +00:00
2021-06-28 15:08:03 +00:00
Every API call to vulnerability findings must be [authenticated ](index.md#authentication ).
2019-10-30 09:27:58 +00:00
Vulnerability findings are project-bound entities. If a user is not
a member of a project and the project is private, a request on
2020-11-19 18:09:13 +00:00
that project results in a `404` status code.
2019-10-30 09:27:58 +00:00
If a user is able to access the project but does not have permission to
[use the Project Security Dashboard ](../user/permissions.md#project-members-permissions ),
2020-11-19 18:09:13 +00:00
any request for vulnerability findings of this project results in a `403` status code.
2019-10-30 09:27:58 +00:00
2020-12-04 21:09:29 +00:00
WARNING:
2019-10-30 09:27:58 +00:00
This API is in an alpha stage and considered unstable.
The response payload may be subject to change or breakage
across GitLab releases.
## Vulnerability findings pagination
By default, `GET` requests return 20 results at a time because the API results
are paginated.
2021-06-28 15:08:03 +00:00
Read more on [pagination ](index.md#pagination ).
2019-10-30 09:27:58 +00:00
## List project vulnerability findings
List all of a project's vulnerability findings.
2020-02-29 03:07:51 +00:00
```plaintext
2019-10-30 09:27:58 +00:00
GET /projects/:id/vulnerability_findings
GET /projects/:id/vulnerability_findings?report_type=sast
GET /projects/:id/vulnerability_findings?report_type=container_scanning
GET /projects/:id/vulnerability_findings?report_type=sast,dast
GET /projects/:id/vulnerability_findings?scope=all
GET /projects/:id/vulnerability_findings?scope=dismissed
GET /projects/:id/vulnerability_findings?severity=high
GET /projects/:id/vulnerability_findings?confidence=unknown,experimental
GET /projects/:id/vulnerability_findings?pipeline_id=42
```
2020-12-04 21:09:29 +00:00
WARNING:
2020-06-05 18:08:19 +00:00
Beginning with GitLab 12.9, the `undefined` severity and confidence level is no longer reported.
2020-03-13 18:09:39 +00:00
2019-10-30 09:27:58 +00:00
| Attribute | Type | Required | Description |
| ------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
2021-06-28 15:08:03 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) which the authenticated user is a member of. |
2019-10-30 09:27:58 +00:00
| `report_type` | string array | no | Returns vulnerability findings belonging to specified report type. Valid values: `sast` , `dast` , `dependency_scanning` , or `container_scanning` . Defaults to all. |
| `scope` | string | no | Returns vulnerability findings for the given scope: `all` or `dismissed` . Defaults to `dismissed` . |
2020-06-05 18:08:19 +00:00
| `severity` | string array | no | Returns vulnerability findings belonging to specified severity level: `info` , `unknown` , `low` , `medium` , `high` , or `critical` . Defaults to all. |
| `confidence` | string array | no | Returns vulnerability findings belonging to specified confidence level: `ignore` , `unknown` , `experimental` , `low` , `medium` , `high` , or `confirmed` . Defaults to all. |
2019-10-30 09:27:58 +00:00
| `pipeline_id` | integer/string | no | Returns vulnerability findings belonging to specified pipeline. |
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/4/vulnerability_findings"
2019-10-30 09:27:58 +00:00
```
Example response:
```json
[
{
"id": null,
2021-09-28 06:09:10 +00:00
"report_type": "sast",
"name": "Possible command injection",
"severity": "high",
"confidence": "high",
2019-10-30 09:27:58 +00:00
"scanner": {
2021-09-28 06:09:10 +00:00
"external_id": "brakeman",
"name": "Brakeman",
"vendor": "GitLab"
2019-10-30 09:27:58 +00:00
},
"identifiers": [
{
2021-09-28 06:09:10 +00:00
"external_type": "brakeman_warning_code",
"external_id": "14",
"name": "Brakeman Warning Code 14",
"url": "https://brakemanscanner.org/docs/warning_types/command_injection/"
2019-10-30 09:27:58 +00:00
}
],
2021-09-28 06:09:10 +00:00
"project_fingerprint": "ac218b1770af030cfeef967752ab803c55afb36d",
"uuid": "ad5e3be3-a193-55f5-a200-bc12865fb09c",
"create_jira_issue_url": null,
"false_positive": true,
"create_vulnerability_feedback_issue_path": "/root/test-false-positive/-/vulnerability_feedback",
"create_vulnerability_feedback_merge_request_path": "/root/test-false-positive/-/vulnerability_feedback",
"create_vulnerability_feedback_dismissal_path": "/root/test-false-positive/-/vulnerability_feedback",
2019-10-30 09:27:58 +00:00
"project": {
2021-09-28 06:09:10 +00:00
"id": 2,
"name": "Test False Positive",
"full_path": "/root/test-false-positive",
"full_name": "Administrator / Test False Positive"
2019-10-30 09:27:58 +00:00
},
"dismissal_feedback": null,
"issue_feedback": null,
"merge_request_feedback": null,
2021-09-28 06:09:10 +00:00
"description": null,
"links": [],
2019-10-30 09:27:58 +00:00
"location": {
2021-09-28 06:09:10 +00:00
"file": "app/controllers/users_controller.rb",
"start_line": 42,
"class": "UsersController",
"method": "list_users"
2019-10-30 09:27:58 +00:00
},
2021-09-28 06:09:10 +00:00
"remediations": [
null
],
"solution": null,
"evidence": null,
"request": null,
"response": null,
"evidence_source": null,
"supporting_messages": [],
"assets": [],
"details": {},
"state": "detected",
"scan": {
"type": "sast",
"status": "success",
"start_time": "2021-09-02T20:55:48",
"end_time": "2021-09-02T20:55:48"
2021-03-16 06:09:57 +00:00
},
2021-09-28 06:09:10 +00:00
"blob_path": "/root/test-false-positive/-/blob/dfd75607752a839bbc9c7362d111effaa470fecd/app/controllers/users_controller.rb#L42"
2019-10-30 09:27:58 +00:00
}
]
```