Malwarebytes Remediation API
The Remediation API from Malwarebytes — 3 operation(s) for remediation.
OpenAPI Specification
openapi: 3.2.0
info:
title: ThreatDown Remediation 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: Remediation
paths:
/nebula/v1/remediation/remediate:
delete:
description: Mark remediation items as safe accross the machines
summary: Mark remediation items as safe
security:
- client_credentials:
- execute
- user_permissions:
- detections.performActions
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:
$schema: http://json-schema.org/draft-07/schema#
type: object
description: Mark remediations as safe accross endpoints
required:
- items
examples:
- items:
6f47dfb6-02e1-4f60-863f-11bcf41a8456:
- 6f47bfb6-02e1-4f60-863f-11bcf41a8456
properties:
groups:
type: array
items:
type: object
title: Search remediation
properties:
fields:
type: array
title: Specify which fields will be included in the response
items:
enum:
- id
- account_id
- machine_id
- path
- job_id
- scanned_at
- threat_name
- status
- category
- type
- options
- machine_name
- group_id
- group_name
- policy_id
- policy_name
- account_name
- online
type: string
default:
- id
- account_id
- machine_id
- path
- job_id
- scanned_at
- threat_name
- status
- category
- type
- options
sort_field:
type: string
title: Sort field
enum:
- scanned_at
default: scanned_at
sort_order:
type: string
title: Whether sorting should be ascending or descending
enum:
- asc
- desc
default: desc
page_size:
type: number
title: The page size
minimum: 0
maximum: 2000
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: remediation constraints
items:
title: Remediation Constraints
type: object
oneOf:
- title: String (Equals, Not Equals) Constraints
required:
- operator
- value
properties:
field:
type: string
oneOf:
- type: string
title: Remediation UID String Fields
enum:
- id
- machine_id
- policy_id
- group_id
- job_id
- account_id
- title: Remediation Simple String Fields
type: string
enum:
- account_name
- group_name
- machine_name
- policy_name
- threat_name
- path
- category
- status
- type
operator:
type: string
description: Operator to apply to the constraint
enum:
- equals
- not_equals
value:
type:
- string
- array
title: Value to search
items:
type: string
case_insensitive:
type: boolean
default: false
if:
properties:
field:
type: string
title: Remediation UID String Fields
enum:
- id
- machine_id
- policy_id
- group_id
- job_id
- account_id
then:
properties:
value:
type:
- string
- array
format: uuid
items:
type: string
format: uuid
- title: String (Contains, Not Contains) Constraints
required:
- operator
- value
properties:
field:
title: Remediation Simple String Fields
type: string
enum:
- account_name
- group_name
- machine_name
- policy_name
- threat_name
- path
- category
- status
- type
operator:
type: string
description: Operator to apply to the constraint
enum:
- contains
- not_contains
value:
type: string
title: Value to search
case_insensitive:
type: boolean
default: false
- title: Boolean (Equals) Constraints
required:
- operator
- value
properties:
field:
type: string
oneOf:
- type: string
title: Remediation Boolean Fields
operator:
type: string
description: Operator to apply to the constraint
enum:
- equals
value:
title: Value to search. Must be true or false
type: boolean
- title: Date (start, end) Constraints
properties:
field:
type: string
title: Remediation Date Fields
enum:
- scanned_at
oneOf:
- minProperties: 1
title: Specify Date Range
not:
anyOf:
- required:
- operator
- required:
- value
properties:
start:
type: string
format: date-time
title: Start Date
end:
type: string
format: date-time
title: End Date
- title: Specify Exact Date
not:
anyOf:
- required:
- start
- required:
- end
required:
- operator
- value
properties:
operator:
type: string
enum:
- equals
value:
type:
- string
- array
format: date-time
title: Value to search
items:
format: date-time
items:
type: object
patternProperties:
^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$:
type: array
minimum: 0
items:
type: string
additionalProperties: true
responses:
'200':
description: response schema
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
title: Response schema for mark as safe
type: object
properties:
success:
description: Machine IDs affected
type: array
items:
type: string
errors:
description: Optional, sent only when an error occurs
type: array
items:
type: string
total_count:
type: number
tags:
- Remediation
operationId: api.nebula.delete.remediate
post:
description: Issue remediation jobs accross the machines
summary: Bulk remediation action
security:
- client_credentials:
- execute
- user_permissions:
- detections.performActions
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:
$schema: http://json-schema.org/draft-07/schema#
type: object
description: Issue remediation jobs accross endpoints
required:
- items
examples:
- items:
6f47dfb6-02e1-4f60-863f-11bcf41a8456:
- 6f47bfb6-02e1-4f60-863f-11bcf41a8456
properties:
groups:
type: array
items:
type: object
title: Search remediation
properties:
fields:
type: array
title: Specify which fields will be included in the response
items:
enum:
- id
- account_id
- machine_id
- path
- job_id
- scanned_at
- threat_name
- status
- category
- type
- options
- machine_name
- group_id
- group_name
- policy_id
- policy_name
- account_name
- online
type: string
default:
- id
- account_id
- machine_id
- path
- job_id
- scanned_at
- threat_name
- status
- category
- type
- options
sort_field:
type: string
title: Sort field
enum:
- scanned_at
default: scanned_at
sort_order:
type: string
title: Whether sorting should be ascending or descending
enum:
- asc
- desc
default: desc
page_size:
type: number
title: The page size
minimum: 0
maximum: 2000
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: remediation constraints
items:
title: Remediation Constraints
type: object
oneOf:
- title: String (Equals, Not Equals) Constraints
required:
- operator
- value
properties:
field:
type: string
oneOf:
- type: string
title: Remediation UID String Fields
enum:
- id
- machine_id
- policy_id
- group_id
- job_id
- account_id
- title: Remediation Simple String Fields
type: string
enum:
- account_name
- group_name
- machine_name
- policy_name
- threat_name
- path
- category
- status
- type
operator:
type: string
description: Operator to apply to the constraint
enum:
- equals
- not_equals
value:
type:
- string
- array
title: Value to search
items:
type: string
case_insensitive:
type: boolean
default: false
if:
properties:
field:
type: string
title: Remediation UID String Fields
enum:
- id
- machine_id
- policy_id
- group_id
- job_id
- account_id
then:
properties:
value:
type:
- string
- array
format: uuid
items:
type: string
format: uuid
- title: String (Contains, Not Contains) Constraints
required:
- operator
- value
properties:
field:
title: Remediation Simple String Fields
type: string
enum:
- account_name
- group_name
- machine_name
- policy_name
- threat_name
- path
- category
- status
- type
operator:
type: string
description: Operator to apply to the constraint
enum:
- contains
- not_contains
value:
type: string
title: Value to search
case_insensitive:
type: boolean
default: false
- title: Boolean (Equals) Constraints
required:
- operator
- value
properties:
field:
type: string
oneOf:
- type: string
title: Remediation Boolean Fields
operator:
type: string
description: Operator to apply to the constraint
enum:
- equals
value:
title: Value to search. Must be true or false
type: boolean
- title: Date (start, end) Constraints
properties:
field:
type: string
title: Remediation Date Fields
enum:
- scanned_at
oneOf:
- minProperties: 1
title: Specify Date Range
not:
anyOf:
- required:
- operator
- required:
- value
properties:
start:
type: string
format: date-time
title: Start Date
end:
type: string
format: date-time
title: End Date
- title: Specify Exact Date
not:
anyOf:
- required:
- start
- required:
- end
required:
- operator
- value
properties:
operator:
type: string
enum:
- equals
value:
type:
- string
- array
format: date-time
title: Value to search
items:
format: date-time
items:
type: object
patternProperties:
^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$:
type: array
minimum: 0
items:
type: string
additionalProperties: true
responses:
'201':
description: response schema
content:
application/json:
schema:
type: object
title: Create job response
required:
- jobs
- total_count
properties:
jobs:
type: array
title: List of jobs
items:
type: object
title: Job items
required:
- machine_id
- job_id
properties:
machine_id:
type: string
title: The ID of the endpoint onto which the job was issued (Ex. "9256034b-7967-4253-a5d9-260663e4fa4f")
pattern: '[\da-fA-F]{8}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{12}$'
examples:
- 9256034b-7967-4253-a5d9-260663e4fa4f
job_id:
type: string
title: The ID of the job. You can use this ID to retrieve additional informations about the job and track its progress, as well as use it as a reference to handle webhooks notifications (Ex. "9256034b-7967-4253-a5d9-260663e4fa4f")
pattern: '[\da-fA-F]{8}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{12}$'
examples:
- 9256034b-7967-4253-a5d9-260663e4fa4f
errors:
type: array
title: tasks not performed
items:
type: object
title: Endpoint ID
additionalProperties: true
properties:
id:
type: string
title: Machine ID (Ex. "9256034b-7967-4253-a5d9-260663e4fa4f")
pattern: '[\da-fA-F]{8}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{12}$'
examples:
- 9256034b-7967-4253-a5d9-260663e4fa4f
account_id:
type: string
title: Account ID (Ex. "9256034b-7967-4253-a5d9-260663e4fa4f")
pattern: '[\da-fA-F]{8}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{12}$'
examples:
- 9256034b-7967-4253-a5d9-260663e4fa4f
account_ids:
type: array
title: Account IDs
items:
type: string
title: Account ID (Ex. "9256034b-7967-4253-a5d9-260663e4fa4f")
pattern: '[\da-fA-F]{8}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{12}$'
examples:
- 9256034b-7967-4253-a5d9-260663e4fa4f
total_count:
type: integer
title: The total number of issued jobs
correlation_id:
type: string
title: Correlation ID of the job (Parent job ID). Could be used to find related child jobs.
pattern: '[\da-fA-F]{8}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{12}$'
examples:
- 9256034b-7967-4253-a5d9-260663e4fa4f
tags:
- Remediation
operationId: api.nebula.post.remediate
/nebula/v1/remediation/export:
post:
description: Export remediation Items
summary: Export remediation Items
security:
- client_credentials:
- read
- user_permissions:
- detections.view
status:
outage:
- auth
parameters:
- name: authorization
required: true
in: header
description: Au
# --- truncated at 32 KB (58 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/malwarebytes/refs/heads/main/openapi/malwarebytes-remediation-api-openapi.yml