Share:

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:

  1. 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.
  2. Check for syntax errors by running the script in the PowerShell ISE. If the syntax is correct, the execution should not generate any output or error message. If your CounterMeasure has syntax errors, it will not be added to the control panel. 
  3. 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 description 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 receives metadata about the incident triggering the CounterMeasure. This metadata 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. The hashtable properties are listed in the table below

CounterMeasures incident metadata

KeyDescription
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
The severity of the outage/anomaly, either "critical" or "warning".
Server
id
The ID number of the server experiencing the incident/clear.
server_key
The server key for the server.
fqdn
The 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.
Customer 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
For resource anomalies: resources experiencing the anomaly/clear.
services
For service incident: services experiencing the incident/clear.


Implementation Reference

Plugin-Configuration Properties

Parameters
Type
Description
Required
name
String
A 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 the 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