Adding Custom Actions
Attach scripts to custom rules to do specific actions in response to network events. Use the Custom Action window to manage custom action scripts.
Use custom actions to select or define the value that is passed to the script and the resulting action.
The following examples are custom actions that are the outcomes of passing values to a script:
Block users and domains.
Initiate work flows and updates in external systems.
Update TAXI servers with a STIX representation of a threat.
Custom actions work best with low volume custom rule events and with custom rules that have a low response limiter value.
On the navigation menu (
), click Admin.In the Custom Action section,, click Define Custom Action.
To upload scripts, click Add. Programming language versions that the product supports are listed in the Interpreter list.
For the security of your deployment, JSA does not support the full range of scripting functionality that is provided by the Python, Perl, or Bash languages.
Specify the parameters to pass to the script that you uploaded.
Table 1: Custom Action Parameters Parameter
Description
Fixed property
Values that are passed to the custom action script.
These properties are not based on the events or flow themselves, but cover other defined values that you can use the script to act on.
For example, pass the fixed properties username and password for a third-party system to a script to send an SMS alert.
Encrypt fixed properties by selecting the Encrypt value check box.
Network event property
Dynamic Ariel properties that are generated by events. Select from the Property list.
For example, the network event property sourceip provides a parameter that matches the source IP address of the triggered event.
For more information about Ariel properties, see the Juniper Secure Analytics Ariel Query Language Guide.
Parameters are passed into your script in the order in which you added them in the Define Custom Action dialog box.
When custom action scripts are run, a chroot jail is set up in the /opt/qradar/bin/ca_jail/ directory. Any content in the /opt/qradar/bin/ca_jail/ directory can be modified and written to by scripts. The custom action user's home directory (/home/customactionuser) can be modified.
A script can run only from inside the jail environment so that it does not interfere with the JSA run environment.
All file access during custom action execution is relative to the /opt/qradar/bin/ca_jail/ directory.
The custom action user account might not have permission to run follow-up commands, such as logging into a firewall and blocking an IP address. Test whether your script runs successfully before you associate it with a rule.
The type of custom action that you implement depends on your network infrastructure and its components. For example, you can configure REST APIs on Cisco devices to block suspect IP addresses. Other third-party vendors might not provide a REST interface, so you might need to develop your own web services solution to run custom actions.
You must run the dos2unix utility on scripts that originate from a Windows or DOS system. Windows or DOS systems typically add control characters. To successfully test custom action scripts by using the script Test Execution function in JSA, you must remove the control characters.
Testing Your Custom Action
Test whether your script runs successfully and has the intended result before you associate it with a rule.
Custom action scripts run inside a testing environment on your JSA managed hosts that is isolated from your production environment. Custom action scripts typically run on the managed host that runs the event processor. However, if you have an All-In-One appliance, custom actions run on the JSA console.
Test Execution is supported only on the JSA console and is not supported on managed hosts.
If you must write to disk from a custom action script, you must use the following directory: /home/customactionuser.
On the navigation menu (
), click Admin.In the Custom actions section, click Define Actions.
Select a custom action from the list and click Test Execution >Execute to test your script. The result of the test and any output that is produced by the script is returned.
After you configure and test your custom action, use the Rule Wizard to create a new event rule and associate the custom action with it.
For more information about event rules, see the Juniper Secure Analytics Users Guide.
Passing Parameters to a Custom Action Script
Sample scripts in Bash, Python, and Perl show how to pass parameters to custom action scripts.
The following simple sample scripts show how to query the asset model API for an asset with the supplied offense source IP address. For the sake of this example, the scripts output the JSON that is returned by the endpoint.
The scripts require three parameters:
Console IP address
API token
Offense source IP address
These parameters are configured in the Define Custom Action window Script Parameters area:
Each parameter is passed to the script in the order in which it was added in the Define Custom Action window. In this case:
console_ip
api_token
offense_source_ip
The variables that are defined at the beginning of each of the sample scripts use the sample parameter names that were added in the Define Custom Action window.
#!/bin/bash console_ip=$1 api_token=$2 offense_source_ip=$3 auth_header="SEC:$api_token" output=$(curl -k -H $auth_header https://$console_ip/console/restapi/api/ asset_model/assets?filter=interfaces%20contains%20%20ip_addresses %20contains%20%20value%20%3D%20%22$offense_source_ip%22) # Basic print out of the output of the command echo $output
#!/usr/bin/python
import sys
import requests
console_ip = sys.argv[1]
api_token = sys.argv[2]
offense_source_ip = sys.argv[3]
auth_header = {’SEC’ : api_token }
endpoint = "https://{0}/console/restapi/api/asset_model/
assets?filter=interfaces%20contains%20%20ip_addresses
%20contains%20%20value%20%3D%20%22{1}%22"
.format(console_ip, offense_source_ip)
response = requests.get(endpoint, headers=auth_header, verify=False)
# Basic print out of the output of the command
print(response.json())#!/usr/bin/perl
use strict;
use warnings;
use LWP::UserAgent;
my $console_ip = $ARGV[0];
my $api_token = $ARGV[1];
my $offense_source_ip = $ARGV[2];
my $endpoint = "https://$console_ip/console/restapi/api/asset_model/
assets?filter=interfaces%20contains%20%20ip_addresses
%20contains%20%20value%20%3D%20%22$offense_source_ip%22";
my $client = LWP::UserAgent -> new(ssl_opts => { verify_hostname => 0 });
my $response = $client -> get($endpoint, "SEC" => $api_token);
# Basic print out of the output of the command
print $response -> decoded_content;