From 3f8742bc0c0bb9cd7f3aa894866ba81844396c3e Mon Sep 17 00:00:00 2001 From: Conrad Weidenkeller Date: Thu, 20 Aug 2026 11:39:20 -0500 Subject: [PATCH] chore(openapi): Add Zone Protected Asset score docs --- packages/go/openapi/doc/openapi.json | 184 ++++++++++++++++++ packages/go/openapi/src/openapi.yaml | 5 + ...set-scores.zone-protected-asset-score.yaml | 149 ++++++++++++++ 3 files changed, 338 insertions(+) create mode 100644 packages/go/openapi/src/paths/asset-scores.zone-protected-asset-score.yaml diff --git a/packages/go/openapi/doc/openapi.json b/packages/go/openapi/doc/openapi.json index cb3338f8117..cc02bbf2116 100644 --- a/packages/go/openapi/doc/openapi.json +++ b/packages/go/openapi/doc/openapi.json @@ -19878,6 +19878,189 @@ } } }, + "/api/v2/asset-scores/zone-protected-asset-score": { + "parameters": [ + { + "$ref": "#/components/parameters/header.prefer" + } + ], + "get": { + "operationId": "GetZoneProtectedAssetScore", + "summary": "Get zone protected asset score", + "description": "Gets a per-day series describing how much of a zone is free of open findings\nover the requested time range. For each day in the range, the score is the\nnumber of objects in the zone without an open finding divided by the total\nnumber of objects in the zone. Zones that attack path analysis does not run\nagainst yield an empty series.\n", + "tags": [ + "Asset Scores", + "Enterprise" + ], + "parameters": [ + { + "name": "environments", + "description": "Environment IDs", + "in": "query", + "required": true, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "asset_group_tag_id", + "description": "The asset group tag id of the zone requested", + "in": "query", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "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": { + "type": "object", + "properties": { + "data": { + "allOf": [ + { + "$ref": "#/components/schemas/api.response.time-window" + }, + { + "type": "object", + "properties": { + "environments": { + "type": "array", + "description": "The environment IDs the caller has access to out of those requested", + "items": { + "type": "string" + } + }, + "asset_group_tag_id": { + "type": "integer", + "description": "The asset group tag id of the zone requested" + }, + "data": { + "type": "array", + "items": { + "type": "object", + "properties": { + "date": { + "type": "string", + "format": "date-time", + "readOnly": true + }, + "exposed_count": { + "type": "integer", + "format": "int64", + "description": "Number of objects in the zone holding an open finding", + "readOnly": true + }, + "protected_count": { + "type": "integer", + "format": "int64", + "description": "Number of objects in the zone without an open finding", + "readOnly": true + }, + "total_count": { + "type": "integer", + "format": "int64", + "description": "Total number of objects in the zone", + "readOnly": true + }, + "value": { + "type": "number", + "format": "double", + "description": "The protected share of the zone, `protected_count` divided by `total_count`", + "readOnly": true + } + } + } + } + } + } + ] + } + } + }, + "examples": { + "Zone protected asset score": { + "value": { + "data": { + "start": "2026-08-01T00:00:00Z", + "end": "2026-08-04T00:00:00Z", + "environments": [ + "S-1-5-21-1004336348-1177238915-682003330" + ], + "asset_group_tag_id": 1, + "data": [ + { + "date": "2026-08-01T00:00:00Z", + "exposed_count": 120, + "protected_count": 880, + "total_count": 1000, + "value": 0.88 + }, + { + "date": "2026-08-02T00:00:00Z", + "exposed_count": 95, + "protected_count": 905, + "total_count": 1000, + "value": 0.905 + }, + { + "date": "2026-08-03T00:00:00Z", + "exposed_count": 80, + "protected_count": 922, + "total_count": 1002, + "value": 0.9201596806387226 + } + ] + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/bad-request" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "429": { + "$ref": "#/components/responses/too-many-requests" + }, + "500": { + "$ref": "#/components/responses/internal-server-error" + } + } + } + }, "/api/v2/meta/{object_id}": { "parameters": [ { @@ -26289,6 +26472,7 @@ "Events (Schedules)", "Attack Paths", "Risk Posture", + "Asset Scores", "Meta Entities", "Alerts" ] diff --git a/packages/go/openapi/src/openapi.yaml b/packages/go/openapi/src/openapi.yaml index 237fd067f02..d3d5e0840fe 100644 --- a/packages/go/openapi/src/openapi.yaml +++ b/packages/go/openapi/src/openapi.yaml @@ -193,6 +193,7 @@ x-tagGroups: - Events (Schedules) - Attack Paths - Risk Posture + - Asset Scores - Meta Entities - Alerts paths: @@ -784,6 +785,10 @@ paths: /api/v2/posture-history/{data_type}: $ref: './paths/risk-posture.posture-history.data-type.yaml' + # asset scores + /api/v2/asset-scores/zone-protected-asset-score: + $ref: './paths/asset-scores.zone-protected-asset-score.yaml' + # meta entity /api/v2/meta/{object_id}: $ref: './paths/meta-entity.meta.id.yaml' diff --git a/packages/go/openapi/src/paths/asset-scores.zone-protected-asset-score.yaml b/packages/go/openapi/src/paths/asset-scores.zone-protected-asset-score.yaml new file mode 100644 index 00000000000..ba52f235561 --- /dev/null +++ b/packages/go/openapi/src/paths/asset-scores.zone-protected-asset-score.yaml @@ -0,0 +1,149 @@ +# Copyright 2026 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 + +parameters: + - $ref: './../parameters/header.prefer.yaml' + +get: + operationId: GetZoneProtectedAssetScore + summary: Get zone protected asset score + description: | + Gets a per-day series describing how much of a zone is free of open findings + over the requested time range. For each day in the range, the score is the + number of objects in the zone without an open finding divided by the total + number of objects in the zone. Zones that attack path analysis does not run + against yield an empty series. + tags: + - Asset Scores + - Enterprise + parameters: + - name: environments + description: Environment IDs + in: query + required: true + schema: + type: array + items: + type: string + - name: asset_group_tag_id + description: The asset group tag id of the zone requested + in: query + required: true + schema: + type: integer + - 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: + type: object + properties: + data: + allOf: + - $ref: './../schemas/api.response.time-window.yaml' + - type: object + properties: + environments: + type: array + description: The environment IDs the caller has access to + out of those requested + items: + type: string + asset_group_tag_id: + type: integer + description: The asset group tag id of the zone requested + data: + type: array + items: + type: object + properties: + date: + type: string + format: date-time + readOnly: true + exposed_count: + type: integer + format: int64 + description: Number of objects in the zone holding an + open finding + readOnly: true + protected_count: + type: integer + format: int64 + description: Number of objects in the zone without an + open finding + readOnly: true + total_count: + type: integer + format: int64 + description: Total number of objects in the zone + readOnly: true + value: + type: number + format: double + description: The protected share of the zone, + `protected_count` divided by `total_count` + readOnly: true + examples: + Zone protected asset score: + value: + data: + start: "2026-08-01T00:00:00Z" + end: "2026-08-04T00:00:00Z" + environments: + - "S-1-5-21-1004336348-1177238915-682003330" + asset_group_tag_id: 1 + data: + - date: "2026-08-01T00:00:00Z" + exposed_count: 120 + protected_count: 880 + total_count: 1000 + value: 0.88 + - date: "2026-08-02T00:00:00Z" + exposed_count: 95 + protected_count: 905 + total_count: 1000 + value: 0.905 + - date: "2026-08-03T00:00:00Z" + exposed_count: 80 + protected_count: 922 + total_count: 1002 + value: 0.9201596806387226 + 400: + $ref: './../responses/bad-request.yaml' + 401: + $ref: './../responses/unauthorized.yaml' + 403: + $ref: './../responses/forbidden.yaml' + 429: + $ref: './../responses/too-many-requests.yaml' + 500: + $ref: './../responses/internal-server-error.yaml'