Malwarebytes MXDR API
The MXDR API from Malwarebytes — 4 operation(s) for mxdr.
OpenAPI Specification
openapi: 3.2.0
info:
title: ThreatDown MXDR 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: MXDR
paths:
/nebula/v1/mxdr/config:
post:
description: Post MXDR Config
summary: Post MXDR Config
security:
- client_credentials:
- write
- user_permissions:
- xdr.update
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: MXDR configuration object
oneOf:
- properties:
type:
const: entra
config:
type: object
properties:
code:
type: string
title: Code
redirect_uri:
type: string
title: redirect_uri
required:
- code
required:
- type
- config
- properties:
type:
const: okta
config:
type: object
properties:
domain:
type: string
title: Okta Domain
api_token:
type: string
title: Okta API Token
required:
- domain
- api_token
required:
- type
- config
- properties:
type:
const: meraki
config:
type: array
items:
type: object
properties:
machine_name:
type: string
title: Machine Name
syslog_ip:
type: string
format: ipv4
title: Syslog IP
syslog_port:
type: integer
minimum: 1
maximum: 65535
title: Syslog Port
machine_id:
type: string
format: uuid
title: Machine ID
required:
- machine_name
- syslog_ip
- syslog_port
- machine_id
required:
- type
- config
- properties:
type:
const: fortinet
config:
type: object
properties:
syslog_port:
type: integer
minimum: 1
maximum: 65535
title: Fortinet Syslog Port
syslog_ip:
type: string
format: ipv4
title: Fortinet Syslog IP
machine_id:
type: string
format: uuid
title: Endpoint Machine ID
machine_name:
type: string
title: Endpoint Machine Name
required:
- syslog_ip
- syslog_port
- machine_id
- machine_name
required:
- type
- config
- properties:
type:
const: watchguard
config:
type: object
properties:
syslog_port:
type: integer
minimum: 1
maximum: 65535
title: Watchguard Syslog Port
syslog_ip:
type: string
format: ipv4
title: Watchguard Syslog IP
machine_id:
type: string
format: uuid
title: Endpoint Machine ID
machine_name:
type: string
title: Endpoint Machine Name
required:
- syslog_ip
- syslog_port
- machine_id
- machine_name
required:
- type
- config
- properties:
type:
const: sonicwall
config:
type: array
items:
type: object
properties:
machine_name:
type: string
title: Machine Name
syslog_ip:
type: string
format: ipv4
title: Syslog IP
syslog_port:
type: integer
minimum: 1
maximum: 65535
title: Syslog Port
machine_id:
type: string
format: uuid
title: Machine ID
required:
- machine_name
- syslog_ip
- syslog_port
- machine_id
required:
- type
- config
- properties:
type:
const: pan
config:
type: array
items:
type: object
properties:
machine_name:
type: string
title: Machine Name
syslog_ip:
type: string
format: ipv4
title: Syslog IP
syslog_port:
type: integer
minimum: 1
maximum: 65535
title: Syslog Port
machine_id:
type: string
format: uuid
title: Machine ID
required:
- machine_name
- syslog_ip
- syslog_port
- machine_id
required:
- type
- config
- properties:
type:
const: msgraphapi
config:
type: object
properties:
tenant_id:
type: string
title: Tenant ID
required:
- tenant_id
required:
- type
- config
responses:
'200':
description: Successful response
tags:
- MXDR
operationId: api.nebula.mxdr.config.post
/nebula/v1/mxdr/config/{type}:
delete:
description: Delete MXDR Config
summary: Delete MXDR Config
security:
- client_credentials:
- write
- user_permissions:
- xdr.update
status:
outage:
- auth
parameters:
- name: type
required: true
in: path
description: Type
schema:
type: string
- 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}$'
responses:
'200':
description: Successful response
tags:
- MXDR
operationId: api.nebula.mxdr.config.delete
/nebula/v1/mxdr/config/status:
get:
description: Get all MXDR Config Status
summary: Get all MXDR Config Status
security:
- client_credentials:
- read
- user_permissions:
- xdr.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}$'
responses:
'200':
description: response schema
content:
application/json:
schema:
title: MXDR Config Status
type: array
items:
type: object
properties:
source:
type: string
enum:
- entra
- okta
- meraki
- msgraphapi
- fortinet
- watchguard
- sonicwall
- internal
- internal_ARW
- internal_PUM
- internal_MWAC
- internal_AE
- internal_PUP
- internal_MALWARE
- internal_SA
- internal_RID
- internal_VULNERABLE_DRIVER
- internal_DNS
- internal_FIREWALL
- internal_BPP
status:
type: boolean
last_log_seen:
type:
- string
- 'null'
format: date-time
required:
- source
- status
- last_log_seen
examples:
- - source: entra
status: true
last_log_seen: '2025-05-23T01:50:29.958684100Z'
- source: okta
status: false
last_log_seen: null
- source: meraki
status: true
last_log_seen: '2025-05-23T01:50:29.958684100Z'
- source: fortinet
status: false
last_log_seen: null
- source: watchguard
status: false
last_log_seen: null
- source: internal
status: false
last_log_seen: null
tags:
- MXDR
operationId: api.nebula.mxdr.config.status.get
/nebula/v1/mxdr/config/all:
get:
description: Get all MXDR Configs
summary: Get all MXDR Configs
security:
- client_credentials:
- read
- user_permissions:
- xdr.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}$'
responses:
'200':
description: response schema
content:
application/json:
schema:
title: MXDR configuration objects
type: array
items:
- type: object
properties:
account_id:
type: string
type:
type: string
config:
type: object
created_at:
type: string
updated_at:
type: string
required: []
examples:
- - account_id: 1b5b34fe-ccde-4423-b2a2-8df4b02c13e0
type: MDR
config:
primary_contact:
user_id: f8f08d43-ce09-46ad-ab43-beede8546f9c
phone: '8767865765'
secondary_contact:
user_id: f7059ed8-be2f-4ccd-8d5a-237e2480f02a
phone: '5435467687'
tertiary_contact:
user_id: 973e6b1d-a81a-4cc2-a8f3-f7f73eb55f1a
phone: '6457658674'
endpoint_isolation: true
identity_response_authorization:
mode: full
config:
disable_identity: true
reset_password: true
force_password_update: true
revoke_session: true
remove_identity_from_groups: true
enforce_mfa: true
region: sec_ops
collaboration_method: Do it for me
is_trial: null
environment_name: ''
created_at: '2024-04-25T11:10:32.724Z'
updated_at: '2024-04-25T08:11:18.392605Z'
- account_id: 1b5b34fe-ccde-4423-b2a2-8df4b02c13e0
type: okta
config:
domain: trial-6711724-admin.okta.com
created_at: '2025-01-29T14:22:46.219864Z'
updated_at: '2025-01-29T14:22:46.219864Z'
- account_id: 1b5b34fe-ccde-4423-b2a2-8df4b02c13e0
type: entra
config: {}
created_at: '2025-01-29T14:22:46.219864Z'
updated_at: '2025-01-29T14:22:46.219864Z'
- account_id: 1b5b34fe-ccde-4423-b2a2-8df4b02c13e0
type: meraki
config:
- machine_name: MachineA
syslog_ip: 1.1.1.3
syslog_port: 5140
machine_id: 14425b5a-c097-49d8-90c9-e6b2a26aa76d
plugin_id: 14425b5a-c097-1234-90c9-e6b2a26aa76d
- machine_name: MachineB
syslog_ip: 1.1.1.2
syslog_port: 5140
machine_id: 14425b5a-c097-49d8-90c9-e6b2a90aa76d
plugin_id: 14425b5a-c097-1234-90c9-e6b2a26aa76d
created_at: '2025-02-20T10:52:04.028218+02:00'
updated_at: '2025-02-20T10:52:04.028218+02:00'
- account_id: 1b5b34fe-ccde-4423-b2a2-8df4b02c13e0
type: fortinet
config:
machine_name: MachineA
syslog_ip: 1.1.1.3
syslog_port: 5140
machine_id: 14425b5a-c097-49d8-90c9-e6b2a26aa76d
plugin_id: 14425b5a-c097-1234-90c9-e6b2a26aa76d
created_at: '2025-02-20T10:52:04.028218+02:00'
updated_at: '2025-02-20T10:52:04.028218+02:00'
- account_id: 1b5b34fe-ccde-4423-b2a2-8df4b02c13e0
type: watchguard
config:
machine_name: MachineB
syslog_ip: 1.1.1.2
syslog_port: 5140
machine_id: 14425b5a-c097-49d8-90c9-e6b2a90aa76d
plugin_id: 14425b5a-c097-1234-90c9-e6b2a26aa76d
created_at: '2025-02-20T10:52:04.028218+02:00'
updated_at: '2025-02-20T10:52:04.028218+02:00'
tags:
- MXDR
operationId: api.nebula.mxdr.config.all.get
components:
securitySchemes:
client_credentials:
type: oauth2
flows:
clientCredentials:
tokenUrl: /token
scopes:
read: Read data of your Nebula account
write: Write data, such as groups, policies, exclusions. Create Webhook subscriptions
execute: Issue jobs on your endpoints, like Scan, Reboot or Isolate.
user_permissions:
type: http
scheme: bearer