Add doc stubs for Vulnerabilities-related APIs

Add stubs for:
- Project Vulnerability Findings API
  (former Project Vulnerabilities API)
- Project Vulnerabilities API
- Standalone Vulnerabilities API
- Permissions table with new permissions
  for Vulnerabilities

doc/api/api_resources.md

@@ -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`                                                                                                                                                                                 |
 

doc/api/vulnerabilities.md

 # 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
+}
+```

doc/api/vulnerability_issue_links.md

+# 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,
+  }
+}
+```

doc/user/permissions.md

@@ -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                        |         |            | ✓           | ✓        | ✓      |