Action Development Guide

GETTING STARTED

This section (and all following ones) assumes that you have already completed the setup steps detailed in SDK Installation and Configuration.

Creating a New Action

Naturally the first step in developing an Action is to create a new Action, based on the template, that you can start editing. Here's the procedure to do so:

Start Eclipse and make sure the Sentinel perspective is selected (Window > Open Perspective > Sentinel).
In the Sentinel SDK pane at left, right click on the actions entry and select New Action Plug-in.
Fill in a name for your new Action (avoid '-' and '_').
Select an option for what Input Objects the Action will process, based on what you expect the Action to do. This will determine where the Action is presented in the user interface.
Also specify whether the Action will process one or multiple events, then select Finish. The SDK will create a new development area for your Solution Pack and populate it with the relevant files.
After the process completes, if you expand the actions section in the Sentinel SDK pane you should see your new Action. If you expand the name you specified, you will see a numbered directory (e.g. 2011.1) that holds the actual source for the Action.

This procedure will clone the Action template to create a new Action in a development directory. You will edit this new Action plug-in to add code, meta-information, documentation, and other key features.

Building Your New Action

One of the nice things about the default Action template, the one that was cloned to create your new Action plug-in, is that it is already a fully-functioning plug-in that you can build and deploy into Sentinel. This new Action won't actually do much since no code has yet been written, but it should be enough for you to test deployment and maybe even debugging. You might find it convenient to create a build now, before you start adding content, to familiarize yourself with the deployment process.

Before running a build, however, note that there are two types of builds:

Development build: This assembles the Action into a running state, but does not do things like build the documentation. It is intended to produce something you can quickly use for debugging and functional testing.
Production build: This does a complete build including documentation and so forth.

Obviously you should choose the build best suited for your current purpose, which at this stage is likely the development build.

Running either type of build is really easy:

Start Eclipse and make sure you are in the Sentinel perspective.
Expand the actions section in the Sentinel SDK pane at left, then expand the directory for your Action.
Right-click on the 2011.1 node for your Action and select Create Development Build.

The above process will run a build on the current files that make up your new Action, which are stored under that 2011.1 node in the tree. The resulting build output will be stored, by default, in the same tree under which you unpacked the SDK, e.g. /plugin-sdk/content/build/Action/<your name>.

Deploy the Action

Once you have created a build of your Action, go ahead and deploy it into Sentinel:

Log in to Sentinel's Web UI as a user with rights to manage Actions.
Select the Applications link in the upper-right header area.
Launch the Control Center application and, when prompted, log in as the same user as before.
Select the Configuration > Action Manager menu item. Action Manager will start.
Select the Manage Plug-ins button in the top menubar, then the green "plus" button.
Browse to and select your new Action plug-in, then select Next then Finish.
After the Action is imported, close the Action Plug-in Manager and return to Action Manager.
Select the green "plus" Add button to create a new Action instance.
Select your new Action from the drop-down list, give the Action instance a name, and configure its parameters.
Select Save to save the instance.

At this point the Action instance (which uses your new Action plug-in) will appear in a couple places in the UI, although specifically where it will appear will depend on what you selected for its Input Objects. If you wish you can also configure a menu entry using the Control Center's Configuration > Event Actions Configuration tool which will let your Action be executed via either the Event Actions accordion (web UI) or the right-click context menu (ActiveView) on a set of selected events.

Debugging an Action

Since Actions often happen in the background, triggered by automatically-detected activity and the like, we have to set up a controlled environment in which we can predictably cause an Action to be executed and know what events will be passed to it. To do this, we leverage Sentinel's Incident framework and the Execute Incident Action tool. Note however that this does not mean that your Action has to know anything about incidents; in this case we're just using the incidents as a container to hold a predefined set of events or other objects to be processed by your Action.

This boils down to the following cases:

If your Action intends to process incidents, then all you need to do is set up a realistic scenario that will create the type of incident that you expect, and work from that.
If your Action is intended to be attached to a correlation rule and will process the resulting correlated event, then you need to set up a temporary test framework:
1. In Sentinel Control Center, go to Configuration > Action Manager and create a new Action instance. Select Create Incident as the Action to take, and set the properties as appropriate.
2. Configure a correlation rule that will detect the events of interest, and attach the new Create Incident Action instance to that rule.
3. When the rule fires, this will result in a new incident with the correlated event attached to it. You can then debug your Action and it will get the correlated event from the Incident.
If your Action will be processing trigger events that are associated with correlation rule output, then follow the same instructions as above, then:
1. When your incident is created with the correlated event attached to it, open the incident in Control Center's Incidents tab
2. Select the Events tab in the incident to view the correlated event.
3. Right-click on the correlated event and select View Trigger Events. This will open a new Search window.
4. Select the trigger event(s) in the web UI, then select Add to incident from the Event Operations dropdown.
5. Find your incident in the list and add the trigger events to it.
6. The incident will now have the trigger events attached to it so that they can be processed by the Action.
If your Action is intended to just process regular raw events, then select a set of events in a search representative of those that will be processed, then select Create Incident from the Event Operations dropdown. The resulting incident will have the events attached to it so you can test against them.

Some details about debugging are noted in the platform documentation, but in essence you will go into the Control Center, open up your incident, turn on the debugger, then select Execute Incident Action for the incident. The debugger will pop up, and you will see your new Action ready for debugging. At this point the structure of the code might not make much sense; we'll cover that in the following sections.

Forward to Plug-in Contents
Back up to Develop to Sentinel