Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 

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.

  1. On the navigation menu (), click Admin.

  2. In the Custom Action section,, click Define Custom Action.

  3. 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.

  4. 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.

Note

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.

  1. On the navigation menu (), click Admin.
  2. In the Custom actions section, click Define Actions.
  3. 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.
  4. 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:

Figure 1: Custom Action Script Parameters
Custom Action Script Parameters

Each parameter is passed to the script in the order in which it was added in the Define Custom Action window. In this case:

  1. console_ip

  2. api_token

  3. 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.

Figure 2: Call_asset_model.sh
Figure 3: Call_asset_model.py
Figure 4: Call_asset_model.pl