BED-4894: Posture API Spec (#953)

* chore: add quantization related parameters and schemas to openapi

* chore: add openapi spec for attack path finding-trends

* chore: add openapi spec for risk posture posture-history

* chore: partial implementation of partition_by for data-quality-stats

* chore: revert data-quality-stats openapi specs

* chore: add completeness data to posture-history and add unpartioned data format

* chore: update finding-trends openapi spec to use snake case

* chore: remove partitioning from posture-history openapi spec

* chore: update return data type for posture-history endpoint spec

* chore: update to use environment_id instead of domain_id

packages/go/openapi/doc/openapi.json

@@ -12170,6 +12170,125 @@
         }
       }
     },
+    "/api/v2/domains/{environment_id}/finding-trends": {
+      "parameters": [
+        {
+          "$ref": "#/components/parameters/header.prefer"
+        },
+        {
+          "name": "environment_id",
+          "description": "Environment ID",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "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": "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": {
+                        "data": {
+                          "type": "object",
+                          "properties": {
+                            "findings": {
+                              "type": "array",
+                              "items": {
+                                "type": "object",
+                                "properties": {
+                                  "environment_id": {
+                                    "type": "string"
+                                  },
+                                  "finding": {
+                                    "type": "string"
+                                  },
+                                  "composite_risk": {
+                                    "type": "number",
+                                    "format": "double"
+                                  },
+                                  "finding_count_start": {
+                                    "type": "integer"
+                                  },
+                                  "finding_count_end": {
+                                    "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": [
         {
@@ -13071,6 +13190,134 @@
         }
       }
     },
+    "/api/v2/domains/{environment_id}/posture-history/{data_type}": {
+      "parameters": [
+        {
+          "$ref": "#/components/parameters/header.prefer"
+        },
+        {
+          "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"
+          }
+        }
+      ],
+      "get": {
+        "operationId": "PostureHistoryForEnvironment",
+        "summary": "Get Posture History",
+        "description": "Gets posture data count changes over a time period",
+        "tags": [
+          "Risk Posture",
+          "Enterprise"
+        ],
+        "parameters": [
+          {
+            "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": {
+                        "data_type": {
+                          "$ref": "#/components/schemas/data_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"
+          }
+        }
+      },
+      "components": {
+        "schemas": {
+          "data_type": {
+            "type": "string",
+            "enum": [
+              "findings",
+              "exposure",
+              "assets",
+              "session_completeness",
+              "group_completeness"
+            ]
+          }
+        }
+      }
+    },
     "/api/v2/meta/{object_id}": {
       "parameters": [
         {
@@ -16026,6 +16273,16 @@
             }
           }
         ]
+      },
+      "data_type": {
+        "type": "string",
+        "enum": [
+          "findings",
+          "exposure",
+          "assets",
+          "session_completeness",
+          "group_completeness"
+        ]
       }
     },
     "responses": {

packages/go/openapi/src/openapi.yaml

@@ -642,6 +642,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-path-types:
     $ref: './paths/attack-paths.attack-path-types.yaml'
   /api/v2/attack-paths:
@@ -658,6 +660,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'
 
   # meta entity
   /api/v2/meta/{object_id}:

packages/go/openapi/src/paths/attack-paths.environment.id.finding-trends.yaml

@@ -0,0 +1,97 @@
+# 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
+
+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
+  description: Lists findings and their changes in between two dates for an environment
+  tags:
+    - 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: 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: './../schemas/api.response.time-window.yaml'
+              - type: object
+                properties:
+                  data:
+                    type: object
+                    properties:
+                      findings:
+                        type: array
+                        items:
+                          type: object
+                          properties:
+                            environment_id:
+                              type: string
+                            finding:
+                              type: string
+                            composite_risk:
+                              type: number
+                              format: double
+                            finding_count_start:
+                              type: integer
+                            finding_count_end:
+                              type: integer
+                      total_finding_count_start:
+                        type: integer
+                      total_finding_count_end:
+                        type: integer
+
+    400:
+      $ref: './../responses/bad-request.yaml'
+    401:
+      $ref: './../responses/unauthorized.yaml'
+    403:
+      $ref: './../responses/forbidden.yaml'
+    404:
+      $ref: './../responses/not-found.yaml'
+    429:
+      $ref: './../responses/too-many-requests.yaml'
+    500:
+      $ref: './../responses/internal-server-error.yaml'