Aegis ‘Depot’ Activity – Aegis Activities for Sentinel
Over a year ago now I did a post on integrating Aegis and Sentinel (available here) using Sentinel WebServices and out of the box Aegis Activities. As integration methods go, webservices are great but you do need to be able to manipulate the results so that they are usable using out of box manipulation activities like regex / xpath etc. - depending on the complexity of the output it can be really trivial or pretty hard.
In this Cool Tool I provide a set of activities which makes this a whole lot easier with a set of specific Sentinel Activities with outputs pre-formatted.
Sentinel Login Activity
Step 1 before we can do any requests to Sentinel is to login. The Login Activity will perform this action and output the SAML token if the connection is a success. It also outputs connection status and an error message if any. The Token lifetime will depend on the Sentinel configuration. A good idea would be to re-use the token until it expires even between workitems using global preferences rather than continuously logging in and out, but this will ultimately depend on the workflow design.
The login activity is the only activity which will require a Username and Password, all other activities will use the Token outputted from this login Activity.
Ok now we have logged in we can perform some more tasks.
Sentinel Search Alerts Activity
Searching for Alerts is going to be one of the most common tasks, and this is done pretty much in the same way as via the Sentinel Console. The Activity inputs are broken into the Connection details which you'll notice now has a Token input instead of a username and Password. The Search Parameters are the Search Filter, start time, endtime and maximum results to return.
The Search Filter will be exactly the same as the filters you'll see in the Sentinel Console. So create your filter in Sentinel and just copy it over.
Start Time and End Time are both in the usual Aegis Time Format in UNIX Timestamp format for standardization but you can do conversions as usual with some of the time activities id required. In the example the start time of the search is based off a time calculation using the Calculator activity (some basic maths!) and the endtime corresponds to the start time of my workitem - obviously these times will depend on whatever logic you use in the workflow to choose a search window!
At runtime, the IDs of all matching alert results are returned in an array as in the screenshot below.
Get Sentinel Alert
So now we can get the details of each alert which we have just found using the AlertID (or Alert URL) with the Get Sentinel Alert Activity. The only input apart from connection info is the alertid which makes it pretty simple.
The output of the Activity however is pretty big - 115 individual outputs defining each possible alert field along with a few generic activity outputs - so no parsing complex JSON strings - its all done.
Some of the outputs themselves are arrays, including the history output which contains the history of the alert, comments added, status changes etc. and Related Events which has the event URL of all the Sentinel events which were correlated to generate this alert.
You'll see the Comments field of this alert includes a message "Updated by Aegis workitem ....." and the State Name is set to investigating ... the next activity will show how Aegis can take over the handling of a particular alert by updating its properties.
Update Sentinel Alert
This activity allows us to add comments, change the owner to a different Sentinel User, change the Priority and State of a Sentinel Alert.
The alert input is an alertid or alert URL.
The Update State / Update Priority / Update User are checkbox inputs to allow you to optionally update the corresponding alert field.
State / Priority / User inputs are all single select dropdown lists which allow you select the new values and limit the selection to valid values.
The user input needs to be a valid Sentinel User, the activity will try and find the user and will generate an error if the user is not a valid user. At this time changing the alert Role is not available. If Aegis is used to handle certain alerts having a dedicated Aegis user in Sentinel would be a good idea.
Finally the comment field which I have put a message in to say this alert is currently being handled by Aegis so Security Gurus can ignore it for now.
The output of this activity is a true/false success with an error message if encountered.
Get Sentinel Event
Get Sentinel Event is pretty similar to Get Sentinel Alert, Events have less parameters than alerts so the number of outputs is less (although still close to 100). The input requires an Event URL to identify the event. Event URLs can be obtained from the 'Related Events' output of the Get Alert activity. Sentinel Events cannot be modified by Aegis as is the case in the Sentinel Console, so the primary purpose is to get more information about the alert especially if more than a single event was correlated and generated the Alert.
The last activity in the activity bundle is the Sentinel Logout Activity. After you've done the work unless you want to keep the token available for other workflows you'll need to want to logout. If you do keep the token alive, you will need to add some logic for when an activity tries to use the token but it has already expired - this may also be required if you have long delays between activities for example if Aegis is waiting for an operator to make a decision on a task which exceeds the token lifetime.
This activity is pretty simple - it just takes the standard connection inputs as we've used in the previous activities and ouputs a true/false plus error message if a problem occurred.
When compared with the method of using webservices via the webservice activity, i'm sure you'll see that this is a whole lot easier with no parsing required to get to individual values. Stay tuned for the next exciting installment of this activity bundle where I will extend it for use with Change Guardian which under the hood looks a lot like Sentinel.
Checked on Sentinel versions : 22.214.171.124.1915 and 126.96.36.199.2101
Activity Installation Instructions are here: