Audit Logging

Audit Logging#

This page provides an overview of audit logging, a feature that enables the systematic tracking and monitoring of user activities to ensure security and compliance. That feature requires access to the Squirro platform using the command line interface.

Overview#

The audit logging feature captures detailed information about HTTP requests and responses in a structured way for user API endpoints, including:

  • user signups

  • user logins with authentication method

  • user logouts

  • user session teminations due to inactivity

  • changing user roles

  • creating/deleting groups

  • creating/deleting workspaces

  • adding/removing users to/from groups

  • adding/removing users to/from workspaces

  • adding/removing groups to/from workspaces

and topic API endpoints, including:

  • creating/deleting projects

  • importing/exporting projects

  • adding/removing users to/from projects

  • adding/removing groups to/from projects

The system logs all these actions automatically using a decorator that wraps the specified endpoints, ensuring it captures all relevant interactions.

Configuration#

By default, a newly deployed Squirro instance has the audit logging feature disabled.

To enable the audit logging feature, go to Server→Configuration, check the security.audit-logger option, and restart the squserd and sqtopicd services for the changes to take effect. The order of restarting the services does not matter.

Log File Location#

The audit logs are stored in *.log.jsonl files (one JSON object per line) for services that have implemented audit logging. Currently, this includes the user and topic services. The log files are located under the following paths:

  • /var/log/squirro/user/user.log.jsonl

  • /var/log/squirro/topic/topic.log.jsonl

All audit log entries are identified by the attribute "log_type": "audit_log" to differentiate them from other structured logs in the same file.

Log Format#

The audit logs are stored in JSON Lines format, with each line representing a single event. The logs are structured as follows:

Field

Description

event

Type of the event: always request.

level

Log level of the event: info (success) or error (failure).

log_type

Type of the log: always audit_log.

request_body

Body of the HTTP request.

request_headers

Headers of the HTTP request.

request_method

Method of the HTTP request.

request_params

Query parameters of the HTTP request.

request_path

API endpoint path of the HTTP request.

request_error

Error detail (present only for failed HTTP requests).

response_headers

Headers of the HTTP response.

response_status_code

Status code of the HTTP response.

timestamp

UTC timestamp of the event.

user_cluster_role

Cluster roles of the user.

user_email

Email address of the user.

user_id

ID of the user.

Example of an audit log entry for a successful request:

{
    "event": "request",
    "level": "info",
    "log_type": "audit_log",
    "request_body": "grant_type=refresh_token&refresh_token=v4.public.r3fr3sh.t0k3n",
    "request_headers": {
        "Accept": "application/json",
        "Accept-Encoding": "gzip, deflate",
        "Connection": "keep-alive",
        "Content-Length": "62",
        "Content-Type": "application/x-www-form-urlencoded",
        "Host": "localhost",
        "User-Agent": "python-requests/2.31.0"
    },
    "request_method": "POST",
    "request_params": {
        "grant_type": "refresh_token",
        "refresh_token": "v4.public.r3fr3sh.t0k3n"
    },
    "request_path": "/api/user/oauth2/token",
    "response_headers": {
        "Content-Length": "0",
        "Content-Type": "text/html; charset=UTF-8",
        "Vary": "Accept"
    },
    "response_status_code": 200,
    "timestamp": "2025-04-16T09:37:55.466277Z",
    "user_cluster_role": [
        "Owner",
        "Admins"
    ],
    "user_email": "[email protected]",
    "user_id": "Y2qTSLzBRtOAJWlX11M9AB"
}

Example of an audit log entry for a failed request:

{
    "event": "request",
    "level": "error",
    "log_type": "audit_log",
    "request_body": {
        "client_id": "2mL1rwP1Rr9h0aIjhPaAbC",
        "client_secret": "219025975c1d9cb9f1306ef7e5418d5ca7f4521a",
        "email": "[email protected]",
        "role": "admin"
    },
    "request_error": "409 Conflict\r\nContent-Type: text/html; charset=UTF-8\r\nContent-Length: 0\r\nVary: Accept",
    "request_headers": {
        "Accept": "application/json",
        "Accept-Encoding": "gzip, deflate",
        "Connection": "keep-alive",
        "Content-Length": "167",
        "Content-Type": "application/json",
        "Host": "127.0.0.1:81",
        "User-Agent": "SquirroToolbox/{__VERSION__} (http://squirro.com/)"
    },
    "request_method": "POST",
    "request_params": {},
    "request_path": "/api/user/v0/_global/users",
    "response_headers": {
        "Content-Length": "0",
        "Content-Type": "text/html; charset=UTF-8",
        "Vary": "Accept"
    },
    "response_status_code": 409,
    "timestamp": "2025-04-16T09:17:53.271004Z",
    "user_cluster_role": [],
    "user_email": "",
    "user_id": ""
}

Monitoring Log Files#

You can follow audit logs in real-time using the tail command with the -f parameter, which allows you to monitor the updates to log files:

tail -f /var/log/squirro/user/user.log.jsonl /var/log/squirro/topic/topic.log.jsonl

Contents