The Account API from Malwarebytes — 2 operation(s) for account.
openapi: 3.2.0
info:
title: ThreatDown Account 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: Account
paths:
/nebula/v1/account/ad/structure:
get:
description: Get the Active Directory structure of an account
summary: Get account AD structure
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:
type: object
additionalProperties:
type: object
properties:
filter:
type: string
description: Filter string
nodes:
type: object
additionalProperties: true
tags:
- Account
operationId: api.nebula.get.account.ad.structure
/nebula/v1/account:
get:
description: Get details of the current account
summary: Get account details
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:
type: object
title: Your license key
properties:
license_key:
type: string
title: The license key associated with the account
id:
type: string
title: The id of the account (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
name:
type: string
title: The Name of the account
options:
type: object
title: Optional field options. Information for MSP.
properties:
msp:
type: object
title: MSP
properties:
name:
type: string
title: Name
redirect_url:
type: string
title: Redirect URL
account_token:
type: string
title: the account token of this account for registering endpoints
client_id:
type: string
title: The default client_id for this account, if any
default_policy_id:
type: string
title: The policy ID associated with this account (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
default_group_id:
type: string
title: The group ID associated with this account (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
owner_id:
type: string
format: uuid
title: The nebula account owner user ID
created_at:
type: string
title: When this account has been created (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'
updated_at:
type: string
title: When the account has been updated the last 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'
product_license_info:
type: array
title: Product license information
items:
type: object
properties:
licensed_product:
type: string
title: Licensed product
description: The licensed products
default: ''
examples:
- MBAE-B,MBAM-B,MBBR-B,MBFT-B,MBRX-B,NCCA-B,NCEP-B,NCRM-B
combo_code:
type: string
title: Combo code
examples:
- NEBULA-EP-COMBO
catalog_code:
type: string
title: Catalog code
default: ''
examples:
- BUS-CLOUD-EPP-01
licensed_seats:
type: integer
title: The number of seats licensed
default: 0
examples:
- 5
license_expires_at:
type: string
title: When the license expires
default: ''
examples:
- '2021-03-18T00:00:00Z'
license_term_type:
type: string
title: The License_term_type Schema
default: ''
examples:
- utility
licensed_ir_remediations:
type: integer
title: Licensed ir remediations
default: 0
examples:
- 0
license_status:
type: string
title: License status
default: ''
examples:
- active
ir_remediations_count:
type: integer
title: Ir remediations count
default: 0
examples:
- 0
machine_counts:
type: array
title: Endpoints linked to products
items:
type: object
title: Items
properties:
product_type:
type: string
title: Product type
examples:
- EDR
- EPP
- IR
os_type:
type: string
title: OS type
examples:
- WORKSTATION
- SERVER
os_platform:
type: string
title: Operation system platform
examples:
- Windows
machine_count:
type: integer
title: Count of machines having this product
tags:
- Account
operationId: api.nebula.get.account
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