debian-mirror-gitlab/doc/api/project_vulnerabilities.md

216 lines
10 KiB
Markdown
Raw Normal View History

2020-04-22 19:07:51 +05:30
# Project Vulnerabilities API **(ULTIMATE)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/10242) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6.
CAUTION: **Caution:**
This API is currently in development and is protected by a **disabled**
[feature flag](../development/feature_flags/index.md).
On a self-managed GitLab instance, an administrator can enable it by starting the Rails console
(`sudo gitlab-rails console`) and then running the following command: `Feature.enable(:first_class_vulnerabilities)`.
To test if the Vulnerabilities API was successfully enabled, run the following command:
`Feature.enabled?(:first_class_vulnerabilities)`.
CAUTION: **Caution:**
This API is in an alpha stage and considered unstable.
The response payload may be subject to change or breakage
across GitLab releases.
Every API call to vulnerabilities must be [authenticated](README.md#authentication).
Vulnerability permissions inherit permissions from their project. If a project is
private, and a user isn't a member of the project to which the vulnerability
belongs, requests to that project will return a `404 Not Found` status code.
## Vulnerabilities pagination
API results are paginated, and `GET` requests return 20 results at a time by default.
Read more on [pagination](README.md#pagination).
## List project vulnerabilities
List all of a project's vulnerabilities.
If an authenticated user does not have permission to
[use the Project Security Dashboard](../user/permissions.md#project-members-permissions),
`GET` requests for vulnerabilities of this project will result in a `403` status code.
```plaintext
GET /projects/:id/vulnerabilities
```
| Attribute | Type | Required | Description |
| ------------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
```bash
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/4/vulnerabilities
```
Example response:
```json
[
{
"author_id": 1,
"confidence": "medium",
"created_at": "2020-04-07T14:01:04.655Z",
"description": null,
"dismissed_at": null,
"dismissed_by_id": null,
"due_date": null,
"finding": {
"confidence": "medium",
"created_at": "2020-04-07T14:01:04.630Z",
"id": 103,
"location_fingerprint": "228998b5db51d86d3b091939e2f5873ada0a14a1",
"metadata_version": "2.0",
"name": "Regular Expression Denial of Service in debug",
"primary_identifier_id": 135,
"project_fingerprint": "05e7cc9978ca495cf739a9f707ed34811e41c615",
"project_id": 24,
"raw_metadata": "{\"category\":\"dependency_scanning\",\"name\":\"Regular Expression Denial of Service\",\"message\":\"Regular Expression Denial of Service in debug\",\"description\":\"The debug module is vulnerable to regular expression denial of service when untrusted user input is passed into the `o` formatter. It takes around 50k characters to block for 2 seconds making this a low severity issue.\",\"cve\":\"yarn.lock:debug:gemnasium:37283ed4-0380-40d7-ada7-2d994afcc62a\",\"severity\":\"Unknown\",\"solution\":\"Upgrade to latest versions.\",\"scanner\":{\"id\":\"gemnasium\",\"name\":\"Gemnasium\"},\"location\":{\"file\":\"yarn.lock\",\"dependency\":{\"package\":{\"name\":\"debug\"},\"version\":\"1.0.5\"}},\"identifiers\":[{\"type\":\"gemnasium\",\"name\":\"Gemnasium-37283ed4-0380-40d7-ada7-2d994afcc62a\",\"value\":\"37283ed4-0380-40d7-ada7-2d994afcc62a\",\"url\":\"https://deps.sec.gitlab.com/packages/npm/debug/versions/1.0.5/advisories\"}],\"links\":[{\"url\":\"https://nodesecurity.io/advisories/534\"},{\"url\":\"https://github.com/visionmedia/debug/issues/501\"},{\"url\":\"https://github.com/visionmedia/debug/pull/504\"}],\"remediations\":[null]}",
"report_type": "dependency_scanning",
"scanner_id": 63,
"severity": "low",
"updated_at": "2020-04-07T14:01:04.664Z",
"uuid": "f1d528ae-d0cc-47f6-a72f-936cec846ae7",
"vulnerability_id": 103
},
"id": 103,
"last_edited_at": null,
"last_edited_by_id": null,
"project": {
"created_at": "2020-04-07T13:54:25.634Z",
"description": "",
"id": 24,
"name": "security-reports",
"name_with_namespace": "gitlab-org / security-reports",
"path": "security-reports",
"path_with_namespace": "gitlab-org/security-reports"
},
"project_default_branch": "master",
"report_type": "dependency_scanning",
"resolved_at": null,
"resolved_by_id": null,
"resolved_on_default_branch": false,
"severity": "low",
"start_date": null,
"state": "detected",
"title": "Regular Expression Denial of Service in debug",
"updated_at": "2020-04-07T14:01:04.655Z",
"updated_by_id": null
}
]
```
## New vulnerability
Creates a new vulnerability.
If an authenticated user does not have a permission to
[create a new vulnerability](../user/permissions.md#project-members-permissions),
this request will result in a `403` status code.
```plaintext
POST /projects/:id/vulnerabilities?finding_id=<your_finding_id>
```
| Attribute | Type | Required | Description |
| ------------------- | ----------------- | ---------- | -----------------------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) which the authenticated user is a member of |
| `finding_id` | integer or string | yes | The ID of a Vulnerability Finding from which the new Vulnerability will be created |
The other attributes of a newly created Vulnerability are populated from
its source Vulnerability Finding, or with these default values:
| Attribute | Value |
|--------------|-------------------------------------------------------|
| `author` | The authenticated user |
| `title` | The `name` attribute of a Vulnerability Finding |
| `state` | `opened` |
| `severity` | The `severity` attribute of a Vulnerability Finding |
| `confidence` | The `confidence` attribute of a Vulnerability Finding |
```shell
curl --header POST "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/vulnerabilities?finding_id=1
```
Example response:
```json
{
"author_id": 1,
"confidence": "medium",
"created_at": "2020-04-07T14:01:04.655Z",
"description": null,
"dismissed_at": null,
"dismissed_by_id": null,
"due_date": null,
"finding": {
"confidence": "medium",
"created_at": "2020-04-07T14:01:04.630Z",
"id": 103,
"location_fingerprint": "228998b5db51d86d3b091939e2f5873ada0a14a1",
"metadata_version": "2.0",
"name": "Regular Expression Denial of Service in debug",
"primary_identifier_id": 135,
"project_fingerprint": "05e7cc9978ca495cf739a9f707ed34811e41c615",
"project_id": 24,
"raw_metadata": "{\"category\":\"dependency_scanning\",\"name\":\"Regular Expression Denial of Service\",\"message\":\"Regular Expression Denial of Service in debug\",\"description\":\"The debug module is vulnerable to regular expression denial of service when untrusted user input is passed into the `o` formatter. It takes around 50k characters to block for 2 seconds making this a low severity issue.\",\"cve\":\"yarn.lock:debug:gemnasium:37283ed4-0380-40d7-ada7-2d994afcc62a\",\"severity\":\"Unknown\",\"solution\":\"Upgrade to latest versions.\",\"scanner\":{\"id\":\"gemnasium\",\"name\":\"Gemnasium\"},\"location\":{\"file\":\"yarn.lock\",\"dependency\":{\"package\":{\"name\":\"debug\"},\"version\":\"1.0.5\"}},\"identifiers\":[{\"type\":\"gemnasium\",\"name\":\"Gemnasium-37283ed4-0380-40d7-ada7-2d994afcc62a\",\"value\":\"37283ed4-0380-40d7-ada7-2d994afcc62a\",\"url\":\"https://deps.sec.gitlab.com/packages/npm/debug/versions/1.0.5/advisories\"}],\"links\":[{\"url\":\"https://nodesecurity.io/advisories/534\"},{\"url\":\"https://github.com/visionmedia/debug/issues/501\"},{\"url\":\"https://github.com/visionmedia/debug/pull/504\"}],\"remediations\":[null]}",
"report_type": "dependency_scanning",
"scanner_id": 63,
"severity": "low",
"updated_at": "2020-04-07T14:01:04.664Z",
"uuid": "f1d528ae-d0cc-47f6-a72f-936cec846ae7",
"vulnerability_id": 103
},
"id": 103,
"last_edited_at": null,
"last_edited_by_id": null,
"project": {
"created_at": "2020-04-07T13:54:25.634Z",
"description": "",
"id": 24,
"name": "security-reports",
"name_with_namespace": "gitlab-org / security-reports",
"path": "security-reports",
"path_with_namespace": "gitlab-org/security-reports"
},
"project_default_branch": "master",
"report_type": "dependency_scanning",
"resolved_at": null,
"resolved_by_id": null,
"resolved_on_default_branch": false,
"severity": "low",
"start_date": null,
"state": "detected",
"title": "Regular Expression Denial of Service in debug",
"updated_at": "2020-04-07T14:01:04.655Z",
"updated_by_id": null
}
```
### Errors
This error occurs when a Finding chosen to create a Vulnerability from is not found, or
is already associated with a different Vulnerability:
```plaintext
A Vulnerability Finding is not found or already attached to a different Vulnerability
```
Status code: `400`
Example response:
```json
{
"message": {
"base": [
"finding is not found or is already attached to a vulnerability"
]
}
}
```