Malwarebytes XDR API
The XDR API from Malwarebytes — 4 operation(s) for xdr.
OpenAPI Specification
openapi: 3.2.0
info:
title: ThreatDown XDR 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: XDR
paths:
/nebula/v1/xdr/alerts/{id}:
get:
description: Get an XDR alert and its full details by ID.
summary: Get alert details
security:
- client_credentials:
- read
- user_permissions:
- xdr.view
status:
outage:
- auth
parameters:
- name: id
required: true
in: path
schema:
type: number
- 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}$'
- name: source
required: true
in: query
description: Alert source
schema:
type: string
enum:
- edr
- okta
- entra
responses:
'200':
description: response schema
content:
application/json:
schema:
type: object
title: Get XDR alert by id
additionalProperties: true
required:
- id
properties:
id:
type: integer
title: Alert ID
examples:
- 123456
account_id:
type: string
title: Account ID
examples:
- 00000000-0000-0000-0000-000000000001
account_name:
type: string
title: Account name
metadata:
type: object
title: Alert actor metadata
additionalProperties: true
properties:
action:
type: object
additionalProperties: false
properties:
user_email:
type:
- string
- 'null'
title: Action actor email
user_name:
type:
- string
- 'null'
title: Action actor name
source:
type: string
title: Alert source
examples:
- okta
- entra
- edr
severity:
type: string
title: Alert severity
examples:
- low
- medium
- high
- critical
status:
type: string
title: Alert status
examples:
- open
- closed
- in_progress
- new
- reopen
category:
type: string
title: Alert category
alert_name:
type: string
title: Alert name
action_taken:
type: string
title: Action taken
examples:
- false_positive
action_user_email:
type: string
title: Action actor email
action_user_name:
type: string
title: Action actor name
action_outcome:
type: string
title: Action outcome
examples:
- allow
- block
- challenge
- fail
has_impacted_asset_hostname:
type: boolean
title: Whether any impacted asset has a non-empty hostname
comments:
type: string
title: Analyst comments
created_at:
type: string
title: Creation timestamp
format: date-time
updated_at:
type: string
title: Update timestamp
format: date-time
respond_audit_event:
type: object
title: Latest matching respond audit event
additionalProperties: false
properties:
user_email:
type:
- string
- 'null'
title: Respond action user email
user_name:
type:
- string
- 'null'
title: Respond action user name
logged_at:
type:
- string
- 'null'
title: Respond action timestamp
format: date-time
rules_triggered:
type: array
title: Triggered rules
items:
type: string
tactics:
type: array
title: Mapped tactics
items:
type: string
tactic_technique:
type: array
title: Mapped tactic-technique pairs
items:
type: string
attack_technique:
type: array
title: Mapped attack-technique pairs
items:
type: string
impacted_asset_hostname:
type: array
title: Impacted asset hostnames
items:
type: string
attack_detection_type:
type: string
title: Attack detection type
attack_category:
type: string
title: Attack category
city:
type: string
title: City
country:
type: string
title: Country
ip:
type: string
title: IP address
domain:
type: string
title: Domain or URL
identity_primary_identifier:
type: string
title: Primary identity
event_type:
type: string
title: Identity event type
details:
type: object
title: Source-specific details
additionalProperties: true
impacted_assets:
type: array
title: Impacted assets
items:
type: object
additionalProperties: true
dynamic_fields:
type: object
title: Dynamic fields
additionalProperties: true
tag:
type: string
title: Tag
message:
type: string
title: Message
pid:
type: string
title: Process ID
process_path:
type: string
title: Process path
detection_id:
type:
- integer
- string
title: Detection ID
machine_id:
type: string
title: Machine ID
format: uuid
module_name:
type: string
title: Module name
visible:
type: integer
title: Visibility flag
installation_type:
type: integer
title: Installation type
technique:
type: string
title: Technique
tactics_description:
type: array
title: Mapped tactic labels
items:
type: string
techniques_description:
type: array
title: Mapped technique labels
items:
type: string
tags:
- XDR
operationId: api.nebula.xdr.get.alert
/nebula/v1/xdr/alerts/{id}/action:
put:
description: Set alert action taken and comment
summary: Set alert action taken
security:
- client_credentials:
- write
- user_permissions:
- xdr.update
status:
outage:
- auth
parameters:
- name: id
required: true
in: path
schema:
type: number
- 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: Change xdr alert action
properties:
action:
type: string
description: Supported values are the raw XDR/ITDR action identifiers Orion accepts on write.
enum:
- DisableUser
- ResetUserPassword
- RevokeUserSessions
- EnforceMFAForUser
- ForcePasswordChange
- RemoveUserFromGroup
- false_positive
examples:
- false_positive
- DisableUser
comment:
type: string
required:
- action
responses:
'200':
description: response schema
content:
application/json:
schema: {}
tags:
- XDR
operationId: api.nebula.xdr.put.alert.action
/nebula/v1/xdr/alerts/status:
put:
description: Set alert status
summary: Set alert status
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: Change xdr alert status
properties:
status:
type: string
enum:
- open
- closed
- in_progress
- new
- reopen
alert_ids:
type: array
minItems: 1
items:
type: integer
required:
- status
- alert_ids
additionalProperties: false
responses:
'200':
description: response schema
content:
application/json:
schema: {}
tags:
- XDR
operationId: api.nebula.xdr.put.alert.status
/nebula/v1/xdr/alerts/action:
put:
description: Set alert action taken and comment for multiple XDR alerts
summary: Set alert action taken in bulk
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: Change xdr alert action in bulk
properties:
action:
type: string
description: Supported values are the raw XDR/ITDR action identifiers Orion accepts on write.
enum:
- DisableUser
- ResetUserPassword
- RevokeUserSessions
- EnforceMFAForUser
- ForcePasswordChange
- RemoveUserFromGroup
- false_positive
examples:
- false_positive
- DisableUser
comment:
type: string
alert_ids:
type: array
minItems: 1
items:
type: integer
required:
- action
- alert_ids
additionalProperties: false
responses:
'200':
description: response schema
content:
application/json:
schema: {}
tags:
- XDR
operationId: api.nebula.xdr.put.alerts.action
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