[-]
  
[-]
  
  
  
  
  
  
  
 
 
[-]
  
  
  
  
[-]
  
 [+]
  
[-]
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 Linux CounterMeasure actions
Direct link to topic in this publication:

You can create custom CounterMeasure actions for Linux using JSON or Python. In most cases, CounterMeasure created using JSON will be sufficient. For more advanced or complex use cases, you have the option to use Python.

Here are some basic CounterMeasure actions that you can create using JSON:

  • Information gathering commands (top, netstat, reading a log file, etc.)
  • Restarting a service or server
  • Deleting files

For advanced use cases such as the following, use Python: 

  • Authentication
  • Interacting with APIs
  • Managing state over multiple steps

See the following sections for more information on how to create custom CounterMeasure actions:

Create CounterMeasure actions using JSON

To create custom Linux CounterMeasures using JSON, create a new JSON file in the /usr/lib/panopta-agent/countermeasures/plugins directory. The command provided in the `command` key-value will be executed when the CounterMeasure is triggered. The command's output (if any) will be returned and available in the Panopta Control Panel. The following example shows a JSON CounterMeasure that returns the output of a netstat command.

JSON
{
"name": "netstat",
"textkey": "info.netstat",
"description": "Gather most recent netstat output",
"max_frequency": 60,
"max_runtime": null,
"author": "support@panopta.com",
"wall_announce_delay": null,
"command": "netstat -ant"
}

For more details, see Implementation Reference. Keep in mind that the command will be run as the panopta-agent user. Any elevated privileges will need to be configured as described in the sudo privileges section.

Create CounterMeasure actions using Python

To create your own CounterMeasure, create a new python file in the /usr/lib/panopta-agent/countermeasures/plugins directory and ensure your implementation subclasses the CountermeasurePlugin class. A full reference is at the bottom of this page. Largely, implementing the run() method and providing a few instance variables is all that is required. You can see a basic example below.

Information
The name of your custom class needs to end with Countermeasure.

Once you're done, make sure you rebuild your agent metadata with the following command: 

Python
python /usr/bin/panopta-agent/panopta_agent.py --rebuild-metadata

Your CounterMeasure will then be available in the Panopta control panel.


  

Logging

If you need to log information in your CounterMeasure plugin, you can use self.log.info("your message here"), which will log to /var/log/panopta-agent/countermeasure.log

Leverage 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 JSON object is available to you in your code via the metadata property. For example, the below code returns the incident metadata right back to Panopta.

CounterMeasure Action metadata example

Python
from CountermeasurePlugin import CountermeasurePlugin

class TestMetaCountermeasure(CountermeasurePlugin):

name = "Test Metadata"
author = "Panopta User"
textkey = "test.metadata"
description = "Returns passed metadata"

def run(self):
output = str(self.metadata)
self.save_text_output(output)
self.save_return_code(0)

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 schema is included below.

Python
{

"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

}

Limit plugin execution time

You may optionally set the maximum time a CounterMeasure plugin may run using the max_runtime property. You may supply any number of seconds, represented as an integer. If it exceeds the allotted time, the CounterMeasure driver will attempt to kill it, though it is not guaranteed

View plugins on an instance

To view all the plugins available to use on an instance, use the following command:

Python
python /usr/bin/panopta-agent/countermeasure.py list_plugins

If you're not seeing an expected plugin, ensure that it is in /usr/lib/panopta-agent/countermeasures/plugins.

sudo privileges

CounterMeasure plugins are executed by the panopta-agent user, which is created at the time of agent installation. The panopta-agent user itself does not have elevated privileges and does not require them to perform it's normal tasks. There may be times, however, when creating custom CounterMeasure plugins that you need the panopta-agent user to have elevated privileges - this requires passwordless access to be configured for the panopta-agent user (an example is below). As well, one out-of-the-box CounterMeasure plugin requires elevated permissions - reboot. If you attempt to run this CounterMeasure before you've configured permissions, it will fail.

Verifying sudo privileges

The agent ships with a CLI helper method to allows you to validate sudo privileges for your CounterMeasure plugins. It will help you identify plugins that the panopta-agent user does not have the proper privileges to run.

First, we need to enable switching to the panopta-agent user.

  • Open /etc/passwd. At the end of the panopta-agent line, remove /usr/sbin/nologin and replace it with /bin/bash
  • Save the file.

Now we can switch to the panopta-agent user:

Python
su panopta-agent

Then, we can run the following command, which will highlight the plugins that require sudo privileges and whether or not those privileges are configured correctly.
Python
python /usr/bin/panopta-agent/countermeasure.py validate_sudo

If you've properly configured sudoers, you'll see an output like below. Otherwise, you'll see Missing Permissions.
Python
Verifying sudo requirements for reboot
reboot:shutdown Pass

Implementation reference

Instance Variable
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
wall_announce_delay
Int
How long to pause execution of the countermeasure after announcing it as a wall message. Set to None to disable wall announcements for this countermeasure
No
max_frequency
Int
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
max_runtime
Int
The longest amount of time that the plugin should be allowed to run. The Countermeasures driver will attempt to kill the execution when it exceeds this time, although due to the condition that may not be guaranteed
No
sudo_requirements
[Command Lines]
List of full command lines this plugin requires sudo access for, which is used for validating sudo configurations
No

Method
Parameters
Description
Required
run
none
Execute the countermeasure action
Yes
validate
none
Method to perform validation on the plugin's setup. This is called by the command-line tool's "validate-plugins" command. Mainly used by helper subclasses that intend to have some additional properties overridden. Should return nothing if the plugin is valid, or a string describing validation issues if there are problems.
No
prepare
none
Method to be run before execution, for any initial setup or validation that the countermeasure action needs to perform
No
save_text_output
output (String)
Save countermeasure output as plain text for later publishing up to the Panopta cloud
No
save_html_output
output (String)
Save countermeasure output as formatted HTML for later publishing up to the Panopta cloud
No
save_return_code
return_code
Save the return code from the countermeasure execution
No