2020-09-11 21:08:44 +00:00
---
2022-09-14 09:12:58 +00:00
stage: Govern
2020-09-11 21:08:44 +00:00
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:
2021-12-23 18:14:10 +00:00
This API is in the process of being deprecated and considered unstable.
2019-10-30 09:27:58 +00:00
The response payload may be subject to change or breakage
2021-12-23 18:14:10 +00:00
across GitLab releases. Please use the
[GraphQL API ](graphql/reference/index.md#queryvulnerabilities )
instead. See the [GraphQL examples ](#replace-vulnerability-findings-rest-api-with-graphql ) to get started.
2019-10-30 09:27:58 +00:00
## 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
}
]
```
2021-12-23 18:14:10 +00:00
## Replace Vulnerability Findings REST API with GraphQL
To prepare for the [upcoming deprecation ](https://gitlab.com/groups/gitlab-org/-/epics/5118 ) of
the Vulnerability Findings REST API endpoint, use the examples below to perform the equivalent operations
with the GraphQL API.
### GraphQL - Project vulnerabilities
2022-08-10 06:10:51 +00:00
Use [`Project.vulnerabilities` ](graphql/reference/index.md#projectvulnerabilities ).
2021-12-23 18:14:10 +00:00
```graphql
{
project(fullPath: "root/security-reports") {
vulnerabilities {
nodes{
id
reportType
title
severity
scanner {
externalId
name
vendor
}
identifiers {
externalType
externalId
name
url
}
falsePositive
project {
id
name
fullPath
}
description
links {
name
url
}
location {
... on
VulnerabilityLocationSast {
file
startLine
endLine
vulnerableClass
vulnerableMethod
blobPath
}
}
details {
... on
VulnerabilityDetailCode {
description
fieldName
lang
name
value
}
}
state
}
}
}
}
```
Example response:
```json
{
"data": {
"project": {
"vulnerabilities": {
"nodes": [
{
"id": "gid://gitlab/Vulnerability/236",
"reportType": "SAST",
"title": "Generic Object Injection Sink",
"severity": "CRITICAL",
"scanner": {
"externalId": "eslint",
"name": "ESLint",
"vendor": "GitLab"
},
"identifiers": [
{
"externalType": "eslint_rule_id",
"externalId": "security/detect-object-injection",
"name": "ESLint rule ID security/detect-object-injection",
"url": "https://github.com/nodesecurity/eslint-plugin-security#detect-object-injection"
},
{
"externalType": "cwe",
"externalId": "94",
"name": "CWE-94",
"url": "https://cwe.mitre.org/data/definitions/94.html"
}
],
"falsePositive": false,
"project": {
"id": "gid://gitlab/Project/20",
"name": "Security Reports",
"fullPath": "root/security-reports"
},
"description": "Bracket object notation with user input is present, this might allow an attacker to access all properties of the object and even it's prototype, leading to possible code execution.",
"links": [],
"location": {
"file": "src/js/main.js",
"startLine": "28",
"endLine": "28",
"vulnerableClass": null,
"vulnerableMethod": null,
"blobPath": "/root/security-reports/-/blob/91031428a5b5dbb81e8d889738b1875c1bfea787/src/js/main.js"
},
"details": [],
"state": "DETECTED"
}
]
}
}
}
}
```