Merge branch '197494-vulnerability-export-documentation' into 'master'

Add documentation for Vulnerability Export API

See merge request gitlab-org/gitlab!28423

doc/api/api_resources.md

@@ -71,8 +71,10 @@ 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](project_vulnerabilities.md) **(ULTIMATE)**   | `/projects/:id/vulnerabilities`                                                                                                                                                                            |
-| [Vulnerability Findings](vulnerability_findings.md) **(ULTIMATE)**  | `/projects/:id/vulnerability_findings`                                                                                                                                                                |
+| [Vulnerabilities](vulnerabilities.md) **(ULTIMATE)**                | `/vulnerabilities/:id`                                                                                                                                                                       |
+| [Vulnerability exports](vulnerability_exports.md) **(ULTIMATE)**    | `/projects/:id/vulnerability_exports`                                                                                                                                                                       |
+| [Project vulnerabilities](project_vulnerabilities.md) **(ULTIMATE)**   | `/projects/:id/vulnerabilities`                                                                                                                                                                            |
+| [Vulnerability findings](vulnerability_findings.md) **(ULTIMATE)**  | `/projects/:id/vulnerability_findings`                                                                                                                                                                |
 | [Wikis](wikis.md)                                                   | `/projects/:id/wikis`                                                                                                                                                                                 |
 
 ## Group resources

doc/api/vulnerability_exports.md

+# Project Vulnerabilities API **(ULTIMATE)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/197494) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10.
+
+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 Vulnerability Exports 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 vulnerability exports must be [authenticated](README.md#authentication).
+
+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
+belongs, requests to that project return a `404 Not Found` status code.
+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
+[create a new vulnerability](../user/permissions.md#project-members-permissions),
+this request results in a `403` status code.
+
+```plaintext
+POST /projects/:id/vulnerability_exports
+```
+
+| Attribute           | Type              | Required   | Description                                                                                                                  |
+| ------------------- | ----------------- | ---------- | -----------------------------------------------------------------------------------------------------------------------------|
+| `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
+curl --header POST "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/vulnerability_exports
+```
+
+The created vulnerability export will be automatically deleted after 1 hour.
+
+Example response:
+
+```json
+{
+  "id": 2,
+  "created_at": "2020-03-30T09:35:38.746Z",
+  "project_id": 1,
+  "format": "csv",
+  "status": "created",
+  "started_at": null,
+  "finished_at": null,
+  "_links": {
+    "self": "https://gitlab.example.com/api/v4/projects/1/vulnerability_exports/2",
+    "download": "https://gitlab.example.com/api/v4/projects/1/vulnerability_exports/2/download"
+  }
+}
+```
+
+## Get single vulnerability export
+
+Gets a single vulnerability export.
+
+```plaintext
+POST /projects/:id/vulnerability_exports/:vulnerability_export_id
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer or string | yes | The vulnerability's ID |
+| `vulnerability_export_id` | integer or string | yes | The vulnerability export's ID |
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/vulnerability_exports/2
+```
+
+If the vulnerability export isn't finished, the response is `202 Accepted`.
+
+Example response:
+
+```json
+{
+  "id": 2,
+  "created_at": "2020-03-30T09:35:38.746Z",
+  "project_id": 1,
+  "format": "csv",
+  "status": "finished",
+  "started_at": "2020-03-30T09:36:54.469Z",
+  "finished_at": "2020-03-30T09:36:55.008Z",
+  "_links": {
+    "self": "https://gitlab.example.com/api/v4/projects/1/vulnerability_exports/2",
+    "download": "https://gitlab.example.com/api/v4/projects/1/vulnerability_exports/2/download"
+  }
+}
+```
+
+## Download vulnerability export
+
+Downloads a single vulnerability export.
+
+```plaintext
+POST /projects/:id/vulnerability_exports/:vulnerability_export_id/download
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer or string | yes | The vulnerability's ID |
+| `vulnerability_export_id` | integer or string | yes | The vulnerability export's ID |
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/vulnerability_exports/2/download
+```
+
+The response will be `404 Not Found` if the vulnerability export is not finished yet or was not found.
+
+Example response:
+
+```csv
+Scanner Type,Scanner Name,Status,Vulnerability,Details,Additional Info,Severity,CVE
+container_scanning,Clair,confirmed,CVE-2017-16997 in glibc,,CVE-2017-16997 in glibc,critical,CVE-2017-16997
+container_scanning,Clair,detected,CVE-2017-18269 in glibc,,CVE-2017-18269 in glibc,critical,CVE-2017-18269
+container_scanning,Clair,detected,CVE-2018-1000001 in glibc,,CVE-2018-1000001 in glibc,high,CVE-2018-1000001
+container_scanning,Clair,detected,CVE-2016-10228 in glibc,,CVE-2016-10228 in glibc,medium,CVE-2016-10228
+container_scanning,Clair,confirmed,CVE-2010-4052 in glibc,,CVE-2010-4052 in glibc,low,CVE-2010-4052
+container_scanning,Clair,detected,CVE-2018-18520 in elfutils,,CVE-2018-18520 in elfutils,low,CVE-2018-18520
+container_scanning,Clair,detected,CVE-2018-16869 in nettle,,CVE-2018-16869 in nettle,unknown,CVE-2018-16869
+dependency_scanning,Gemnasium,detected,Regular Expression Denial of Service in debug,,Regular Expression Denial of Service in debug,unknown,yarn.lock:debug:gemnasium:37283ed4-0380-40d7-ada7-2d994afcc62a
+dependency_scanning,Gemnasium,detected,Authentication bypass via incorrect DOM traversal and canonicalization in saml2-js,,Authentication bypass via incorrect DOM traversal and canonicalization in saml2-js,unknown,yarn.lock:saml2-js:gemnasium:9952e574-7b5b-46fa-a270-aeb694198a98
+sast,Find Security Bugs,detected,Predictable pseudorandom number generator,,Predictable pseudorandom number generator,medium,818bf5dacb291e15d9e6dc3c5ac32178:PREDICTABLE_RANDOM:src/main/java/com/gitlab/security_products/tests/App.java:47
+sast,Find Security Bugs,detected,Cipher with no integrity,,Cipher with no integrity,medium,e6449b89335daf53c0db4c0219bc1634:CIPHER_INTEGRITY:src/main/java/com/gitlab/security_products/tests/App.java:29
+sast,Find Security Bugs,detected,Predictable pseudorandom number generator,,Predictable pseudorandom number generator,medium,e8ff1d01f74cd372f78da8f5247d3e73:PREDICTABLE_RANDOM:src/main/java/com/gitlab/security_products/tests/App.java:41
+sast,Find Security Bugs,confirmed,ECB mode is insecure 2,,ECB mode is insecure,medium,ea0f905fc76f2739d5f10a1fd1e37a10:ECB_MODE:src/main/java/com/gitlab/security_products/tests/App.java:29
+```