The Nebula API lets you remotely manage the security of your endpoints. To use the API, a client credential pair and Account ID are required.
To generate the credentials, log into Nebula and go to Integrate.
For more information on APIs, see Nebula API Documentation or hover over the tooltip next to OAuth2 Clients on the Integrate page and click the link.
Below are some basic and common API examples using PowerShell.
Get-NebulaToken
An access token is required for all public API requests. For examples of obtaining an access token with JavaScript or Python, see Nebula API examples. Use this function in every file to get a token to authenticate other functions that call API endpoints.
#Requires -Version 3.0
# Set the security protocol to TLS 1.2
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
function Get-NebulaToken {
<#
.SYNOPSIS
Authenticate to a Nebula account, returning an OAuth2 token.
.DESCRIPTION
Authenticates via the Nebula Public API using an OAuth2 Client Pair.
Client credentials should be stored/retrieved from secure store as they provide access to your Nebula account.
Returns an authentication object containing OAuth2 Bearer Token and metadata with expiry and BaseUrl.
.PARAMETER AccountId
The Nebula AccountID e.g. aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa
This can be found between the first // in the console's URL.
E.g. https://cloud.malwarebytes.com/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa/dashboard/securityAdvisor
Required to supply this value to others API endpoints that consume Nebula.Token objects.
.PARAMETER ClientID
ClientID e.g. aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa
.PARAMETER ClientSecret
ClientSecret e.g. 000000ABCDEF000000ABCDEF000000AB000000ABCDEF000000ABCDEF000000AB
.PARAMETER Scope
OPTIONAL - Specify the read, write, and/or execute scope of the token. Defaults to read write execute.
.PARAMETER Verbose
OPTIONAL - Indicates that additional details should be displayed.
This parameter uses the built-in -Verbose feature to show internal processing steps.
Example: Get-NebulaToken -AccountID $accountID -ClientID $clientID -ClientSecret $clientSecret -Verbose
.OUTPUTS
Outputs a Nebula.Token PSCustomObject that can be used as a parameter or in a pipeline for other Nebula API endpoints.
.NOTES
Header returned contains:
'Authorization' = $TokenRequest.access_token
'AccountID' = $AccountID
The ClientID & ClientSecrect should be stoted/retreived from a secure credential store as it provides access to your Nebula account.
.EXAMPLE
$accountID = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa'
$clientID = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa'
$clientSecret = '000000ABCDEF000000ABCDEF000000AB000000ABCDEF000000ABCDEF000000AB'
$NebulaToken = Get-NebulaToken -AccountID $accountID -ClientID $clientID -ClientSecret $clientSecret
.EXAMPLE
$NebulaToken = Get-NebulaToken -AccountID $accountID -ClientID $clientID -ClientSecret $clientSecret -Verbose
.EXAMPLE
Get-NebulaToken -AccountID 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa' -ClientID 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa' -ClientSecret '000000ABCDEF000000ABCDEF000000AB000000ABCDEF000000ABCDEF000000AB'
#>
Param (
[Parameter(Mandatory=$true)][ValidateNotNullOrEmpty()]
[ValidatePattern('^[{(]?([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})[)}]?$')]
[string] $AccountID,
[Parameter(Mandatory=$true)] [ValidateNotNullOrEmpty()]
[ValidatePattern('^[{(]?([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})[)}]?$')]
[string] $ClientID,
[Parameter(Mandatory=$true)] [ValidateNotNullOrEmpty()]
[ValidatePattern('^[a-f0-9]{64}$')]
[string] $ClientSecret,
[Parameter(Mandatory=$false)][ValidateNotNullOrEmpty()][ValidateSet('read','write','execute','read write','read execute','write execute','read write execute')]
[string] $Scope = 'read write execute',
[ValidateNotNullOrEmpty()][Parameter(Mandatory=$false)]
[string] $BaseUrl = 'https://api.malwarebytes.com'
)
Write-Verbose 'Executing function Get-NebulaToken'
Try {
$URI = $BaseUrl + '/oauth2/token'
Write-Verbose $URI
$credential_pair = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(($ClientID, $ClientSecret -join ':')))
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$headers = @{
'Authorization' = ('Basic', $credential_pair -join ' ');
'Content-Type' = 'application/x-www-form-urlencoded'
}
$headers | Select-Object -Property * | Out-String | Write-Verbose
$body = @{
scope="$Scope"
grant_type='client_credentials'
}
$body | Format-List | Out-String | Write-Verbose
$TokenRequest = Invoke-RestMethod -Method POST -Uri $URI -Body $body -Headers $headers
Write-Verbose -Message 'Creating NebulaToken object'
$NebulaToken = [PSCustomObject]@{
'PSTypeName' = 'Nebula.Token'
'accountID' = $AccountID
'access_token' = $TokenRequest.access_token
'expires_in' = $TokenRequest.expires_in
'expires_at' = (Get-Date).AddSeconds($TokenRequest.expires_in)
'headers' = @{
'Authorization' = 'Bearer ' + $TokenRequest.access_token
'accountid' = $AccountID
'Content-Type' = 'application/json'
}
'scope' = $TokenRequest.scope
'token_type' = $TokenRequest.token_type
'baseurl' = $BaseUrl
}
$NebulaToken | Out-String | Write-Verbose
}
Catch {
Write-Host "The following error occured while obtaining the token from Nebula: $_"
$ErrorRecord = $_
$Result = $ErrorRecord.ErrorDetails.Message | ConvertFrom-Json
Write-Host $Result
Return $ErrorRecord
}
Return $NebulaToken
}
Get-NebulaAccount
Use this function to get account details.
function Get-NebulaAccount {
<#
.SYNOPSIS
Receive Nebula Account Details.
.DESCRIPTION
GET request that returns an overview of a Nebula account's details.
.PARAMETER Nebula.Token
Can be provided as a parameter or in a pipeline; see .EXAMPLE.
.PARAMETER DumpResponse
OPTIONAL - Print the entire formatted response to screen.
.OUTPUTS
Outputs the response which includes account name, license info & usage, default policy & group's ids.
.EXAMPLE
$NebulaToken = Get-NebulaToken -AccountID 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa' -ClientID 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa' -ClientSecret '000000ABCDEF000000ABCDEF000000AB000000ABCDEF000000ABCDEF000000AB'
Get-NebulaAccount -NebulaToken $NebulaToken
.EXAMPLE
Get-NebulaToken -AccountID $accountID -ClientID $clientID -ClientSecret $clientSecret | Get-NebulaAccount
#>
Param (
[Parameter(Mandatory=$true, ValueFromPipeline=$true)]
[ValidateNotNullOrEmpty()]
[PSTypeName('Nebula.Token')]$NebulaToken,
[Parameter()] [switch] $DumpResponse
)
Write-Verbose 'Function Get-NebulaAccount'
Try {
$URI = 'https://api.malwarebytes.com/nebula/v1/account'
$request = Invoke-RestMethod -Method GET -Uri $URI -Headers $NebulaToken.Headers
}
Catch {
Write-Host "The following error occured while obtaining Account from Nebula: $_"
$ErrorRecord = $_
Return $ErrorRecord
}
if ($DumpResponse) {
$request | ConvertTo-Json -Depth 5 | Out-Host
}
Return $request
}
Get-NebulaDetection
Use this function to get detections.
function Get-NebulaDetection {
<#
.SYNOPSIS
Receive Nebula Detections.
.DESCRIPTION
Returns either detections from a specified time period or a specific detection if it's id is provided. Use one of the date flags, i.e -OneMonth to specify the time range.
.PARAMETER Nebula.Token
Can be provided as a parameter or in a pipeline; see .EXAMPLE.
.PARAMETER DetectionID
OPTIONAL - Provide to retrieve information about a specific detection.
.PARAMETER OneWeek, OneMonth, ThreeMonths, OneYear
OPTIONAL - Provide one to specify the time range.
.PARAMETER DumpResponse
OPTIONAL - Print the entire formatted response to screen.
.OUTPUTS
Outputs detection or detections.
.EXAMPLE
$NebulaToken = Get-NebulaToken -AccountID 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa' -ClientID 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa' -ClientSecret '000000ABCDEF000000ABCDEF000000AB000000ABCDEF000000ABCDEF000000AB'
Get-NebulaDetection -NebulaToken $NebulaToken
.EXAMPLE
Get-NebulaToken -AccountID $accountID -ClientID $clientID -ClientSecret $clientSecret | Get-NebulaDetection -ThreeMonths
.EXAMPLE
Get-NebulaToken -AccountID $accountID -ClientID $clientID -ClientSecret $clientSecret | Get-NebulaDetection -DetectionID 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa'
#>
[CmdletBinding()]
param (
[Parameter(Mandatory = $true, ValueFromPipeline = $true)]
[ValidateNotNullOrEmpty()]
[PSTypeName('Nebula.Token')] $NebulaToken,
[Parameter(Mandatory = $false)]
[string] $DetectionID,
[switch]$OneWeek,
[switch]$OneMonth,
[switch]$ThreeMonths,
[switch]$OneYear,
[Parameter()]
[switch] $DumpResponse
)
Begin {
Write-Verbose 'Initializing Get-NebulaDetection'
# Initialize exclusions as an empty array for consistent output
$detections = @()
$body = @{
next_cursor = ''
page_size = 2000 # Set the desired page size
}
}
Process {
# Collect all switches in an array
$selectedSwitches = @($OneWeek, $OneMonth, $ThreeMonths, $OneYear)
# Check how many switches are set to true
$countSelected = ($selectedSwitches | Where-Object { $_ }).Count
# Validate: Only allow 0 or 1 switch
if ($countSelected -gt 1) {
throw "You can specify only one time range option: -OneWeek, -OneMonth, -ThreeMonths, or -OneYear."
}
switch ($countSelected) {
1 {
# Determine which switch was selected
if ($OneWeek) { $offset = -7 }
if ($OneMonth) { $offset = -30 }
if ($ThreeMonths) { $offset = -90 }
if ($OneYear) { $offset = -365 }
}
0 { $offset = -7 }
}
$dateStr = (Get-Date).AddDays($offset).ToString("yyyy-MM-ddTHH:mm:ssZ")
if (!($DetectionID)) {
Try {
$URI = 'https://api.malwarebytes.com/nebula/v1/detections'
$body.Add('start_date', $dateStr)
do {
$bodyJson = $body | ConvertTo-JSON
$request = Invoke-RestMethod -Method POST -Uri $URI -Body $bodyJson -Headers $NebulaToken.Headers
$detections += $request.detections
$body.next_cursor = $request.next_cursor
} while ($body.next_cursor -ne '')
} Catch {
Write-Error -Message "Error obtaining Detections from Nebula: $_"
}
} else {
Try {
$URI = "https://api.malwarebytes.com/nebula/v1/detections/" + $DetectionID
$request = Invoke-RestMethod -Method GET -Uri $URI -Headers $NebulaToken.Headers
$detections = $request
}
Catch {
Write-Error -Message "Error obtaining Schedule ID $DetectionID from Nebula: $_"
}
}
}
End {
if ($DumpResponse) {
Write-Host "Dumping Detections"
# Convert to JSON for each item to ensure consistent detailed output
$detections | ForEach-Object { $_ | ConvertTo-Json -Depth 5 | Out-Host }
}
return $detections
}
}
Get-NebulaEndpoints
Use this function to get endpoints.
function Get-NebulaEndpoint {
<#
.SYNOPSIS
Receive Nebula Endpoints.
.DESCRIPTION
Returns either all endpoints or a specific endpoint if it's id is provided.
.PARAMETER Nebula.Token
Can be provided as a parameter or in a pipeline; see .EXAMPLE.
.PARAMETER HostName
OPTIONAL - Search for endpoint by HostName.
.PARAMETER HostName
OPTIONAL - Search for endpoint by Alias.
.PARAMETER DumpResponse
OPTIONAL - Print the entire formatted response to screen.
.OUTPUTS
Outputs endpoint or endpoints.
.EXAMPLE
$NebulaToken = Get-NebulaToken -AccountID 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa' -ClientID 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa' -ClientSecret '000000ABCDEF000000ABCDEF000000AB000000ABCDEF000000ABCDEF000000AB'
Get-NebulaEndpoint -NebulaToken $NebulaToken
.EXAMPLE
Get-NebulaToken -AccountID $accountID -ClientID $clientID -ClientSecret $clientSecret | Get-NebulaEndpoint -HostName 'PC1234'
.EXAMPLE
Get-NebulaToken -AccountID $accountID -ClientID $clientID -ClientSecret $clientSecret | Get-NebulaEndpoint
#>
[CmdletBinding()]
param (
[Parameter(Mandatory = $true, ValueFromPipeline = $true)]
[ValidateNotNullOrEmpty()]
[PSTypeName('Nebula.Token')] $NebulaToken,
[Parameter(Mandatory = $false)]
[string] $HostName,
[Parameter(Mandatory = $false)]
[string] $Alias,
[Parameter()]
[switch] $DumpResponse
)
Begin {
Write-Verbose 'Initializing Get-NebulaEndpoint'
# Check if both $HostName and $Alias are provided
if ($HostName -and $Alias) {
throw "You cannot both -HostName and Alias. Please provide only one."
}
# Initialize endpoints as an empty array for consistent output
$endpoints = @()
$body = @{
next_cursor = ''
page_size = 2000
}
}
Process {
if (!($HostName -or $Alias)) {
Try {
$bodyJson = $body | ConvertTo-Json
$URI = 'https://api.malwarebytes.com/nebula/v1/endpoints'
$next_cursor = $body.next_cursor
do {
$body.next_cursor = $next_cursor
$bodyJson = $body | ConvertTo-Json
$request = Invoke-RestMethod -Method POST -Uri $URI -Body $bodyJson -Headers $NebulaToken.Headers
$endpoints += $request.endpoints
$next_cursor = $request.next_cursor
} while ($next_cursor -ne '')
}
Catch {
Write-Error -Message "Error obtaining Endpoints from Nebula: $_"
}
} elseif ($HostName) {
Try {
$body = @{"host_name.keyword" = $HostName} | ConvertTo-Json
$URI = "https://api.malwarebytes.com/nebula/v1/endpoints"
$request = Invoke-RestMethod -Method POST -Uri $URI -Body $body -Headers $NebulaToken.Headers
$endpoints = $request
}
Catch {
Write-Error -Message "Error obtaining Endpoint ID $EndpointID from Nebula: $_"
}
} elseif ($Alias) {
Try {
$body = @{ "alias" = $Alias } | ConvertTo-Json
$URI = "https://api.malwarebytes.com/nebula/v1/endpoints"
$request = Invoke-RestMethod -Method POST -Uri $URI -Body $body -Headers $NebulaToken.Headers
$endpoints = $request
}
Catch {
Write-Error -Message "Error obtaining Alias $Alias from Nebula: $_"
}
}
}
End {
if ($DumpResponse) {
Write-Host "Dumping Endpoints"
# Convert to JSON for each item to ensure consistent detailed output
$endpoints | ForEach-Object { $_ | ConvertTo-Json -Depth 5 | Out-Host }
}
return $endpoints
}
}
Get-NebulaEvent
Use this function to get events.
function Get-NebulaEvent {
<#
.SYNOPSIS
Receive Nebula Events.
.DESCRIPTION
Returns either all events within a time frame or events from a specific endpoint if its machine_id is provided.
.PARAMETER Nebula.Token
Can be provided as a parameter or in a pipeline; see .EXAMPLE.
.PARAMETER machine_id
OPTIONAL - Search for events for endpoint with machine_id.
.PARAMETER OneWeek, OneMonth, ThreeMonths, OneYear
OPTIONAL - Time frame of events.
.PARAMETER DumpResponse
OPTIONAL - Print the entire formatted response to screen.
.OUTPUTS
Outputs events within the time frame or events for a specified endpoint.
.EXAMPLE
$NebulaToken = Get-NebulaToken -AccountID 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa' -ClientID 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa' -ClientSecret '000000ABCDEF000000ABCDEF000000AB000000ABCDEF000000ABCDEF000000AB'
Get-NebulaEvent -NebulaToken $NebulaToken
.EXAMPLE
Get-NebulaToken -AccountID $accountID -ClientID $clientID -ClientSecret $clientSecret | Get-NebulaEvent -machine_id 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa'
.EXAMPLE
Get-NebulaToken -AccountID $accountID -ClientID $clientID -ClientSecret $clientSecret | Get-NebulaEvent -OneMonth # Get all events from the last month
#>
[CmdletBinding()]
param (
[Parameter(Mandatory = $true, ValueFromPipeline = $true)]
[ValidateNotNullOrEmpty()]
[PSTypeName('Nebula.Token')] $NebulaToken,
[Parameter(Mandatory = $false)]
[string]$machine_id,
[switch]$OneWeek,
[switch]$OneMonth,
[switch]$ThreeMonths,
[switch]$OneYear,
[Parameter()]
[switch] $DumpResponse
)
Begin {
Write-Verbose 'Initializing Get-NebulaEvent'
# Initialize exclusions as an empty array for consistent output
$events = @()
$next_cursor = ''
$page_size = 2000 # Set the desired page size
$useStartDate = $false
}
Process {
# Collect all switches in an array
$selectedSwitches = @($OneWeek, $OneMonth, $ThreeMonths, $OneYear)
# Check how many switches are set to true
$countSelected = ($selectedSwitches | Where-Object { $_ }).Count
# Validate: Only allow 0 or 1 switch
if ($countSelected -gt 1) {
throw "You can specify only one time range option: -OneWeek, -OneMonth, -ThreeMonths, or -OneYear."
}
switch ($countSelected) {
1 {
$useStartDate = $true
# Determine which switch was selected
if ($OneWeek) { $offset = -7 }
if ($OneMonth) { $offset = -30 }
if ($ThreeMonths) { $offset = -90 }
if ($OneYear) { $offset = -365 }
}
0 {
$offset = -7 # Default start date of a week ago
}
}
$dateStr = (Get-Date).AddDays($offset).ToString("yyyy-MM-ddTHH:mm:ssZ")
Try {
$URI = 'https://api.malwarebytes.com/nebula/v1/events'
# Start forming the URI with page_size and 'start'
if ($useStartDate) {
$URI += "?start=$dateStr&page_size=$page_size"
} else {
$URI += "?page_size=$page_size"
}
# Add machine_id if it is provided
if ($machine_id) {
$URI += "&machine_id=$machine_id"
}
do {
# Build the URI correctly with next_cursor if available
if ($next_cursor) {
$uriWithCursor = "$URI&next_cursor=$next_cursor"
} else {
$uriWithCursor = $URI
}
$request = Invoke-RestMethod -Method GET -Uri $uriWithCursor -Headers $NebulaToken.Headers
$events += $request.events
$next_cursor = $request.next_cursor
} while ($next_cursor -ne '')
} Catch {
Write-Error -Message "Error obtaining Events from Nebula: $_"
}
}
End {
if ($DumpResponse) {
Write-Host "Dumping Events"
# Convert to JSON for each item to ensure consistent detailed output
$events | ForEach-Object { $_ | ConvertTo-Json -Depth 5 | Out-Host }
}
return $events
}
}
Get-NebulaExclusion
Use this function to get exclusions.
function Get-NebulaExclusion {
<#
.SYNOPSIS
Receive Nebula Exclusions.
.DESCRIPTION
Returns either all exclusions or a specific exclusion if its ID is provided.
.PARAMETER Nebula.Token
Can be provided as a parameter or in a pipeline; see .EXAMPLE.
.PARAMETER ExclusionID
OPTIONAL - Get a specific exclusion.
.PARAMETER DumpResponse
OPTIONAL - Print the entire formatted response to screen.
.OUTPUTS
Outputs all exclusions or a single exclusion.
.EXAMPLE
$NebulaToken = Get-NebulaToken -AccountID 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa' -ClientID 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa' -ClientSecret '000000ABCDEF000000ABCDEF000000AB000000ABCDEF000000ABCDEF000000AB'
Get-NebulaExclusion -NebulaToken $NebulaToken
.EXAMPLE
Get-NebulaToken -AccountID $accountID -ClientID $clientID -ClientSecret $clientSecret | Get-NebulaExclusion -machine_id 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa'
.EXAMPLE
Get-NebulaToken -AccountID $accountID -ClientID $clientID -ClientSecret $clientSecret | Get-NebulaExclusion -OneMonth # Get all events from the last month
#>
[CmdletBinding()]
param (
[Parameter(Mandatory = $true, ValueFromPipeline = $true)]
[ValidateNotNullOrEmpty()]
[PSTypeName('Nebula.Token')] $NebulaToken,
[Parameter(Mandatory = $false)]
[string] $ExclusionID,
[Parameter()]
[switch] $DumpResponse
)
Begin {
Write-Verbose 'Initializing Get-NebulaExclusion'
# Initialize exclusions as an empty array for consistent output
$exclusions = @()
}
Process {
if (!($ExclusionID)) {
Try {
$URI = 'https://api.malwarebytes.com/nebula/v1/exclusions'
$next_cursor = ''
$page_size = 2000 # Set the desired page size
do {
# Build the URI with next_cursor and page_size
if ($next_cursor) {
$uriWithCursor = "$($URI)?next_cursor=$next_cursor&page_size=$page_size"
} else {
$uriWithCursor = "$($URI)?page_size=$page_size"
}
$request = Invoke-RestMethod -Method GET -Uri $uriWithCursor -Headers $NebulaToken.Headers
$exclusions += $request.exclusions
$next_cursor = $request.next_cursor
} while ($next_cursor -ne '')
} Catch {
Write-Error -Message "Error obtaining Exclusions from Nebula: $_"
}
} else {
Try {
$URI = "https://api.malwarebytes.com/nebula/v1/exclusions/" + $ExclusionID
$request = Invoke-RestMethod -Method GET -Uri $URI -Headers $NebulaToken.Headers
$exclusions = $request
} Catch {
Write-Error -Message "Error obtaining Schedule ID $ExclusionID from Nebula: $_"
}
}
}
End {
if ($DumpResponse) {
Write-Host "Dumping Exclusions"
# Convert to JSON for each item to ensure consistent detailed output
$exclusions | ForEach-Object { $_ | ConvertTo-Json -Depth 5 | Out-Host }
}
return $exclusions
}
}
Get-NebulaGroup
Use this function to get groups.
#Requires -Version 3.0
function Get-NebulaGroup {
<#
.SYNOPSIS
Gathers all groups, or a single group.
.DESCRIPTION
Gathers all groups, or a single group if the GroupID parameter is provided.
.PARAMETER Nebula.Token
Can be provided as a parameter or in a pipeline; see .EXAMPLE.
.PARAMETER GroupID
If provided returns this group's information.
.PARAMETER DumpResponse
OPTIONAL - Print the entire formatted response to screen.
.OUTPUTS
Outputs the response which includes groups' id, name, policy_name, schedule_ids.
.EXAMPLE
Get-NebulaGroup -NebulaToken $NebulaToken
.EXAMPLE
Get-NebulaToken -AccountID $accountID -ClientID $clientID -ClientSecret $clientSecret | Get-NebulaGroup
#>
[CmdletBinding()]
Param (
[Parameter(Mandatory=$true, ValueFromPipeline=$true)]
[ValidateNotNullOrEmpty()]
[PSTypeName('Nebula.Token')]$NebulaToken,
[Parameter(Mandatory=$false)]
[string]$GroupID,
[Parameter()] [switch] $DumpResponse
)
Begin {
Write-Verbose 'Function Get-NebulaGroup'
# Initialize groups as an empty array for consistent output
$groups = @()
}
Process {
if (-not $GroupID) {
# No GroupID provided, retrieve all groups
Try {
$URI = 'https://api.malwarebytes.com/nebula/v1/groups'
$next_cursor = ''
do {
$uriWithCursor = if ($next_cursor) { "$($URI)?next_cursor=$($next_cursor)" } else { $URI }
$request = Invoke-RestMethod -Method GET -Uri $uriWithCursor -Headers $NebulaToken.Headers
$groups += $request.groups
$next_cursor = $request.next_cursor
} while ($next_cursor -ne '')
}
Catch {
Write-Error -Message "Error obtaining Groups from Nebula: $_"
}
} else {
# GroupID provided, retrieve specific group
Try {
$URI = "https://api.malwarebytes.com/nebula/v1/groups/$GroupID"
$request = Invoke-RestMethod -Method GET -Uri $URI -Headers $NebulaToken.Headers
$groups = $request
}
Catch {
Write-Error -Message "Error obtaining Group ID $GroupID from Nebula: $_"
}
}
}
End {
if ($DumpResponse) {
Write-Host "Dumping Groups"
$groups | ConvertTo-Json -Depth 5 | Out-Host
}
return $groups
}
}
Get-NebulaPolicy
Use this function to get policies.
function Get-NebulaPolicy {
<#
.SYNOPSIS
Gathers all policies, or a single policy.
.DESCRIPTION
Gathers all policies, or a single policy if the PolicyID parameter is provided.
.PARAMETER Nebula.Token
Can be provided as a parameter or in a pipeline; see .EXAMPLE.
.PARAMETER PolicyID
If provided returns this policy's information.
.PARAMETER DumpResponse
OPTIONAL - Print the entire formatted response to screen.
.OUTPUTS
Outputs the response which includes policies' id, name, groups, exclusions.
.EXAMPLE
Get-NebulaPolicy -NebulaToken $NebulaToken
.EXAMPME
Get-NebulaToken -AccountID $accountID -ClientID $clientID -ClientSecret $clientSecret | Get-NebulaPolicy -PolicyID "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa"
#>
[CmdletBinding()]
param (
[Parameter(Mandatory = $true, ValueFromPipeline = $true)]
[ValidateNotNullOrEmpty()]
[PSTypeName('Nebula.Token')] $NebulaToken,
[Parameter(Mandatory = $false)]
[string] $PolicyID,
[Parameter()]
[switch] $DumpResponse
)
Begin {
Write-Verbose 'Initializing Get-NebulaPolicy'
# Initialize policies as an empty array for consistent output
$policies = @()
}
Process {
if (!($PolicyID)) {
Try {
$URI = 'https://api.malwarebytes.com/nebula/v1/policies'
$request = Invoke-RestMethod -Method GET -Uri $URI -Headers $NebulaToken.Headers
$policies = $request
}
Catch {
Write-Error -Message "Error obtaining Policies from Nebula: $_"
}
} else {
Try {
$URI = "https://api.malwarebytes.com/nebula/v1/policies/$PolicyID"
$request = Invoke-RestMethod -Method GET -Uri $URI -Headers $NebulaToken.Headers
$policies = $request
}
Catch {
Write-Error -Message "Error obtaining Policy ID $PolicyID from Nebula: $_"
}
}
}
End {
if ($DumpResponse) {
Write-Host "Dumping Policies"
# Convert to JSON for each item to ensure consistent detailed output
$policies | ForEach-Object { $_ | ConvertTo-Json -Depth 5 | Out-Host }
}
return $policies
}
}
Get-NebulaQuarantine
Use this function to get items in the quarantine.
function Get-NebulaQuarantine {
<#
.SYNOPSIS
Gathers quarantine items.
.DESCRIPTION
Gathers all quarantine items in a specified time frame: OneWeek, OneMonth, ThreeMonths, OneYear.
.PARAMETER Nebula.Token
Can be provided as a parameter or in a pipeline; see .EXAMPLE.
.PARAMETER OneWeek, OneMonth, ThreeMonths, OneYear
Mutually exclusive time frame, defaults to OneWeek.
.PARAMETER DumpResponse
OPTIONAL - Print the entire formatted response to screen.
.OUTPUTS
Outputs quarantined items.
.EXAMPLE
Get-NebulaPolicy -NebulaToken $NebulaToken
.EXAMPME
Get-NebulaToken -AccountID $accountID -ClientID $clientID -ClientSecret $clientSecret | Get-NebulaPolicy -PolicyID "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaa"
#>
[CmdletBinding()]
param (
[Parameter(Mandatory = $true, ValueFromPipeline = $true)]
[ValidateNotNullOrEmpty()]
[PSTypeName('Nebula.Token')] $NebulaToken,
[switch]$OneWeek,
[switch]$OneMonth,
[switch]$ThreeMonths,
[switch]$OneYear,
[Parameter()]
[switch] $DumpResponse
)
Begin {
Write-Verbose 'Initializing Get-NebulaQuarantine'
# Initialize exclusions as an empty array for consistent output
$quarantine = @()
$next_cursor = ''
$page_size = 2000 # Set the desired page size
$useSinceDate = $false
}
Process {
# Collect all switches in an array
$selectedSwitches = @($OneWeek, $OneMonth, $ThreeMonths, $OneYear)
# Check how many switches are set to true
$countSelected = ($selectedSwitches | Where-Object { $_ }).Count
# Validate: Only allow 0 or 1 switch
if ($countSelected -gt 1) {
throw "You can specify only one time range option: -OneWeek, -OneMonth, -ThreeMonths, or -OneYear."
}
switch ($countSelected) {
1 {
$useSinceDate = $true
# Determine which switch was selected
if ($OneWeek) { $offset = -7 }
if ($OneMonth) { $offset = -30 }
if ($ThreeMonths) { $offset = -90 }
if ($OneYear) { $offset = -365 }
}
0 {
$offset = -7 # Default start date of a week ago
}
}
$dateStr = (Get-Date).AddDays($offset).ToString("yyyy-MM-ddTHH:mm:ssZ")
Try {
$URI = 'https://api.malwarebytes.com/nebula/v1/quarantine'
# Start forming the URI with page_size and 'start'
if ($useSinceDate) {
$URI += "?since=$dateStr&page_size=$page_size"
} else {
$URI += "?page_size=$page_size"
}
do {
# Build the URI correctly with next_cursor if available
if ($next_cursor) {
$uriWithCursor = "$URI&next_cursor=$next_cursor"
} else {
$uriWithCursor = $URI
}
$request = Invoke-RestMethod -Method GET -Uri $uriWithCursor -Headers $NebulaToken.Headers
$quarantine += $request.quarantined_threats
$next_cursor = $request.next_cursor
} while ($next_cursor -ne '')
} Catch {
Write-Error -Message "Error obtaining Quarantine from Nebula: $_"
}
}
End {
if ($DumpResponse) {
Write-Host "Dumping Quarantine"
# Convert to JSON for each item to ensure consistent detailed output
$quarantine | ForEach-Object { $_ | ConvertTo-Json -Depth 5 | Out-Host }
}
return $quarantine
}
}
Get-NebulaSchedule
Use this function to get schedules.
function Get-NebulaSchedule {
<#
.SYNOPSIS
Gathers all schedules, or a single schedule.
.DESCRIPTION
Gathers all schedules, or a single schedule if the ScheduleID parameter is provided.
.PARAMETER Nebula.Token
Can be provided as a parameter or in a pipeline; see .EXAMPLE.
.PARAMETER GroupID
If provided returns this schedule's information.
.PARAMETER DumpResponse
OPTIONAL - Print the entire formatted response to screen.
.OUTPUTS
Outputs all schedules or the schedule requested.
.EXAMPLE
Get-NebulaGroup -NebulaToken $NebulaToken
.EXAMPLE
Get-NebulaToken -AccountID $accountID -ClientID $clientID -ClientSecret $clientSecret | Get-NebulaGroup
#>
[CmdletBinding()]
param (
[Parameter(Mandatory = $true, ValueFromPipeline = $true)]
[ValidateNotNullOrEmpty()]
[PSTypeName('Nebula.Token')] $NebulaToken,
[Parameter(Mandatory = $false)]
[string] $ScheduleID,
[Parameter()]
[switch] $DumpResponse
)
Begin {
Write-Verbose 'Initializing Get-NebulaSchedule'
# Initialize schedules as an empty array for consistent output
$schedules = @()
}
Process {
if (!($ScheduleID)) {
Try {
$URI = 'https://api.malwarebytes.com/nebula/v1/schedules'
$next_cursor = ''
$page_size = 2000 # Set the desired page size
do {
# Build the URI correctly with next_cursor if available
if ($next_cursor) {
$uriWithCursor = "$($URI)?next_cursor=$next_cursor&page_size=$page_size"
} else {
$uriWithCursor = "$($URI)?page_size=$page_size"
}
$request = Invoke-RestMethod -Method GET -Uri $uriWithCursor -Headers $NebulaToken.Headers
$schedules += $request.schedules
$next_cursor = $request.next_cursor
} while ($next_cursor -ne '')
}
Catch {
Write-Error -Message "Error obtaining Schedules from Nebula: $_"
}
} else {
Try {
$URI = "https://api.malwarebytes.com/nebula/v1/schedules/" + $ScheduleID
$request = Invoke-RestMethod -Method GET -Uri $URI -Headers $NebulaToken.Headers
$schedules = $request
}
Catch {
Write-Error -Message "Error obtaining Schedule ID $ScheduleID from Nebula: $_"
}
}
}
End {
if ($DumpResponse) {
Write-Host "Dumping Schedules"
# Convert to JSON for each item to ensure consistent detailed output
$schedules | ForEach-Object { $_ | ConvertTo-Json -Depth 5 | Out-Host }
}
return $schedules
}
}
Get-NebulaAppBlockActivity
Use this function get AppBlock activity. Specify time frames up to one year, 7 day default
function Get-NebulaAppBlockActivity {
<#
.SYNOPSIS
Gathers AppBlock Activity.
.DESCRIPTION
Gathers AppBlock activity. Iterates through paginated response.
.PARAMETER Nebula.Token
Can be provided as a parameter or in a pipeline; see .EXAMPLE.
.PARAMETER OneWeek, OneMonth, ThreeMonths, OneYear
Mutually exclusive time frame, defaults to OneWeek.
.PARAMETER DumpResponse
OPTIONAL - Print the entire formatted response to screen.
.OUTPUTS
Outputs AppBlock Activity in the given timeframe.
.EXAMPLE
Get-NebulaAppBlockActivity -NebulaToken $NebulaToken
.EXAMPLE
Get-NebulaToken -AccountID $accountID -ClientID $clientID -ClientSecret $clientSecret | Get-NebulaAppBlockActivity
#>
[CmdletBinding()]
param (
[Parameter(Mandatory = $true, ValueFromPipeline = $true)]
[ValidateNotNullOrEmpty()]
[PSTypeName('Nebula.Token')] $NebulaToken,
[switch]$OneWeek,
[switch]$OneMonth,
[switch]$ThreeMonths,
[switch]$OneYear,
[Parameter()]
[switch] $DumpResponse
)
Begin {
Write-Verbose 'Initializing Get-NebulaAppBlockActivity'
$body = @{
next_cursor = ''
page_size = 2000 # Set the desired page size
}
# Initialize $ab as an empty array for consistent output
$ab = @()
}
Process {
# Collect all switches in an array
$selectedSwitches = @($OneWeek, $OneMonth, $ThreeMonths, $OneYear)
# Check how many switches are set to true
$countSelected = ($selectedSwitches | Where-Object { $_ }).Count
# Validate: Only allow 0 or 1 switch
if ($countSelected -gt 1) {
throw "You can specify only one time range option: -OneWeek, -OneMonth, -ThreeMonths, or -OneYear."
}
switch ($countSelected) {
1 {
# Determine which switch was selected
if ($OneWeek) { $offset = -7 }
if ($OneMonth) { $offset = -30 }
if ($ThreeMonths) { $offset = -90 }
if ($OneYear) { $offset = -365 }
}
0 { $offset = -7 }
}
$dateStr = (Get-Date).AddDays($offset).ToString("yyyy-MM-ddTHH:mm:ssZ")
Try {
$URI = 'https://api.malwarebytes.com/nebula/v1/app-block/activity'
$body.Add('scanned_at_after', $dateStr)
do {
$bodyJson = $body | ConvertTo-JSON
$request = Invoke-RestMethod -Method POST -Uri $URI -Body $bodyJson -Headers $NebulaToken.Headers
$ab += $request.results
$body.next_cursor = $request.next_cursor
} while ($body.next_cursor -ne '')
}
Catch {
Write-Error -Message "Error obtaining AppBlock Activity from Nebula $($_.Exception.Message)"
}
}
End {
if ($DumpResponse) {
Write-Host "Dumping AppBlock Activity"
# Convert to JSON for each item to ensure consistent detailed output
$request | ForEach-Object { $_ | ConvertTo-Json -Depth 5 | Out-Host }
}
return $ab
}
}
Get-NebulaSuspiciousActivity
Use this function to get Suspicious Activity events.
function Get-NebulaSuspiciousActivity {
<#
.SYNOPSIS
Gathers all Suspicious Activities.
.DESCRIPTION
Gathers all Suspicious Activities from Nebula. Iterates through paginated response.
.PARAMETER Nebula.Token
Can be provided as a parameter or in a pipeline; see .EXAMPLE.
.PARAMETER DumpResponse
OPTIONAL - Print the entire formatted response to screen.
.OUTPUTS
Outputs all Suspicious Activities.
.EXAMPLE
Get-NebulaSuspiciousActivity -NebulaToken $NebulaToken
.EXAMPLE
Get-NebulaToken -AccountID $account_id -ClientID $clientID -ClientSecret $clientSecret | Get-NebulaSuspiciousActivity
#>
[CmdletBinding()]
param (
[Parameter(Mandatory = $true, ValueFromPipeline = $true)]
[ValidateNotNullOrEmpty()]
[PSTypeName('Nebula.Token')] $NebulaToken,
[Parameter()]
[switch] $DumpResponse
)
Begin {
Write-Verbose 'Initializing Get-NebulaSuspiciousActivity'
# Initialize Suspicious Activities as an empty array for consistent output
$sa = @()
}
Process {
Try {
$URI = "https://api.malwarebytes.com/nebula/v1/sa"
$next_cursor = ''
$page_size = 2000 # Set the desired page size
do {
# Build the URI correctly with next_cursor if available
if ($next_cursor) {
$uriWithCursor = "$($URI)?next_cursor=$next_cursor&page_size=$page_size"
} else {
$uriWithCursor = "$($URI)?page_size=$page_size"
}
$request = Invoke-RestMethod -Method GET -Uri $uriWithCursor -Headers $NebulaToken.Headers
$sa += $request.sa
$next_cursor = $request.next_cursor
} while ($next_cursor -ne '')
}
Catch {
Write-Error -Message "Error obtaining Suspicious Activities from Nebula $($_.Exception.Message)"
}
}
End {
if ($DumpResponse) {
Write-Host "Dumping Suspicious Activities"
# Convert to JSON for each item to ensure consistent detailed output
$sa | ForEach-Object { $_ | ConvertTo-Json -Depth 5 | Out-Host }
}
return $sa
}
}
Get-NebulaUsers
Use this function to get of all users and their roles on your Nebula account.
function Get-NebulaUsers {
<#
.SYNOPSIS
Gathers all users.
.DESCRIPTION
Gathers all users from Nebula. Iterates through paginated response.
.PARAMETER Nebula.Token
Can be provided as a parameter or in a pipeline; see .EXAMPLE.
.PARAMETER DumpResponse
OPTIONAL - Print the entire formatted response to screen.
.OUTPUTS
Outputs all users.
.EXAMPLE
Get-NebulaUsers -NebulaToken $NebulaToken
.EXAMPLE
Get-NebulaToken -AccountID $accountID -ClientID $clientID -ClientSecret $clientSecret | Get-NebulaUsers
#>
[CmdletBinding()]
param (
[Parameter(Mandatory = $true, ValueFromPipeline = $true)]
[ValidateNotNullOrEmpty()]
[PSTypeName('Nebula.Token')] $NebulaToken,
[Parameter()]
[switch] $DumpResponse
)
Begin {
Write-Verbose 'Initializing Get-NebulaUsers'
# Initialize users as an empty array for consistent output
$users = @()
}
Process {
Try {
$URI = 'https://api.malwarebytes.com/nebula/v1/users'
$next_cursor = ''
$page_size = 2000 # Set the desired page size
do {
# Build the URI correctly with next_cursor if available
if ($next_cursor) {
$uriWithCursor = "$($URI)?next_cursor=$next_cursor&page_size=$page_size"
} else {
$uriWithCursor = "$($URI)?page_size=$page_size"
}
$request = Invoke-RestMethod -Method GET -Uri $uriWithCursor -Headers $NebulaToken.Headers
$users += $request.users
$next_cursor = $request.next_cursor
} while ($next_cursor -ne '')
}
Catch {
Write-Error -Message "Error obtaining users from OneView $($_.Exception.Message)"
}
}
End {
if ($DumpResponse) {
Write-Host "Dumping Users"
# Convert to JSON for each item to ensure consistent detailed output
$users | ForEach-Object { $_ | ConvertTo-Json -Depth 5 | Out-Host }
}
return $users
}
}