Pulling activity and event data

Introduction

Obtaining event detail from your IBM Security Verify tenant is as simple as two API calls which allows your SIEM, Business Intelligence (BI), and analytics tools to consume all audit events from the platform.

The IBM Security Verify event API allows for:

  1. Page sizing
  2. Filtering on event types (e.g. management, authentication, sso, etc)
  3. Resource filtering (e.g. user, token, app_consent)
  4. Timespan filtering (i.e. searching after a time, or between times)

❗️

Handling lots of events

The events API will max out at 10,000 events in the response. The API provides a simple way to allow you to make subsequent calls with ease. It includes a search_after object which includes a time and id which represents the last event in the current call, which allows you to make a second call that will not overlap events.

Gathering information

The API client used by the application must have the following permissions in IBM Security Verify:

  • Manage reports
  • Read reports

The application must have acquired an Access Token using the Client Credentials flow

Variables

The following variables are needed for this guide:

VariableExample ValueDescription
tenant_urltenant.verify.ibm.comThe URL of your IBM Security Verify tenant.
access_tokeneWn4Z5xChc3q9B9dqbGgFlsHDh7uhAOnmNeKW5EzThe access token obtained from the token endpoint.

Get all events

The simplest call to make is get all events from the platform without filters. Though in larger environments, you will likely get over 10,000 records which needs to be handled through pagination.

curl -X GET "https://${tenant_url}/v1.0/events" -H "Authorization: Bearer ${access_token}"

Expected response:

{
    "response": {
        "events": {
            "search_after": {
                "total_events": 54,
                "max_size_limit": "false",
                "time": "1559156150862",
                "id": "def9ea72-30ce-4589-800a-7306e306ea2e"
            },
            "events": [
                {
                    "geoip": {
                        "continent_name": "North America",
                        "country_iso_code": "US",
                        "country_name": "United States",
                        "location": {
                            "lon": "-97.822",
                            "lat": "37.751"
                        }
                    },
                    {...},
                    {...},
                    {...}
                }...

To filter on specific events on certain types, we'll use a filter query string.

The query string for this call will include event_type.

Each event type will need to be escaped with \" on each side of the value.

  1. \"management\" corresponds with management events
  2. \"authentication\" corresponds with authentication events into the CI platform.
  3. \"sso\" corresponds with SSO events.
    etc...
curl -X GET "https://${tenant_url}/v1.0/events?event_type=\"sso\"" -H "Authorization: Bearer ${access_token}"
-H 'Authorization: Bearer {token}'

You may string multiple together to multiples event types together, separated by commas. For example: event_type=\"sso\",\"authentication\"

Handling pagination (max records)

If your call response includes total_events that exceed the total events count in the response, or "max_size_limit": "true", you can make a second call with a filter as to not overlap with the first call.

For example, if the first call we made was:

GET https://mytenant.ice.ibmcloud.com/v1.0/events with a response of:

{
    "response": {
        "events": {
            "search_after": {
                "total_events": 19540,
                "max_size_limit": "false",
                "time": "1559156150862",
                "id": "def9ea72-30ce-4589-800a-7306e306ea2e"
            },

We know that:

  1. The response includes 10,000 records, and
  2. We've hit the max size limit, and
  3. The last event in the response has the time of 1559156150862 and id of def9ea72-30ce-4589-800a-7306e306ea2e.

Therefore, our next call will look like:

GET /v1.0/events?after=\"1559156150862\",\"def9ea72-30ce-4589-800a-7306e306ea2e\" which responds with:

{
    "response": {
        "events": {
            "search_after": {
            "total_events": 19450,
            "max_size_limit": "false",
            "time": "1559227423000",
            "id": "f253f26d-bb00-497b-a508-b3ea0e4f6d6f"
        }
      }

When max size limit is false, then we know we do not need to make an additional call. If you are also using page sizing though, and your size is less than 10,000 then it will always say max_size_limit false.


Did this page help you?