Workflow automation with NetIQ Sentinel and NetIQ Aegis

Martin Cotter

By: Martin Cotter

January 17, 2014 11:48 am

Reads: 441

Comments:0

Rating:5.0

Aegis doesn’t need application specific adapters to integrate with applications. No programming or scripting required – you will need some experience with Aegis though! 

Please note this procedure is based on 7.1.1.1 – It may work exactly as is for other versions of Sentinel unless there are changes on the Sentinel side which may require some small changes.

Sentinel provides a REST Webservice – so Aegis can use this as an integration point using an out of the box activity.

First of all, why would you want to integrate Aegis and Sentinel?

  1. Trigger workflows based on events from Sentinel
  2. Trigger workflows based on events correlated from Sentinel and other external systems.
  3. Data mining/Forensic Analysis – Determine if there is relevant event information in Sentinel that relates to a current workflow triggered by another system.

Ok – so let’s provide a simple use case and see how the Integration would work.

  1. NetIQ AppManager generates a ‘Server Down’ alarm and triggers a workflow to remediate the condition.
  2. Find Details on Server – Its location, contact, purpose, Criticality, Hardware/Virtual
  3. Check Sentinel for security alarms generated on that server in previous 60 minutes.
  4. If Virtual attempt to power it back on
  5. If Physical (or Virtual restart Fails) contact the Server Contact with the info collected from Sentinel and AppManager, and the result of the Power-on attempt.
  6. If no response from Contact, start escalation workflow.
  7. Update original alert with resolution details

This Use-Case isn’t Sentinel centric. It communicates with a number of different systems in order to achieve its automation goal – AppManager, Sentinel, a CMDB/Directory/Database/Spreadsheet, Virtualization Software of some type, email/paging software.

You will see from the technique used that we can monitor for Sentinel events and trigger and correlate based on Sentinel events in this way also.

So first of all I will show a possible solution using Aegis Workflow, so you have a general idea of what is to come, and something to refer back to when doing the technical bit! Please note this is a very simplistic implementation, it rather assumes ideal world and only has one error handler for a condition that will definitely happen.

(click to enlarge)

sentinel_1

The basic plan is this:

  1. Validate the Sentinel SAML token. After a successful login, Sentinel issues a SAML token which is used to identify the user until the token expires – We will use this token in subsequent activities interacting with Sentinel. When you first run this workflow, you won’t have a SAML token! So we start with a dummy token. Validate token will either end in success, or raise an exception if the token can’t be validated.
  2. Assuming validation failed, we need to login into Sentinel to get a new token. To do this you first need to base64 encode your username:password into encoded string which is used for the login. The login will return a token which will be wrapped in metadata so it will need to be extacted. We then save the token for use in future runs. The token can be saved in a password variable which can only be decrypted at runtime.
  3. Ok we are logged in! So we need to query for events that match a Sentinel Filter over a timerange. The start time is calculated as 60 minutes before the time of the ‘Server Down’ Alarm. Sentinel expects the date in a specific format so we format both the start time and end time in expected format.
  4. Now Create A Search Job. This creates a search job in Sentinel which does the search and generates a URL where the results can be found. Aegis needs to check the status of the search Job and only continues when the job has completed.
  5. Now get the results from the URL that the job created.
  6. Clean up after yourself – delete the search job!
  7. Do something with the individual events – in this case just create a list containing the important event fields.

That’s what we will do in the following description. It is always important to have a flowchart of the workflow you are going to build so ensure all logic and features are implemented correctly and as efficiently as possible.

So first things first – we will integrate using the Sentinel REST WebService. Aegis has a HTTP request activity called ‘Get Web Page Content’, so out of the box we have our method to communicate with the webservice.

For details on the webservice itself, check out the Sentinel API documentation for more details – this is the link on my 7.1 SP1 system – it may vary dependent on version! This demo just touches on the features available in the REST API for Sentinel!

https://<sentinelserver>:<port>/ SentinelRESTServices/apidoc/en/index.html

