From Developer Community
Developing Sentinel Action Plug-ins
Overview
Sentinel Action plug-ins are invoked when a correlation rule fires or when a right-click Menu Tool is invoked. In general correlated and raw events, plus associated incidents, should be considered the "input" to Actions; the Action will take this information and then perform some sort of analysis, delivery, or remediation activity.
One important concept to note: there are several shades of "actions" in the Sentinel interface, which can get a bit confusing:
- Tasks that are linked to correlation rule firings or right-click Menu Tools are in general called actions
- There are some "internal" or "native" actions, like "Add to Dynamic List", that fall into this category
- You may also associate a JavaScript-based Action instance, based on a configured Action plug-in, as one of these correlation-triggered actions.
- Action plug-ins include the code and supporting meta-information to perform a given activity, but are not called directly
- Before a plug-in can be used, it must be configured as an Action instance which includes setting all appropriate parameters (this is akin to deploying a Collector into the ESM interface)
- Once an Action plug-in is configured as an Action instance, it will be available for selection as an action triggered by a correlation rule
To sum up, Action plug-ins are imported into Sentinel, but then you must configure them into a live Action instance with configured parameters. Only then can you attach it to a correlation rule or Menu Tool.
A word about Integrators:
- Integrators serve a similar function as Connectors in that they provide a simplified protocol-layer interface to the Actions
- A simple API is exposed by each Integrator to an associated Action so that the Action can concentrate on data processing and not on protocol communications and failure modes
- Just like with Actions, each Integrator plug-in must be deployed with a given configuration before it can be used
- Many Actions use Integrators by using a configurable parameter to select which Integrator to use; other Actions dynamically search for and select an Integrator
The Action framework is relatively new, but with this functionality now Sentinel has the ability to dynamically and automatically react to detected issues in the environment and perform remediation activities.
Getting Started
This section assumes that you have already completed the setup steps detailed in SDK Pre-Requisites and SDK Installation and Configuration.
To begin creating a Sentinel Action plug-in:
- Expand the "Actions" entry under the Ant tab (Window > Show View > Ant if not available) (you should hide internal targets by selecting the target/slash icon in the toolbar)
- Double-click on the "new" entry under "Actions", and follow the prompts
- Give the Action a descriptive name, such as "Block IP at Firewall"
- In the Package Explorer tab, select the "actions" project and hit F5 to refresh the listing
- You should see your new Action development directory appear in the list under "actions" with the name that you selected
This procedure will clone the Action template to create a new skeleton Action in a development directory. You will edit the files in this new Action plug-in to add code, meta-information, documentation, and other key features.
Building the Plug-in
In order to build your plug-in from the development directory into a functional plug-in (the default template will work as a fully-functional plug-in), perform the following steps:
- Expand the "actions" project in the Package Explorer tab
- Expand the directory that contains your Action development directory
- Expand the "6.1" directory to reveal the development files
- Drag the "build.xml" file in that directory over to the Ant tab
- You should see a new Ant project with the name of your Action
- Expand your Action under the Ant tab
- Double-click on the "build" target and follow the prompts
- Select "n" when asked to increment the release number
- The resulting built plug-in and associated files will be created under the directory
/proj/content/build/<plug-in name>.
- The plug-in will be named <plug-in name>_<template version>r<release version>.acz
- This initial build is just to test that things are working; as you develop your plug-in you can rebuild as many times as you like to debug and test your work
- When development is complete, you can remove the project from the Ant tab to reduce clutter; if you go back to working on the same plug-in, you can re-drop the "build.xml" to the Ant tab
It is expected that you will build your plug-in many times during development; the build process is fully automated. In addition to the ant build command, which does a complete build, you can also use the ant build-zip which only builds the portion of the plug-in based on code (e.g. no documentation etc), for more rapid development cycles.
Development Process
The development process consists of:
- Clone the template to make a new skeleton plug-in (see above)
- Modify the development code (see below) and meta-information files
- Build for test and debug (see above)
- Repeat previous two steps
- Perform a final build and release your plug-in
Exploring the Template
The newly created skeleton Action development directory has the structure displayed at right.
- The top level directory is given the name of the Action, as you specified during the
ant new process.
- If you change this name, the plugin will take on the new name
- But note that the name in the Ant tab will retain the old name unless you edit build.xml
- The archive directory is a place to contain old copies of the plug-in, for reference
- The research directory is a place to contain research, design, and integration documentation
- The sample directory is a place to put sample input or output files
- The 6.1 directory is the actual development directory where the plug-in resides
- The "6.1" refers to the version of the template in use
- Under 6.1
- The docs directory contains the embedded plug-in documentation template (see below)
- The parameters directory contains the plug-in parameters (see below)
- The build.xml file contains the build instructions for this specific plug-in
- Drag the build.xml file over to the Ant tab to run the build
- If you change the name of the plug-in, also edit this file and change the project name on the first line
- The plugin.properties file contains meta-information about the plug-in, such as a description (see below)
- The release.properties file contains the current release number of the plug-in
- This is incremented if you select "y" to the corresponding question during the build
- In general we recommend you increment this for any publicly-released plug-ins.
- The actiontarget.js file contains the actual code that is run when the plug-in is executed.
- The overall control structure of the plug-in is defined elsewhere in the template; you just need to build the methods defined in this file
- You can create additional *.js files as necessary to create new classes or methods
JavaScript Files
The Action execution structure is not actually defined in the *.js file in the development directory. Instead it is defined in a template which calls out to the methods that you will define in that file. The two are combined during the build process that creates the actual plug-in.
The overall flow of Action execution looks like this:
The steps in light green are the methods that you will create; the rest of the template will handle the control flow necessary to make the Action work correctly.
- Detailed walkthrough: Implementing the Action methods defined in the template
JavaScript Notes
When building your code, there are several things to remember:
- The JavaScript interpreter is based on Rhino
- You can use all of the standard JS objects including E4X
- Many Sentinel-specific objects are defined, like Identities and Accounts, that you can access and use in your code
- Some sample code is provided to, for example, access and use Integrators
- [Advanced] You can call Java methods by importing the appropriate JDK classes
- [Advanced] You can also define your own Java objects and methods in your own JAR files, and include them in the Action plug-in
Meta-information Files
The template also includes several files that contain meta-information used to help define properties of the plug-in.
plugin.properties
The plugin.properties file contains some meta-information about the Action. One of the first and last things you should do is review this file and make any necessary adjustments:
- uuid: the unique ID for this Action (autogenerated, DO NOT EDIT)
- entitlement: Not used
- plugindesk: description of the Action; edit this to describe what the Action does
- integrators: list integrators that can be used by this Action plug-in
release.properties
The release.properties file contains the current release version number for the plug-in. It is automatically maintained by the build process; you are prompted to increment the release number if you wish:
- Novell recommends that you increment the release number when you begin work on a new version that will be release to production or the public. In other words, if the current production version is "5", select "y" to the "increment release number?" question when you begin working on the next release and build it for the first time.
- The only circumstance in which you should manually edit this file is if you accidentally increment the release number.
- The release number appears in the filename of the built plug-in: "Novell_Identity-Manager_6.1r1.clz"
(follow heading link)
(follow heading link)
