diff options
Diffstat (limited to 'doc/api/project_vulnerabilities.md')
| -rw-r--r-- | doc/api/project_vulnerabilities.md | 215 |
1 files changed, 215 insertions, 0 deletions
diff --git a/doc/api/project_vulnerabilities.md b/doc/api/project_vulnerabilities.md new file mode 100644 index 00000000000..84bbc789b0c --- /dev/null +++ b/doc/api/project_vulnerabilities.md @@ -0,0 +1,215 @@ +# 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" + ] + } +} +``` |