SpecterOps Data Quality API
The Data Quality API from SpecterOps — 6 operation(s) for data quality.
The Data Quality API from SpecterOps — 6 operation(s) for data quality.
openapi: 3.0.3
info:
title: BloodHound AD Base Entities 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.\nEndpoint availability is denoted using the `Community` and `Enterprise` tags.\n\nContact information listed is for BloodHound Enterprise customers. To get help with\nBloodHound Community Edition, please join our\n[Slack community](https://ghst.ly/BHSlack/).\n\n## Authentication\n\nThe BloodHound API supports two kinds of authentication: JWT bearer tokens and Signed Requests.\nFor quick tests or one-time calls, the JWT used by your browser may be the simplest route. For\nmore secure and long lived API integrations, the recommended option is signed requests.\n\n### JWT Bearer Token\n\nThe API will accept calls using the following header structure in the HTTP request:\n```\nAuthorization: Bearer $JWT_TOKEN\n```\nIf you open the Network tab within your browser, you will see calls against the API made utilizing\nthis structure. JWT bearer tokens are supported by the BloodHound API, however it is recommended\nthey only be used for temporary access. JWT tokens expire after a set amount of time and require\nre-authentication using secret credentials.\n\n### Signed Requests\n\nSigned requests are the recommended form of authentication for the BloodHound API. Not only are\nsigned requests better for long lived integrations, they also provide more security for the\nrequests being sent. They provide authentication of the client, as well as verification of request\nintegrity when received by the server.\n\nSigned requests consist of three main parts: The client token ID, the request timestamp, and a\nbase64 encoded HMAC signature. These three pieces of information are sent with the request using\nthe following header structure:\n\n```\nAuthorization: bhesignature $TOKEN_ID\nRequestDate: $RFC3339_DATETIME\nSignature: $BASE64ENCODED_HMAC_SIGNATURE\n```\n\nTo use signed requests, you will need to generate an API token. Each API token generated in the\nBloodHound API comes with two parts: The Token ID, which is used in the `Authorization` header,\nand the Token Key, which is used as part of the HMAC hashing process. The token ID should be\nconsidered as public (like a username) and the token key should be considered secret (like a\npassword). Once an API token is generated, you can use the key to sign requests.\n\nFor more documentation about how to work with authentication in the API, including examples\nof how to generate an API token in the BloodHound UI, please refer to this support doc:\n[Working with the BloodHound API](https://bloodhound.specterops.io/integrations/bloodhound-api/working-with-api).\n\n#### Signed Request Pseudo-code Example\n\nFirst, a digest is initiated with HMAC-SHA-256 using the token key as the digest key:\n```python\ndigester = hmac.new(sha256, api_token_key)\n```\n\nOperationKey is the first HMAC digest link in the signature chain. This prevents replay attacks that\nseek to modify the request method or URI. It is composed of concatenating the request method and\nthe request URI with no delimiter and computing the HMAC digest using the token key as the digest\nsecret:\n```python\n# Example: GET /api/v2/test/resource HTTP/1.1\n# Signature Component: GET/api/v2/test/resource\ndigester.write(request_method + request_uri)\n\n# Update the digester for further chaining\ndigester = hmac.New(sha256, digester.hash())\n```\n\nDateKey is the next HMAC digest link in the signature chain. This encodes the RFC3339\nformatted datetime value as part of the signature to the hour to prevent replay\nattacks that are older than max two hours. This value is added to the signature chain\nby cutting off all values from the RFC3339 formatted datetime from the hours value\nforward:\n```python\n# Example: 2020-12-01T23:59:60Z\n# Signature Component: 2020-12-01T23\nrequest_datetime = date.now()\ndigester.write(request_datetime[:13])\n\n# Update the digester for further chaining\ndigester = hmac.New(sha256, digester.hash())\n```\n\nBody signing is the last HMAC digest link in the signature chain. This encodes the\nrequest body as part of the signature to prevent replay attacks that seek to modify\nthe payload of a signed request. In the case where there is no body content the\nHMAC digest is computed anyway, simply with no values written to the digester:\n```python\nif request.body is not empty:\n digester.write(request.body)\n```\n\nFinally, base64 encode the final hash and write the three required headers before\nsending the request:\n```python\nencoded_hash = base64_encode(digester.hash())\nrequest.header.write('Authorization', 'bhesignature ' + token_id)\nrequest.header.write('RequestDate', request_datetime)\nrequest.header.write('Signature', encoded_hash)\n```\n"
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:
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.
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
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.
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
schemas:
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'
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.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
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
format: int32
nullable: true
run_id:
type: string
format: uuid
api.params.query.limit:
type: integer
minimum: 0
description: The limit of results requested by the client.
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.
'
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
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
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
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.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.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.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
format: int32
nullable: true
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-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.params.query.skip:
type: integer
minimum: 0
description: The number of items to skip in a paginated response.
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
parameters:
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]+)$
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'
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'
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 (Schedu
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/specterops/refs/heads/main/openapi/specterops-data-quality-api-openapi.yml