Calling the Audit Logs API

  • 19 January 2024
  • 0 replies
  • 195 views

Userlevel 3
Badge +3

This topic describes calling the Audit Logs API in Pigment. Use this API to help you programmatically monitor user activity, potential security issues, and suspicious behavior within your enterprise. You can use it in conjunction with a Security Information and Event Management (SIEM) or another auditing tool for active monitoring and tracking. 

Before you begin

 

Prerequisite information

  • Workspace Account Type. Only Pigment members with the Account type Security Admin can create the Audit Logs API key you need to perform this task. For more information on API keys in Pigment, see Create an Audit Logs API Key.
  • Bearer header. You must include your Audit Log API key in the bearer header of your API request. This assures secure authentication and authorization when you call the API.

Prerequisite tasks

We recommend that you obtain your Audit Logs API key before you start. For more information on Audit Logs API keys in Pigment, see Create an Audit Logs API Key

You should also read this article that gives an overview of the Audit Logs API: Monitor your Pigment Workspace with Audit Logs API.
 

Call the Audit Logs API

Each API request returns a batch of 1000 events, if you need to access more audit events, then you can use pagination. We explain how to use this parameter and its corresponding values at the end of this topic.  

Audit events retrieved from the API are composed of a JSON with standard fields. We describe these in more detail in the section below The Audit Event.

Events are sorted in descending order, starting from most to least recent event, and they’re sorted by the field ingestionTimestamp . The field eventTimestamp represents the timestamp when the event occurred. The maximum lookback period for each API query is 180 days prior to the date of query.

To ensure that you don’t miss any audit events, we recommend that the time ranges for your queries overlap a little. These are defined with the parameter ingestedSince. In the event that you retrieve duplicated events, you can use the unique field eventId to deduplicate your events. 

Here’s the information you need to call the Audit Logs API in Pigment.

Base URL

https://api/audit/v1/events?ingestedSince

HTTP Verb 

GET

API Parameters

You can use the following parameters for the Audit Logs API. They’re both optional:

Parameter Description
ingestedSince This value is a date format. If you don’t provide a value here, then the default value is 180 days prior to the current date. This is converted from your timezone to a UTC timestamp.
cursor The value for this parameter is provided by the nextEventsCursor in your API response payload. You use this to to return more events in your API request based on a cursor-pagination method. We explain how to use this parameter and its corresponding value at the end of this topic.  

 

Sample Query 

GET https://api/audit/v1/events?ingestedSince=2023-11-27

Sample cURL Query 

curl -X GET 'https://pigment.app/api/audit/v1/events?ingestedSince=2023-11-27' \
-H 'authorization: Bearer XXXX'

Authentication Header

In this example, xxx is your Audit Logs API key. 

Authorization: Bearer xxx

The Audit Event

When the Audit Logs API is called, the requested audit events are returned as a JSON. The type of returned audit events determine the final format of the JSON.

Here’s some important information about the returned audit events: 

  • The API returns a maximum of 1000 audit events per API request.
    You can retrieve more events by using pagination, for more information below. 
  • Events are sorted in descending order, starting from most to least recent event.
    These are sorted by the field: ingestionTimestamp 
  • A timestamp is indicated for the occurring event.
    This is controlled by the field:  eventTimestamp
  • Each event has an earliest possible start date, these are listed below. This is the date when the event was available in the Audit Logs API. 
  • Depending on how you query the API, you may fetch duplicate events. You should use the eventId property to deduplicate the events: this is a unique ID for each event.

Every audit event returned by the Audit Logs API has the following standard fields:

Field  Description Sample Value
eventId The unique identifier assigned to the audit event. 
a1234567-a123-000a-1234-1234567aa12a

 

eventTimestamp Timestamp in UTC format of when the event occurred.
2023-12-07T12:04:31.0146524+00:00
ingestionTimestamp

Timestamp in UTC format of when the event was ingested on the event stream.

This may be a different value from the eventTimestamp because, in some circumstances, there might be a slight delay between when the event occurred and when it is ingested.

2023-12-07T12:04:31.0287907+00:00
actor

Details of the user who generated the event.

This is always a user on a Workspace, and is identified by the user ID.

If the actor is indicated as the Pigment Support account, then you see the user’s details who was impersonating the Pigment Support account. More information on actor details in this case is provided below.  

