Malwarebytes ITDR API
The ITDR API from Malwarebytes — 29 operation(s) for itdr.
OpenAPI Specification
openapi: 3.2.0
info:
title: ThreatDown ITDR 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: ITDR
paths:
/nebula/v1/itdr/config:
post:
description: Post ITDR Config
summary: Post ITDR 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: ITDR configuration object
description: Requires /itdr/config/identity-protection-setting to be configured first.
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: msgraphapi
config:
type: object
properties:
tenant_id:
type: string
title: Tenant ID
required:
- tenant_id
required:
- type
- config
responses:
'200':
description: response schema
content:
application/json:
schema:
title: ITDR Config Write Response
type: object
properties:
account_id:
type: string
format: uuid
type:
type: string
config:
type: object
additionalProperties: true
created_at:
type:
- string
- 'null'
updated_at:
type:
- string
- 'null'
additionalProperties: true
tags:
- ITDR
operationId: api.nebula.itdr.config.post
/nebula/v1/itdr/darkweb-monitoring/identities:
delete:
description: Remove identities from ITDR darkweb monitoring for the current account by email.
summary: Remove ITDR Darkweb Monitoring Identities
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:
title: ITDR Darkweb Monitoring Identities DELETE
description: Removes one or more identities from ITDR dark web monitoring by email and returns the updated monitored identity list.
type: object
required:
- emails
properties:
emails:
type: array
description: Normalized email addresses of the monitored identities to remove.
items:
type: string
additionalProperties: false
responses:
'200':
description: response schema
content:
application/json:
schema:
title: ITDR Darkweb Monitoring Identities
description: Current ITDR dark web monitoring configuration for an account, returned after reads and add/remove mutations.
type: object
required:
- identities
properties:
identities:
type: array
description: Monitored identities currently configured for dark web monitoring on the account.
items:
type: object
required:
- email
properties:
global_identity_id:
type:
- integer
- 'null'
description: Global identity identifier when the monitored email is linked to a known identity.
email:
type: string
description: Email address being monitored.
role:
type:
- string
- 'null'
description: Identity role, when available from the linked global identity.
metadata:
type:
- object
- 'null'
additionalProperties: true
description: Optional monitoring metadata stored with the identity.
additionalProperties: true
additionalProperties: false
tags:
- ITDR
operationId: api.nebula.itdr.darkweb.monitoring.identities.delete
get:
description: Get ITDR Darkweb Monitoring Identities
summary: Get ITDR Darkweb Monitoring Identities
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: ITDR Darkweb Monitoring Identities
description: Current ITDR dark web monitoring configuration for an account, returned after reads and add/remove mutations.
type: object
required:
- identities
properties:
identities:
type: array
description: Monitored identities currently configured for dark web monitoring on the account.
items:
type: object
required:
- email
properties:
global_identity_id:
type:
- integer
- 'null'
description: Global identity identifier when the monitored email is linked to a known identity.
email:
type: string
description: Email address being monitored.
role:
type:
- string
- 'null'
description: Identity role, when available from the linked global identity.
metadata:
type:
- object
- 'null'
additionalProperties: true
description: Optional monitoring metadata stored with the identity.
additionalProperties: true
additionalProperties: false
tags:
- ITDR
operationId: api.nebula.itdr.darkweb.monitoring.identities.get
post:
description: Add identities to ITDR darkweb monitoring for the current account.
summary: Add ITDR Darkweb Monitoring Identities
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:
title: ITDR Darkweb Monitoring Identities POST
description: Adds one or more identities to ITDR dark web monitoring and returns the updated monitored identity list.
type: object
required:
- identities
properties:
identities:
type: array
items:
type: object
required:
- email
properties:
email:
type: string
description: Email address of the identity to add to dark web monitoring.
additionalProperties: false
additionalProperties: false
responses:
'200':
description: response schema
content:
application/json:
schema:
title: ITDR Darkweb Monitoring Identities
description: Current ITDR dark web monitoring configuration for an account, returned after reads and add/remove mutations.
type: object
required:
- identities
properties:
identities:
type: array
description: Monitored identities currently configured for dark web monitoring on the account.
items:
type: object
required:
- email
properties:
global_identity_id:
type:
- integer
- 'null'
description: Global identity identifier when the monitored email is linked to a known identity.
email:
type: string
description: Email address being monitored.
role:
type:
- string
- 'null'
description: Identity role, when available from the linked global identity.
metadata:
type:
- object
- 'null'
additionalProperties: true
description: Optional monitoring metadata stored with the identity.
additionalProperties: true
additionalProperties: false
tags:
- ITDR
operationId: api.nebula.itdr.darkweb.monitoring.identities.post
/nebula/v1/itdr/login-restrictions/groups:
delete:
description: Delete ITDR Login Restriction Group
summary: Delete ITDR Login Restriction Group
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
required:
- group_ids
properties:
group_ids:
type: array
minItems: 1
items:
type: integer
minimum: 1
additionalProperties: false
responses:
'200':
description: response schema
content:
application/json:
schema:
type: object
required:
- deleted
properties:
deleted:
type: boolean
additionalProperties: false
tags:
- ITDR
operationId: api.nebula.itdr.login.restrictions.group.delete
get:
description: Get ITDR Login Restriction Groups
summary: Get ITDR Login Restriction Groups
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:
type: object
title: ITDR Login Restriction Groups
required:
- groups
properties:
groups:
type: array
items:
title: ITDR Login Restriction Group
type: object
required:
- id
- name
- country_mode
properties:
id:
type: integer
minimum: 1
account_id:
type: string
format: uuid
name:
type: string
minLength: 1
maxLength: 128
country_mode:
type: string
enum:
- allow_all
- allow_only
- deny_only
countries:
type: array
items:
title: ITDR Login Restriction Country
type: object
required:
- code
- name
properties:
code:
type: string
name:
type: string
metadata:
type: object
additionalProperties: true
additionalProperties: false
allOf:
- title: ISO-3166-1 alpha-2 country code and name pairs
type: object
required:
- code
- name
properties:
code:
type: string
enum:
- AD
- AE
- AF
- AG
- AI
- AL
- AM
- AO
- AQ
- AR
- AS
- AT
- AU
- AW
- AX
- AZ
- BA
- BB
- BD
- BE
- BF
- BG
- BH
- BI
- BJ
- BL
- BM
- BN
- BO
- BQ
- BR
- BS
- BT
- BV
- BW
- BY
- BZ
- CA
- CC
- CD
- CF
- CG
- CH
- CI
- CK
- CL
- CM
- CN
- CO
- CR
- CU
- CV
- CW
- CX
- CY
- CZ
- DE
- DJ
- DK
- DM
- DO
- DZ
- EC
- EE
- EG
- EH
- ER
- ES
- ET
- FI
- FJ
- FK
- FM
- FO
- FR
- GA
- GB
- GD
- GE
- GF
- GG
- GH
- GI
- GL
- GM
- GN
- GP
- GQ
- GR
- GS
- GT
- GU
- GW
- GY
- HK
- HM
- HN
- HR
- HT
- HU
- ID
- IE
- IL
- IM
- IN
- IO
- IQ
- IR
- IS
- IT
- JE
- JM
- JO
- JP
- KE
- KG
- KH
- KI
- KM
- KN
- KP
- KR
- KW
- KY
- KZ
- LA
- LB
- LC
- LI
- LK
- LR
- LS
- LT
- LU
- LV
- LY
- MA
- MC
- MD
- ME
- MF
- MG
- MH
- MK
- ML
- MM
- MN
- MO
- MP
- MQ
- MR
- MS
- MT
- MU
- MV
- MW
- MX
- MY
- MZ
- NA
- NC
- NE
- NF
- NG
- NI
- NL
- 'NO'
- NP
- NR
- NU
- NZ
- OM
- PA
- PE
- PF
- PG
- PH
- PK
- PL
- PM
- PN
- PR
- PS
- PT
- PW
- PY
- QA
- RE
- RO
- RS
- RU
- RW
- SA
- SB
- SC
- SD
- SE
- SG
- SH
- SI
- SJ
- SK
- SL
- SM
- SN
- SO
- SR
- SS
- ST
- SV
- SX
- SY
- SZ
- TC
- TD
- TF
- TG
- TH
- TJ
- TK
- TL
- TM
- TN
- TO
- TR
- TT
- TV
- TW
- TZ
- UA
- UG
- UM
- US
- UY
- UZ
- VA
- VC
- VE
- VG
- VI
- VN
- VU
- WF
- WS
- XK
- YE
- YT
- ZA
- ZM
- ZW
name:
type: string
enum:
- Afghanistan
- Albania
- Algeria
- American Samoa
- Andorra
- Angola
- Anguilla
- Antarctica
- Antigua and Barbuda
- Argentina
- Armenia
- Aruba
- Australia
- Austria
- Azerbaijan
- Bahamas
- Bahrain
- Bangladesh
- Barbados
- Belarus
- Belgium
- Belize
- Benin
- Bermuda
# --- truncated at 32 KB (789 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/malwarebytes/refs/heads/main/openapi/malwarebytes-itdr-api-openapi.yml