Malwarebytes Detections API
Detections contain information on threats such as malware, ransomware, and malicious URLs found across your account. Use the detection APIs to export detection data and retrieve details about a specific detection.
OpenAPI Specification
openapi: 3.2.0
info:
title: Malwarebytes Detections API
version: 1.0.0
description: 'Operations tagged Detections across 2 of this provider''s published API definitions: malwarebytes-threatdown-nebula-openapi.json, malwarebytes-threatdown-oneview-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.threatdown.com
tags:
- name: Detections
description: "Detections contain information on threats such as malware, ransomware, and malicious URLs found across your account. \n\nUse the detection APIs to export detection data and retrieve details about a specific detection."
paths:
/nebula/v1/detections/export:
servers:
- url: https://api.threatdown.com
post:
description: Export detections.
summary: Export detections
security:
- client_credentials:
- read
- user_permissions:
- vulnerabilities.view
status:
outage:
- auth
- search_stateless
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:
- type
- group_id
- path
- status
- id
- machine_id
- account_id
- account.name
- group.name
- detection_id
- scanned_at
- scanned_at_offset_seconds
- reported_at
- resource_created_at
- resource_modified_at
- category
- is_rtp_stream_event
- process_name
- cleaned_at
- machine_name
- machine_ip
- child_trace_count
- source_location
- destination_location
- machine_location
- trace_ip
- trace_port
- threat_name
- is_root_detection
- agent.at
- agent.last_user
- agent.fully_qualified_host_name
- agent.started_at_local
- agent.started_at_offset
- agent.os_info.os_type
- agent.os_info.os_version
- agent.os_info.os_platform
- agent.os_info.os_architecture
- agent.os_info.os_release_name
- agent.domain_name
- agent.engine_version
- agent.policy_etag
- agent.host_name
- agent.nics.ips
- agent.nics.mac_address
- agent.protection_status
- agent.object_guid
- rid_details.rule_id
- rid_details.ip
- rid_details.attack_user
- rid_details.protocol
- rid_details.port
- rid_details.attempts
- rid_details.duration
- rid_details.create_time
- rid_details.expire_time
- sha256
- md5
- affected_application
- scan_result.device.disk_model
- action_taken
- active_directory.user.display_name
- active_directory.user.distinguished_name
- active_directory.user.sam_account_name
- active_directory.user.ou
- active_directory.machine.display_name
- active_directory.machine.distinguished_name
- active_directory.machine.sam_account_name
- active_directory.machine.ou
groups:
type: array
title: List of queries
items:
type: object
required:
- account_ids
title: List of queries to fetch endpoints
additionalProperties: true
properties:
account_ids:
type: array
title: List of account IDs for this query
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
responses:
'200':
description: Successful response
tags:
- Detections
operationId: api.v2.nebula.post.export.detections
/nebula/v1/detections/export/async:
servers:
- url: https://api.threatdown.com
post:
description: Export detections asynchronously.
summary: Export detections asynchronously
security:
- client_credentials:
- read
- user_permissions:
- vulnerabilities.view
status:
outage:
- auth
- search_stateless
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:
- type
- group_id
- path
- status
- id
- machine_id
- account_id
- account.name
- group.name
- detection_id
- scanned_at
- scanned_at_offset_seconds
- reported_at
- resource_created_at
- resource_modified_at
- category
- is_rtp_stream_event
- process_name
- cleaned_at
- machine_name
- machine_ip
- child_trace_count
- source_location
- destination_location
- machine_location
- trace_ip
- trace_port
- threat_name
- is_root_detection
- agent.at
- agent.last_user
- agent.fully_qualified_host_name
- agent.started_at_local
- agent.started_at_offset
- agent.os_info.os_type
- agent.os_info.os_version
- agent.os_info.os_platform
- agent.os_info.os_architecture
- agent.os_info.os_release_name
- agent.domain_name
- agent.engine_version
- agent.policy_etag
- agent.host_name
- agent.nics.ips
- agent.nics.mac_address
- agent.protection_status
- agent.object_guid
- rid_details.rule_id
- rid_details.ip
- rid_details.attack_user
- rid_details.protocol
- rid_details.port
- rid_details.attempts
- rid_details.duration
- rid_details.create_time
- rid_details.expire_time
- sha256
- md5
- affected_application
- scan_result.device.disk_model
- action_taken
- active_directory.user.display_name
- active_directory.user.distinguished_name
- active_directory.user.sam_account_name
- active_directory.user.ou
- active_directory.machine.display_name
- active_directory.machine.distinguished_name
- active_directory.machine.sam_account_name
- active_directory.machine.ou
groups:
type: array
title: List of queries
items:
type: object
required:
- account_ids
title: List of queries to fetch endpoints
additionalProperties: true
properties:
account_ids:
type: array
title: List of account IDs for this query
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
responses:
'200':
description: Successful response
tags:
- Detections
operationId: api.v2.nebula.post.export.detections.async
/nebula/v1/detections/{id}:
servers:
- url: https://api.threatdown.com
get:
description: Get detection and its full information by ID.
summary: Get detection by ID
security:
- client_credentials:
- read
- user_permissions:
- vulnerabilities.view
status:
outage:
- auth
parameters:
- name: id
required: true
in: path
description: Valid UUID (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: 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: Get detection by id
additionalProperties: true
required:
- id
- scan_id
- machine_id
- detection_id
- scanned_at
- scanned_at_local
- reported_at
- status
- type
- path
- category
- ip_address
- url
- port
- affected_application
- md5
- process_name
properties:
id:
type: string
title: 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
scan_id:
type: string
title: Scan ID this detection belongs to (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
machine_id:
type: string
title: Endpoint ID this detection belongs to (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
machine_name:
type: string
title: Machine name
group_id:
type: string
title: Group ID the endpoint has
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
group_name:
type: string
title: Group name the endpoint has
policy_id:
type: string
title: The ID of the policy associated to the machine where this detection happened (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
policy_name:
type: string
title: Policy name
detection_id:
type: string
title: Detection id from endpoint
scanned_at:
type: string
title: Scanned at time (Ex. "2020-03-23T17:23:17.860482Z")
pattern: ^\d{4}-[0-1]\d-[0-3]\d[(t|T)\s](?:[0-2]\d:[0-5]\d:[0-5]\d|23:59:60)(?:\.\d+)?(?:(z|Z)|[+-]\d{2}:\d{2})$
examples:
- '2020-03-23T17:23:17.860482Z'
scanned_at_local:
type: string
title: Scanned at local time (Ex. "2020-03-23T17:23:17.860482Z")
pattern: ^\d{4}-[0-1]\d-[0-3]\d[(t|T)\s](?:[0-2]\d:[0-5]\d:[0-5]\d|23:59:60)(?:\.\d+)?(?:(z|Z)|[+-]\d{2}:\d{2})$
examples:
- '2020-03-23T17:23:17.860482Z'
reported_at:
type: string
title: Detection reported at time (Ex. "2020-03-23T17:23:17.860482Z")
pattern: ^\d{4}-[0-1]\d-[0-3]\d[(t|T)\s](?:[0-2]\d:[0-5]\d:[0-5]\d|23:59:60)(?:\.\d+)?(?:(z|Z)|[+-]\d{2}:\d{2})$
examples:
- '2020-03-23T17:23:17.860482Z'
status:
type: string
title: Status
action_taken:
type: string
title: Action Taken
examples:
- unknown
- failed
- noActionByUser
- quarantined
- replaced
- deleteOnReboot
- replaceOnReboot
- blocked
- whitelisted
- unquarantined
threat_name:
type: string
title: Threat name
type:
type: array
title: Type
items:
type: string
title: Items
path:
type: string
title: Path
category:
type: string
title: Category
ip_address:
type: string
title: IP address
url:
type: string
title: Url
port:
type: string
title: Port
affected_application:
type: string
title: Affected application
md5:
type: string
title: Md5
process_name:
type: string
title: Process name
tags:
- Detections
operationId: api.v2.nebula.get.detections.id
/nebula/v1/detections:
servers:
- url: https://api.threatdown.com
post:
description: Search detections.
summary: Search detections
security:
- client_credentials:
- read
- user_permissions:
- vulnerabilities.view
status:
outage:
- auth
- search_stateless
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: Search detections request. Leading wildcards are not supported for constraint fields without '.keyword' suffix.
required: []
properties:
protection_status:
type: string
title: Protection status of the endpoint(s)
pattern: (^$|protected|scan_only|unprotected|unknown|pending|mobile_protection)
scan_type:
type: string
title: Type of the scan
schedule_id:
type: string
title: ID of the schedule
schedule_etag:
type: string
title: ETAG of the schedule
job_id:
type: string
title: ID of the job originating this detection
domain_name:
type: string
title: Filter the search to the endpoints with specified domain name
engine_version:
type: string
title: Filter the search to the endpoints with specified engine version
last_user:
type: string
title: Last user that logged into the machine
last_user.keyword:
type: string
title: Last user that logged into the machine (exact match). This 'contains' type search will look for the exact match anywhere in the field.
plugins.siem.reboot_reason:
type: string
title: Filter the search to the endpoints with specified reboot reason, as reported by the SIEM plugin
plugins.siem.plugin_version:
type: string
title: Filter the search to the endpoints with specified SIEM plugin version
plugins.browser_phishing_protection.plugin_version:
type: string
title: Filter the search to the endpoints with specified Browser Phishing Protection plugin version
plugins.incident_response.reboot_reason:
type: string
title: Filter the search to the endpoints with specified reboot reason, as reported by IR plugin
plugins.incident_response.plugin_version:
type: string
title: Filter the search to the endpoints with specified IR plugin version
plugins.endpoint_detection_response.reboot_reason:
type: string
title: Filter the search to the endpoints with specified reboot reason, as reported by EDR plugin
plugins.endpoint_detection_response.plugin_version:
type: string
title: Filter the search to the endpoints with specified EDR plugin version
plugins.endpoint_protection.reboot_reason:
type: string
title: Filter the search to the endpoints with specified reboot reason, as reported by EP plugin
plugins.endpoint_protection.update_package_version:
type: string
title: Filter the search to the endpoints with specified EP update package version
plugins.endpoint_protection.component_package_version:
type: string
title: Filter the search to the endpoints with specified EP component package version
plugins.endpoint_protection.sdk_version:
type: string
title: Filter the search to the endpoints with specified EP SDK version
plugins.endpoint_protection.plugin_version:
type: string
title: Filter the search to the endpoints with specified EP plugin version
plugins.asset_manager.reboot_reason:
type: string
title: Filter the search to the endpoints with specified reboot reason, as reported by asset manager plugin
plugins.asset_manager.plugin_version:
type: string
title: Filter the search to the endpoints with specified asset manager plugin version
fully_qualified_host_name:
type: string
title: Filter the search to the endpoints with specified, fully qualified host name
host_name:
type: string
title: Filter the search to the endpoints with specified host name
os_info.os_release_name:
type: string
title: Filter the search to the endpoints with specified release name of OS
os_info.os_architecture:
type: string
title: Filter the search to the endpoints with specified OS architecture
os_info.os_platform:
type: string
title: Filter the search to the endpoints with specified OS
os_info.os_version:
type: string
title: Filter the search to the endpoints with specified OS version
os_info.os_type:
type: string
title: Filter the search to the endpoints with specified OS type
nics.description:
type: string
title: Filter the search to the endpoints with specified NICS description
nics.mac_address:
type: string
title: Filter the search to the endpoints with specified NICS MAC address
nics.ips:
type: string
title: Filter the search to the endpoints with specified ips
host_name.keyword:
type: string
title: Filter the search to the endpoints that have the specified host's name. This 'contains' type search will look for the exact match anywhere in the field.
fully_qualified_host_name.keyword:
type: string
title: Filter the search to the endpoints that have the specified, fully_qualified_host's name. This 'contains' type search will look for the exact match anywhere in the field.
engine_version.keyword:
type: string
title: Filter the search by engine version. This 'contains' type search will look for the exact match anywhere in the field.
domain_name.keyword:
type: string
title: Filter the search by domain name. This 'contains' type search will look for the exact match anywhere in the field.
at_after:
type: string
title: At after cursor (Ex. "2020-03-23T17:23:17.860482Z")
pattern: ^([0-9]+)-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])[Tt]([01][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9]|60)(\.[0-9]+)?(([Zz])|([\+|\-]([01][0-9]|2[0-3]):[0-5][0-9]))$
examples:
- '2020-03-23T17:23:17.860482Z'
at_before:
type: string
title: At before cursor (Ex. "2020-03-23T17:23:17.860482Z")
pattern: ^([0-9]+)-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])[Tt]([01][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9]|60)(\.[0-9]+)?(([Zz])|([\+|\-]([01][0-9]|2[0-3]):[0-5][0-9]))$
examples:
- '2020-03-23T17:23:17.860482Z'
machine_name.keyword:
type: string
title: The name of the machine. This 'contains' type search will look for the exact match anywhere in the field.
machine_name:
type: string
title: The name of the machine
process_name.keyword:
type: string
title: The name of the process that originated this detection. This 'contains' type search will look for the exact match anywhere in the field.
process_name:
type: string
title: The name of the process that originated this detection
affected_application.keyword:
type: string
title: The application affected by this detection. This 'contains' type search will look for the exact match anywhere in the field.
affected_application:
type: string
title: The application affected by this detection
category:
type: string
title: The category of this detection
not.category:
type: string
title: The category to exclude from search
md5:
type: string
title: The md5 hash of this detection
sha256:
type: string
title: The sha256 hash of this detection
path.keyword:
type: string
title: The path where this detection happened. This 'contains' type search will look for the exact match anywhere in the field.
path:
type: string
title: The path where this detection happened
type:
type: string
title: The type of the detection
not.type:
type: string
title: The type to exclude from search
threat_name.keyword:
type: string
title: The name of the threat. This 'contains' type search will look for the exact match anywhere in the field.
threat_name:
type: string
title: The name of the threat
status:
type: string
title: The status of the detection
action_taken:
type: string
title: The action taken of the detection
examples:
- unknown
- failed
- noActionByUser
- quarantined
- replaced
- deleteOnReboot
- replaceOnReboot
- blocked
- whitelisted
- unquarantined
correlation_hash:
type: string
title: The hash
group_id:
type: string
title: The ID of the group to which the endpoint is assigned (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
machine_id:
type: string
title: The ID of the endpoint (machine) where this detection originated (Ex. "9256034b-7967-4253-a5d9-260663e4fa4f")
pattern: '[\da-fA-F]{8}-?
# --- truncated at 32 KB (235 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/malwarebytes/refs/heads/main/openapi/malwarebytes-detections-api-openapi.yml