Audit Log

Grainite Audit Log provides a security-relevant, chronological set of records documenting the sequence of actions within a cluster. The cluster audits the activities generated by principals, and by applications that use the Grainite API.

Prerequisites

Prior to enabling auditing on Grainite clusters, the following prerequisites must be met.

1. Deploy a secure Grainite cluster in a cloud environment.

2. Enable Role-Based Access Control.

3. Create a user who has the privileges to perform security-related tasks as outlined in the Role-Based Access Control document. Alternatively, the cluster_admin can enable auditing of the applications within the cluster.

On your local machine:

1. Download and set up gx as described in the environment setup.

2. Ensure you have a Maven installation (version 3.8.3 or higher).

Setup:

Audit log is implemented as a Grainite application. Thus you will first need to run the below command to generate the application YAML configuration file which we'll be loading to your cluster.

gx security setup-audit

Once the command is complete, you'll see that the application's YAML configuration file was generated with the path provided in the output. Please replace <path_to_app.yaml> in the command below with the path provided in your console output.

gx load -c <path_to_app.yaml>

Config

To set up the auditing environment, you will need to update the global_policies.yaml file and add the audit section. A sample is provided below.

…
audit:
  apps:
    - <env_name>/<app_name>
  log-level: 3
  destination: <remote_ip>:<port>
…

apps: This allows you to specify the applications for which auditing must be enabled within the cluster. It is specified using the following format: <environment>/<app_name>

log-level: The log levels provide control over the type of information that admins want to be captured with auditing.

• 1: Global level commands (e.g. gx security)

• 2: Level 1 + Application level commands (e.g. gx topic dump)

• 3: Everything (includes read/write/update operations)

destination: This contains the listener of the audit messages.

Reading Audit Log Message:

A sample message that is generated by the auditing feature is shown below.

Jun  7 22:27:08 grainite-RBAC audit: {"PodRequestId":"8","RequestType":"authorization","TimeStamp":"2023-06-07 22:27:08.0876","PodId":"gxs-2","ClientIp":"XX.XXX.XX.X","ClientPort":"XXXXX","ServerIp":"XX.XXX.XX.XX","ServerPort":"5057","ClusterName":"my-cluster","ErrorCode":"1000","ErrorMessage":"","OriginalQuery":"RegisterApp","Environment":"default","Application":"userflows","Principal":["cluster_admin"],"Roles":["cluster_admin"],"Operation":"NONE","Resource":"","Succeeded":"True","Destination":"XX.XXX.XX.XXX:XXX"}#015

Below is a description of each field in the audit log message:

Field	Description
PodRequestId	A unique entry generated for each audit log message per pod(podID).
RequestType	Type of request to carry out the operation. We currently support Authorization.
TimeStamp	UTC time stamp of the request to the cluster.
PodID	Grainite Pod on which request was executed. In a 3-node cluster, the possible values are gxs-0, gxs-1, and gxs-2.
ClientIP	Client IP address of the user or application making the request.
ClientPort	Port from the client side of the connection
ServerIp	Server IP address that received and executed the request.
ServerPort	Server port that received the request.
ClusterName	This is the name of the cluster.
ErrorCode	Generated error code.
ErrorMessage	Database generated error text.
OriginalQuery	Type of query from the principal.
Environment	Namespace to which query was sent. If no namespace exists, the default will be specified.
Application	Specifies the name of the application which executed the database action.
Principal	The principal that initiated the request (from client certificate or other grainite app).
Roles	Role(s) assigned to the Principal
Operation	Type of operation performed on the resource
Resource	Grainite resources such as Topic or Table
Succeeded	Status of operation
Destination	Remote Destination server IP that the log will be sent to