Blog

Event Retrieval API in Halo

If you’re using Halo’s alerting capabilities to monitor your servers (with File Integrity Monitoring, Configuration Scanning, or Special Events), you may want to pull your Halo event logs into another program, like Splunk, Sumo Logic, or even a SIEM, that will search, monitor and analyze your data.


Halo has a security API to enable you to make API calls to retrieve event data for all of the alerts you’ve set up in Halo as well as logs of Halo Portal usage.  Let’s say, for example, you’d like to pull the security event data from Halo.  First, you (or a site admin) would log into the Halo portal and go to Settings > Site Administration > API Keys.

Generate an API key to use for retrieving security events (you can use a read-only API key if you like; a full-access key is not required for this function) and save it – now you can use that key to integrate with whatever program you are using to parse Halo server events!

All events have the following attributes, plus more specific attributes depending on the type of event.  You can read more about the other types of events in our API docs.

As you are building your API integration, keep in mind that we use the authentication process recommended in OAuth’s documentation, which we have outlined in this blog post.

Once an application has authenticated, it can request a list of events using an HTTP GET request.  Here is a call to the event API using the cURL HTTP client program:

curl -X GET -H "Authorization: Bearer 9dcf45c67594c09009fd5a9c63b69c3d" https://portal.cloudpassage.com/v1/events

The request can include a timestamp indicating that it would like a list of all events between timestamp x and timestamp y (using the parameters “since” and “until”).  If no timestamps are included in the call, it will be assumed the application is requesting all events.

This call retrieves events filtered by timestamp:

curl -X GET -H "Authorization: Bearer 9dcf45c67594c09009fd5a9c63b69c3d" ''https://portal.cloudpassage.com/v1/events?per_page=30&since=2012-10-22&until=2012-10-23'

Note: The timestamp in the queries are specified in an ISO-8601 format.

Requests that return multiple results are paginated by default. The default page size is 10 items.

You can also specify custom page size up to 100 items with the per_page parameter. For example:

curl -X GET -H "Authorization: Bearer 0fd56cecbfa1f002a631ca8529355342" 'https://portal.cloudpassage.com/v1/events?page=4&per_page=30&since=2012-10-22&until=2012-10-23'

Note: Reading JSON outputs can be very difficult without the use of a JSON formatting program. There are many available but the one I use is a Python program called json.tool. To make the JSON output more readable, I simply pipe the response to an API call to json.tool like this:

curl -X GET -H "Authorization: Bearer 9dcf45c67594c09009fd5a9c63b69c3d" https://portal.cloudpassage.com/v1/events | python -m json.tool

You can find more assistance on how to use our new Security Event Retrieval API in our API Documentation or by asking questions / browsing in our support forums.  Have fun out there!

Related Posts