Malwarebytes Security Advisor API
The Security Advisor API from Malwarebytes — 8 operation(s) for security advisor.
OpenAPI Specification
openapi: 3.2.0
info:
title: ThreatDown Security Advisor 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: Security Advisor
paths:
/sam/assets/software:
post:
description: Bulk issue software update jobs per machine id
summary: Issue bulk software update jobs
security:
- client_credentials:
- read
- execute
- user_permissions:
- softwareInventory.view
- patchManagement.manage
- softwareInventory.performActions
status:
outage:
- auth
- search_stateful
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: Bulk update software
description: Allows to create several job `Software Update` by the `machine_id`
type: array
items:
type: object
properties:
application_name:
type: string
architecture:
type: string
current_version:
type: string
new_version:
type: string
product:
type: integer
vendor:
type: string
language:
type: string
machine_id:
type: string
responses:
'200':
description: response schema
content:
application/json:
schema:
title: Security Advisor Module Software Assets Response
description: Response for Security Advisor Module software asset operations, providing job tracking, error reporting, and total count information for software asset management tasks.
type: object
properties:
jobs:
type: array
title: Security Advisor Software Jobs
description: Array of Security Advisor Module jobs initiated for software asset operations, containing machine and job identifiers for tracking purposes.
items:
type: object
title: Software Asset Job
description: Individual software asset job with machine and job identifiers for tracking Security Advisor operations.
properties:
machine_id:
type: string
title: Machine Identifier
description: Unique identifier of the endpoint machine where the Security Advisor software asset operation is being performed.
job_id:
type: string
title: Job Identifier
description: Unique identifier for the Security Advisor software asset job, used for tracking operation status and results.
required:
- machine_id
- job_id
additionalProperties: false
errors:
type: array
title: Operation Errors
description: Array of error messages encountered during Security Advisor software asset operations, providing details about any failures or issues.
items:
type: string
title: Error Message
description: Descriptive error message detailing issues encountered during Security Advisor software asset operations.
total_count:
type: integer
title: Total Operations Count
description: Total number of Security Advisor software asset operations initiated, providing a count of all jobs regardless of success or failure status.
minimum: 0
required:
- jobs
- errors
- total_count
additionalProperties: false
tags:
- Security Advisor
operationId: api.sam.assets.software
/sam/details:
get:
description: Get list of issues found by the Security Advisor Module
summary: List SAM issues
security:
- client_credentials:
- read
- user_permissions:
- account.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: Security Advisor Module (SAM) Details Response
description: Comprehensive Security Advisor Module response containing aggregated security scoring and actionable issues across all enabled security categories including endpoint protection, DNS security, vulnerability management, patch management, firewall management, browser phishing protection, and email security.
type: object
properties:
total:
type: object
title: Composite Security Advisor Score
description: Aggregated Security Advisor scoring metrics across all enabled security categories. Provides current achievement, maximum achievable with current setup, and theoretical maximum if all features were enabled.
properties:
actual:
type: integer
title: Current Achieved Score
description: The total Security Advisor points currently achieved across all enabled categories. This represents the sum of actual scores from all security categories that the account has implemented.
achievable:
type: integer
title: Maximum Achievable Score
description: The maximum Security Advisor points that can be achieved with the current product licenses and configuration. This score is attainable by addressing all identified security issues without requiring additional product licenses.
possible:
type: integer
title: Theoretical Maximum Score
description: The theoretical maximum Security Advisor points if all security features and products were enabled and optimally configured. This represents the highest possible security posture across all available security categories.
required:
- actual
- achievable
- possible
additionalProperties: false
issues:
type: array
title: Security Advisor Issues Collection
description: Comprehensive collection of actionable security issues identified by the Security Advisor Module across all enabled security categories. Each issue represents a specific security gap that can be addressed to improve the overall security posture.
items:
type: object
title: Security Advisor Issue
description: Individual Security Advisor issue with metadata, impact metrics, and actionable recommendations for remediation.
properties:
id:
type: string
title: Issue Identifier
description: Unique identifier for the security issue, typically corresponding to a policy ID, group ID, or account ID depending on the issue's scope and granularity.
severity:
type: string
title: Issue Severity Level
description: Risk severity classification of the security issue. Values include HIGH (critical security gaps), MEDIUM (moderate risk issues), and LOW (minor optimizations).
enum:
- HIGH
- MEDIUM
- LOW
factor:
type: string
title: Security Category Factor
description: The primary security category this issue belongs to, such as POLICY, EDR, DNS, VULNERABILITY_ASSESSMENT, PATCH_MANAGEMENT, FIREWALL_MANAGEMENT, BROWSER_PHISHING_PROTECTION, or EMAIL_SECURITY.
issueType:
type: string
title: Specific Issue Type
description: Detailed classification of the specific security issue type, such as EP_POLICY_WEAK, CRITICAL_VULNERABILITIES, DNS_RULE_NOT_ENABLED, NO_FIREWALL_POLICY, etc. Maps to the IssuesType enum values.
scoreImpactPercentage:
type:
- number
- integer
title: Security Advisor Score Impact
description: The percentage impact this issue has on the overall Security Advisor score. Calculated as (issue points / total possible points) * 100. Higher values indicate issues with greater Security Advisor impact.
recommendation:
type: string
title: Remediation Recommendation
description: Actionable recommendation for addressing this security issue. Maps to predefined recommendation types like OPTIMIZE_POLICY, ENABLE_PROTECTION, APPLY_PATCHES, CREATE_SCHEDULE, etc.
affectingCount:
type: integer
title: Affected Resources Count
description: The number of resources (endpoints, inboxes, domains, etc.) affected by this security issue. Indicates the scope and reach of the security gap.
affectingType:
type: string
title: Affected Resource Type
description: The type of resources affected by this issue. Values include ENDPOINT (devices/machines), INBOX (email mailboxes), DOMAIN (DNS domains), or NONE for account-level issues.
enum:
- ENDPOINT
- INBOX
- DOMAIN
- NONE
issueAction:
type: string
title: Issue Action Classification
description: Specific action classification for this issue, such as IMMEDIATE_ACTION_REQUIRED, providing additional context for prioritization and response urgency.
canOptimize:
type: boolean
title: Optimization Availability
description: Indicates whether this security issue can be automatically optimized or requires manual intervention. True means the issue can be addressed through automated optimization features.
accountImpact:
type: number
title: Account-Level Impact Percentage
description: The percentage impact this issue has on the overall account Security Advisor score, calculated relative to the total possible account score.
categoryImpact:
type: number
title: Category-Level Impact Percentage
description: The percentage impact this issue has on its specific Security Advisor category score, calculated relative to the category's total possible score.
status:
type: string
title: Issue Status
description: Current status of the security issue, indicating its lifecycle state and resolution progress.
factorMetadata:
type:
- object
- 'null'
title: Issue Context Metadata
description: Contextual metadata providing detailed information about the security issue, including affected resources, configuration details, and quantitative metrics specific to the issue type.
properties:
type:
type: string
title: Metadata Type
description: The category type of this metadata, typically matching the security category (e.g., POLICY, EDR, DNS, VULNERABILITY_ASSESSMENT, etc.).
granularity:
type: string
title: Issue Granularity Level
description: The scope level at which this issue is identified and managed. Values include 'group' (device group level), 'policy' (security policy level), or 'account' (account-wide level).
enum:
- GROUP
- POLICY
- ACCOUNT
data:
type: object
title: Contextual Data
description: Detailed contextual information specific to the issue type, providing actionable details for issue resolution.
properties:
policyId:
type: string
title: Security Policy ID
description: Unique identifier of the security policy associated with this issue, used for policy-level security configurations.
policyName:
type: string
title: Security Policy Name
description: Human-readable name of the security policy, providing context for administrators to identify the specific policy requiring attention.
subcategories:
type: array
title: Policy Subcategories
description: List of specific security subcategories or features within the policy that are related to this issue.
items:
type: string
groupId:
type: string
title: Device Group ID
description: Unique identifier of the device group affected by this security issue, used for group-level security management.
groupName:
type: string
title: Device Group Name
description: Human-readable name of the device group, helping administrators identify which set of endpoints requires attention.
subCategories:
type: array
title: Security Subcategories
description: Array of specific security subcategories or protection features that are affected by this issue.
items:
type: string
ruleName:
type: string
title: Security Rule Name
description: Name of the specific security rule (e.g., DNS rule, firewall rule) that is associated with this issue.
ruleId:
type: string
title: Security Rule ID
description: Unique identifier of the security rule that needs attention or configuration.
patchCount:
type: integer
title: Outstanding Patches Count
description: Number of outstanding security patches (critical or important) that need to be applied to resolve this patch management issue.
vulnerabilitiesCount:
type: integer
title: Vulnerabilities Count
description: Number of security vulnerabilities (critical or high severity) detected that need to be addressed for this vulnerability assessment issue.
required:
- id
- severity
- factor
- issueType
- recommendation
- affectingCount
- affectingType
- canOptimize
- accountImpact
- categoryImpact
required:
- total
- issues
additionalProperties: false
tags:
- Security Advisor
operationId: api.sam.details
/sam/details/{category}:
get:
description: Get list of issues found by the Security Advisor Module filtered by category
summary: List SAM issues by category
security:
- client_credentials:
- read
- user_permissions:
- account.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: Security Advisor Module (SAM) Details by Category Response
description: Comprehensive Security Advisor Module response containing aggregated security scoring and actionable issues for a specific security category including endpoint protection, DNS security, vulnerability management, patch management, firewall management, browser phishing protection, and email security.
type: object
properties:
total:
type: object
title: Category Security Advisor Score
description: Security Advisor scoring metrics for the specific requested category. Provides current achievement, maximum achievable with current setup, and theoretical maximum if all features were enabled for this category.
properties:
actual:
type: integer
title: Current Achieved Score
description: The Security Advisor points currently achieved for this specific category. This represents the actual score from security measures implemented in this category.
achievable:
type: integer
title: Maximum Achievable Score
description: The maximum Security Advisor points that can be achieved for this category with the current product licenses and configuration. This score is attainable by addressing all identified security issues without requiring additional product licenses.
possible:
type: integer
title: Theoretical Maximum Score
description: The theoretical maximum Security Advisor points for this category if all security features and products were enabled and optimally configured. This represents the highest possible security posture for this specific category.
percentAchieved:
type: number
title: Percentage of Achieved Score
description: The percentage of the achievable score that has been achieved.
status:
type: string
title: Performance Status Classification
description: Qualitative assessment of the category's security posture based on the achievement percentage. Values include 'Very Good' (91-100%), 'Good' (76-90%), 'Fair' (51-75%), 'Poor' (26-50%), and 'Very Poor' (0-25%).
enum:
- Very Good
- Good
- Fair
- Poor
- Very Poor
required:
- actual
- achievable
- possible
additionalProperties: false
issues:
type: array
title: Category Security Advisor Issues Collection
description: Comprehensive collection of actionable security issues identified by the Security Advisor Module for the specific requested category. Each issue represents a specific security gap within this category that can be addressed to improve the overall security posture.
items:
type: object
title: Security Advisor Issue
description: Individual Security Advisor issue with metadata, impact metrics, and actionable recommendations for remediation.
properties:
id:
type: string
title: Issue Identifier
description: Unique identifier for the security issue, typically corresponding to a policy ID, group ID, or account ID depending on the issue's scope and granularity.
severity:
type: string
title: Issue Severity Level
description: Risk severity classification of the security issue. Values include HIGH (critical security gaps), MEDIUM (moderate risk issues), and LOW (minor optimizations).
enum:
- HIGH
- MEDIUM
- LOW
factor:
type: string
title: Security Category Factor
description: The primary security category this issue belongs to, such as POLICY, EDR, DNS, VULNERABILITY_ASSESSMENT, PATCH_MANAGEMENT, FIREWALL_MANAGEMENT, BROWSER_PHISHING_PROTECTION, or EMAIL_SECURITY.
issueType:
type: string
title: Specific Issue Type
description: Detailed classification of the specific security issue type, such as EP_POLICY_WEAK, CRITICAL_VULNERABILITIES, DNS_RULE_NOT_ENABLED, NO_FIREWALL_POLICY, etc. Maps to the IssuesType enum values.
scoreImpactPercentage:
type:
- number
- integer
title: Security Advisor Score Impact
description: The percentage impact this issue has on the overall Security Advisor score. Calculated as (issue points / total possible points) * 100. Higher values indicate issues with greater Security Advisor impact.
recommendation:
type: string
title: Remediation Recommendation
description: Actionable recommendation for addressing this security issue. Maps to predefined recommendation types like OPTIMIZE_POLICY, ENABLE_PROTECTION, APPLY_PATCHES, CREATE_SCHEDULE, etc.
affectingCount:
type: integer
title: Affected Resources Count
description: The number of resources (endpoints, inboxes, domains, etc.) affected by this security issue. Indicates the scope and reach of the security gap.
affectingType:
type: string
title: Affected Resource Type
description: The type of resources affected by this issue. Values include ENDPOINT (devices/machines), INBOX (email mailboxes), DOMAIN (DNS domains), IDENTITY (user identities), or NONE for account-level issues.
enum:
- ENDPOINT
- INBOX
- DOMAIN
- IDENTITY
- NONE
issueAction:
type: string
title: Issue Action Classification
description: Specific action classification for this issue, such as IMMEDIATE_ACTION_REQUIRED, providing additional context for prioritization and response urgency.
canOptimize:
type: boolean
title: Optimization Availability
description: Indicates whether this security issue can be automatically optimized or requires manual intervention. True means the issue can be addressed through automated optimization features.
accountImpact:
type: number
title: Account-Level Impact Percentage
description: The percentage impact this issue has on the overall account Security Advisor score, calculated relative to the total possible account score.
categoryImpact:
type: number
title: Category-Level Impact Percentage
description: The percentage impact this issue has on its specific Security Advisor category score, calculated relative to the category's total possible score.
status:
type: string
title: Issue Status
description: Current status of the security issue, indicating its lifecycle state and resolution progress.
factorMetadata:
type:
- object
- 'null'
title: Issue Context Metadata
description: Contextual metadata providing detailed information about the security issue, including affected resources, configuration details, and quantitative metrics specific to the issue type.
properties:
type:
type: string
title: Metadata Type
description: The category type of this metadata, typically matching the security category (e.g., POLICY, EDR,
# --- truncated at 32 KB (84 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/malwarebytes/refs/heads/main/openapi/malwarebytes-security-advisor-api-openapi.yml