diff options
Diffstat (limited to 'doc/api/vulnerabilities.md')
| -rw-r--r-- | doc/api/vulnerabilities.md | 223 |
1 files changed, 222 insertions, 1 deletions
diff --git a/doc/api/vulnerabilities.md b/doc/api/vulnerabilities.md index 21b3a6f4c96..ff1a6a7ebcd 100644 --- a/doc/api/vulnerabilities.md +++ b/doc/api/vulnerabilities.md @@ -1,3 +1,224 @@ # Vulnerabilities API **(ULTIMATE)** -This document was moved to [another location](vulnerability_findings.md). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/10242) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. + +NOTE: **Note:** +The former Vulnerabilities API was renamed to Vulnerability Findings API +and its documentation was moved to [a different location](vulnerability_findings.md). +This document now describes the new Vulnerabilities API that provides access to +[Standalone Vulnerabilities](https://gitlab.com/groups/gitlab-org/-/epics/634). + +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. + +## Single vulnerability + +Gets a single vulnerability + +```plaintext +GET /vulnerabilities/:id +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer or string | yes | The ID of a Vulnerability to get | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/vulnerabilities/1 +``` + +Example response: + +```json +{ + "id": 1, + "title": "Predictable pseudorandom number generator", + "description": null, + "state": "opened", + "severity": "medium", + "confidence": "medium", + "report_type": "sast", + "project": { + "id": 32, + "name": "security-reports", + "full_path": "/gitlab-examples/security/security-reports", + "full_name": "gitlab-examples / security / security-reports" + }, + "author_id": 1, + "updated_by_id": null, + "last_edited_by_id": null, + "closed_by_id": null, + "start_date": null, + "due_date": null, + "created_at": "2019-10-13T15:08:40.219Z", + "updated_at": "2019-10-13T15:09:40.382Z", + "last_edited_at": null, + "closed_at": null +} +``` + +## Confirm vulnerability + +Confirms a given vulnerability. Returns status code `304` if the vulnerability is already confirmed. + +If an authenticated user does not have permission to +[confirm vulnerabilities](../user/permissions.md#project-members-permissions), +this request will result in a `403` status code. + +```plaintext +POST /vulnerabilities/:id/confirm +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer or string | yes | The ID of a vulnerability to confirm | + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/vulnerabilities/5/confirm" +``` + +Example response: + +```json +{ + "id": 2, + "title": "Predictable pseudorandom number generator", + "description": null, + "state": "confirmed", + "severity": "medium", + "confidence": "medium", + "report_type": "sast", + "project": { + "id": 32, + "name": "security-reports", + "full_path": "/gitlab-examples/security/security-reports", + "full_name": "gitlab-examples / security / security-reports" + }, + "author_id": 1, + "updated_by_id": null, + "last_edited_by_id": null, + "closed_by_id": null, + "start_date": null, + "due_date": null, + "created_at": "2019-10-13T15:08:40.219Z", + "updated_at": "2019-10-13T15:09:40.382Z", + "last_edited_at": null, + "closed_at": null +} +``` + +## Resolve vulnerability + +Resolves a given vulnerability. Returns status code `304` if the vulnerability is already resolved. + +If an authenticated user does not have permission to +[resolve vulnerabilities](../user/permissions.md#project-members-permissions), +this request will result in a `403` status code. + +```plaintext +POST /vulnerabilities/:id/resolve +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer or string | yes | The ID of a Vulnerability to resolve | + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/vulnerabilities/5/resolve" +``` + +Example response: + +```json +{ + "id": 2, + "title": "Predictable pseudorandom number generator", + "description": null, + "state": "resolved", + "severity": "medium", + "confidence": "medium", + "report_type": "sast", + "project": { + "id": 32, + "name": "security-reports", + "full_path": "/gitlab-examples/security/security-reports", + "full_name": "gitlab-examples / security / security-reports" + }, + "author_id": 1, + "updated_by_id": null, + "last_edited_by_id": null, + "closed_by_id": null, + "start_date": null, + "due_date": null, + "created_at": "2019-10-13T15:08:40.219Z", + "updated_at": "2019-10-13T15:09:40.382Z", + "last_edited_at": null, + "closed_at": null +} +``` + +## Dismiss vulnerability + +Dismisses a given vulnerability. Returns status code `304` if the vulnerability is already dismissed. + +If an authenticated user does not have permission to +[dismiss vulnerabilities](../user/permissions.md#project-members-permissions), +this request will result in a `403` status code. + +```plaintext +POST /vulnerabilities/:id/dismiss +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer or string | yes | The ID of a vulnerability to dismiss | + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/vulnerabilities/5/dismiss" +``` + +Example response: + +```json +{ + "id": 2, + "title": "Predictable pseudorandom number generator", + "description": null, + "state": "closed", + "severity": "medium", + "confidence": "medium", + "report_type": "sast", + "project": { + "id": 32, + "name": "security-reports", + "full_path": "/gitlab-examples/security/security-reports", + "full_name": "gitlab-examples / security / security-reports" + }, + "author_id": 1, + "updated_by_id": null, + "last_edited_by_id": null, + "closed_by_id": null, + "start_date": null, + "due_date": null, + "created_at": "2019-10-13T15:08:40.219Z", + "updated_at": "2019-10-13T15:09:40.382Z", + "last_edited_at": null, + "closed_at": null +} +``` |