Commit 7d49730a authored by Mehmet Emin INAC's avatar Mehmet Emin INAC

Update API docs for vulnerability export endpoints

parent d4b363e9
# Project Vulnerabilities API **(ULTIMATE)** # Vulnerability export API **(ULTIMATE)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/197494) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/197494) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. [Updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30397) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0.
CAUTION: **Caution:** CAUTION: **Caution:**
This API is currently in development and is protected by a **disabled** This API is currently in development and is protected by a **disabled**
...@@ -17,21 +17,21 @@ across GitLab releases. ...@@ -17,21 +17,21 @@ across GitLab releases.
Every API call to vulnerability exports must be [authenticated](README.md#authentication). Every API call to vulnerability exports must be [authenticated](README.md#authentication).
## Create a project-level vulnerability export
Creates a new vulnerability export for a project.
Vulnerability export permissions inherit permissions from their project. If a project is Vulnerability export 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 private and a user isn't a member of the project to which the vulnerability
belongs, requests to that project return a `404 Not Found` status code. belongs, requests to that project return a `404 Not Found` status code.
Vulnerability exports can be only accessed by the export's author. Vulnerability exports can be only accessed by the export's author.
## Create vulnerability export
Creates a new vulnerability export.
If an authenticated user doesn't have permission to If an authenticated user doesn't have permission to
[create a new vulnerability](../user/permissions.md#project-members-permissions), [create a new vulnerability](../user/permissions.md#project-members-permissions),
this request results in a `403` status code. this request results in a `403` status code.
```plaintext ```plaintext
POST /projects/:id/vulnerability_exports POST /security/projects/:id/vulnerability_exports
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
...@@ -39,7 +39,7 @@ POST /projects/:id/vulnerability_exports ...@@ -39,7 +39,7 @@ POST /projects/:id/vulnerability_exports
| `id` | integer or string | yes | The ID or [URL-encoded path](README.md#namespaced-path-encoding) of the project which the authenticated user is a member of | | `id` | integer or string | yes | The ID or [URL-encoded path](README.md#namespaced-path-encoding) of the project which the authenticated user is a member of |
```shell ```shell
curl --header POST "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/vulnerability_exports curl --header POST "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/security/projects/1/vulnerability_exports
``` ```
The created vulnerability export will be automatically deleted after 1 hour. The created vulnerability export will be automatically deleted after 1 hour.
...@@ -56,8 +56,40 @@ Example response: ...@@ -56,8 +56,40 @@ Example response:
"started_at": null, "started_at": null,
"finished_at": null, "finished_at": null,
"_links": { "_links": {
"self": "https://gitlab.example.com/api/v4/projects/1/vulnerability_exports/2", "self": "https://gitlab.example.com/api/v4/security/vulnerability_exports/2",
"download": "https://gitlab.example.com/api/v4/projects/1/vulnerability_exports/2/download" "download": "https://gitlab.example.com/api/v4/security/vulnerability_exports/2/download"
}
}
```
## Create an instance-level vulnerability export
Creates a new vulnerability export for the projects of the user selected in the Security Dashboard.
```plaintext
POST /security/vulnerability_exports
```
```shell
curl --header POST "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/security/vulnerability_exports
```
The created vulnerability export is automatically deleted after one hour.
Example response:
```json
{
"id": 2,
"created_at": "2020-03-30T09:35:38.746Z",
"project_id": null,
"format": "csv",
"status": "created",
"started_at": null,
"finished_at": null,
"_links": {
"self": "https://gitlab.example.com/api/v4/security/vulnerability_exports/2",
"download": "https://gitlab.example.com/api/v4/security/vulnerability_exports/2/download"
} }
} }
``` ```
...@@ -67,16 +99,15 @@ Example response: ...@@ -67,16 +99,15 @@ Example response:
Gets a single vulnerability export. Gets a single vulnerability export.
```plaintext ```plaintext
POST /projects/:id/vulnerability_exports/:vulnerability_export_id GET /security/vulnerability_exports/:id
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | | --------- | ---- | -------- | ----------- |
| `id` | integer or string | yes | The vulnerability's ID | | `id` | integer or string | yes | The vulnerability export's ID |
| `vulnerability_export_id` | integer or string | yes | The vulnerability export's ID |
```shell ```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/vulnerability_exports/2 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/security/vulnerability_exports/2
``` ```
If the vulnerability export isn't finished, the response is `202 Accepted`. If the vulnerability export isn't finished, the response is `202 Accepted`.
...@@ -93,8 +124,8 @@ Example response: ...@@ -93,8 +124,8 @@ Example response:
"started_at": "2020-03-30T09:36:54.469Z", "started_at": "2020-03-30T09:36:54.469Z",
"finished_at": "2020-03-30T09:36:55.008Z", "finished_at": "2020-03-30T09:36:55.008Z",
"_links": { "_links": {
"self": "https://gitlab.example.com/api/v4/projects/1/vulnerability_exports/2", "self": "https://gitlab.example.com/api/v4/security/vulnerability_exports/2",
"download": "https://gitlab.example.com/api/v4/projects/1/vulnerability_exports/2/download" "download": "https://gitlab.example.com/api/v4/security/vulnerability_exports/2/download"
} }
} }
``` ```
...@@ -104,16 +135,15 @@ Example response: ...@@ -104,16 +135,15 @@ Example response:
Downloads a single vulnerability export. Downloads a single vulnerability export.
```plaintext ```plaintext
POST /projects/:id/vulnerability_exports/:vulnerability_export_id/download GET /security/vulnerability_exports/:id/download
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | | --------- | ---- | -------- | ----------- |
| `id` | integer or string | yes | The vulnerability's ID | | `id` | integer or string | yes | The vulnerability export's ID |
| `vulnerability_export_id` | integer or string | yes | The vulnerability export's ID |
```shell ```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/vulnerability_exports/2/download curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/security/vulnerability_exports/2/download
``` ```
The response will be `404 Not Found` if the vulnerability export is not finished yet or was not found. The response will be `404 Not Found` if the vulnerability export is not finished yet or was not found.
......
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