If the event was generated through the Pigment Import or Export API, then you see the API key details instead of the user details.  More information is provided below.

"user":{
"id":"ABC123",
"name":"Acme Support",
"email":"SUPPORT123@AcmeInc.COM",
"impersonator":{
"id":"ABC1234",
"name":"John Doe",
"email":"John.Doe@AcmeInc.COM"
},
"jwt":{
"id":"ABC1234",
"issuedAt":"2023-12-20T10:24:58Z",
"expiresAt":"2023-12-20T14:24:58Z"
context

The workspace or organization in which the actor generated the event.

This also contains additional user details, for example, browser and IP address.

"organization":{
"id":"ABC1234",
"name":"Acme Inc."
},
"clientContext":{
"ipAddress":"10.100.100.10",
"userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 99_15_7"
}

 

eventType

The type of audit event that occurred.

More information on the different event types are provided in this article Audit Logs API Events and Event Types

DimensionCreated
payload

This information in this field can vary depending on the eventType

The payload contains some standard fields:

  • entity: This provides information, on where in the Pigment application the actor generated the event, for example id and name .
     
  • entityType : Describes the type of entity. For example, a View, Board, Metric, Transaction List, Dimension List, Table, or Application. 
     
  • settings: Depending on the eventType, this can contain additional details , such as isSecurityBlockdataType
"entity": {
"id": "ABC1234",
"name": "My new list",
"application": {
"id": "ABC1234",
"name": "My new app"
},
"entityType": "Dimension"
},
"settings": {
"isSecurityBlock": false
}

 

 

actor in the audit event

  • Pigment Support as the actor : As part of Pigment Support services, Pigment members are able to impersonate the Pigment Support user account to access your Workspace. The Pigment Support Account will not have UserLoggedIn or UserLoggedOut events. Instead, each time the Pigment Support account starts a session in the workspace, there will be the event SupportSessionStarted. You can use the Audit Logs API to monitor events that are generated by this account, specifically by using the impersonator parameter in the actor payload. 
    Here’s a sample response using this parameter:
"actor": {
"user": {
"id": "ABC123",
"name": "Acme Support",
"email": "SUPPORT123@AcmeInc.COM",
"impersonator": {
"id": "ABC1234",
"name": "John Doe",
"email": "John.Doe@AcmeInc.COM"
},
"jwt": {
"id": "ABC1234",
"issuedAt": "2023-12-20T10:24:58Z",
"expiresAt": "2023-12-20T14:24:58Z"
}
}
}
  • API as the actor: If any events were executed through Pigment API (e.g. Export or User Provisioning), the actor parameter contains a field api with details of the API key that’s used to generate that event:
"api": {
"apiKeyId": "11111111-a111-1111-111d-11ba11111da1",
"apiKeyName": "My Export API KEY"
}

 

Retrieve Additional Events with Pagination

The Audit Logs API retrieves audit trail events in batches, with each batch size containing 1000 events. The API uses a cursor-based pagination to retrieve additional events per batch. 

A cursor-paginated method returns: 

  • a batch of the total set of results
  • a cursor that points to the next batch of the results

When there are more than 1000 events available for your API request, the hasMoreEvents parameter in your response payload is set to true

{
"events": [{}],
"hasMoreEvents": true,
"nextEventsCursor": "cD0yMDIxLTAxLTA2KzAzAAABM"
}

If you need to retrieve another batch of additional events, you need to do the following:

  1. Locate the nextEventsCursor parameter in your response payload, and copy its value. 
  2. Create a new API query, appending the cursor parameter and the value provided for nextEventsCursor

    The examples below use the ingestedSince and cursor parameters.

    Here we use the same value that was returned for the nextEventsCursor parameter in the previous example: 
    Sample Query:  
    GET 'https://api/audit/v1/events?ingestedSince=2024-01-11T20:00:00&cursor=cD0yMDIxLTAxLTA2KzAzAAABM'

    Sample cURL Query: 
    curl -X GET 'https://pigment.app/api/audit/v1/events?ingestedSince=2023-11-27T15:00:00&cursor=cD0yMDIxLTAxLTA2KzAzAAABM' \     -H 'authorization: Bearer XXXX'
  3. Repeat this process for each batch of API events that you need.  

0 replies

Be the first to reply!

Reply