How to use SAFE’s Audit APIs
  • 6 Minutes to read
  • PDF

How to use SAFE’s Audit APIs

  • PDF

Article summary

By default, SAFE provides a downloadable audit log within the application. For details, see Advanced Settings.

Overview

SAFE provides the capability to access security information, which can be integrated into a customer's chosen Security Information and Event Management (SIEM) platform. This integration is facilitated through a generic interface that makes relevant information available to the target SIEM. Additionally, SAFE supports the integration process to ensure seamless connection with the customer's platform. The logs provided will include the following details:

  • Timestamp

  • Source IP and Port

  • Username

  • Action/Activity — This may include activities such as:

    • Application login/logout

    • Modifications to integrations (initial setup, updates, testing, and starting/stopping synchronizations)

    • Changes to groups (creation, updates, and deletions)

    • Alterations in risk scenarios (creation, updates, and deletions)

    • Updates to any questionnaires

These logs are provided in a JSON format for easy integration and readability.

For customers who have purchased the "Bring Your Own Account (BYOA)" option, AWS CloudWatch logs will also be made accessible for integration into their chosen SIEM system.

If the customer requires custom modifications to the generic interface for better compatibility with their SIEM, such work will be defined and agreed upon through a specific Statement of Work (SOW).

This solution caters to customers seeking enhanced visibility into user actions, including login and logout activities on the SAFE platform, within their SIEM.

Architecture

SAFE Application Overview

The diagram in Figure 1 illustrates the architecture of the SAFE Application, which efficiently forwards application audit logs to a CloudWatch Log Group. SIEM tools, equipped with appropriate Add-ons and Plugins, can directly retrieve these logs from the CloudWatch Log Group, facilitating streamlined integration and monitoring.

SAFE Application Workflow

In Figure 2, we detail the SAFE Application's workflow for transmitting application audit logs to a CloudWatch Log Group. Simultaneously, AWS CloudTrail forwards infrastructure-level audit logs to an S3 bucket. SIEM tools can seamlessly access these logs from both CloudWatch Log Group and the S3 bucket using enhanced Add-ons and Plugins. This functionality is specifically available to Bring Your Own Account (BYOA) customers who manage their own AWS accounts for CloudTrail log ingestion.

Prerequisites

  • SIEM Compatibility: Ensure that the customer's SIEM tool is compatible with AWS services and can ingest logs from CloudWatch and S3, either through native integrations or using available plugins and add-ons.

  • IAM Role Configuration: SAFE must set up an IAM role within the AWS account with permissions to read logs from CloudWatch and S3. This role should be assumable by the SIEM tool to securely access the logs.

  • Network Connectivity: Verify that the customer's network infrastructure allows outbound connections to AWS services. This includes configuring firewalls and security groups to permit traffic to necessary AWS endpoints.

Notes:

For customers who prefer not to have live integration with dynamic updates, scripting can be built to periodically query our APIs:

  • POST /api/v3/audit-logs/export: This API takes the number of days as a payload and returns a UUID, which must be used with the subsequent API call.

  • GET /api/v3/audit-logs/export/: With the UUID, this API allows customers to retrieve data daily and dump it to an S3 or similar location for post-processing.

GET /api/v3/users:

To fetch the list of users onboarded to the SAFE One Application

This API allows users to GET the list of SAFE users currently onboarded to their SAFE application. It provides important details such as the user's First Name, Last Name, Email Address, Last Login Time, and Role as part of the response.

This API needs to be called for Audit Logs, as:

  • Audit logs represent users by their UUID (User ID column).

  • The user API will provide ‘uuid’ to user mapping for your reference.

Note: This API is now available in Swagger as well.

Parameters


Name

Description

page

integer

(query)

Pagination parameter for page number

pagelen

integer

(query)

Number of items on this page, default is 10

searchKey

string

(query)

Filter users by passing different criteria



Example Request:


curl --location 'https://us.safeone.ai/api/v3/users' \

--header 'Authorization: Bearer {{safe-bearer-token}}'



Responses


Code

Description

Links

200

User details are presented as an array of individual user object

Response Information

  1. page (Integer) - This defines the current page number

  2. pagelen(Integer) - This defines the maximum number of items visible per page

  3. size(Integer) - This contains the total number of items in the response across all the pages

  4. next(String) - This contains the hyperlink for the next page, if the current page is last, then the value will be null

  5. previous(String) - This contains the hyperlink for the previous page, if the current page is the first page, then the value will be null

  6. values(Array) - This is an array of dictionaries, where each dictionary corresponds to a user in SAFE and consists of the following values

    1. peopleId(Integer) - The unique ID of the user.

    2. emailId(String) - The email ID of the user.

    3. firstName (String) - The first name of the user.

    4. lastName(String) - The last name of the user.

    5. uuid(String) - The unique identifier assigned to the user across SAFE.

    6. updatedAt(String) - The timestamp when the user's details were last updated.

    7. lastLoginTime(String) - The user's last SAFE login timestamp.

    8. role(String) - The role of the user in SAFE.

    9. authenticationType(String) - The authentication type of the user logging into SAFE. This value can be either Native (login via SAFE's MFA), or SSO (login via SSO).

Media type

application/json

Controls Accept header.


Example Value

Schema



{

 "size": 1,

 "page": 1,

 "pagelen": 10,

 "previous": null,

 "next": "https://example-domain.safeone.ai/api/v3/users?page=2&pagelen=100",

 "values": [

   {

     "peopleId": 1,

     "emailId": "john.doe@domain.com",

     "firstName": "John",

     "lastName": "Doe",

     "uuid": "12345678-1234-1234-1234-123456789012",

     "updatedAt": "2022-01-13T05:03:50.428Z",

     "lastLoginTime": "2022-01-13T05:03:50.428Z",

     "role": "Admin",

     "authenticationType": "Native"

   }

 ]

}

No links

401

UNAUTHORIZED

Media type

application/json


Example Value

Schema

{

 "status": "error",

 "message": "invalid authorization header!"

}



No links

403

FORBIDDEN

Media type

application/json


Example Value

Schema

{

 "Message": "User is not authorized to access this resource with an explicit deny"

}



No links


—----------------------------------------------------------------------------------------------------------------------------


POST /api/v3/reports:


This API helps SAFE users to trigger reports. We can use the same API to trigger Audit Logs export. It will return a UUID which needs to be used in the next API.


Parameters


Name

Description

NA

NA



Example Request:

The following example shows how SAFE users can call this POST API via cURL to request the audit logs for the past 1 day:



curl -X 'POST' \

 'https://us.safeone.ai/api/v3/reports' \

 -H 'accept: application/json' \

 -H 'Authorization: Bearer {{safe-bearer-token}}' \

 -H 'Content-Type: application/json' \

 -d '{

 "type": "AUDIT_LOGS",

 "format": "csv",

 "reportMeta": {

   "days": 1

 }

}'



Responses


Code

Description

Links

202

A UUID is provided by SAFE in the response.


Media type

application/json


Example Value

Schema


{

   "success": true,

   "message": "Report generation request is queued and will be processed shortly",

   "data": {

       "uuid": "1eebc0b2-b019-42b3-8132-c15c5926b21e"

   }

}

No Links

401

UNAUTHORIZED

Media type

application/json


Example Value

Schema

{

   "message": "Unauthorized"

}


No Links


GET /api/v3/reports/<uuid>:

This API allows SAFE users to retrieve the Audit logs using UUID generated from the previous API i.e., POST /api/v3/reports.


Parameters


Name

Description

NA

NA


Example Request:

The following example shows how SAFE users can call this GET API via cURL to get the audit logs for the past 1 day by providing the UUID:


curl -X 'GET' \ 'https://preprod.safeone.ai/api/v3/reports/1eebc0b2-b019-42b3-8132-c15c5926b21e' \

--header 'Authorization: Bearer {{safe-bearer-token}}'


Note: Replace the UUID (highlighted in bold above) with your UUID generated from the previous API.


Responses


Code

Description

Links

200

Provides a pre-signed link. Clicking/opening the link in a browser lets the user download a CSV containing the audit logs.


Media type

application/json


Example Value

Schema


{

   "success": true,

   "message": "Please download the report from the provided URL. The link will expire in 5 minutes.",

   "data": {

       "preSignedUrl": "<Download Link>"

   }

}

No Links

400

Bad Request


Media type

application/json


Example Value

Schema


{

   "success": false,

   "message": "Report not found for report id:1eebc0b2-b019-42b3-8132-c15c5926b21e"

}

No Links




Notes

If the customer does not want to have a live integration with dynamic updates which, they can build scripting to query our APIs periodically:

  1. POST /api/v3/audit-logs/export

  2. GET /api/v3/audit-logs/export/<uuid>

The first API takes the number of days as a payload and returns a UUID which needs to be passed to the second one. A customer can use this on a daily basis to pull data and dump it to an S3 or similar for post-processing.

These APIs are not intended for regular polling. Audit logs can be retrieved covering a minimum of a 24-hour period (e.g. time of request - 24 hours). SAFE monitors API usage and reserves the right to limit traffic for audit logs if there is excessive usage.



Was this article helpful?

What's Next