Malwarebytes Drive Encryption API
The Drive Encryption API from Malwarebytes — 5 operation(s) for drive encryption.
OpenAPI Specification
openapi: 3.2.0
info:
title: ThreatDown Drive Encryption API
description: '# Introduction
ThreatDown Nebula API lets you remotely manage the security of your `Endpoints`, analyze their `assets`, perform advanced analysis on `Detections` of `Malware`, `Ransomware`, `Exploits` and other threats found by the `ThreatDown Endpoint Agent`, and issue jobs like `Scan`, `Isolate`, `Remediate` or `Reboot`.
To get started, you need a client credential pair (OAuth2 application). You can get a valid application through our sales team.
You can retrieve your `client_id` and `client_secret` credentials pair in your Nebula console by going to the Integrate page in Nebula. You must also know your Nebula `account_id`.
## Cross-Origin Resource Sharing
This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with [W3C spec](https://www.w3.org/TR/cors/).
This allows cross-domain communication from the browser.
All responses have a wildcard same-origin which makes them completely public and accessible to everyone, including any code on any site.
## Authentication
ThreatDown API uses OAuth2, an open protocol to allow secure authorization in a simple and standard method from web, mobile, and desktop applications.
See the Authentication section for specific information about supported grants.
## Access'' scopes
When creating a new application, you can decide the level of access it has to your account''s data. This utility allows you to restrict the scope of access to your account''s data depending on the application''s needs. For example, if you only need to analyze detections found on your endpoint, the read scope will be enough to prevent that application from modifying data or issuing jobs.
Specifying access scopes gives you more control over the access of your data. For example, you may want your company''s IT department to be able to isolate infected endpoints, while you may want your analysts to only read data for generating reports. To do so, you can create two applications using different scopes, and provide the right people with the right pair of credentials for programmatic access.
## User permissions
The user associated with the client (i.e. the user that created the OAuth2 application) must have the required permissions to perform the requested operation. If the user does not have sufficient permissions, the API will respond with a `403 Forbidden` status code.
For each API, you can find the required permissions in the AUTHORIZATIONS dropdown, under `user_permissions`.
Some API requires additional permissions based on the data in the body:
- **jobs** issue API requires `<entity>.performActions` depending on the `command` (\<entity\> can be `endpoints`, `softwareInventory`, or `detections`)
- **notifications** create/update API requires `<entity>.view` depending on the `category`
- **reports** create/update API requires `<entity>.view` depending on the `type`
## Rate Limiting
ThreatDown API implements a rate-limiting mechanism to prevent abuse. The rate-limiting mechanism is implemented using a leaky bucket algorithm. Once you exceed the available limit, our server will respond with a `429` status code. You can throttle your requests and retry them later.
The current limit, which you can see in the table below, has shown to be enough for most use cases. If you encounter `429` error codes, consider taking the following actions to minimize your APIs usage:
- Subscribe to webhooks events instead of polling the API for reacting to changes.
- Throttle the requests you send to the ThreatDown API for not exceeding the limit.
- Batch requests when possible.
- Contact us and request to increase the API quota for your application.
Currently, the default available quota is `360` requests per minute.
'
version: 1.0.0
x-logo:
altText: ThreatDown logo
url: https://assets.threatdown.com/hermes/ThreatDown_Horizontal_Navy.png
backgroundColor: '#FFFFFF'
servers:
- url: https://api.threatdown.com
tags:
- name: Drive Encryption
paths:
/nebula/v1/drive-encryption/export:
post:
description: Export drive encryption data
summary: Export drive encryption data
security:
- client_credentials:
- read
- user_permissions:
- driveEncryption.view
status:
outage:
- auth
parameters:
- name: authorization
required: true
in: header
description: Authorization token
schema:
type: string
- name: accountid
required: true
in: header
description: Your Nebula account id (Ex. "9256034b-7967-4253-a5d9-260663e4fa4f")
schema:
type: string
pattern: '[\da-fA-F]{8}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{12}$'
requestBody:
content:
application/json:
schema:
type: object
title: Export request
required:
- groups
- select
- format
properties:
format:
type: string
title: The output file
enum:
- csv
- xlsx
- html
- ods
- txt
- rtf
- json
download:
type: boolean
title: Whether to instruct the client to download the response as a file. Only clients like browsers are supported
type:
type: string
title: The encoding of the output
enum:
- string
- base64
- binary
default: string
select:
type: array
title: Which fields to select from the response
items:
type: object
title: Field
required:
- field
- newField
properties:
newField:
type: string
title: the new value
field:
type: string
title: The response field to map to a new value
enum:
- machine_id
- machine_name
- machine_encryption_status
- volume_id
- drive_label
- drive_type
- status
- encryption_method
- encryption_scope
- source
- has_recovery_key
- policy_name
- encrypted_at
- readiness_issues
- last_reported_at
- recovery_key_id
- recovery_key_created_at
- recovery_key_updated_at
- recovery_key_last_rotated_at
- recovery_key
- recovery_key_error
groups:
type: array
title: List of queries
items:
type: object
title: Query to fetch Drive Encryption data
allOf:
- type: object
title: Drive Encryption Search Request
properties:
sort_field:
type: string
title: Sort field
enum:
- machine_name
- status
- source
- encrypted_at
default: machine_name
sort_order:
type: string
title: Whether sorting should be ascending or descending
enum:
- asc
- desc
default: asc
page_size:
type: number
title: The page size. Use 0 for a count-only request (returns total_count with no drive rows).
minimum: 0
maximum: 200
next_cursor:
type: string
title: The pagination cursor for next set of results. For further documentation, check Pagination section.
examples:
- eyJzdGFydF9pbmRleCI6MTAwfQ==
constraints:
type: array
title: Drive encryption constraints
items:
title: Drive Encryption Constraints
type: object
required:
- field
anyOf:
- title: String and Boolean (Equals) Constraints
required:
- operator
- value
properties:
field:
type: string
oneOf:
- title: Drive Encryption UID String Fields
type: string
enum:
- machine_id
- volume_id
- title: Drive Encryption Simple String Fields
type: string
enum:
- drive_type
- encryption_method
- encryption_scope
- has_recovery_key
- is_ready
- issue_reason
- machine_encryption_status
- machine_name
- policy_name
- present
- recovery_key_id
- recovery_key_used
- source
- status
- suspended
operator:
type: string
description: Operator to apply to the constraint
enum:
- equals
- contains
value:
oneOf:
- type:
- string
- boolean
title: Scalar value to search
- type: array
items:
type: string
minItems: 1
title: Array of string values to search (OR semantics)
title: Value to search
if:
properties:
field:
title: Drive Encryption UID String Fields
type: string
enum:
- machine_id
- volume_id
then:
properties:
operator:
enum:
- equals
value:
type:
- string
- array
format: uuid
items:
type: string
format: uuid
minItems: 1
title: Machine ID or array of machine IDs (OR semantics)
- title: Machine Display Name (Contains) Constraint
required:
- operator
- value
properties:
field:
type: string
enum:
- machine_display_name
operator:
type: string
enum:
- contains
value:
type: string
title: Value to search by machine display name
- title: Date (gte, lte) Constraints
properties:
field:
type: string
oneOf:
- title: Drive Encryption Date Fields
type: string
enum:
- encrypted_at
- recovery_key_last_rotated_at
gte:
type: string
format: date-time
title: Greater than or equals
lte:
type: string
format: date-time
title: Less than or equals
start:
type: string
format: date-time
title: Start Date
end:
type: string
format: date-time
title: End Date
not:
anyOf:
- required:
- operator
- required:
- value
anyOf:
- required:
- gte
- required:
- lte
- required:
- start
- required:
- end
populate:
type: object
title: The populate object Schema
properties:
machine_display_name:
type: boolean
title: Populate with the machine display name from Pistol
responses:
'200':
description: Successful response
tags:
- Drive Encryption
operationId: api.nebula.post.drive-encryption.export
/nebula/v1/drive-encryption/export/recovery-keys:
post:
description: Export drive encryption data for the current account as a streamed CSV download.
summary: Export drive encryption CSV
security:
- client_credentials:
- read
- user_permissions:
- driveEncryption.manage
status:
outage:
- auth
parameters:
- name: authorization
required: true
in: header
description: Authorization token
schema:
type: string
- name: accountid
required: true
in: header
description: Your Nebula account id (Ex. "9256034b-7967-4253-a5d9-260663e4fa4f")
schema:
type: string
pattern: '[\da-fA-F]{8}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{12}$'
requestBody:
content:
application/json:
schema:
type: object
title: Drive Encryption Recovery Keys Export Request
required:
- include_recovery_key
properties:
include_recovery_key:
type: boolean
title: Whether plaintext recovery keys should be included in the CSV export
justification:
type: string
title: Optional free-text justification for including recovery keys in the export
responses:
'200':
description: Successful response
tags:
- Drive Encryption
operationId: api.nebula.post.drive-encryption.export.recovery-keys
/nebula/v1/drive-encryption/groupby:
post:
description: Placeholder. Please extend this
summary: Placeholder. Please extend this
deprecated: false
security:
- client_credentials:
- read
- user_permissions:
- driveEncryption.view
status:
outage:
- auth
parameters:
- name: authorization
required: true
in: header
description: Authorization token
schema:
type: string
- name: accountid
required: true
in: header
description: Your Nebula account id (Ex. "9256034b-7967-4253-a5d9-260663e4fa4f")
schema:
type: string
pattern: '[\da-fA-F]{8}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{12}$'
requestBody:
content:
application/json:
schema:
type: object
title: Drive Encryption Group-By Request
required:
- group_by
properties:
group_by:
type: string
title: Field to group drives by
enum:
- machine_id
- status
- source
page_size:
type: integer
title: The page size
minimum: 1
maximum: 200
next_cursor:
type: string
title: Pagination cursor — the opaque string returned as next_cursor in the previous response. Omit to start from the first page.
constraints:
type: array
title: Drive encryption filter constraints
items:
title: Drive Encryption Constraints
type: object
required:
- field
anyOf:
- title: String and Boolean (Equals) Constraints
required:
- operator
- value
properties:
field:
type: string
oneOf:
- title: Drive Encryption UID String Fields
type: string
enum:
- machine_id
- volume_id
- title: Drive Encryption Simple String Fields
type: string
enum:
- drive_type
- encryption_method
- encryption_scope
- has_recovery_key
- is_ready
- issue_reason
- machine_encryption_status
- machine_name
- policy_name
- present
- recovery_key_id
- recovery_key_used
- source
- status
- suspended
operator:
type: string
description: Operator to apply to the constraint
enum:
- equals
- contains
value:
oneOf:
- type:
- string
- boolean
title: Scalar value to search
- type: array
items:
type: string
minItems: 1
title: Array of string values to search (OR semantics)
title: Value to search
if:
properties:
field:
title: Drive Encryption UID String Fields
type: string
enum:
- machine_id
- volume_id
then:
properties:
operator:
enum:
- equals
value:
type:
- string
- array
format: uuid
items:
type: string
format: uuid
minItems: 1
title: Machine ID or array of machine IDs (OR semantics)
- title: Machine Display Name (Contains) Constraint
required:
- operator
- value
properties:
field:
type: string
enum:
- machine_display_name
operator:
type: string
enum:
- contains
value:
type: string
title: Value to search by machine display name
- title: Date (gte, lte) Constraints
properties:
field:
type: string
oneOf:
- title: Drive Encryption Date Fields
type: string
enum:
- encrypted_at
- recovery_key_last_rotated_at
gte:
type: string
format: date-time
title: Greater than or equals
lte:
type: string
format: date-time
title: Less than or equals
start:
type: string
format: date-time
title: Start Date
end:
type: string
format: date-time
title: End Date
not:
anyOf:
- required:
- operator
- required:
- value
anyOf:
- required:
- gte
- required:
- lte
- required:
- start
- required:
- end
responses:
'200':
description: response schema
content:
application/json:
schema:
type: object
title: Drive Encryption Group-By Response
required:
- results
- total_count
properties:
results:
type: array
title: List of drive groups
items:
type: object
required:
- value
- total
properties:
value:
type: string
title: The group key (machine UUID, status string, or source string)
total:
type: integer
title: Number of drive rows in this group
machine_name:
type: string
title: Machine display name — present only when group_by=machine_id
total_count:
type: integer
title: Total number of drive rows matching the filters (not the number of groups)
next_cursor:
type: string
title: Opaque pagination cursor — pass as next_cursor in the next request to fetch the next page. Absent when the current page is the last one.
tags:
- Drive Encryption
operationId: api.nebula.post.drive-encryption.groupby
/nebula/v1/drive-encryption:
post:
description: Search drive encryption data for endpoints in the current account using Orion grid-style pagination, sorting, and constraints.
summary: Search drive encryption
security:
- client_credentials:
- read
- user_permissions:
- driveEncryption.view
status:
outage:
- auth
parameters:
- name: authorization
required: true
in: header
description: Authorization token
schema:
type: string
- name: accountid
required: true
in: header
description: Your Nebula account id (Ex. "9256034b-7967-4253-a5d9-260663e4fa4f")
schema:
type: string
pattern: '[\da-fA-F]{8}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{12}$'
requestBody:
content:
application/json:
schema:
type: object
title: Drive Encryption Search Request
properties:
sort_field:
type: string
title: Sort field
enum:
- machine_name
- status
- source
- encrypted_at
default: machine_name
sort_order:
type: string
title: Whether sorting should be ascending or descending
enum:
- asc
- desc
default: asc
page_size:
type: number
title: The page size. Use 0 for a count-only request (returns total_count with no drive rows).
minimum: 0
maximum: 200
next_cursor:
type: string
title: The pagination cursor for next set of results. For further documentation, check Pagination section.
examples:
- eyJzdGFydF9pbmRleCI6MTAwfQ==
constraints:
type: array
title: Drive encryption constraints
items:
title: Drive Encryption Constraints
type: object
required:
- field
anyOf:
- title: String and Boolean (Equals) Constraints
required:
- operator
- value
properties:
field:
type: string
oneOf:
- title: Drive Encryption UID String Fields
type: string
enum:
- machine_id
- volume_id
- title: Drive Encryption Simple String Fields
type: string
enum:
- drive_type
- encryption_method
- encryption_scope
- has_recovery_key
- is_ready
- issue_reason
- machine_encryption_status
- machine_name
- policy_name
- present
- recovery_key_id
- recovery_key_used
- source
- status
- suspended
operator:
type: string
description: Operator to apply to the constraint
enum:
- equals
- contains
value:
oneOf:
- type:
- string
- boolean
title: Scalar value to search
- type: array
items:
type: string
minItems: 1
title: Array of string values to search (OR semantics)
title: Value to search
if:
properties:
field:
title: Drive Encryption UID String Fields
type: string
enum:
- machine_id
- volume_id
then:
properties:
operator:
enum:
- equals
value:
type:
- string
- array
format: uuid
items:
type: string
format: uuid
minItems: 1
title: Machine ID or array of machine IDs (OR semantics)
- title: Machine Display Name (Contains) Constraint
required:
- operator
- value
properties:
field:
type: string
enum:
- machine_display_name
operator:
type: string
enum:
- contains
value:
type: string
title: Value to search by machine display name
- title: Date (gte, lte) Constraints
properties:
field:
type: string
oneOf:
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/malwarebytes/refs/heads/main/openapi/malwarebytes-drive-encryption-api-openapi.yml