- 27 Jun 2024
- 9 Minutes To Read
- Print
- DarkLight
- PDF
Audit Trail
- Updated On 27 Jun 2024
- 9 Minutes To Read
- Print
- DarkLight
- PDF
The audit trail capability tracks all activities that have been performed in the Mambu Core Banking system via the UI or API v1 and v2. Audit records are grouped per tenant. You can search and filter through stored events using a simple API or periodically pull batches of events into your own log management software for further analysis.
We start storing events from the point that the audit trail feature is enabled. Events are stored for the same length of time as the one defined in your agreement. For more information, please contact your Customer Success Manager.
The audit trail feature only covers the Mambu application. Additionally, configuration as code payloads are not covered by the audit trail feature. We recommend using version control to retain a comprehensive changelog for these payloads.
Auditing for actions taken on add-on products, such as the Mambu Payment Gateway (MPG) or the Mambu Process Orchestrator (MPO), may be covered by their own logging and auditing solutions.
With audit trail you are able to:
- Identify what Mambu application users have done and when they did it.
- Choose who to audit and what type of information to audit.
Some example use cases might be:
- Investigate suspicious activity or potential fraud.
- Detect actions performed by an unauthorized user.
- Monitor and gather data about specific activities.
- Generate compliance and audit reports from audit data.
Use of Audit Trail requires API Consumers, which is an Early Access feature. For more information, see Authentication below.
Authentication
To authenticate audit trail requests you must use an API key generated by an API consumer that has the Manage Audit Trail (MANAGE_AUDIT_TRAIL
) permission assigned to it. For more information, see API Consumers.
Supported operations
Base URL: https://TENANT_NAME.mambu.com/api
Action | Endpoint | Description |
---|---|---|
GET | /v1/events | Get a list of events. |
Headers
Other than the authentication header with the API key, there are no other additional headers required.
Parameters
The following is a list of query parameters you can use to filter your requests.
Name | Description | Required |
---|---|---|
FIELD_NAME[OPERATOR] =FIELD_VALUE | A filter using a LHS bracket with an operator. There can be more than one filter used per request. For a list of field names, see Field Names below. For a list of available operators, see Operators below. | ✘ |
from | Allows you to offset results, the default is 0. Can be used in conjunction with the size parameter to return equally sized sets. Note that the number provided is not inclusive, so, for example, given a total results set of 100 events, from=10 will return the 11th to the 100th event. For information about limits, see Warnings below. | ✘ |
size | The number of event entries to return. If not specified, the default is 100. Can be used with the from parameter to page through a list of events in equally sized sets. For information on limits, see Warnings below. | ✘ |
sort_by | The field name by which to sort the returned events. For a list of field names, see Field Names below. If not specified the results will be sorted chronologically using the ocurred_at field. | ✘ |
sort_order | The order by which to sort the returned events using either asc (ascending) or desc (descending) order. If not specified, the default is descending order. | ✘ |
Requests
The following section shows sample requests using curl. For all examples, replace TENANT_NAME
with your actual tenant URL.
Sample request
Get all UI login activities for today
curl --location -g --request GET 'https://TENANT_NAME.mambu.com/api/v1/events?event_source[eq]=UI&resource[contains]=login&occurred_at[gte]=2021-08-08T00:00:00.000Z' \
--header 'apikey: {apikey}'
{apikey}
is an API key from the audit trail API consumer. For more information about authentication, see Authentication above.
Sample response
{
"events": [
{
"occurred_at": "2021-08-09T09:47:04.664Z",
"response_code": 200.0,
"resource": "login",
"event_source": "UI",
"client_ip": "80.131.123.137",
"request_method": "POST",
"request_payload": "{\"username\":[\"johnsmith\"],\"loginType\":[\"onlineLogin\"]}",
"resource_fragment": "/servlet/login",
"request_uri": "/servlet/login",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.131 Safari/537.36",
"response_payload": "SUCCESS",
"username": "johnsmith"
}
],
"from": 0,
"size": 100,
"totalItemsCount": 1
}
Additional sample requests
{apikey}
is an API key from the audit trail API consumer. For more information about authentication, see Authentication above.
Get API requests with failed authorization
curl --location -g --request GET 'https://TENANT_NAME.mambu.com/api/v1/events?event_source[eq]=API&response_code[eq]=401&=' \
--header 'apikey: {apikey}'
Get the last ten clients viewed by user “johnsmith”
curl --location -g --request GET 'https://TENANT_NAME.mambu.com/api/v1/events?event_source[eq]=UI&occurred_at[gte]=2020-04-09T19:20:01.040Z&resource[eq]=client&username[eq]=johnsmith&request_uri[eq]=/desktop/dispatch/GetClient&size=10' \
--header 'apikey: {apikey}'
Page through all events in batches of 10
curl --location --request GET 'https://TENANT_NAME.mambu.com/api/v1/events?from=0&size=10&occurred_at[gte]=2021-08-11T11:00:00.000Z' \ --header 'apikey: {apikey}'
curl --location --request GET 'https://TENANT_NAME.mambu.com/api/v1/events?from=10&size=10&occurred_at[gte]=2021-08-11T11:00:00.000Z' \ --header 'apikey: {apikey}'
curl --location --request GET 'https://TENANT_NAME.mambu.com/api/v1/events?from=20&size=10&occurred_at[gte]=2021-08-11T11:00:00.000Z' \ --header 'apikey: {apikey}'
Notice that in this last example we are using a filter on the occurred_at
field. This is important as, if no constraints are used and the default descending chronological order is applied, any new events matching your query will be included in the index and possibly cause your sets to intersect. Fixing the time at a given point is one way to ensure new events are not included in your results and your sets contain only unique events.
Parameter components
Field Names
Event fields | Description | Supported operators |
---|---|---|
event_source | The events that are supposed to be audited fall within the following categories: API , UI | eq , ne , in |
request_uri | The part of the request's URL after the base URL and up to the query string | eq , ne , startsWith , in , contains |
request_method | HTTP request method (GET , POST , PUT , etc) | eq , ne , in |
request_payload | The raw request data as a string, with sensitive information removed (see details in note below). Parameter may be empty. | eq , ne , startsWith , in , contains |
user_agent | The value of HTTP user agent header | eq , ne , startsWith , in , contains |
resource | For API requests, this value is obtained from parsing the URL. e.g for /api/clients" the resulting value is "clients" | eq , ne , startsWith , in , contains |
resource_fragment | For API requests this holds the request URI For UI operations this holds the raw URL hash | eq , ne , startsWith , in , contains |
username | The user who carried out the action or the name of the API consumer (may be empty) | eq , ne , startsWith , in , contains |
client_ip | IP address from http request or X_FORWARDED_FOR header if present | eq , ne , startsWith , in |
response_code | HTTP response code | eq , ne , in , gt , gte , lt , lte |
occurred_at | The timestamp, in UTC, when the event has been generated (when creating queries on this field the provided values must be in ISO8601 standard) | eq , ne , in , gt , gte , lt , lte |
response_payload | The raw response payload with sensitive information removed (see details in note below). A response payload is not included with every record. | eq , ne , startsWith , in , contains |
Operators
Operator | Description | Example |
---|---|---|
eq | Equals - exact match, applies to any type of fields | username[eq]=demo@mambu.com |
ne | Not equals, applies to any type of fields | username[ne]=demo@mambu.com |
gt | Greater than, applies to numeric or date fields | occurred_at[gt]=2018-05-01 |
gte | Greater than or equal, applies to numeric or date fields | occurred_at[gte]=2018-05-01 |
lt | Less than, applies to numeric or date fields | occurred_at[lt]=2018-05-01 |
lte | Less than or equal, applies to numeric or date fields | occurred_at[lte]=2018-05-01 |
startsWith | Starts with, applies to string fields | username[startsWith]=demo |
in | Element in list (exact match), applies to any type of fields | username[in]= user1@mambu.com,user2@mambu.com |
contains | This operator can be used with various content types. "key":"value" represents a search element. The order of the key and the value matters, for example, using the element "mykey": "myvalue" is not the same as "myvalue":"mykey" . The operator works with multiple elements that are delimited by ',' .The order of the elements doesn’t matter, for example request_payload[contains]= "key1":"value1","key2":"value2" will return the same results as request_payload[contains]= "key2":"value2","key1":"value1" . | request_payload[contains]= "provisionedThroughFederation": true, "detailsLevel":"BASIC" |
Warnings
Data retrieval limits
Given a set of filter query parameters, you can only retrieve 10,000 entries.
The combination of the values of the size
parameter and the from
parameter must not exceed 10,000 or else you'll receive a 400 Bad Request
status code with an error message such as:
"message": "From (10) and size (10000) combination exceed 10000, the maximum allowed window. Default size is 100"
The maximum value of the size
parameter is 10,000. The maximum value of the from
parameter is 10,000.
If you want to retrieve entries that are past the last 10,000 entries retrieved then you must use the filter query parameters to alter your request.
For example you can use the occurred_at
parameter and pass in an operator in order to narrow your query.
Example
In the following example we show how you can use the filter parameters to change your requests and retrieve different sets of events.
Suppose that you want to get a simple list of all the latest events that have happened in your tenant.
With the following request you would retrieve the 10,000 latest entries:
curl --location --request GET 'https://TENANT_NAME.mambu.com/api/v1/events?size=10000' \
--header 'apikey: {apikey}'
Suppose the events retrieved are from the 4 August, 2021 until the 18 August, 2021.
If you wanted to retrieve events before the 4th August, 2021 then you could change your request by using the occurred_at
filter query parameter and passing in an operator. For example:
curl --location -g --request GET 'https://TENANT_NAME.mambu.com/api/v1/events?size=10000&occurred_at[lte]=2021-08-04T00:00:00.000Z' \
--header 'apikey: {apikey}'
This could, for example, retrieve events from the 4 August, 2021 until the 13 July, 2021.
User-Agent header
When audit trail is enabled, you must provide a User-Agent
header for all requests to any endpoint, or the request will fail with the error message:
{
"returnCode": 4,
"returnStatus": "INVALID_PARAMETERS",
"errorSource": "The user agent cannot be null when the Audit Trail feature is enabled"
}
Note that if you are using a REST client like Postman or Curl, this header is probably provided automatically. However, if you generate a request to the API, you must provide it yourself.
The User-Agent
header provides information regarding the browser and operating system (such as the browser version), and information about the library or tool issuing the request (such as the client Java version). It is generally used to assist with debugging problems.
Invalid characters in a header or path
When using basic authentication, the requests you make to any of our APIs must be RFC 7230 compliant. If you're using basic authentication and your request has an invalid character in either the header or the path, then you will receive a 400 Bad Request
status code and this request will not be logged in audit trail. Invalid characters are any characters that are not included in ASCII.
We recommend validating your requests or using a well tested HTTP request library in your integrations. However if you experience any issues with repeated bad requests, please contact us through Mambu Support.
Example
The example below will result in a 400 Bad Request
status code because one of the headers includes the á
character which is not in the ASCII.
curl --location --request GET 'https://TENANT_NAME.mambu.com/api/clients' \
--header 'Accept: application/vnd.mambu.v2+json' \
--header 'Content-Type: application/json' \
--header 'á: value' \
--header 'Authorization: Basic {auth}' \
--data-raw ''
Security
The following information is removed from request payloads when using audit trail:
PASSWORD,
PAGINATION_DETAILS,
FETCHING_INFO,
MOBILE_PHONE,
EMAIL_ADDRESS,
ADDRESSES,
BIRTH_DATE,
MOBILE_PHONE1,
MOBILE_PHONE2,
FIRST_NAME,
LAST_NAME,
HOME_PHONE,
MIDDLE_NAME,
NOTES,
GROUP_NAME,
ADDRESS_LINE_1,
ADDRESS_LINE_2,
ADDRESS_LATITUDE,
ADDRESS_LONGITUDE,
DESCRIPTION,
TITLE,
TEXT,
ASSET_NAME,
LOAN_NAME,
NAME,
POST_CODE,
COUNTRY,
REGION,
GENDER,
IBAN