For the examples that follow, sigea-se01 is my Sentinel server, and 8443 is my port.

Ok lets follow the same same numbering system again so it links back to the overview:

    1. Validate the SAML token.

We will use the ‘Get Web Page Content’ activity for all the activities which interact with the Sentinel WebService. The activity is configured almost the same for each function. For All (except the login) the Headers will have a single value :

Authorization: X-SAML xxxxxxxxx

Where xxxxxxx is the SAML token. The first time we run this we won’t have a cert but we can use a dummy string instead.

The Request Method is GET

Content Type is text/html

URL is:
https://sigea-se01:8443/SentinelRESTServices/preauthorize?path=/objects/identity&httpMethod=GET

This is what it looks like at run-time:

sentinel_2

If Authorization is a success the Response data will be equal to:

{“Authorized”:”true”}

If Authorization fails, the activity raises an exception which can be caught be error handler. Authorization fails in the same way if the token is expired or invalid.

    2. Assuming Authentication Failed

We need to login to Sentinel.

The login procedure requires the Sentinel login account and returns a SAML token which is used is subsequent webservice calls.

The value username:password for the logging in user must be base64 encoded. This can be done by a powershell script for example, but there is an activity available here which does this directly for you, Base64 encode and decode.

This is how the activity looks at runtime – you can see my user is admin and the password (as it is stored in an Aegis Password attribute in this case) is encrypted so can’t be seen. The output value is the base64 encoded value.

sentinel_3

So now we are ready to do the actual login.

This is how to configure the ‘Get Web Page Content’ activity for login:

sentinel_4

I have used a Work Item Attribute (variable) for the URL … you URL should be something like this:

https://sigea-se01:8443/SentinelAuthServices/auth/tokens

Headers input I have used input builder to combine a variable with the output of the Base encode login activity. In plain text it looks like this:

Authorization: Basic YWRtaW46UzFtcHMwbg==

And that it! At runtime the output will look like this…

sentinel_5

You can see that the response Data output contains the SAML token. You can use the regular expression activity to extract the token from the Response Data output with a regular expression of:

{“Token”:”(.*)”,”TokenDigest”:”.*

And then we have the SAML token – we are now ready to make some requests from Sentinel.

    3. Ok we are logged in!

We will get to this either after a SAML token validation succeeds or we login to to SAML token expiration/doesn’t exist. So our Use Case says we need to collect events from Sentinel for 60 minutes on the affected Computer since the event occurred. Both the initiating time and the computer name will be part of the event so we can assume for this example that we already have those values available via the event attributes. We can use date/time activities to calculate the start time and endtime and format the times in this format : yyyy-MM-ddTHH:hh:mm.000Z (MM = month, mm= minute)

    4. Now Create A Search Job.

To collect events from Sentinel, we need to create an event search job, and then fetch the job results. Again we are using the ‘Get Web Page Content’ activity to interact with the WebServices. A search Job is a feature of Sentinel.

For the Event Search Job, we need to POST data to the webservice. I will show this using content type of application/json … this is just an example!

{   "filter":"sev:4",

   "start":"2013-04-03T21:08:34.940Z",

   "end":"2014-04-03T21:08:34.940Z",

   "pgsize":5,

   "max-results":50000,

   "type":"USER"

}

The filter luckily is pretty simple to generate as it’s the same filter that you would create in Sentinel itself, but there are some caveats!

When I create the filter in Sentinel to get all events from my machine sigea-multi2, this is the filter:

(sev:[0 TO 5]) AND (shn:”sigea\-multi2″)

However this won’t work via the webservice as the quotes and \ are not expected and need to be escaped or omitted. It needs to be:

(sev:[0 TO 5]) AND (shn:sigea-multi2)

Or

(sev:[0 TO 5]) AND (shn:\”sigea\\-multi2\”)

This actually makes our life easier as I don’t have to escape any characters using first option. You’ll also see this filter still works also in Sentinel Console. I will use the filter above for this scenario – returning all events of all severities for the machine.

Pgsize is the number of results to return in each result page. Having a smaller page size makes the data easier to handle, but we may need to access more pages.

Max-results – The total maximum number of results to return.

Type – Leave as USER unless you know a reason to change it.

From Aegis perspective the pgsize and maximum results values should be chosen carefully – to ensure the workflow works efficiently and will depend on various factors so test this. Don’t return 1000s of results unless you have reason to so and a super-efficient way of handling that data!

This is the data I will POST – The items in red are variables. I set my pgsize equal to the maximum number of results so I only get one page of results to simplify this example.

{   "filter":"(sev:[0 TO 5]) AND (shn:sigea-multi2)” ,

   "start":”2013-04-03T21:08:34.940Z”,

   "end":”2014-04-03T21:08:34.940Z”,

   "pgsize":20,

   "max-results":20,

   "type":"USER"

}

The URL for this webservice call is :

https://<sentinelserver>:<port>/SentinelRESTServices/objects/event-search

The Content Type is application/json

Mehod is POST

And your Headers should have a single value the same as when we validated the SAML token

This is the output at runtime:

sentinel_6

We can use the URL in the Response HTTP Headers to get the Search Job results – probably a good idea to put in a pause for a few seconds to allow the search to complete. In any event, after the pause you should check the status of the job and wait for it to complete before continuing – the same call will give details on where the results are. To do this the activity should be configured in almost the same way, except there is no POST data and the Request method is GET. The URL is the URL from the Response Headers Location:yyyy value.

Runtime:

sentinel_7

The response data output from job status activity is full of information, but I am only concerned about two things. The job status and the URL to find my search results at. Both values can be parsed using a regular expression from the result data. If the job complete status is false, go back and delay some more and retry until the job completes (limit the number of retries to avoid endless loop). If true continue. This is the regular expression which will extract the two values:

.*?searching-complete”:(.*?),.*?results”:{“@href”:”(.*?)}.*

The first result is true/false, the second part is the URL with results. Great!

    5. Now get the results from the URL that the job created.

You can go direct to that URL in browser to see the page content data that will be returned back into Aegis. This is a temporary URL only– don’t send the URL to anyone as the URL may already be expired!

So you need to pull the content of this URL into Aegis. The activity is set up exactly like the last webservice call, except the URL is the value from the last regular expression.

The result again is a large amount of data in the response data output, all the events in a single response which isn’t very useful. Again Regex activity can be used to extract all the individual events into elements in an array. The Regex for this is:

.*?{“meta”:{“type”:”event”,(.*?)}}

    6. Clean up after yourself – delete the search job!

At this point we no longer need to the search job that was created earlier. If it is stopped it will be removed automatically after a few minutes, or you can delete (stop and archive) immediately if you want to clean up after you (always best Aegis practice!). We are done now with Sentinel specifics! Check the API document to find out how to do this – it is not required step.

    7. Do something with the individual events – in this case just create a list containing the important event fields.

As we have each event now in an element of an array we can pretty much do anything we like with this data. For this use case all we are going to do is format the relevant attributes of the events as text so they are available for the Server Owner to view. Again we use the Regex activity!

This is a sample event from my system in raw form:

 "@href":"https://sigea-se01:8443/SentinelRESTServices/objects/event/1389282500790/6DDFC2E9-5ABA-1031-B105-0050569778CE"},"shn":"sigea-multi2","dt":"2014-01-09T15:48:20.790Z","estz":"Europe/Dublin","xdasreg":0,"ei":"{\"Logon ID\":\"0x13d04\",\"Channel\":\"Security\",\"Category\":\"Other Account Management Events\",\"Provider Name\":\"Microsoft-Windows-Security-Auditing\"}","et":"2014 January 9 15:49:38 UTC+0000","RefId01":0,"agent":"Microsoft Active Directory and Windows","sev":0,"estzmonth":0,"rv164":"2014-04-10T00:00:00.000Z","spt":"2014-01-09T15:48:20.790Z","CustomerId":1,"rv77":"0","pn":"Microsoft Active Directory and Windows","src":"FB9BF1E0-5AAF-1031-9ADB-005056C00008","rv99":"0","obsassetid":0,"estzmin":48,"estzdiy":9,"estzdiw":5,"estzdim":9,"xdastaxname":"XDAS_AE_QUERY_TRUST","piu":101400,"repip":"10.113.66.189","xdasdetail":0,"evt":"The Password Policy Checking API was called.","xdasprov":0,"vul":0,"st":"N","sn":"sigea-multi2.sigea.moc","rv1":0,"msg":"The Password Policy Checking API was called. Subject: Security ID: S-1-5-21-2436503940-2797641611-2025748366-1263 Account Name: sqldba Account Domain: SIGEA Logon ID: 0x13d04 Additional Information: Caller Workstation: SIGEA-MULTI2 Provided Account Name (unauthenticated): - Status Code: 0x0","rv40":"4793","rv41":"sigea.moc","rn":"sigea-multi2.sigea.moc","xdasclass":1,"sun":"sqldba","rv35":"SIGEA","rv32":"OS","rv39":"default","xdasid":4,"rv25":"6DDFC2E9-5ABA-1031-B104-0050569778CE","xdasoutcomename":"XDAS_OUT_SUCCESS","estzhour":15,"xdasoutcome":0,"repassetid":0,"dhn":"sigea-multi2","port":"Microsoft Active Directory and Windows","det":"2014-01-09T15:49:38.000Z","rv192":"default","rv24":{"@href":"https://sigea-se01:8443/SentinelRESTServices/objects/eventsource/7B77B330-5B47-1031-8C81-005056C00008"},"rv22":{"@href":"https://sigea-se01:8443/SentinelRESTServices/objects/collector/FB9BF1E0-5AAF-1031-9ADB-005056C00008"},"rv172":{"@href":"https://sigea-se01:8443/SentinelRESTServices/objects/search-target/CB53CD9A-6A84-484D-9E8F-58A142270D1B"},"rv23":{"@href":"https://sigea-se01:8443/SentinelRESTServices/objects/connector/ABC28FD0-5AB4-1031-A3EA-005056C00008"},"rv21":{"@href":"https://sigea-se01:8443/SentinelRESTServices/objects/collectormgr/C76D2820-C395-1029-BB86-001321B5C0B3"},"rv122":{"@href":"https://sigea-se01:8443/SentinelRESTServices/objects/collector-plugin/1DB52CEC-597D-1029-8F39-0014223D9DEC"},"rv121":{"@href":"https://sigea-se01:8443/SentinelRESTServices/objects/sentinel-system/61090180-7474-1030-8343-0050569778CE"},"rv171":{"@href":https://sigea-se01:8443/SentinelRESTServices/objects/EventRetentionPolicy/408E7E50-C02E-4325-B7C5-2B9FE4853476

A regex to pull out just the parts I want is this:

.*?shn":"(.*?)".*dt":"(.*?)".*?"Provider Name\\":\\"(.*?)\\".*?sev":(\d).*?pn":"(.*?)".*?"repip":"(.*?)".*?"evt":"(.*?)","xdas.*?"msg":"(.*?)","rv.*?sun":"(.*?").*

At runtime this gives me the values I want.

sentinel_8

Summary – This article shows a method to connect with Sentinel without an adapter. Using adapters if available will always be easier but Aegis provides the tools to deliver solutions without adapters.

VN:F [1.9.22_1171]
Rating: 5.0/5 (1 vote cast)
Workflow automation with NetIQ Sentinel and NetIQ Aegis, 5.0 out of 5 based on 1 rating

Tags:
Categories: Aegis, Sentinel, Technical Solutions

Disclaimer: As with everything else at NetIQ Cool Solutions, this content is definitely not supported by NetIQ, so Customer Support will not be able to help you if it has any adverse effect on your environment.  It just worked for at least one person, and perhaps it will be useful for you too.  Be sure to test in a non-production environment.

Comment