12. Network & Policy » Response¶
Responses provide a powerful way to automate and extend the system’s reaction to the anomalies detected by Sensor, and to the filtering rules identified by Filter. Different Responses can be configured for each IP, subnet, traffic threshold, or anomaly type.
To add a new Response, go to Configuration » Network & Policy » [+] and click [Response].
The top bar permits renaming and deleting the Response, as well as showing a list with the IP classes configured to use it.
12.1. Response Actions¶
When invoked by a Sensor or Filter, the Response runs the actions it contains. These are built-in modules that provide the means to execute commands, send notifications, send BGP routing updates, write logs, etc.
There are two types of actions:
Anomaly Actions are executed by Sensor for each traffic anomaly. To execute such an action immediately upon the detection of an anomaly or while an anomaly is being detected, add it to the When an anomaly is detected… panel. To execute an action when the anomaly expires, add it to the When an anomaly expires… panel
Filtering Rule Actions are executed for each filtering rule identified by Filter. To execute such action immediately upon the identification of a filtering rule or while a filtering rule is being identified, add it to the When a filtering rule is detected.. panel. To execute an action when the filtering rule expires, add it to the When a filtering rule expires… panel
To add an action, click the [+] button from the title bar of the relevant panel from the left-hand side of the window. To view, edit, delete or rename an action, select the action’s name. To enable or disable an action, click the small on/off switch button displayed next to it.
Each action configuration panel contains some action-specific fields. The following fields are present in all actions:
● Action Name – Short description of the action● Action Priority – Select the order of execution relative to the other actions defined within the same panel. Lower numerical values correspond to increased priority● Periodicity – Actions can be executed once per anomaly/filtering rule, or periodically. The frequency of execution is 5 seconds for Packet Sensor, Packet Filter, Sensor Cluster, and Filter Cluster, or 5-60 seconds for Flow Sensor, depending upon its Granularity parameter● Execution – Actions can be executed automatically without end-user intervention or manually by an Operator or Administrator that clicks the lightning icon from Reports » Tools » Anomalies● Preconditions Policy – When the first option is selected, the action is executed only when all preconditions (defined below) are evaluated as true. When the second option is selected, the action is executed if at least one precondition is evaluated as true. The action is executed without restrictions when the list of preconditions is empty● Record Action – When checked, the name of the action is recorded and displayed in anomaly reports● Preconditions – May contain rules that, when evaluated as false, will deny the action’s execution. Each precondition is composed of a conditional parameter, a comparison function, and a user-defined value. Conditional parameters are linked to internal variables whose values are constantly updated by Sensors and Filters. Appendix 4 - Conditional Parameters & Dynamic Parameters lists and describes each conditional parameter
Dynamic parameters are variables defined within curly brackets “{ and }”, used as parameters or script arguments for most Response actions. Almost every conditional parameter has a corresponding dynamic parameter. All dynamic parameters are listed in Appendix 4 - Conditional Parameters & Dynamic Parameters.
12.2. Extending the Built-in Preconditions and Actions¶
If you need to improve the logic in which actions are allowed to run, add the precondition named Custom Script Return Value. With it, you can implement your own custom precondition, or you can mix logical disjunction and logical conjunction in any way you wish. Just set the Comparison field to “equal to”, and in the Value field enter the path to a custom script that accepts dynamic parameters (full list on Appendix 4 - Conditional Parameters & Dynamic Parameters) as arguments.
If you want to extend the number of actions, add the Response action named Execute a command or script with dynamic parameters as arguments. You can pass useful information collected from Wanguard as arguments to your script. Make sure that the script can be run as the “andrisoft” user, and that your script does not require any input from the terminal during execution. You can check if the permissions of the “andrisoft” user are sufficient by executing the script from the CLI with the “sudo -u andrisoft /path/to/your/script.sh” command. It is recommended to output the script’s output to a temporary file, in order to catch any errors, by appending ” > /tmp/script_output.txt 2>&1” to the command. That way you can verify the script’s output in /tmp/script_output.txt.
To access data not related to the current anomaly or filtering rule, or to automate the actions available on Reports » Tools, call the REST API from within your script.
As an example, the script shown below will write the anomaly number ({anomaly} as 1st argument), attacked IP ({ip} as 2nd argument), detecting Sensor ({sensor} as 3rd argument), and current kbps/s value ({latest_anomaly_bps_kilo} as 4th argument) to a temporary file when the decoder that detected the anomaly is either NTP or SNMP.
#!/bin/sh
DECODER=$1
if [ "$DECODER" = "NTP" ] || [ "$DECODER" = "SNMP" ];
then
exit 0;
else
exit 1;
fi
#!/bin/sh
echo "Anomaly: $1, IP: $2, Sensor: $3, Kbits/s: $4" > /tmp/test.txt
Note
When writing a script, make sure that it can be accessed and executed by the system account named “andrisoft”. You can check if there are permission-related issues by executing the script manually with “sudo -u andrisoft /path/to/script”. Dynamic parameters should be passed within single or double-quotes.
12.3. Using the REST API¶
The REST API’s calls are fully documented at www.andrisoft.com/wanguard-api-ui. To be able to use the REST API, make sure that you have the package wanrestapi installed on your Console. Then go to General Settings » User Management and enable REST API Access for one of your users. Open http://<console_ip>/wanguard-api-ui and authenticate with the user’s credentials by clicking the [Authorize] button from the top-right part of the web page.
The API calls are ordered in a way that resembles the navigation structure of Wanguard Console. If you click on any resource, you will see what parameters it accepts, you can test the call to see the results, and you can also copy/paste the exact command needed to call the method from any scripting language or from the CLI. Each REST API call uses one of the following HTTP methods:
#!/bin/sh
curl -X GET --header 'Accept: application/json' --header 'Authorization: Basic XXXXXXX==' 'https://console/wanguard-api/v1/anomalies?status=Active'
#!/usr/bin/php
<?php
error_reporting(E_ALL);
$wgUser = 'api_user';
$wgPass = 'api_pass';
$wgUrl = 'https://wanguard_console/wanguard-api/v1/bgp_announcements_actions';
$payload = json_encode([ 'batch_action' => "Clear" ]);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $wgUrl);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_ANY);
curl_setopt($ch, CURLOPT_USERPWD, "$wgUser:$wgPass");
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type:application/json']);
$result = curl_exec($ch);
if (curl_errno($ch)) {
echo sprintf("Error: %s\n", curl_error($ch));
} else {
echo $result;
}
curl_close($ch);
?>