139 lines
6.2 KiB
Markdown
139 lines
6.2 KiB
Markdown
---
|
|
stage: Secure
|
|
group: Threat Insights
|
|
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
|
|
---
|
|
|
|
# Vulnerability Findings API **(ULTIMATE)**
|
|
|
|
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/19029) in GitLab 12.5.
|
|
|
|
NOTE:
|
|
This API resource is renamed from Vulnerabilities to Vulnerability Findings because the Vulnerabilities are reserved
|
|
for serving [Vulnerability objects](https://gitlab.com/gitlab-org/gitlab/-/issues/13561).
|
|
To fix any broken integrations with the former Vulnerabilities API, change the `vulnerabilities` URL part to be
|
|
`vulnerability_findings`.
|
|
|
|
Every API call to vulnerability findings must be [authenticated](index.md#authentication).
|
|
|
|
Vulnerability findings are project-bound entities. If a user is not
|
|
a member of a project and the project is private, a request on
|
|
that project results in a `404` status code.
|
|
|
|
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),
|
|
any request for vulnerability findings of this project results in a `403` status code.
|
|
|
|
WARNING:
|
|
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.
|
|
|
|
Read more on [pagination](index.md#pagination).
|
|
|
|
## List project vulnerability findings
|
|
|
|
List all of a project's vulnerability findings.
|
|
|
|
```plaintext
|
|
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
|
|
```
|
|
|
|
WARNING:
|
|
Beginning with GitLab 12.9, the `undefined` severity and confidence level is no longer reported.
|
|
|
|
| Attribute | Type | Required | Description |
|
|
| ------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
| `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. |
|
|
| `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`. |
|
|
| `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. |
|
|
| `pipeline_id` | integer/string | no | Returns vulnerability findings belonging to specified pipeline. |
|
|
|
|
```shell
|
|
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/vulnerability_findings"
|
|
```
|
|
|
|
Example response:
|
|
|
|
```json
|
|
[
|
|
{
|
|
"id": null,
|
|
"report_type": "sast",
|
|
"name": "Possible command injection",
|
|
"severity": "high",
|
|
"confidence": "high",
|
|
"scanner": {
|
|
"external_id": "brakeman",
|
|
"name": "Brakeman",
|
|
"vendor": "GitLab"
|
|
},
|
|
"identifiers": [
|
|
{
|
|
"external_type": "brakeman_warning_code",
|
|
"external_id": "14",
|
|
"name": "Brakeman Warning Code 14",
|
|
"url": "https://brakemanscanner.org/docs/warning_types/command_injection/"
|
|
}
|
|
],
|
|
"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",
|
|
"project": {
|
|
"id": 2,
|
|
"name": "Test False Positive",
|
|
"full_path": "/root/test-false-positive",
|
|
"full_name": "Administrator / Test False Positive"
|
|
},
|
|
"dismissal_feedback": null,
|
|
"issue_feedback": null,
|
|
"merge_request_feedback": null,
|
|
"description": null,
|
|
"links": [],
|
|
"location": {
|
|
"file": "app/controllers/users_controller.rb",
|
|
"start_line": 42,
|
|
"class": "UsersController",
|
|
"method": "list_users"
|
|
},
|
|
"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"
|
|
},
|
|
"blob_path": "/root/test-false-positive/-/blob/dfd75607752a839bbc9c7362d111effaa470fecd/app/controllers/users_controller.rb#L42"
|
|
}
|
|
]
|
|
```
|