SpecterOps Data Quality API

openapi: 3.2.0
info:
  title: BloodHound Data Quality API
  contact:
    name: BloodHound Enterprise Support
    url: https://bloodhound.specterops.io/
    email: support@specterops.io
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: v2
  description: This is the API that drives BloodHound Enterprise and Community Edition.
servers:
- url: /
  description: This is the base path for all endpoints, relative to the domain where the API is being hosted.
security:
- JWTBearerToken: []
- SignedRequest: []
  RequestDate: []
  HMACSignature: []
tags:
- name: Data Quality
paths:
  /api/v2/completeness:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    get:
      operationId: GetCompletenessStats
      summary: Get database completeness stats
      description: Get the percentage of local admins and sessions collected
      tags:
      - Data Quality
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    additionalProperties:
                      type: number
                      format: double
        '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/ad-domains/{domain_id}/data-quality-stats:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    - name: domain_id
      description: Domain ID
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: GetAdDomainDataQualityStats
      summary: Get AD domain data quality stats
      description: Time series list of data quality stats for a given AD domain
      tags:
      - Data Quality
      parameters:
      - name: sort_by
        description: Sortable columns are created_at, updated_at.
        in: query
        schema:
          $ref: '#/components/schemas/api.params.query.sort-by'
      - 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 (inclusive) in RFC-3339 format; Defaults to current datetime
        in: query
        schema:
          type: string
          format: date-time
      - $ref: '#/components/parameters/query.skip'
      - $ref: '#/components/parameters/query.limit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/api.response.pagination'
                - $ref: '#/components/schemas/api.response.time-window'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/model.ad-data-quality-stat'
        '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/azure-tenants/{tenant_id}/data-quality-stats:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    - name: tenant_id
      description: Tenant ID
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: GetAzureTenantDataQualityStats
      summary: Get Azure tenant data quality stats
      description: Time series list of data quality stats for a given Azure tenant
      tags:
      - Data Quality
      parameters:
      - name: sort_by
        description: Sortable columns are created_at, updated_at.
        in: query
        schema:
          $ref: '#/components/schemas/api.params.query.sort-by'
      - 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 (inclusive) in RFC-3339 format; Defaults to current datetime
        in: query
        schema:
          type: string
          format: date-time
      - $ref: '#/components/parameters/query.skip'
      - $ref: '#/components/parameters/query.limit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/api.response.pagination'
                - $ref: '#/components/schemas/api.response.time-window'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/model.azure-data-quality-stat'
        '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/platform/{platform_id}/data-quality-stats:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    - name: platform_id
      description: Platform ID
      in: path
      required: true
      schema:
        type: string
        enum:
        - ad
        - azure
    get:
      operationId: GetPlatformDataQualityAggregate
      summary: Get platform data quality aggregate
      description: Time series list of aggregate data quality stats for a given platform
      tags:
      - Data Quality
      parameters:
      - name: sort_by
        description: Sortable columns are created_at, updated_at.
        in: query
        schema:
          $ref: '#/components/schemas/api.params.query.sort-by'
      - 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 (inclusive) in RFC-3339 format; Defaults to current datetime
        in: query
        schema:
          type: string
          format: date-time
      - $ref: '#/components/parameters/query.skip'
      - $ref: '#/components/parameters/query.limit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.response.data-quality-platform-aggregate'
        '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/data-quality-stats:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    get:
      operationId: GetDataQualityStats
      summary: Get environment-specific data quality stats
      description: Time series list of data quality stats for a given environment
      tags:
      - Data Quality
      parameters:
      - name: environment_id
        description: Required. Filters results to the given environment.
        required: true
        in: query
        schema:
          type: string
      - name: sort_by
        description: Sortable columns are created_at, updated_at.
        in: query
        schema:
          $ref: '#/components/schemas/api.params.query.sort-by'
      - 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 (inclusive) in RFC-3339 format; Defaults to current datetime
        in: query
        schema:
          type: string
          format: date-time
      - $ref: '#/components/parameters/query.skip'
      - $ref: '#/components/parameters/query.limit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/api.response.pagination'
                - $ref: '#/components/schemas/api.response.time-window'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/model.data-quality-stat'
        '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/data-quality-stats-aggregations:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    get:
      operationId: GetDataQualityAggregations
      summary: Get data quality aggregations by environment kind
      description: Returns data quality metric counts aggregated per environment kind, optionally scoped to an OpenGraph schema extension, combined across environment instances for each collection run. Results can be filtered, sorted, and paginated.
      tags:
      - Data Quality
      parameters:
      - name: schema_environment_kind_id
        description: 'Required. Scopes the aggregation to a single environment kind id.

          '
        in: query
        required: true
        schema:
          type: integer
          format: int32
      - name: schema_extension_id
        description: 'Optional. Scopes the aggregation to a single OpenGraph schema extension id. The extension must exist or a 404 is returned.

          '
        in: query
        schema:
          type: integer
          format: int32
      - name: sort_by
        description: 'Sortable columns are created_at, updated_at.

          '
        in: query
        schema:
          $ref: '#/components/schemas/api.params.query.sort-by'
      - 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 (inclusive) in RFC-3339 format; Defaults to current datetime
        in: query
        schema:
          type: string
          format: date-time
      - $ref: '#/components/parameters/query.skip'
      - $ref: '#/components/parameters/query.limit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/api.response.pagination'
                - $ref: '#/components/schemas/api.response.time-window'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/model.data-quality-aggregation'
        '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:
  responses:
    forbidden:
      description: '**Forbidden**

        This is most commonly caused by an authenticated client trying to

        access a resource that it does not have permission for.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/api.error-wrapper'
          example:
            http_status: 403
            timestamp: '2024-02-19T19:27:43.866Z'
            request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            errors:
            - context: clients
              message: You do not have permission to access this resource
    internal-server-error:
      description: '**Internal Server Error**

        This is usually the result of either an unexpected database or application error.

        The client may try modifying or resending the request, but the error is likely not related to the client

        doing something wrong.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/api.error-wrapper'
          example:
            http_status: 500
            timestamp: '2024-02-19T19:27:43.866Z'
            request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            errors:
            - context: clients
              message: The request could not be handled due to an unexpected database error.
    unauthorized:
      description: '**Unauthorized**

        This endpoint failed an authentication requirement. Either the client tried to access

        a protected endpoint without being authenticated, or an auth validation failed (ex- invalid

        credentials or expired token).

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/api.error-wrapper'
          example:
            http_status: 401
            timestamp: '2024-02-19T19:27:43.866Z'
            request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            errors:
            - context: login
              message: Unauthorized
    too-many-requests:
      description: '**Too Many Requests**

        The client has sent too many requests within a certain time window

        and tripped the rate limiting middleware.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/api.error-wrapper'
          example:
            http_status: 429
            timestamp: '2024-02-19T19:27:43.866Z'
            request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            errors:
            - context: middleware
              message: Too many requests. Please try again later.
    not-found:
      description: '**Not Found**

        This error typically comes from operations where a valid ID was passed to the request

        to look up an entity but the entity could not be found.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/api.error-wrapper'
          example:
            http_status: 404
            timestamp: '2024-02-19T19:27:43.866Z'
            request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            errors:
            - context: clients
              message: The requested client could not be found.
    bad-request:
      description: '**Bad Request**

        This could be due to one of the following reasons:

        - JSON payload is missing or malformed

        - Path or query parameters are missing or invalid/malformed

        - The data sent is not valid (ex- sending a `string` in an `integer` field)

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/api.error-wrapper'
          example:
            http_status: 400
            timestamp: '2024-02-19T19:27:43.866Z'
            request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            errors:
            - context: clients
              message: The JSON payload could not be unmarshalled.
  schemas:
    api.params.query.limit:
      type: integer
      minimum: 0
      description: The limit of results requested by the client.
    api.response.data-quality-platform-aggregate:
      allOf:
      - $ref: '#/components/schemas/api.response.pagination'
      - $ref: '#/components/schemas/api.response.time-window'
      - type: object
        properties:
          data:
            type: array
            items:
              oneOf:
              - $ref: '#/components/schemas/model.ad-data-quality-aggregation'
              - $ref: '#/components/schemas/model.azure-data-quality-aggregation'
    model.components.int32.id:
      type: object
      properties:
        id:
          type: integer
          format: int32
          readOnly: true
          description: This is the unique identifier for this object.
    model.azure-data-quality-aggregation:
      allOf:
      - $ref: '#/components/schemas/model.components.int32.id'
      - $ref: '#/components/schemas/model.components.timestamps'
      - type: object
        properties:
          tenants:
            type: integer
          users:
            type: integer
          groups:
            type: integer
          apps:
            type: integer
          service_principals:
            type: integer
          devices:
            type: integer
          management_groups:
            type: integer
          subscriptions:
            type: integer
          resource_groups:
            type: integer
          vms:
            type: integer
          key_vaults:
            type: integer
          relationships:
            type: integer
          run_id:
            type: string
            format: uuid
    null.time:
      type: object
      properties:
        time:
          type: string
          format: date-time
          description: An RFC-3339 formatted string
        valid:
          description: Valid is true if `time` is not `null`.
          type: boolean
    api.error-detail:
      type: object
      properties:
        context:
          type: string
          description: The context in which the error took place
        message:
          type: string
          description: A human-readable description of the error
    api.params.query.sort-by:
      type: string
      description: 'Sort by column. Can be used multiple times; prepend a hyphen for descending order.

        See parameter description for details about which columns are sortable.

        '
    model.components.timestamps:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        deleted_at:
          readOnly: true
          allOf:
          - $ref: '#/components/schemas/null.time'
    model.ad-data-quality-stat:
      allOf:
      - $ref: '#/components/schemas/model.components.int32.id'
      - $ref: '#/components/schemas/model.components.timestamps'
      - type: object
        properties:
          domain_sid:
            type: string
          users:
            type: integer
          groups:
            type: integer
          computers:
            type: integer
          ous:
            type: integer
          containers:
            type: integer
          gpos:
            type: integer
          aiacas:
            type: integer
          rootcas:
            type: integer
          enterprisecas:
            type: integer
          ntauthstores:
            type: integer
          certtemplates:
            type: integer
          acls:
            type: integer
          sessions:
            type: integer
          relationships:
            type: integer
          session_completeness:
            type: number
            format: double
          local_group_completeness:
            type: number
            format: double
          run_id:
            type: string
            format: uuid
    model.data-quality-stat:
      allOf:
      - $ref: '#/components/schemas/model.components.int32.id'
      - $ref: '#/components/schemas/model.components.timestamps'
      - type: object
        properties:
          extension_id:
            type: integer
          environment_kind_id:
            type: integer
          environment_id:
            type: string
          metric_type:
            type: string
            enum:
            - node
            - relationship
          metric_name:
            type: string
          metric_value:
            type: number
            format: double
          kind_id:
            description: The kind ID for the counted node kind. Present when `metric_type` is `node`; otherwise null.
            type:
            - integer
            - 'null'
            format: int32
          run_id:
            type: string
            format: uuid
    api.response.time-window:
      type: object
      properties:
        start:
          type: string
          format: date-time
          description: The RFC-3339 timestamp to describe the beginning of a time range
        end:
          type: string
          format: date-time
          description: The RFC-3339 timestamp to describe the end of a time range
    api.response.pagination:
      type: object
      properties:
        count:
          type: integer
          minimum: 0
          description: The total number of results.
        skip:
          $ref: '#/components/schemas/api.params.query.skip'
        limit:
          $ref: '#/components/schemas/api.params.query.limit'
    model.data-quality-aggregation:
      allOf:
      - $ref: '#/components/schemas/model.components.int32.id'
      - $ref: '#/components/schemas/model.components.timestamps'
      - type: object
        properties:
          run_id:
            type: string
          extension_id:
            type: integer
            format: int32
          environment_kind_id:
            type: integer
            format: int32
          metric_type:
            type: string
            enum:
            - node
            - relationship
          metric_name:
            type: string
          metric_value:
            type: number
            format: double
          kind_id:
            description: The kind ID for the counted node kind. Present when `metric_type` is `node`; otherwise null.
            type:
            - integer
            - 'null'
            format: int32
    api.params.query.skip:
      type: integer
      minimum: 0
      description: The number of items to skip in a paginated response.
    model.azure-data-quality-stat:
      allOf:
      - $ref: '#/components/schemas/model.components.int32.id'
      - $ref: '#/components/schemas/model.components.timestamps'
      - type: object
        properties:
          tenantid:
            type: string
            format: uuid
          users:
            type: integer
          groups:
            type: integer
          apps:
            type: integer
          service_principals:
            type: integer
          devices:
            type: integer
          management_groups:
            type: integer
          subscriptions:
            type: integer
          resource_groups:
            type: integer
          vms:
            type: integer
          key_vaults:
            type: integer
          relationships:
            type: integer
          run_id:
            type: string
            format: uuid
    api.error-wrapper:
      type: object
      description: ''
      properties:
        http_status:
          type: integer
          description: The HTTP status code
          minimum: 100
          maximum: 600
        timestamp:
          type: string
          format: date-time
          description: The RFC-3339 timestamp in which the error response was sent
        request_id:
          type: string
          format: uuid
          description: The unique identifier of the request that failed
        errors:
          type: array
          items:
            $ref: '#/components/schemas/api.error-detail'
          description: The error(s) that occurred from processing the request
    model.ad-data-quality-aggregation:
      allOf:
      - $ref: '#/components/schemas/model.components.int32.id'
      - $ref: '#/components/schemas/model.components.timestamps'
      - type: object
        properties:
          domains:
            type: integer
          users:
            type: integer
          groups:
            type: integer
          computers:
            type: integer
          ous:
            type: integer
          containers:
            type: integer
          gpos:
            type: integer
          aiacas:
            type: integer
          rootcas:
            type: integer
          enterprisecas:
            type: integer
          ntauthstores:
            type: integer
          certtemplates:
            type: integer
          acls:
            type: integer
          sessions:
            type: integer
          relationships:
            type: integer
          session_completeness:
            type: number
            format: float
          local_group_completeness:
            type: number
            format: float
          run_id:
            type: string
            format: uuid
  parameters:
    query.limit:
      name: limit
      description: This query parameter is used for setting an upper limit of objects returned in paginated responses.
      in: query
      schema:
        $ref: '#/components/schemas/api.params.query.limit'
    query.skip:
      name: skip
      description: This query parameter is used for determining the number of objects to skip in pagination.
      in: query
      schema:
        $ref: '#/components/schemas/api.params.query.skip'
    header.prefer:
      name: Prefer
      description: Prefer header, used to specify a custom timeout in seconds using the wait parameter as per RFC7240. Passing in wait=-1 bypasses all timeout limits when the feature is enabled.
      in: header
      required: false
      schema:
        type: string
        default: wait=30
        pattern: ^wait=(-1|[0-9]+)$
  securitySchemes:
    JWTBearerToken:
      description: '`Authorization: Bearer $JWT_TOKEN`

        '
      type: http
      scheme: bearer
      bearerFormat: JWT
    SignedRequest:
      description: '`Authorization: bhesignature $TOKEN_ID`

        '
      type: apiKey
      name: Authorization
      in: header
    RequestDate:
      description: '`RequestDate: $RFC3339_DATETIME`

        '
      type: apiKey
      name: RequestDate
      in: header
    HMACSignature:
      description: '`Signature: $BASE64ENCODED_HMAC_SIGNATURE`

        '
      type: apiKey
      name: Signature
      in: header
x-tagGroups:
- name: Community & Enterprise
  tags:
  - Auth
  - Roles
  - Permissions
  - API Tokens
  - BloodHound Users
  - Collectors
  - Collection Uploads
  - Custom Node Management
  - API Info
  - Search
  - Audit
  - Config
  - Asset Isolation
  - Graph
  - Azure Entities
  - AD Base Entities
  - Computers
  - Containers
  - Domains
  - GPOs
  - AIA CAs
  - Root CAs
  - Enterprise CAs
  - NT Auth Stores
  - Cert Templates
  - OUs
  - AD Users
  - Groups
  - Data Quality
  - Datapipe
  - Cypher
  - OpenGraph (Experimental)
- name: Enterprise Only
  tags:
  - EULA
  - BHE Users
  - Analysis
  - Client Ingest
  - Clients
  - Jobs
  - Tasks
  - Events (Schedules)
  - Attack Paths
  - Risk Posture
  - Meta Entities
  - Alerts