Audit Logs
Audit logs maintain a historical record of activity events, noting the time, responsible user or service, and affected entity.
Audit logs enable organizations to meet certain compliance and business policy requirements. Additionally, Administrators use audit logs to track user activity, and security teams use them to investigate breaches and ensure regulatory compliance.
Key Features
-
The audit logs are structured in JSON format, ensuring machine-readability.
-
This format facilitates easy integration with third-party tools.
-
It eliminates the need for users to navigate through numerous log files.
Considerations
Security
-
Like other
gadmin
configurations, only the Linux user with server access can enable and configure the audit log. -
Access to the audit log is restricted to those who have access to TigerGraph logs.
-
Sensitive data or PII in the audit log, such as credentials or sensitive query payload information is masked by default.
Configuration Commands
Configuration | Description | Type (Default Value) |
---|---|---|
|
Setting to enable audit logs. |
boolean (false) |
|
Modify the DataBaseName field in log file header. |
name (TigerGraph) |
|
Modify the relative audit log path. |
path string (<TG_LogRoot>/AuditLog/) |
|
Modify the modification date when a new audit log file is created. |
Integer (90) |
|
Modify the audit log file’s max size. |
Integer (100) |
|
Modify the max amount of Audit Log files in the Audit Log folder. |
Integer (100) |
|
Mask Sensitive data or PII in the audit log. |
Default value is: |
Additionally, all audit log files are stored in JSON format. Each log entry is a JSON object, and the log file is one JSON array of these objects.
For more information see section Consuming Audit Logs or for a complete list of TigerGraph gadmin
configs see Configuration Parameters.
Apply Configuration Changes
If you use gadmin
config to change any of these parameters, you need to run gadmin config apply -y
for it to take effect.
You can change multiple parameters and then run gadmin config apply
for all of them together
$ gadmin config apply -y $ gadmin restart gsql -y
Setup Environment
Audit logging is disabled by default in a TigerGraph system.
gadmin
to run the following command to enable the setting:$ gadmin config set System.Audit.Enable true
Once enabled, the audit log will be found in the <System.LogRoot>/AuditLog
folder.
The <System.LogRoot>
represents the default path for all TigerGraph logs, set to tigergraph/log
by default.
<System.LogRoot>
), execute the following command:$ gadmin config set System.Audit.LogDirRelativePath <audit-log-relative-path>
$ gadmin config set System.LogRoot <log-root-path>
Take note that altering |
Log File Policy
A new audit log file will be created when any of the following situations occur:
-
The GSQL service is restarted.
-
The latest audit log file size exceeds the
System.Audit.LogConfig.LogFileMaxSizeMB
value. The value of this field is100MB
by default.You can modify this value by running the following command:$ gadmin config set System.Audit.LogConfig.LogFileMaxSizeMB <file-size>
-
Log files will be removed if its lifetime exceeds
System.Audit.LogConfig.LogFileMaxDurationDay
. The value of this field is90
days by default.You can modify this value by running the following command:$ gadmin config set System.Audit.LogConfig.LogFileMaxDurationDay <max-duration-day>
-
Lastly, the oldest audit log file will be automatically deleted, if the amount of audit logs in the audit log folder exceeds the
System.Audit.LogConfig.LogRotationFileNumber
value. The default of this value is100
audit logs.You can modify this value by running the following command:$ gadmin config set System.Audit.LogConfig.LogRotationFileNumber <file-number>
Other Customizable Configs
There is a “DatabaseName” field appended to the header of each audit log file. The value of this field is "TigerGraph" by default.
$ gadmin config set System.Audit.DataBaseName <database-name>
gadmin
Customizable Configs
You can configure gadmin
command’s audit logging rotation rules with the following gadmin configs:
gadmin config set Gadmin.BasicConfig.LogConfig.LogFileMaxDurationDay: <lifetime of a file>
gadmin config set Gadmin.BasicConfig.LogConfig.LogFileMaxSizeMB: <file rotation size>
gadmin config set Gadmin.BasicConfig.LogConfig.LogRotationFileNumber: <the rotation file number>
Consuming Audit Logs
Log Format
All audit log files are stored in JSON format, even when users are actively interacting with TigerGraph, so audit logs can be consumed at run time.
Audit log files are separated by GSQL service and REST++ API calls. Both having separate file names:
|
[ {"serverHostIP":"127.0.0.1","databaseName":"TigerGraph","version":"1.0","timestamp":"2023-12-20T14:42:50.243-07:00"}, {"endpoint":"/gsql/file","clientHost":"127.0.0.1:43746","clientOSUsername":"tigergraph","userAgent":"GSQL Shell","userName":"tigergraph","authType":"USER_PASS","message":"Successfully created user 'u1'.","timestamp":"2023-12-20T14:42:50.243-07:00","actionName":"createUser","status":“SUCCESS”}, {"endpoint":"/gsql/file","clientHost":"127.0.0.1:54746","clientOSUsername":"tigergraph","userAgent":"GSQL Shell","userName":"tigergraph","authType":"USER_PASS","message":"Successfully created query 'printVertex'.","timestamp":"2023-12-20T14:42:50.243-07:00","actionName":"createQuery","status":“SUCCESS”}, {"endpoint":"/gsql/library","clientHost":"127.0.0.1:54770","clientOSUsername":"tigergraph",,"userName":"tigergraph","authType":"USER_PASS","message":"callTemplateQuery succeed","timestamp":"2023-12-20T14:42:50.243-07:00","actionName":"callTemplateQuery","status":“SUCCESS”} ]
-
Each audit log file is a JSON array of JSON objects, one object per log entry.
-
Each object is formatted as a single line for better readability of high volume data.
GSQL Service Audit Logs
{ "version": "1.0", "timestamp":"2023-12-20T14:42:50.243-07:00", "dataBaseName": "TigerGraph", "serverHostIP": "192.168.1.1", }
The audit log will record any user-triggered activity, such as:
-
login,
-
Password change,
-
grant role,
-
create a query,
-
etc…
Each activity will have its own audit log entry and fields. |
createQuery
activity will produce an audit log entry with the following fields:{ "timestamp":"2023-12-20T14:42:50.243-07:00", "userName": "tigergraph", "authType": "password", "clientHost": "<IP or FQDN>:<Port>", "clientOSUsername":"OSusername", "userAgent": "GSQL Shell", "endpoint": "/gsql/file", "actionName": "createQuery", "status": “SUCCESS”, "message": "Successfully created query 'query_name'" }
For user login/auth
related activities, one more field called failedAttempts
is added to the JSON.
This field indicates how many times this user failed to provide the correct credentials.
{ "timestamp": "2023-12-20T14:42:50.243-07:00", "userName": "tigergraph", "authType": "SAML SSO", "clientHost": "<IP or FQDN>:<Port>", "clientOSUsername":"tigergraph", "userAgent": "GraphStudio", "endpoint": "/gsql/simpleauth", "actionName": "login", "failedAttempts" : 1, "status" : "FAILURE", "message": "Username doesn't exist" }
REST++ API Call Audit Logs
Audit logs for REST++ calls are found in the log.Audit-RESTPP
file.
They are similar to GSQL service audit logs, such as, the status for API calls will be either SUCCESS
or FAILURE
, but they are different in these ways:
-
The duration is the runtime cost with seconds.
-
The code will be the return codes from the REST++ server, see Return Codes.
-
A new field
requestId
is also added.
Values in requestParams
and requestBody
will be masked if they contain PII data.
{
"timestamp": "2023-10-02T15:06:18.365Z",
"userName": "tigergraph",
"authType": "token",
"clientHost": "<IP or FQDN>:<Port>",
"userAgent": "curl",
"endpoint": "/restpp/query/{graph_name}/{query_name}",
"actionName": "runQuery",
"status": "SUCCESS",
"duration": 3.24,
"requestId": "16842763.RESTPP_1_1.1561401340785.N",
"requestParams": "",
"requestBody": "",
"code": "REST-0000",
"message": "<success/error message>"
}
gadmin Audit Logs
Audit logs for gadmin command executions are found in the log.Audit-GADMIN
file.
Besides the basic information such as timestamp
, OS
, username
, they capture the gadmin
commands executed on the node and the outcomes:
gadmin start all
{
"timestamp": "2024-05-13 23:45:34.940",
"session id": 1418,
"OS username": "tigergraph",
"host": "10.128.0.48",
"command": "gadmin start all",
"status": "SUCCESS"
}
Known Issues
-
The real client IP address could be removed or masked by a firewall or another intermediate redirect layer before arriving at the TigerGraph service.
-
Thus, TigerGraph cannot get the actual client ip, instead it will put the ip address of the last layer who forwarded the request to TigerGraph service in the audit log.
-
-
Even when REST++ authentication is enabled and when a request that failed due to an invalid request parameter, the username in the corresponding audit log will be marked as
unknown
instead of the actual username.-
This is because request parameter validation happens before token validation. Thus, REST++ calls do not know the username before it gets printed in the audit log.
-
-
If the user logs into TG Cloud using SSO, they will not be required to provide credentials again when opening GraphStudio.
-
Therefore, the login event would not be reflected in the audit log, but the user’s subsequent operations (
create query
,install query
, etc.) will be recorded in the audit log as normal.
-