From 4a50f5c86eaa9a7d62ad8a85fc55a2c164e7ca2f Mon Sep 17 00:00:00 2001 From: tinygrasshopper <451613+tinygrasshopper@users.noreply.github.com> Date: Wed, 18 Sep 2024 11:01:27 +0000 Subject: [PATCH] docs: synchronizing api spec with user-docs --- docs/.gitbook/assets/rest-spec.json | 187 +++++++++--------------- docs/snyk-api/rest-api/changelog.md | 29 ++++ tools/api-docs-generator/sync-state.yml | 2 +- 3 files changed, 97 insertions(+), 121 deletions(-) diff --git a/docs/.gitbook/assets/rest-spec.json b/docs/.gitbook/assets/rest-spec.json index 3244e94ee53c..98a5c46d4ca6 100644 --- a/docs/.gitbook/assets/rest-spec.json +++ b/docs/.gitbook/assets/rest-spec.json @@ -2440,7 +2440,7 @@ ], "type": "object" }, - "CommonIssueModel": { + "CommonIssueModelVThree": { "properties": { "attributes": { "properties": { @@ -2471,11 +2471,6 @@ ], "type": "string" }, - "key": { - "description": "The Snyk vulnerability ID.", - "example": "SNYK-JAVA-COMFASTERXMLWOODSTOX-2928754", - "type": "string" - }, "problems": { "items": { "$ref": "#/components/schemas/Problem" @@ -2483,86 +2478,7 @@ "type": "array" }, "severities": { - "description": "The severity level of the vulnerability: ‘low’, ‘medium’, ‘high’ or ‘critical’.", - "items": { - "$ref": "#/components/schemas/Severity" - }, - "type": "array" - }, - "slots": { - "$ref": "#/components/schemas/Slots" - }, - "title": { - "description": "A human-readable title for this issue.", - "example": "XML External Entity (XXE) Injection", - "type": "string" - }, - "type": { - "description": "The issue type", - "example": "package_vulnerability", - "type": "string" - }, - "updated_at": { - "description": "When the vulnerability information was last modified.", - "example": "2022-06-16T14:00:24.315507Z", - "format": "date-time", - "type": "string" - } - }, - "type": "object" - }, - "id": { - "description": "The Snyk ID of the vulnerability.", - "example": "SNYK-JAVA-COMFASTERXMLWOODSTOX-2928754", - "type": "string" - }, - "type": { - "description": "The type of the REST resource. Always ‘issue’.", - "example": "issue", - "type": "string" - } - }, - "type": "object" - }, - "CommonIssueModelVTwo": { - "properties": { - "attributes": { - "properties": { - "coordinates": { - "items": { - "$ref": "#/components/schemas/CoordinateVTwo" - }, - "type": "array" - }, - "created_at": { - "example": "2022-06-16T13:51:13Z", - "format": "date-time", - "type": "string" - }, - "description": { - "description": "A description of the issue in Markdown format", - "example": "## Overview\\n\\n\\nAffected versions of this package are vulnerable to XML External Entity (XXE) Injection.", - "type": "string" - }, - "effective_severity_level": { - "description": "The type from enumeration of the issue’s severity level. This is usually set from the issue’s producer, but can be overridden by policies.", - "enum": [ - "info", - "low", - "medium", - "high", - "critical" - ], - "type": "string" - }, - "problems": { - "items": { - "$ref": "#/components/schemas/Problem" - }, - "type": "array" - }, - "severities": { - "description": "The severity level of the vulnerability: ‘low’, ‘medium’, ‘high’ or ‘critical’.", + "description": "An array of dictionaries containing all known data related to the vulnerability", "items": { "$ref": "#/components/schemas/Severity" }, @@ -2624,25 +2540,6 @@ "type": "string" }, "Coordinate": { - "properties": { - "remedies": { - "items": { - "$ref": "#/components/schemas/Remedy" - }, - "type": "array" - }, - "representation": { - "description": "The affected versions of this vulnerability.", - "items": { - "example": "5.3.0", - "type": "string" - }, - "type": "array" - } - }, - "type": "object" - }, - "CoordinateVTwo": { "properties": { "remedies": { "items": { @@ -3356,6 +3253,26 @@ }, "type": "object" }, + "ExploitDetails": { + "description": "Details about the exploits", + "properties": { + "maturity_levels": { + "description": "List of maturity levels", + "items": { + "$ref": "#/components/schemas/MaturityLevel" + }, + "type": "array" + }, + "sources": { + "description": "Sources for determining exploit maturity level, e.g., CISA, ExploitDB, Snyk.", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + }, "FilePosition": { "properties": { "column": { @@ -4816,7 +4733,7 @@ "properties": { "data": { "items": { - "$ref": "#/components/schemas/CommonIssueModel" + "$ref": "#/components/schemas/CommonIssueModelVThree" }, "type": "array" }, @@ -4836,7 +4753,7 @@ "properties": { "data": { "items": { - "$ref": "#/components/schemas/CommonIssueModelVTwo" + "$ref": "#/components/schemas/CommonIssueModelVThree" }, "type": "array" }, @@ -4979,6 +4896,27 @@ }, "type": "object" }, + "MaturityLevel": { + "description": "Details about the maturity level", + "properties": { + "format": { + "description": "The standard by which the “maturity” value is shown.", + "example": "CVSSv4", + "type": "string" + }, + "level": { + "description": "Exploit maturity of the vulnerability. For CVSSv3: Proof of Concept, Functional, High. For CVSSv4: Unreported, Proof of Concept, Attacked.", + "example": "Attacked", + "type": "string" + }, + "type": { + "description": "Indicates if the CVSS item is primary or secondary. Clients should prefer the primary CVSS vector.", + "example": "primary", + "type": "string" + } + }, + "type": "object" + }, "MemberRoleRelationship": { "additionalProperties": false, "nullable": true, @@ -5736,12 +5674,12 @@ "properties": { "name": { "description": "The package’s name", - "example": "woodstox-core", + "example": "spring-core", "type": "string" }, "namespace": { "description": "A name prefix, such as a maven group id or docker image owner", - "example": "com.fasterxml.woodstox", + "example": "org.springframework", "type": "string" }, "type": { @@ -5756,7 +5694,7 @@ }, "version": { "description": "The version of the package", - "example": "5.0.0", + "example": "1.0.0", "type": "string" } }, @@ -7573,11 +7511,12 @@ "Severity": { "properties": { "level": { + "description": "Level of severity calculated via vector", "example": "medium", "type": "string" }, "score": { - "description": "The CVSSv3 value of the vulnerability.", + "description": "The CVSS score calculated from the vector, representing the severity of the vulnerability on a scale from 0 to 10.", "example": 5.3, "nullable": true, "type": "number" @@ -7587,11 +7526,21 @@ "example": "Snyk", "type": "string" }, + "type": { + "description": "Indicates if the CVSS item is primary or secondary. Clients should prefer the primary CVSS vector.", + "example": "primary", + "type": "string" + }, "vector": { - "description": "The CVSSv3 value of the vulnerability.", + "description": "CVSS vector string detailing the metrics of a vulnerability.", "example": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:L", "nullable": true, "type": "string" + }, + "version": { + "description": "CVSS version being described.", + "example": "4.0", + "type": "string" } }, "type": "object" @@ -7681,10 +7630,8 @@ "format": "date-time", "type": "string" }, - "exploit": { - "description": "The exploit maturity. Value of ‘No Data’, ‘Not Defined’, ‘Unproven’, ‘Proof of Concept’, ‘Functional’ or ‘High’.", - "example": "Not Defined", - "type": "string" + "exploit_details": { + "$ref": "#/components/schemas/ExploitDetails" }, "publication_time": { "description": "The time at which this vulnerability was published.", @@ -44900,9 +44847,9 @@ "2023-03-29~beta", "2023-04-17", "2023-08-21", - "2024-06-26~beta" + "2024-06-26" ], - "x-snyk-api-version": "2023-08-21" + "x-snyk-api-version": "2024-06-26" }, "x-snyk-api-resource": "issues" }, @@ -45001,9 +44948,9 @@ "x-snyk-api-releases": [ "2022-06-29~beta", "2022-09-15", - "2024-06-26~beta" + "2024-06-26" ], - "x-snyk-api-version": "2022-09-15" + "x-snyk-api-version": "2024-06-26" }, "x-snyk-api-resource": "issues" }, diff --git a/docs/snyk-api/rest-api/changelog.md b/docs/snyk-api/rest-api/changelog.md index 741e6086ecf2..f608bb387e83 100644 --- a/docs/snyk-api/rest-api/changelog.md +++ b/docs/snyk-api/rest-api/changelog.md @@ -1,3 +1,32 @@ +## 2024-09-04 + +### GET - `/orgs/{org_id}/packages/{purl}/issues` - Updated +- removed the optional property `data/items/attributes/coordinates/items/representation` from the response with the `200` status +![Badge](https://img.shields.io/badge/Breaking-yellow) +- removed the optional property `data/items/attributes/key` from the response with the `200` status +![Badge](https://img.shields.io/badge/Breaking-yellow) +- removed the optional property `data/items/attributes/slots/exploit` from the response with the `200` status +![Badge](https://img.shields.io/badge/Breaking-yellow) +- added the optional property `data/items/attributes/severities/items/type` to the response with the `200` status + +- added the optional property `data/items/attributes/severities/items/version` to the response with the `200` status + +- added the optional property `data/items/attributes/slots/exploit_details` to the response with the `200` status + +- added the required property `data/items/attributes/coordinates/items/representations` to the response with the `200` status + + + +### POST - `/orgs/{org_id}/packages/issues` - Updated +- removed the optional property `data/items/attributes/slots/exploit` from the response with the `200` status +![Badge](https://img.shields.io/badge/Breaking-yellow) +- added the optional property `data/items/attributes/severities/items/type` to the response with the `200` status + +- added the optional property `data/items/attributes/severities/items/version` to the response with the `200` status + +- added the optional property `data/items/attributes/slots/exploit_details` to the response with the `200` status + + ## 2024-08-25 - Updated 2024-09-11 ### POST - `/orgs/{org_id}/apps` - Updated diff --git a/tools/api-docs-generator/sync-state.yml b/tools/api-docs-generator/sync-state.yml index a8259879ad74..218f63061313 100644 --- a/tools/api-docs-generator/sync-state.yml +++ b/tools/api-docs-generator/sync-state.yml @@ -1 +1 @@ -lastSyncedVersion: "2024-08-25" +lastSyncedVersion: "2024-09-04"