Skip to content

Audit Logging ≥0.3.0

Licensed only

This feature requires an enterprise license.

Aspected can record all authentication and authorization events to a structured log file. This provides a complete trail of who accessed the system, what they attempted to do, and whether the request was permitted.

Configuration

To enable audit logging:

config.yml
server:
  audit:
    enabled: true
    path: ./audit        # Directory where audit log files are stored

Or via environment variables:

export ASPECTED_SERVER_AUDIT_ENABLED=true
export ASPECTED_SERVER_AUDIT_PATH=./audit

Log Format

Audit logs are written as JSONL (one JSON object per line) to daily rotating files named by date (e.g. 2026-08-10.jsonl). Each entry contains the following fields:

Field Type Description
timestamp string ISO 8601 timestamp with nanosecond precision.
authType string Authentication method used: JWT, StaticToken, or None.
token object (JWT only) Decoded token with header and payload sections.
ipAddress string Client IP address.
userAgent string Client User-Agent header value.
action string The action that was attempted (e.g. search_index, list_docs).
resource string The target resource name (e.g. index name), if applicable.
authStatus string Result of the authorization check.
message string Additional context when relevant (e.g. error details).

Auth Status Values

Status Description
Ok Request was authenticated and authorized.
Forbidden Token was valid but insufficient permissions.
MissingToken No authentication token was provided.
InvalidToken Token was malformed or signature verification failed.

Example Entries

Successful JWT request:

{
  "timestamp": "2026-08-10T12:37:24.732Z",
  "authType": "JWT",
  "token": {
    "header": { "alg": "HS256", "typ": "JWT" },
    "payload": { "sub": "1234567890", "iat": 1516239022, "acc": "deny", "indexes": "manage" }
  },
  "ipAddress": "127.0.0.1",
  "userAgent": "curl/7.54.1",
  "action": "list_docs",
  "resource": "test",
  "authStatus": "Ok"
}

Denied request (insufficient permissions):

{
  "timestamp": "2026-08-10T11:55:19.030Z",
  "authType": "JWT",
  "token": {
    "header": { "alg": "HS256", "typ": "JWT" },
    "payload": { "sub": "1234567890", "iat": 1516239022, "acc": "manage", "indexes": "deny" }
  },
  "ipAddress": "127.0.0.1",
  "userAgent": "curl/7.54.1",
  "action": "list_docs",
  "authStatus": "Forbidden"
}

Missing token:

{
  "timestamp": "2026-08-10T12:58:05.999Z",
  "authType": "None",
  "ipAddress": "127.0.0.1",
  "userAgent": "curl/7.54.1",
  "action": "/indexes/test2/search",
  "authStatus": "MissingToken",
  "message": "Token not set"
}

Storage Considerations

  • Audit logs are stored as daily files and are not automatically rotated or cleaned up.
  • In high-traffic environments, monitor disk usage in the audit directory.
  • Each log entry is written atomically (one line per event) making the files safe to tail or stream.