From 0476a90625b55da9e3e1fe7825af2aa1591f9ed5 Mon Sep 17 00:00:00 2001 From: Cody Bentley Date: Fri, 3 Jan 2025 11:16:39 -0700 Subject: [PATCH] feat: bed-5132 - updated openapi spec for posture page api contract --- packages/go/openapi/doc/openapi.json | 267 ++++++++++++++++++ packages/go/openapi/src/openapi.yaml | 8 +- ...ck-paths.attack-paths.finding-trends.yaml} | 41 +-- ...sk-posture.posture-history.data-type.yaml} | 35 +-- .../schemas/enum.posture-history-type.yaml | 24 ++ 5 files changed, 335 insertions(+), 40 deletions(-) rename packages/go/openapi/src/paths/{attack-paths.environment.id.finding-trends.yaml => attack-paths.attack-paths.finding-trends.yaml} (76%) rename packages/go/openapi/src/paths/{risk-posture.environment.id.posture-history.type.yaml => risk-posture.posture-history.data-type.yaml} (83%) create mode 100644 packages/go/openapi/src/schemas/enum.posture-history-type.yaml diff --git a/packages/go/openapi/doc/openapi.json b/packages/go/openapi/doc/openapi.json index b4f8c0b54d..9173b66709 100644 --- a/packages/go/openapi/doc/openapi.json +++ b/packages/go/openapi/doc/openapi.json @@ -12479,6 +12479,139 @@ } } }, + "/api/v2/attack-paths/finding-trends": { + "parameters": [ + { + "$ref": "#/components/parameters/header.prefer" + } + ], + "get": { + "operationId": "FindingTrendsForEnvironment", + "summary": "List finding trends", + "description": "Lists findings and their changes in between two dates for an environment", + "tags": [ + "Attack Paths", + "Enterprise" + ], + "parameters": [ + { + "name": "environments", + "description": "Environment IDs", + "in": "query", + "required": true, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "start", + "description": "Beginning datetime of range (inclusive) in RFC-3339 format; Defaults to current datetime minus 30 days", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "end", + "description": "Ending datetime of range (exclusive) in RFC-3339 format; Defaults to current datetime", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/api.response.time-window" + }, + { + "type": "object", + "properties": { + "environments": { + "type": "array", + "items": { + "type": "string" + } + }, + "data": { + "type": "object", + "properties": { + "findings": { + "type": "array", + "items": { + "type": "object", + "properties": { + "finding": { + "type": "string" + }, + "display_title": { + "type": "string" + }, + "display_type": { + "type": "string" + }, + "finding_count_start": { + "type": "integer" + }, + "finding_count_end": { + "type": "integer" + }, + "finding_count_increase": { + "type": "integer" + }, + "finding_count_decrease": { + "type": "integer" + } + } + } + }, + "total_finding_count_start": { + "type": "integer" + }, + "total_finding_count_end": { + "type": "integer" + } + } + } + } + } + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/bad-request" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not-found" + }, + "429": { + "$ref": "#/components/responses/too-many-requests" + }, + "500": { + "$ref": "#/components/responses/internal-server-error" + } + } + } + }, "/api/v2/attack-path-types": { "parameters": [ { @@ -13376,6 +13509,129 @@ } } }, + "/api/v2/posture-history/{data_type}": { + "parameters": [ + { + "$ref": "#/components/parameters/header.prefer" + }, + { + "name": "data_type", + "description": "The type of posture data to return", + "in": "path", + "required": true, + "schema": { + "$ref": "#/components/schemas/enum.posture-history-type" + } + } + ], + "get": { + "operationId": "PostureHistoryForEnvironments", + "summary": "Get Posture History", + "description": "Gets posture data count changes over a time period", + "tags": [ + "Risk Posture", + "Enterprise" + ], + "parameters": [ + { + "name": "environments", + "description": "Environment IDs", + "in": "query", + "required": true, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "start", + "description": "Beginning datetime of range (inclusive) in RFC-3339 format; Defaults to current datetime minus 30 days", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "end", + "description": "Ending datetime of range (exclusive) in RFC-3339 format; Defaults to current datetime", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/api.response.time-window" + }, + { + "type": "object", + "properties": { + "environments": { + "type": "array", + "items": { + "type": "string" + } + }, + "data_type": { + "$ref": "#/components/schemas/enum.posture-history-type" + }, + "data": { + "type": "array", + "items": { + "type": "object", + "properties": { + "date": { + "type": "string", + "format": "date-time", + "readOnly": true + }, + "value": { + "type": "number", + "format": "double", + "readOnly": true + } + } + } + } + } + } + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/bad-request" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not-found" + }, + "429": { + "$ref": "#/components/responses/too-many-requests" + }, + "500": { + "$ref": "#/components/responses/internal-server-error" + } + } + } + }, "/api/v2/meta/{object_id}": { "parameters": [ { @@ -16323,6 +16579,17 @@ } } ] + }, + "enum.posture-history-type": { + "type": "string", + "description": "This enum describes the valid data types for posture history results.", + "enum": [ + "findings", + "exposure", + "assets", + "session_completeness", + "group_completeness" + ] } }, "responses": { diff --git a/packages/go/openapi/src/openapi.yaml b/packages/go/openapi/src/openapi.yaml index 18634a3866..b2f91ecfea 100644 --- a/packages/go/openapi/src/openapi.yaml +++ b/packages/go/openapi/src/openapi.yaml @@ -646,8 +646,8 @@ paths: # attack paths /api/v2/domains/{domain_id}/attack-path-findings: $ref: './paths/attack-paths.domains.id.attack-path-findings.yaml' -# /api/v2/domains/{environment_id}/finding-trends: -# $ref: './paths/attack-paths.environment.id.finding-trends.yaml' + /api/v2/attack-paths/finding-trends: + $ref: './paths/attack-paths.attack-paths.finding-trends.yaml' /api/v2/attack-path-types: $ref: './paths/attack-paths.attack-path-types.yaml' /api/v2/attack-paths: @@ -664,8 +664,8 @@ paths: # risk posture /api/v2/posture-stats: $ref: './paths/risk-posture.posture-stats.yaml' -# /api/v2/domains/{environment_id}/posture-history/{data_type}: -# $ref: './paths/risk-posture.environment.id.posture-history.type.yaml' + /api/v2/posture-history/{data_type}: + $ref: './paths/risk-posture.posture-history.data-type.yaml' # meta entity /api/v2/meta/{object_id}: diff --git a/packages/go/openapi/src/paths/attack-paths.environment.id.finding-trends.yaml b/packages/go/openapi/src/paths/attack-paths.attack-paths.finding-trends.yaml similarity index 76% rename from packages/go/openapi/src/paths/attack-paths.environment.id.finding-trends.yaml rename to packages/go/openapi/src/paths/attack-paths.attack-paths.finding-trends.yaml index 548b255215..839c4f34d0 100644 --- a/packages/go/openapi/src/paths/attack-paths.environment.id.finding-trends.yaml +++ b/packages/go/openapi/src/paths/attack-paths.attack-paths.finding-trends.yaml @@ -16,12 +16,7 @@ parameters: - $ref: './../parameters/header.prefer.yaml' - - name: environment_id - description: Environment ID - in: path - required: true - schema: - type: string + get: operationId: FindingTrendsForEnvironment summary: List finding trends @@ -30,11 +25,14 @@ get: - Attack Paths - Enterprise parameters: - # - name: sort_by - # description: Sortable columns are composite_risk, start_count, end_count, change. - # in: query - # schema: - # $ref: './../schemas/api.params.query.sort-by.yaml' + - name: environments + description: Environment IDs + in: query + required: true + schema: + type: array + items: + type: string - name: start description: Beginning datetime of range (inclusive) in RFC-3339 format; Defaults to current datetime minus 30 days @@ -59,6 +57,10 @@ get: - $ref: './../schemas/api.response.time-window.yaml' - type: object properties: + environments: + type: array + items: + type: string data: type: object properties: @@ -67,17 +69,24 @@ get: items: type: object properties: - environment_id: - type: string +# environments: // TODO: to be determined if useful +# type: array +# items: +# type: string finding: type: string - composite_risk: - type: number - format: double + display_title: + type: string + display_type: + type: string finding_count_start: type: integer finding_count_end: type: integer + finding_count_increase: + type: integer + finding_count_decrease: + type: integer total_finding_count_start: type: integer total_finding_count_end: diff --git a/packages/go/openapi/src/paths/risk-posture.environment.id.posture-history.type.yaml b/packages/go/openapi/src/paths/risk-posture.posture-history.data-type.yaml similarity index 83% rename from packages/go/openapi/src/paths/risk-posture.environment.id.posture-history.type.yaml rename to packages/go/openapi/src/paths/risk-posture.posture-history.data-type.yaml index 01fb001306..5e4b31f3af 100644 --- a/packages/go/openapi/src/paths/risk-posture.environment.id.posture-history.type.yaml +++ b/packages/go/openapi/src/paths/risk-posture.posture-history.data-type.yaml @@ -16,26 +16,28 @@ parameters: - $ref: './../parameters/header.prefer.yaml' - - name: environment_id - description: Environment ID - in: path - required: true - schema: - type: string - name: data_type description: The type of posture data to return in: path required: true schema: - $ref: '#/components/schemas/data_type' + $ref: './../schemas/enum.posture-history-type.yaml' get: - operationId: PostureHistoryForEnvironment + operationId: PostureHistoryForEnvironments summary: Get Posture History description: Gets posture data count changes over a time period tags: - Risk Posture - Enterprise parameters: + - name: environments + description: Environment IDs + in: query + required: true + schema: + type: array + items: + type: string - name: start description: Beginning datetime of range (inclusive) in RFC-3339 format; Defaults to current datetime minus 30 days @@ -60,8 +62,12 @@ get: - $ref: './../schemas/api.response.time-window.yaml' - type: object properties: + environments: + type: array + items: + type: string data_type: - $ref: '#/components/schemas/data_type' + $ref: './../schemas/enum.posture-history-type.yaml' data: type: array items: @@ -88,14 +94,3 @@ get: $ref: './../responses/too-many-requests.yaml' 500: $ref: './../responses/internal-server-error.yaml' - -components: - schemas: - data_type: - type: string - enum: - - findings - - exposure - - assets - - session_completeness - - group_completeness diff --git a/packages/go/openapi/src/schemas/enum.posture-history-type.yaml b/packages/go/openapi/src/schemas/enum.posture-history-type.yaml new file mode 100644 index 0000000000..4947864a23 --- /dev/null +++ b/packages/go/openapi/src/schemas/enum.posture-history-type.yaml @@ -0,0 +1,24 @@ +# Copyright 2024 Specter Ops, Inc. +# +# Licensed under the Apache License, Version 2.0 +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +type: string +description: This enum describes the valid data types for posture history results. +enum: + - findings + - exposure + - assets + - session_completeness + - group_completeness