JavaScript Correlation Actions

The action defined using JavaScript can be executed when the correlation rule fires. The script can be executed either as a standalone action or with an incident creation action.

Using JavaScript, you can access Sentinel system methods to execute actions such as:

To create a JavaScript Correlation Rule:

  1. Create a JavaScript file with .js extension.

  2. Place the .js file in the default working directory on the machine where Correlation Engine is running. The default working directory for the script is $ESEC_HOME/config/exec or %ESEC_HOME\config\exec.

NOTE: The working directory for the script can be changed by specifying exec.location = c:\\ in execution.properties file located in $ESEC_HOME/config or %ESEC_HOME%\config. Restart the correlation engine services to activate the changes made to execution.properties file.

Changing the working directory for Execute Script (JavaScript) correlation actions also changes the working directory for Execute Command correlation actions and right-click menu actions.

  1. In the Sentinel Control Center, create a Correlation Action to execute a JavaScript file. For more information on creating an action, see "Correlation Action Administration".

For example:

Action Name: JavaScriptAction

Action: Execute Script

Script Name: action.js

image\ebx_497722478.gif

  1. Create a Correlation Rule. For more information on creating a Correlation Rule, see "Creating a Correlation Rule".

  2. Deploy Correlation Rule and associate the new Correlation Action to the Correlation Rule. For more information on deploying correlation rule, see "Deploying/Undeploying Correlation Rules".

image\ebx_985866891.gif

Sample JavaScript Correlation Actions

The code sample below starts or stops a Collector based on information in the correlated event.

importPackage(java.lang);
var CollectorName = "TC_5";
var evt = scriptEnv.getCurrentEvent();
var collNm = evt.getPort();
var outfile = new java.io.PrintWriter(new java.io.FileWriter("/opt/jaya/strtcoll.txt", true));
if(collNm && collNm.equals(CollectorName))
{
   var collist = ESM.collectorsForName(collNm);
   if (collist.size() > 0)
   {
      var coll = collist.get(0);
      outfile.println("Stopping " + CollectorName);
      coll.stop();
      Thread.sleep(60000);
      outfile.println("starting " +CollectorName);
      coll.start();
   }
}
else
{
   outfile.println("JSTest collector does not exist");
}
outfile.close();

JavaScript Debugger

You can debug JavaScript files from the Sentinel Control Center with the help of the JavaScript debugger. The JavaScript Debugger is a local debugger that executes scripts with respect to the machine on which the Sentinel Control Center is running. The JavaScript Debugger instantiates a debug session from the correlation engine manager.

A JavaScript Correlation Action can only be debugged after it is associated with a fired Correlation Rule. Therefore, a prerequisite to debugging is to create a correlation rule that is guaranteed to fire, then associate the JavaScript Correlation Action with that rule.

The debugger has the following controls:

image\ebx_2081589318.gif

Run

Run the script until the next breakpoint is encountered.

image\ebx_-1874251219.gif

Step Into

Step into a function, one line at a time.

image\ebx_-1211617871.gif

Pause

Pause the running script.

image\ebx_-1969818135.gif

Stop

Stop the script.

image\ebx_-1342681565.gif

Step Over

Step over a function to the next line in the script.

image\ebx_-690001941.gif

Step Out

Step out of the function to the next line in the script.

To open a JavaScript Debugger:

  1. Click Correlation on the Menu Bar and select Correlation Engine Manager. Alternatively, you can click Correlation Engine Manager button on the Tool Bar.

image\ebx_1466379382.gif

  1. Select a JavaScript Action associated with Correlation Rule. Right click and select Debug. The Debug JavaScript Correlation Action window displays.

image\ebx_-532450537.gif

The screen displays the following message: Retrieved source file, waiting for associated correlation rule to fire….

The correlation rule must fire (and a correlated event or incident must be created) before you can debug the script. After the rule fires, this text panel is replaced by a debug panel and the actual debugging session begins. The following JavaScript Correlation Action window displays.

image\ebx_1014359582.gif

  1. Click Run. The debugger panel displays the source code and positions the cursor on the first line of the script.

image\ebx_1930745919.gif

You can debug the script as many times as needed (without requiring a new correlation rule to fire). After the debugger gets to the end of the script (or after you click the Stop button), click Run again.

  1. To debug the script using a different rule, different correlated event, or different incident, close the debugger window and repeat the debugging process.