[-]
  
[-]
  
  
  
  
  
  
  
 
 
[-]
  
  
  
  
[-]
  
 [+]
  
[-]
Monitoring
  
 [+]
 [+]
 [+]
  
[-]
Monitoring guides
  
  
[-]
Templates
  
  
  
[-]
Cloud monitoring
 [+]
  
  
 [+]
Kubernetes
[-]
Network checks
 [+]
  
  
  
[-]
 [+]
  
  
  
  
  
  
 [+]
 [+]
 [+]
 [+]
[-]
CounterMeasures
  
 [+]
 [-]
   
   
  
  
[-]
Panopta OnSight
 [+]
 [+]
[-]
SNMP
 [+]
  
[-]
Alerting
 [+]
 [+]
 [+]
 [+]
 [+]
[-]
Reporting
  
  
  
[-]
Maintenance
  
  
[-]
API
  
  
  
  
[-]
Users, Groups, and Authentication
 [+]
  
  
  
[-]
Billing and Payments
  
  
  
  
  
  
 
[-]
  
  
  
  
  
  
  
  
  
  
  
  
Updated on 7/26/2019
Online Help
Custom Windows CounterMeasures actions
Direct link to topic in this publication:

At their core, CounterMeasures are just PowerShell plugins with two required functions. For example, the CounterMeasure below simply returns the output of the Get-ChildItem command.

To create your own CounterMeasure, create a new .ps1 file in the C:\Program Files (x86)\PanoptaAgent\cm_ps_plugins directory. At a minimum, your CounterMeasure needs to implement two functions - Plugin-Configuration, which provides config and metadata about your CounterMeasure and Execute, which is the driver for your CounterMeasure.

Once you're done crafting your CounterMeasure, rebuild your agent metadata via the instance's details page in the Panopta control panel. Your custom plugin will then be available in the Panopta control panel.

CustomCounterMeasure.ps1

JavaScript
function Plugin-Configuration {
$properties = @{}

#Required: a name for your custom CounterMeasure
$properties.add("name", "My Custom CounterMeasure")

#Required: a descirption of your custom CounterMeasure
$properties.add("description", "Returns the current dir list")


#Required: a distinct textkey for your custom CounterMeasure
$properties.add("textkey", "Panopta.ListDirectoryCM")


#Required: the name of the CounterMeasure Author
$properties.add("author", "Panopta.HeadDeveloper")

#Optional: The maximum frequency at which a CounterMeasure can run
$properties.add("max_frequency", "60")


# Required
return $properties
}

function Execute {
# The Metadata param will receive information about the incident the CM is responding to
param([hashtable]$metadata)

# Dictionary to to hold the returned CM payload - you can name this anything
$returndata = @{}

# Dictionary to hold each chunk of information you want to return - you can name this anything
$output = @{}

# Array to hold your 1..n dictionaries of output - you can name this anything
$output_list = New-Object System.Collections.ArrayList

# Required: either success or error. key must be return_code
$returndata.add("return_code", "success")


# Required: output type the data you are returning. either text or html. key must be format
$output.add("format", "text")

# Required: output content. key must be format
$output.add("output", "$(Get-ChildItem | Format-Table -Property Name, Length | Out-String)")

# add your output chunks to your array
$output_list.add($output);

# add your array to your top-level dictionary. key must be output
$returndata.add("output", $output_list)


# return your countermeasure data
return $returndata
}

Leveraging Incident Data

When the agent is notified that it should run a local CounterMeasure action, it also receives metadata about the underlying incident triggering the CounterMeasure. This metadata JSON object is available to you in your code via the metadata parameter. For example, the below code just returns the incident metadata right back to Panopta.

CounterMeasure return metadata

JavaScript
function Plugin-Configuration {

$properties = @{}

$properties.add("name", "Return mmeta")

$properties.add("description", "Returns the invoking incident's md")

$properties.add("textkey", "Panopta.MetadataCM")

$properties.add("author", "Panopta.HeadDeveloper")



return $properties

}

function Execute {

# The Metadata param will receive information about the incident the CM is responding to

param([hashtable]$metadata)

$returndata = @{}

$output = @{}

$output_list = New-Object System.Collections.ArrayList



$returndata.add("return_code", "success")

$output.add("format", "text")

$output.add("output", metadata)

$output_list.add($output);



$returndata.add("output", $output_list)

return $returndata

}

This is helpful as it allows you to take action based on certain criteria, such as which application or metrics triggered the incident. The payload scheme is included below.

CounterMeasures incident metadata

JavaScript
{

"outage": {

"id": "", # The ID number of the associated incident.

"alert_label": "", # Alert label of the incident/anomaly.

"timestamp": "", # UTC timestamp of when the incident/clear occurred.

"severity": "", # Severity of the outage/anomaly, either "critical" or "warning".

"reasons": "", # The reasons for network service incidents or the details for anomalies.

},

"server": {

"id": "", # The ID number of the server experiencing the incident/clear.

"server_key": "", # The server key for the server.

"fqdn": "", # Fully qualified domain name of the server experiencing the incident/clear.

"name": "", # Name of the server experiencing the incident/clear.

"tags": "", # The tags for the server.

"partner_server_id": "", # The partner server id for the server.

# Custom attributes

},

"metrics": "", # Services experiencing the incident/clear or resources experiencing the anomaly/clear.

"metric_tags": "", # The tags for all of the metrics involved in the outage.

"resource": None, # For resource anomalies: resources experiencing the anomaly/clear.

# id, name, item_type

"services": [], # For service incident: services experiencing the incident/clear.

# id, name, item_type, location

}

Implementation Reference

Plugin-Configuration Properties

Parameters
Type
Description
Required
name
String
Human-readable name for the Countermeasure, will be displayed in the control panel and alerts
Yes
author
String
Identifier of the author (recommended to be your email address)
Yes
textkey
String
Unique identifier for the countermeasure, should be lowercase letters, numbers, underscores, and periods. No spaces allowed
Yes
description
String
Description of the countermeasure, for display at command line and in the Panopta control panel
Yes
max_frequency
String
The shortest allowed time between two executions of this plugin, in seconds. If less than that time has elapsed, the second execution won't be performed. Leave set to None to disable frequency checks
No

Execute Properties

The Execute function returns a dictionary, which contains two things: the CounterMeasure execution status and an array of output items. You can name the returned dictionary whatever you like, but for clarity, we'll use the property name $returndata.


Parameter
Type
Description
Required
ReturnData["return_code"]
String
Execution status of the CounterMeasure - either success or error
Yes
ReturnData[outputs_list]
Array of Dictionaries
An array output chunks that you'd like returned for viewing in the Panopta control panel
Yes
outputs_list["format"]
String
Either text or HTML
Yes
outputs_list["output"]
String
Output to be returned
Yes

Plugin Functions

Function
Parameters
Description
Required
Execution
none
Executes the countermeasure action
Yes
Plugin-Configuration
none
Returns CounterMeasure plugin configuration information
Yes