Consul
Audit Logging
Enterprise
This feature requires HashiCorp Cloud Platform (HCP) or self-managed Consul Enterprise. Refer to the enterprise feature matrix for additional information.
This page describes the process to enable and configure audit logging on Consul Enterprise clusters. Audit logging enables security and compliance teams within an organization to get greater insight into Consul access and usage patterns.
Introduction
Audit logs capture a list of authenticated events that Consul processes through its HTTP API. This list includes both attempted and committed operations, and each item includes a timestamp, the operation performed, and the user who initiated the action. Consul compiles these events into JSON format for export.
Consul's audit logs only capture events initiated through the HTTP API. The audit log does not record operations that take place over the internal RPC communication channel used for agent communication.
For detailed specifications to configure the Consul Enterprise's audit logging behavior, review the Agent audit log configuration reference.
Configure audit logging
You must enable audit logging on every agent to accurately capture all operations performed through the HTTP API. To enable logging, add the audit configuration block to the agent's configuration.
Log to file
The following example configures a destination called My Sink. Audit logging operates continuously, which requires you to set rotation parameters. This example configures Consul to generate a JSON file at the destination path, and then rotate to a new file either when the log file size is greater than 25165824 bytes (24 megabytes) or when 24 hours pass without a log rotation. Because files rotate, audit events are saved in files named: /tmp/audit-<TIMESTAMP>.json.
audit {
enabled = true
sink "My sink" {
type = "file"
format = "json"
path = "/tmp/audit.json"
delivery_guarantee = "best-effort"
rotate_duration = "24h"
rotate_max_files = 15
rotate_bytes = 25165824
}
}
Log to standard out
The following example configures a destination called My Sink which emits audit logs to standard out.
audit {
enabled = true
sink "My sink" {
type = "file"
format = "json"
path = "/dev/stdout"
delivery_guarantee = "best-effort"
}
}
Audit logging configuration parameters are not part of Consul's reloadable configurations. You must fully restart the Consul agents to apply the configuration.
Review audit log content
In this example you will review logging for two different requests. Both of them use the /v1/catalog/service/ endpoint to retrieve information about the ssh service in the Consul catalog. The difference between the two requests is that one is not authenticated and the other uses a valid ACL token.
Anonymous request
The following example shows an HTTP request recorded in the audit log. At the bottom, the stage field is set to OperationStart, which indicates the agent began processing the request.
The value of the payload.auth.accessor_id field is the accessor ID of the ACL token included with the request. In this case, 00000000-0000-0000-0000-000000000002 is the ID of the anonymous token.
{
"created_at": "2025-07-31T14:32:38.559349128Z",
"event_type": "audit",
"payload": {
"id": "674891c9-a5a0-e0ba-c738-00cab3c42f16",
"version": "1",
"type": "HTTPEvent",
"timestamp": "2025-07-31T14:32:38.558390378Z",
"auth": {
"accessor_id": "00000000-0000-0000-0000-000000000002",
"description": "Anonymous Token",
"create_time": "2025-07-30T09:14:52.866798047Z"
},
"request": {
"operation": "GET",
"endpoint": "/v1/catalog/service/ssh",
"remote_addr": "127.0.0.1:45110",
"user_agent": "curl/7.88.1",
"host": "127.0.0.1:8500"
},
"stage": "OperationStart"
}
}
After Consul processes the request, it writes a corresponding log entry for the HTTP response. In the following example, the stage field is set to OperationComplete which indicates the agent has completed processing the request. Directly above, the status indicates the HTTP request was completed with 200 response.
{
"created_at": "2025-07-31T14:32:38.562146462Z",
"event_type": "audit",
"payload": {
"id": "c7d9614e-b110-729a-4c0b-6123f5c341a1",
"version": "1",
"type": "HTTPEvent",
"timestamp": "2025-07-31T14:32:38.561802712Z",
"auth": {
"accessor_id": "00000000-0000-0000-0000-000000000002",
"description": "Anonymous Token",
"create_time": "2025-07-30T09:14:52.866798047Z"
},
"request": {
"operation": "GET",
"endpoint": "/v1/catalog/service/ssh",
"remote_addr": "127.0.0.1:45110",
"user_agent": "curl/7.88.1",
"host": "127.0.0.1:8500"
},
"response": {
"status": "200"
},
"stage": "OperationComplete"
}
}
Authenticated request
The following example shows an HTTP request recorded in the audit log. At the bottom, the stage field is set to OperationStart, which indicates the agent began processing the request.
The value of the payload.auth.accessor_id field is the accessor ID of the ACL token included with the request.
{
"created_at": "2025-07-31T14:55:23.751575302Z",
"event_type": "audit",
"payload": {
"id": "bcaa81eb-0687-9d62-f288-bf82215fa5c6",
"version": "1",
"type": "HTTPEvent",
"timestamp": "2025-07-31T14:55:23.746568552Z",
"auth": {
"accessor_id": "540c5184-3bc7-852a-641c-cac2b46f2885",
"description": "Bootstrap Token (Global Management)",
"create_time": "2025-07-30T09:14:55.301395548Z"
},
"request": {
"operation": "GET",
"endpoint": "/v1/catalog/service/ssh",
"remote_addr": "127.0.0.1:54166",
"user_agent": "curl/7.88.1",
"host": "127.0.0.1:8500"
},
"stage": "OperationStart"
}
}
After Consul processes the request, it writes a corresponding log entry for the HTTP response. In the following example, the stage field is set to OperationComplete, which indicates the agent has completed processing the request. Directly above, the status indicates the HTTP request was completed with 200 response.
{
"created_at": "2025-07-31T14:55:23.754546469Z",
"event_type": "audit",
"payload": {
"id": "16193bc9-71cf-1d4b-a772-faba8b9dea00",
"version": "1",
"type": "HTTPEvent",
"timestamp": "2025-07-31T14:55:23.75438301Z",
"auth": {
"accessor_id": "540c5184-3bc7-852a-641c-cac2b46f2885",
"description": "Bootstrap Token (Global Management)",
"create_time": "2025-07-30T09:14:55.301395548Z"
},
"request": {
"operation": "GET",
"endpoint": "/v1/catalog/service/ssh",
"remote_addr": "127.0.0.1:54166",
"user_agent": "curl/7.88.1",
"host": "127.0.0.1:8500"
},
"response": {
"status": "200"
},
"stage": "OperationComplete"
}
}