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.

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.

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.

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.

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

param([hashtable]$metadata)

$returndata = @{}

$output = @{}

$output_list = New-ObjectSystem.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

Key

Description

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