Commit db713662 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

Merge branch '10242-4-add-doc-stubs-for-vuln-findings-api' into 'master'

Add API documentation stubs for Vulnerabilities API changes

See merge request gitlab-org/gitlab!17364
parents 97ceffeb a09247a3
......@@ -71,7 +71,7 @@ The following API resources are available in the project context:
| [Services](services.md) | `/projects/:id/services` |
| [Tags](tags.md) | `/projects/:id/repository/tags` |
| [Visual Review discussions](visual_review_discussions.md) **(STARTER**) | `/projects/:id/merge_requests/:merge_request_id/visual_review_discussions` |
| [Vulnerabilities](vulnerabilities.md) **(ULTIMATE)** | `/projects/:id/vulnerabilities` |
| [Vulnerabilities](project_vulnerabilities.md) **(ULTIMATE)** | `/projects/:id/vulnerabilities` |
| [Vulnerability Findings](vulnerability_findings.md) **(ULTIMATE)** | `/projects/:id/vulnerability_findings` |
| [Wikis](wikis.md) | `/projects/:id/wikis` |
......
# 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"
]
}
}
```
# 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
}
```
# Vulnerability Issue links API **(ULTIMATE)**
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.
## List related issues
Get a list of related issues of a given issue, sorted by the relationship creation datetime (ascending).
Issues will be filtered according to the user authorizations.
```plaintext
GET /projects/:id/issues/:issue_iid/links
```
Parameters:
| 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 |
| `issue_iid` | integer | yes | The internal ID of a project's issue |
```json
[
{
"id" : 84,
"iid" : 14,
"issue_link_id": 1
"project_id" : 4,
"created_at" : "2016-01-07T12:44:33.959Z",
"title" : "Issues with auth",
"state" : "opened",
"assignees" : [],
"assignee" : null,
"labels" : [
"bug"
],
"author" : {
"name" : "Alexandra Bashirian",
"avatar_url" : null,
"state" : "active",
"web_url" : "https://gitlab.example.com/eileen.lowe",
"id" : 18,
"username" : "eileen.lowe"
},
"description" : null,
"updated_at" : "2016-01-07T12:44:33.959Z",
"milestone" : null,
"subscribed" : true,
"user_notes_count": 0,
"due_date": null,
"web_url": "http://example.com/example/example/issues/14",
"confidential": false,
"weight": null,
}
]
```
## Create an issue link
Creates a two-way relation between two issues. User must be allowed to update both issues in order to succeed.
```plaintext
POST /projects/:id/issues/:issue_iid/links
```
| 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 |
| `issue_iid` | integer | yes | The internal ID of a project's issue |
| `target_project_id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) of a target project |
| `target_issue_iid` | integer or string | yes | The internal ID of a target project's issue |
```json
{
"source_issue" : {
"id" : 83,
"iid" : 11,
"project_id" : 4,
"created_at" : "2016-01-07T12:44:33.959Z",
"title" : "Issues with auth",
"state" : "opened",
"assignees" : [],
"assignee" : null,
"labels" : [
"bug"
],
"author" : {
"name" : "Alexandra Bashirian",
"avatar_url" : null,
"state" : "active",
"web_url" : "https://gitlab.example.com/eileen.lowe",
"id" : 18,
"username" : "eileen.lowe"
},
"description" : null,
"updated_at" : "2016-01-07T12:44:33.959Z",
"milestone" : null,
"subscribed" : true,
"user_notes_count": 0,
"due_date": null,
"web_url": "http://example.com/example/example/issues/11",
"confidential": false,
"weight": null,
},
"target_issue" : {
"id" : 84,
"iid" : 14,
"project_id" : 4,
"created_at" : "2016-01-07T12:44:33.959Z",
"title" : "Issues with auth",
"state" : "opened",
"assignees" : [],
"assignee" : null,
"labels" : [
"bug"
],
"author" : {
"name" : "Alexandra Bashirian",
"avatar_url" : null,
"state" : "active",
"web_url" : "https://gitlab.example.com/eileen.lowe",
"id" : 18,
"username" : "eileen.lowe"
},
"description" : null,
"updated_at" : "2016-01-07T12:44:33.959Z",
"milestone" : null,
"subscribed" : true,
"user_notes_count": 0,
"due_date": null,
"web_url": "http://example.com/example/example/issues/14",
"confidential": false,
"weight": null,
}
}
```
## Delete an issue link
Deletes an issue link, removing the two-way relationship.
```plaintext
DELETE /projects/:id/issues/:issue_iid/links/:issue_link_id
```
| 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 |
| `issue_iid` | integer | yes | The internal ID of a project's issue |
| `issue_link_id` | integer or string | yes | The ID of an issue relationship |
```json
{
"source_issue" : {
"id" : 83,
"iid" : 11,
"project_id" : 4,
"created_at" : "2016-01-07T12:44:33.959Z",
"title" : "Issues with auth",
"state" : "opened",
"assignees" : [],
"assignee" : null,
"labels" : [
"bug"
],
"author" : {
"name" : "Alexandra Bashirian",
"avatar_url" : null,
"state" : "active",
"web_url" : "https://gitlab.example.com/eileen.lowe",
"id" : 18,
"username" : "eileen.lowe"
},
"description" : null,
"updated_at" : "2016-01-07T12:44:33.959Z",
"milestone" : null,
"subscribed" : true,
"user_notes_count": 0,
"due_date": null,
"web_url": "http://example.com/example/example/issues/11",
"confidential": false,
"weight": null,
},
"target_issue" : {
"id" : 84,
"iid" : 14,
"project_id" : 4,
"created_at" : "2016-01-07T12:44:33.959Z",
"title" : "Issues with auth",
"state" : "opened",
"assignees" : [],
"assignee" : null,
"labels" : [
"bug"
],
"author" : {
"name" : "Alexandra Bashirian",
"avatar_url" : null,
"state" : "active",
"web_url" : "https://gitlab.example.com/eileen.lowe",
"id" : 18,
"username" : "eileen.lowe"
},
"description" : null,
"updated_at" : "2016-01-07T12:44:33.959Z",
"milestone" : null,
"subscribed" : true,
"user_notes_count": 0,
"due_date": null,
"web_url": "http://example.com/example/example/issues/14",
"confidential": false,
"weight": null,
}
}
```
......@@ -107,8 +107,12 @@ The following table depicts the various user permission levels in a project.
| Remove a container registry image | | | ✓ | ✓ | ✓ |
| Create/edit/delete project milestones | | | ✓ | ✓ | ✓ |
| Use security dashboard **(ULTIMATE)** | | | ✓ | ✓ | ✓ |
| View vulnerabilities in Dependency list **(ULTIMATE)** | | | ✓ | ✓ | ✓ |
| Create issue from vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ |
| View vulnerability findings in Dependency list **(ULTIMATE)** | | | ✓ | ✓ | ✓ |
| Create issue from vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ |
| Dismiss vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ |
| View vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ |
| Create vulnerability from vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ |
| Resolve vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ |
| Dismiss vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ |
| Apply code change suggestions | | | ✓ | ✓ | ✓ |
| Create and edit wiki pages | | | ✓ | ✓ | ✓ |
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment