The new version of the Audit log described in this article is active only on the single tenant and exclusive instances. If using the multi-tenant instance, please refer to the old [Audit log](🔗) article.
As security is a crucial concern to Bloomreach, we consider it necessary to allow our clients to have an overview of all activities performed in the Bloomreach Engagement app. Especially when an activity is suspicious, we want you to be able to detect and investigate it. Audit logs, capturing and storing records of user activity within Bloomreach Engagement, enable you to do just that.
# What is Audit log?
Audit logs are **chronological records of user activity within the Bloomreach Engagement application**. They capture audit trails that help in investigations of unauthorized access, data leak, or GDPR incidents, and they help with understanding alerts of repeated incidents and whether company-specific policies are met.
In simple terms, Audit Logs do that by answering the question of _Who_? Did _What_? _When_? And _Where_?
**Who?** - The actor that performed an action. This can be public access, authenticated user, API key, or Bloomreach Engagement's internal process.
**Did What?** - What action was performed can be identified by a unique combination of a request method and request path. Some records contain references to a specific resource and additional information within a service data.
**When?** - Each action has a precise timestamp. Time within the Bloomreach Engagement platform is synchronized using Network Time Protocol (NTP).
**Where?** - Actions are logged from different parts and scopes of the application. The scope is one of: an instance, account, or project. Service name refers to one of many internal services. The screen where an action was performed by users from a browser can be accessed by the referrer URL.
# Enabling and accessing the Audit log
To **enable** Audit log, you have to contact your CSM, and unless previously included within the original order form, a Letter of instruction must be signed. Enabling the Audit log usually takes up to 3 business days.
**Access** is managed by a CSM utilizing GSuite Google Groups (separate from the Access management within the Bloomreach Engagement application). Only the members of this group will be able to access the data. You will need Google Identities to use Google Groups. These identities are either Google's user accounts or service accounts.
For security reasons (as a protection from any kind of manipulation or tampering with the audit log), there is no direct access from the Application, and users will be granted read-only access to the Google Cloud Storage bucket containing exported Audit log data, which means the data itself cannot be directly edited.
## Different ways of accessing the Audit log
### Accessing with Google Cloud SDK tools: _gsutil_
You need to install [gsutil](🔗) first. _gsutil_ performs all operations, including uploads and downloads, using HTTPS and transport-layer security (TLS).
Then authenticate with a google service account. You need a service account private key JSON file.
If you would like to learn more about accessing Audit logs through Google Drive SDKs tools, please refer to the [article](🔗).
### Accessing with direct API calls
The second option is to access the audit log through direct API calls. If you want to learn more about it, read the [article](🔗). You can see the example for using Google Cloud SDK python libraries down below:
Unique Bucket name
Your bucket name included in the code is unique. You need to replace "iid" in the above examples with your unique instance identifier `
instance_id` (three alphanumeric lowercase symbols). Bucket naming convention is `
instance_id + "-auditlog-storage"` followed by `
day` (path formatting).
# How does Audit log work
The audit log tracks requests sent by application users. Results are stored in a **separate GCS bucket** and can be downloaded and processed by an automated system.
The Bloomreach Engagement app contains a component that verifies user access for all parts of the application. Every time a logged user performs an action, this component creates an event, which is then stored in specific storage. Some events are considered to be sensitive and are therefore supplemented with additional information (e.g. how many rows have been exported/imported etc.).
**Buckets** are named`
[instance-auditlog-storage]`, where “instance” is the name of the instance in which the bucket is stored. The data in these buckets are organized in folders according to time in the following way: Year > Month > Day.
**Files** with audit log events are JSON one line. This means every event is noted on one line. Files are created every hour and each file contains new logs. Files are not updated after creation. Delayed records are written in a file with an incremental number suffix.
Files are available for download for at least 60 days. After this time period, they can be moved into our archive storage and are not accessible for download.
# Understanding the Audit log
### Correlating multiple records
Some actions may generate more records on different levels of the application. Different components add component-specific information to the logs as service data. The unique request ID is generated on the first touchpoint and then propagated to subsequent events.
### Scope identification
All events contain a field that defines on which layer the event was created - connecting it with a specific project, account, or instance.
An action performed on a project level has the _Scope type_ value “PROJECT” and\_ Scope ID \_value is the project token
An action performed on an account level has the _Scope type_ value “ACCOUNT” and _Scope ID_ value is the account ID
An action performed on the instance level has the _Scope type_ value “INSTANCE” and **no** _Scope ID_ value
### Correlating user activity
Use session ID to correlate and analyze the flow of user activity during a session. A new unique session ID is created for each login session and discarded after logout or session expiration. Methods that do not require authentication do not have a session ID.
## Audit log record schema
Log records have a predefined schema and come in JSON format. The top-level schema is fixed which makes audit logs to be easily imported into all commonly used SIEMs (e.g. Splunk, Graylog).
Fixed schema fields are reliable, can be used as indexed columns, and shall be used for SIEM alerts. Drilling down, records may contain not fixed (untyped) fields that are meant to provide additional information, are useful during investigations, and may be used for less critical SIEM alerts.
### Schema: Fixed fields
Fixed fields are always present. These include:
|timestamp||The timestamp of the operation, ISO 8601 datetime in UTC, e.g. 2020-07-09T11:30:57.239442245Z|
|request||method or path|
|status||HTTP status code, e.g. 403 for Forbidden actions|
|serviceName||The internal name of the service within Bloomreach Engagement architecture|
|scopeType||enum: INSTANCE, ACCOUNT, PROJECT|
|scopeID||A unique project or account identifier|
|requestID||A unique ID, useful for correlating individual records connected with single user action|
Scope-related fields (scopeType, scopeID) are present only for methods requiring authorization. Fields are not present for other methods which are public methods or require only authentication.
### Schema: Optional fields
Optional fields are present only for some operations.
|resource_id||Every operation on a specific resource with internal ID, e.g. customer, scenario, banner, experiment. Useful for, e.g. filtering, alerts|
### Schema: Service Data
**GenericServiceData** Generic service data provide some additional information only for informational use cases. This information may be useful during investigations. The info field is not fixed and should not be used for critical use cases.
|info (untyped)||JSON encoded string, informational field, and schema is not fixed and it's subject to change|
|version_id||Every operation on a specific resource with enabled versioning history, e.g. reports create/update, scenario create/update/start|
|policyChanges||A list of policy changes.
|updateTime||The timestamp of the operation|
|userID||User ID of the subject performing the operation|
|requests||A list of the requested IDs.
## Examples of audit logs visualized in Splunk
Audit log files are best visualized and evaluated in a dedicated security system, such as Splunk, Graylog, Kibana, etc.
Here are some self-explanatory samples of the visualization: