Groups are used to contain and organize endpoints. Policies, which determine the software settings, and endpoints, are assigned to groups. Endpoints use the policies in the groups they are assigned to determine which software settings are enabled. Use these APIs to create, manage, and move endpoints into groups.
openapi: 3.2.0
info:
title: Malwarebytes Groups API
version: 1.0.0
description: 'Operations tagged Groups 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: Groups
description: 'Groups are used to contain and organize endpoints. Policies, which determine the software settings, and endpoints, are assigned to groups. Endpoints use the policies in the groups they are assigned to determine which software settings are enabled.
Use these APIs to create, manage, and move endpoints into groups.'
paths:
/nebula/v1/groups/{id}:
servers:
- url: https://api.threatdown.com
delete:
description: Delete group by id.
summary: Delete group by id
security:
- client_credentials:
- write
- user_permissions:
- groups.delete
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: Successful response
tags:
- Groups
operationId: api.nebula.delete.groups
get:
description: Get group by id.
summary: Get group by id
security:
- client_credentials:
- read
- user_permissions:
- groups.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
responses:
'200':
description: response schema
content:
application/json:
schema:
type: object
title: Group
additionalProperties: true
properties:
id:
type: string
title: The Id of the group
account_id:
type: string
title: The account id to which this group belong
name:
type: string
title: The neame of the group
machines_count:
type: integer
title: Count of machines
policy_id:
type: string
title: Policy id associated to the group
policy_name:
type: string
title: Policy name
updated_at:
type: string
title: Updated at
examples:
- '2017-04-06T20:26:07.345213Z'
is_default:
type: boolean
title: Default
schedule_ids:
type: array
title: Array of schedule ids
items:
type: string
title: Schedule Id
parent_id:
type: string
title: Parent id
root_id:
type: string
title: Root id
ou_object_id:
type:
- string
- 'null'
title: Ou object id
child_group_count:
type: integer
title: Child group count
tags:
- Groups
operationId: api.nebula.getbyid.groups
put:
description: Update group.
summary: Update group
security:
- client_credentials:
- write
- user_permissions:
- groups.edit
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}$'
requestBody:
content:
application/json:
schema:
type: object
title: Group Save
description: Payload for creating a group
required:
- name
- policy_id
properties:
name:
type: string
title: Name
policy_id:
type: string
title: Policy Id
examples:
- 575ec9d1-9ade-4a2b-98cd-d6b5e5ea63d7
parent_id:
type: string
title: Parent Id
description: Id of parent group.
schedule_ids:
type: array
title: Schedule IDs this group should be assigned to
description: Schedule IDs this group should be assigned to
items:
type: string
pattern: '[\da-fA-F]{8}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{12}$'
title: The schedule ID (Ex. "9256034b-7967-4253-a5d9-260663e4fa4f")
examples:
- 9256034b-7967-4253-a5d9-260663e4fa4f
responses:
'200':
description: response schema
content:
application/json:
schema:
type: object
title: Group
additionalProperties: true
properties:
id:
type: string
title: The Id of the group
account_id:
type: string
title: The account id to which this group belong
name:
type: string
title: The neame of the group
machines_count:
type: integer
title: Count of machines
policy_id:
type: string
title: Policy id associated to the group
policy_name:
type: string
title: Policy name
updated_at:
type: string
title: Updated at
examples:
- '2017-04-06T20:26:07.345213Z'
is_default:
type: boolean
title: Default
schedule_ids:
type: array
title: Array of schedule ids
items:
type: string
title: Schedule Id
parent_id:
type: string
title: Parent id
root_id:
type: string
title: Root id
ou_object_id:
type:
- string
- 'null'
title: Ou object id
child_group_count:
type: integer
title: Child group count
tags:
- Groups
operationId: api.nebula.put.groups
/nebula/v1/groups:
servers:
- url: https://api.threatdown.com
get:
description: Get all groups in an account.
summary: Get all groups
security:
- client_credentials:
- read
- user_permissions:
- groups.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}$'
- name: name
required: false
in: query
description: Filter by group name
schema:
type: string
- name: parent_id
required: false
in: query
description: For filtering by parent group 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}$'
- name: filter_by_parent_id
required: false
in: query
description: Set this to 'true' when parent_id has been set.
schema:
type: string
- name: next_cursor
required: false
in: query
description: The pagination cursor for next set of results. For further documentation, check Pagination section.
schema:
type: string
responses:
'200':
description: response schema
content:
application/json:
schema:
type: object
title: Collection of groups
required:
- groups
- total_count
- next_cursor
properties:
groups:
type: array
title: Groups
items:
type: object
title: Group
additionalProperties: true
properties:
id:
type: string
title: The Id of the group
account_id:
type: string
title: The account id to which this group belong
name:
type: string
title: The neame of the group
machines_count:
type: integer
title: Count of machines
policy_id:
type: string
title: Policy id associated to the group
policy_name:
type: string
title: Policy name
updated_at:
type: string
title: Updated at
examples:
- '2017-04-06T20:26:07.345213Z'
is_default:
type: boolean
title: Default
schedule_ids:
type: array
title: Array of schedule ids
items:
type: string
title: Schedule Id
parent_id:
type: string
title: Parent id
root_id:
type: string
title: Root id
ou_object_id:
type:
- string
- 'null'
title: Ou object id
child_group_count:
type: integer
title: Child group count
total_count:
type: integer
title: Total Count
description: Total count of results.
next_cursor:
type: string
title: The pagination cursor for next set of results. For further documentation, check Pagination section.
examples:
- eyJzdGFydF9pbmRleCI6MTAwfQ==
tags:
- Groups
operationId: api.nebula.get.groups
post:
description: Create group.
summary: Create group
security:
- client_credentials:
- write
- user_permissions:
- groups.create
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: Group Save
description: Payload for creating a group
required:
- name
- policy_id
properties:
name:
type: string
title: Name
policy_id:
type: string
title: Policy Id
examples:
- 575ec9d1-9ade-4a2b-98cd-d6b5e5ea63d7
parent_id:
type: string
title: Parent Id
description: Id of parent group.
schedule_ids:
type: array
title: Schedule IDs this group should be assigned to
description: Schedule IDs this group should be assigned to
items:
type: string
pattern: '[\da-fA-F]{8}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{12}$'
title: The schedule ID (Ex. "9256034b-7967-4253-a5d9-260663e4fa4f")
examples:
- 9256034b-7967-4253-a5d9-260663e4fa4f
responses:
'200':
description: response schema
content:
application/json:
schema:
type: object
title: Group
additionalProperties: true
properties:
id:
type: string
title: The Id of the group
account_id:
type: string
title: The account id to which this group belong
name:
type: string
title: The neame of the group
machines_count:
type: integer
title: Count of machines
policy_id:
type: string
title: Policy id associated to the group
policy_name:
type: string
title: Policy name
updated_at:
type: string
title: Updated at
examples:
- '2017-04-06T20:26:07.345213Z'
is_default:
type: boolean
title: Default
schedule_ids:
type: array
title: Array of schedule ids
items:
type: string
title: Schedule Id
parent_id:
type: string
title: Parent id
root_id:
type: string
title: Root id
ou_object_id:
type:
- string
- 'null'
title: Ou object id
child_group_count:
type: integer
title: Child group count
tags:
- Groups
operationId: api.nebula.post.groups
/nebula/v1/groups/{id}/machines:
servers:
- url: https://api.threatdown.com
post:
description: "Use this endpoint to move machines in a group.\nThis API endpoint allows you to specify queries instead of explicitly specifying endpoint ids. See example for more details.\n\nTo assign all your `Mac Os` to a group, and on all your endpoints for a certain account with policy matching the string `serious policy`, use the following body:\n\n```json\n \"queries\": [{\n \"os_info.os_platform\": \"Mac Os\"\n }, {\n \"policy_name\": \"serious policy\" \n }]\n```\nThe constraints accepted are the same accepted by the search endpoints route. Refer to `POST -> /endpoints` for more information about the constraints accepted.\n\nYou can also send a mix of explicit endpoint ids and queries in the same request: \n```json\n \"endpoints\": [{ \"id\": \"<endpoint_id>\" }],\n \"queries\": [{\n \"os_info.os_platform\": \"Mac Os\"\n }, {\n \"policy_name\": \"serious policy\" \n }]\n```\n"
summary: Assign endpoints to a group
security:
- client_credentials:
- write
- user_permissions:
- groups.create
status:
outage:
- auth
- search_stateful
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}$'
requestBody:
content:
application/json:
schema:
type: object
title: Update groups in bulks
required:
- endpoints
- queries
properties:
endpoints:
type: array
title: Endpoints
items:
type: object
title: Endpoint items
required:
- id
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
queries:
type: array
title: Groups
items:
type: object
title: Group items
allOf:
- type: object
title: Search endpoints request. Leading wildcards are not supported for constraint fields without '.keyword' suffix.
properties:
name_multi_search:
type: string
title: Search either alias, host name of fully qualified host name
machine_id:
type: string
title: Filter the search to the endpoints with specified id
is_isolated:
type: boolean
title: Indicates whether the endpoints are isolated or not
is_software_update_available:
type: boolean
title: Indicates whether the agent has an available update
has_alerts:
type: boolean
title: Indicates whether the endpoint needs attention
alerts.codes:
type: string
title: Alert codes
suspicious_activity_found:
type: boolean
title: Filter the search to the endpoints that have open suspicious activities
reboot_required:
type: boolean
title: Filter the search to the endpoints needing a reboot
infection_found:
type: boolean
title: Filter the search to the endpoints with one or more security threats found
policy_id:
type: string
title: Filter the search to the endpoints with specified policy (id)
policy_name:
type: string
title: Filter the search to the endpoints with specified policy (name)
policy_etag:
type: string
title: Filter the search to the endpoints with specified policy etag
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.
alias:
type: string
title: Aliases for the machine
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.siem.alerts.codes:
type: string
title: Filter the search to the endpoints with specified SIEM alerts
plugins.browser_phishing_protection.plugin_version:
type: string
title: Filter the search to the endpoints with specified Browser Phishing Protection plugin version
plugins.browser_phishing_protection.alerts.codes:
type: string
title: Filter the search to the endpoints with specified Browser Phishing Protection alerts
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.incident_response.alerts.codes:
type: string
title: Filter the search to the endpoints with specified IR plugin alerts
plugins.endpoint_detection_and_response.reboot_reason:
type: string
title: Filter the search to the endpoints with specified reboot reason, as reported by EDR plugin
plugins.endpoint_detection_and_response.plugin_version:
type: string
title: Filter the search to the endpoints with specified EDR plugin version
plugins.endpoint_detection_and_response.alerts.codes:
type: string
title: Filter the search to the endpoints with specified EDR plugin alerts
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.update_package_version.keyword:
type: string
title: Filter the search to the endpoints with wildcard 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.endpoint_protection.alerts.codes:
type: string
title: Filter the search to the endpoints with specified EP plugin alerts
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
plugins.asset_manager.alerts.codes:
type: string
title: Filter the search to the endpoints with specified asset manager alerts
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_release_name.keyword:
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
group_name.keyword:
type: string
title: Filter the search to the endpoints belonging to the specified group's name. This 'contains' type search will look for the exact match anywhere in the field.
policy_name.keyword:
type: string
title: Filter the search to the endpoints assigned to the specified policy's name. This 'contains' type search will look for the exact match anywhere in the field.
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 specified engine version.
engine_version_gt:
type: string
title: Filter the search by engine version greater than specified value.
engine_version_gte:
type: string
title: Filter the search by engine version greater than or equal to specified value.
engine_version_lt:
type: string
title: Filter the search by engine version less than specified value.
engine_version_lte:
type: string
title: Filter the search by engine version less than or equal to specified value.
protection_status:
type: string
title: Protection status of the endpoint(s)
pattern: (^$|protected|scan_only|unprotected|unknown|pending|mobile_protection)
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.
group_id:
type: string
title: Filter the search by grou
# --- truncated at 32 KB (119 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/malwarebytes/refs/heads/main/openapi/malwarebytes-groups-api-openapi.yml