Skip to main content

Nebula API examples using PowerShell

Updated: 

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.

Generate client credentials

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'   = $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-NebulaDetections

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' # Get endpoint with HostName 'PC1234'
.EXAMPLE 
    Get-NebulaToken -AccountID $accountID -ClientID $clientID -ClientSecret $clientSecret | Get-NebulaEndpoint # Get all endpoints
  #>
[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 NebulaToken
      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
  }
}

Still have questions?

Support is available via chat, phone or by creating a ticket. You can also use our virtual assistant for guided assistance.

Learn more