> ## Documentation Index
> Fetch the complete documentation index at: https://docs.golf.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit Log Schema

> Complete reference for the audit log entry structure and field definitions

# Audit Log Schema

Golf Gateway generates structured audit logs for all MCP traffic, authentication events, and security analysis. This reference documents the complete schema used for audit log entries.

## Quick Reference

| Category           | Key Fields                                                           | Purpose                            |
| ------------------ | -------------------------------------------------------------------- | ---------------------------------- |
| **Core**           | `timestamp`, `event_type`, `component`                               | Event identification and timing    |
| **Identity**       | `session_id`, `gateway_id`, `organization_id`                        | Session and gateway tracking       |
| **User**           | `user.sub`, `user.email`, `user.authenticated`                       | User identity (privacy-compliant)  |
| **Authentication** | `authentication.result`, `authentication.provider_type`              | Auth method and result             |
| **Security**       | `security.threat_score`, `security.blocked`, `security.was_scrubbed` | Threat detection and PII scrubbing |
| **MCP Protocol**   | `mcp_method`, `mcp_tool_name`, `mcp_*_payload`                       | MCP JSON-RPC details               |
| **Integrity**      | `sequence`, `prev_hash`, `integrity_hash`                            | Tamper-proof hash chain            |
| **Internal**       | `message`, `correlation`, `metadata`                                 | Internal processing (not exported) |

***

## Schema Overview

<Accordion title="View Complete Schema Example">
  ```json theme={null}
  {
    "timestamp": "2024-01-15T10:30:45.123456+00:00",
    "event_type": "mcp_request",
    "component": "mcp_parser",
    "session_id": "sess_abc123def456",
    "gateway_id": "550e8400-e29b-41d4-a716-446655440000",
    "gateway_name": "production-gateway",
    "organization_id": "org_xyz789",
    "client_info": {
      "name": "claude-desktop",
      "version": "1.2.3"
    },
    "authentication": {
      "method": "oauth2",
      "result": "success",
      "completed_at": 1705315845123,
      "provider_type": "auth0",
      "provider_name": "Production Auth0",
      "authorization_result": "granted",
      "scopes": ["read:mcp", "write:mcp"],
      "granted_at": 1705315845123,
      "user_id": "auth0|abc123",
      "email": "a1b2c3d4e5f6g7h8",
      "session_created": true,
      "session_type": "authenticated"
    },
    "security": {
      "threat_score": 0.02,
      "threats_detected": [],
      "analyzed": true,
      "blocked": false,
      "detection_method": "llm",
      "content_size_bytes": 256,
      "inference_ms": 38.5,
      "was_scrubbed": false,
      "entities_redacted": 0,
      "fields_masked": 0
    },
    "request": {
      "method": "POST",
      "path": "/finance-tools/mcp",
      "size_bytes": 256,
      "headers": {}
    },
    "upstream": {
      "host": "mcp-server.internal",
      "port": 3001,
      "url": "http://mcp-server.internal:3001",
      "name": "finance-tools"
    },
    "user": {
      "sub": "auth0|abc123",
      "email": "a1b2c3d4e5f6g7h8",
      "authenticated": true,
      "anonymous": false
    },
    "mcp_method": "tools/call",
    "mcp_tool_name": "get_account_balance",
    "mcp_request_payload": "{\n  \"jsonrpc\": \"2.0\",\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"get_account_balance\",\n    \"arguments\": {\"account_id\": \"12345\"}\n  },\n  \"id\": 1\n}",
    "mcp_request_tokens": 45,
    "has_error": false,
    "sequence": 12345,
    "prev_hash": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    "integrity_hash": "d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5"
  }
  ```
</Accordion>

Each audit log entry is a JSON object. The sections below document each field category in detail.

```json theme={null}
{
  "timestamp": "2024-01-15T10:30:45.123456+00:00",
  "event_type": "mcp_request",
  "component": "mcp_parser",
  "session_id": "sess_abc123",
  "gateway_id": "550e8400-e29b-41d4-a716-446655440000",
  "gateway_name": "production-gateway",
  "organization_id": "org_xyz789",
  "client_info": { ... },
  "authentication": { ... },
  "security": { ... },
  "request": { ... },
  "upstream": { ... },
  "user": { ... },
  "mcp_method": "tools/call",
  "mcp_tool_name": "get_weather",
  "mcp_request_payload": "{ ... }",
  "mcp_request_tokens": 150,
  "sequence": 12345,
  "prev_hash": "a1b2c3...",
  "integrity_hash": "d4e5f6..."
}
```

***

## Core Fields

These fields are present on every audit log entry.

| Field        | Type   | Description                                                                 |
| ------------ | ------ | --------------------------------------------------------------------------- |
| `timestamp`  | string | ISO 8601 timestamp with timezone (e.g., `2024-01-15T10:30:45.123456+00:00`) |
| `event_type` | string | Type of audit event (see [Event Types](#event-types))                       |
| `component`  | string | System component that generated the event                                   |

### Event Types

| Value                      | Description                             |
| -------------------------- | --------------------------------------- |
| `mcp_request`              | Standard MCP JSON-RPC request           |
| `mcp_response`             | Standard MCP JSON-RPC response          |
| `mcp_sampling_request`     | Sampling/createMessage request          |
| `mcp_sampling_response`    | Sampling/createMessage response         |
| `mcp_elicitation_request`  | Server-initiated elicitation request    |
| `mcp_elicitation_response` | Elicitation response from client        |
| `mcp_notification`         | MCP notification (no response expected) |
| `authentication`           | Authentication event                    |
| `security`                 | Security analysis event                 |

### Component Values

| Value        | Description                            |
| ------------ | -------------------------------------- |
| `mcp_parser` | MCP message parsing                    |
| `auth`       | Authentication and authorization       |
| `security`   | Security analysis and threat detection |

***

## Session and Identity

| Field             | Type           | Description                                  |
| ----------------- | -------------- | -------------------------------------------- |
| `session_id`      | string \| null | MCP protocol session identifier              |
| `gateway_id`      | string \| null | Gateway UUID (multi-gateway deployments)     |
| `gateway_name`    | string \| null | Human-readable gateway name                  |
| `organization_id` | string \| null | Organization UUID (multi-tenant deployments) |

***

## Integrity Fields

These fields provide tamper-proof audit logging through cryptographic hash chaining.

| Field            | Type            | Description                                |
| ---------------- | --------------- | ------------------------------------------ |
| `sequence`       | integer \| null | Monotonically increasing sequence number   |
| `prev_hash`      | string \| null  | HMAC-SHA256 hash of the previous log entry |
| `integrity_hash` | string \| null  | HMAC-SHA256 hash of the current entry      |

<Info>
  The integrity chain allows verification that no log entries have been modified or deleted. Configure the hash key with `GOLF_SECURITY_INTEGRITY_KEY`.
</Info>

***

## Client Info

Information about the MCP client, extracted from the `initialize` request.

| Field                 | Type   | Description                                        |
| --------------------- | ------ | -------------------------------------------------- |
| `client_info.name`    | string | MCP client name (e.g., "claude-desktop", "cursor") |
| `client_info.version` | string | MCP client version                                 |

**Example:**

```json theme={null}
{
  "client_info": {
    "name": "claude-desktop",
    "version": "1.2.3"
  }
}
```

***

## Authentication

Authentication and authorization results.

| Field                                 | Type           | Description                                                |
| ------------------------------------- | -------------- | ---------------------------------------------------------- |
| `authentication.method`               | string         | Authentication method (default: `oauth2`)                  |
| `authentication.result`               | string         | `success`, `failed`, or `anonymous`                        |
| `authentication.completed_at`         | integer        | Unix timestamp in milliseconds                             |
| `authentication.provider_type`        | string \| null | IDP type: `auth0`, `okta`, `microsoft-entra-id`, `descope` |
| `authentication.provider_name`        | string \| null | Human-readable provider name                               |
| `authentication.authorization_result` | string         | `granted`, `denied`, or `anonymous`                        |
| `authentication.scopes`               | array          | Granted OAuth scopes                                       |
| `authentication.granted_at`           | integer        | Unix timestamp in milliseconds                             |
| `authentication.user_id`              | string \| null | User subject identifier                                    |
| `authentication.email`                | string \| null | User email (hashed before export)                          |
| `authentication.name`                 | string \| null | User display name (removed before export)                  |
| `authentication.session_created`      | boolean        | Whether a new session was created                          |
| `authentication.session_type`         | string         | `authenticated` or `anonymous`                             |

**Example:**

```json theme={null}
{
  "authentication": {
    "method": "oauth2",
    "result": "success",
    "completed_at": 1705315845123,
    "provider_type": "auth0",
    "provider_name": "Production Auth0",
    "authorization_result": "granted",
    "scopes": ["read:mcp", "write:mcp"],
    "granted_at": 1705315845123,
    "user_id": "auth0|abc123",
    "email": "a1b2c3d4e5f6g7h8",
    "session_created": true,
    "session_type": "authenticated"
  }
}
```

***

## Security

Security analysis and threat detection results.

| Field                         | Type            | Description                                                |
| ----------------------------- | --------------- | ---------------------------------------------------------- |
| `security.threat_score`       | float           | Threat score from 0.0 (safe) to 1.0 (malicious)            |
| `security.threats_detected`   | array           | List of detected threat types                              |
| `security.analyzed`           | boolean         | Whether security analysis was performed                    |
| `security.skipped_reason`     | string \| null  | Reason analysis was skipped                                |
| `security.blocked`            | boolean         | Whether the request/response was blocked                   |
| `security.detection_method`   | string \| null  | `llm`, `pattern`, or `rate_limit`                          |
| `security.threat_category`    | string \| null  | `prompt_injection`, `jailbreak`, `data_exfiltration`, etc. |
| `security.content_size_bytes` | integer \| null | Size of analyzed content in bytes                          |
| `security.inference_ms`       | float \| null   | LLM inference duration in milliseconds                     |

### PII Scrubbing Fields

| Field                         | Type          | Description                             |
| ----------------------------- | ------------- | --------------------------------------- |
| `security.was_scrubbed`       | boolean       | Whether content was scrubbed for PII    |
| `security.entities_redacted`  | integer       | Total PII entities redacted             |
| `security.fields_masked`      | integer       | Total fields masked by name             |
| `security.entities_by_type`   | object        | Breakdown of redacted entities by type  |
| `security.redacted_paths`     | array         | JSON paths where entities were redacted |
| `security.masked_field_names` | array         | Field names that were masked            |
| `security.custom_rules_fired` | array         | Custom regex rules that matched         |
| `security.scrub_duration_ms`  | float \| null | Scrubbing duration in milliseconds      |

**Example (threat detected):**

```json theme={null}
{
  "security": {
    "threat_score": 0.95,
    "threats_detected": ["prompt_injection"],
    "analyzed": true,
    "blocked": true,
    "detection_method": "llm",
    "threat_category": "prompt_injection",
    "content_size_bytes": 1024,
    "inference_ms": 45.2
  }
}
```

**Example (PII scrubbed):**

```json theme={null}
{
  "security": {
    "threat_score": 0.0,
    "threats_detected": [],
    "analyzed": true,
    "blocked": false,
    "was_scrubbed": true,
    "entities_redacted": 3,
    "fields_masked": 1,
    "entities_by_type": {
      "email": 2,
      "phone": 1
    },
    "redacted_paths": ["result.content[0].text"],
    "masked_field_names": ["ssn"],
    "scrub_duration_ms": 12.5
  }
}
```

***

## Request

Request context information.

| Field                | Type            | Description                                        |
| -------------------- | --------------- | -------------------------------------------------- |
| `request.method`     | string \| null  | HTTP or MCP method                                 |
| `request.path`       | string \| null  | Request path or resource                           |
| `request.size_bytes` | integer \| null | Request size in bytes                              |
| `request.headers`    | object          | Request headers (sanitized to empty before export) |

***

## Upstream

Information about the upstream MCP server.

| Field           | Type           | Description                    |
| --------------- | -------------- | ------------------------------ |
| `upstream.host` | string         | Upstream server hostname       |
| `upstream.port` | integer        | Upstream server port (1-65535) |
| `upstream.url`  | string \| null | Original URL for display       |
| `upstream.name` | string \| null | Upstream server name           |

**Example:**

```json theme={null}
{
  "upstream": {
    "host": "mcp-server.internal",
    "port": 3001,
    "name": "finance-tools"
  }
}
```

***

## User

User identity information.

| Field                | Type           | Description                                         |
| -------------------- | -------------- | --------------------------------------------------- |
| `user.sub`           | string \| null | User subject identifier                             |
| `user.email`         | string \| null | User email (hashed to 16-char SHA256 before export) |
| `user.name`          | string \| null | User display name (removed before export)           |
| `user.authenticated` | boolean        | Whether user is authenticated                       |
| `user.anonymous`     | boolean        | Whether user is anonymous                           |

<Warning>
  For privacy compliance, `user.email` is hashed and `user.name` is removed before export to external systems.
</Warning>

***

## MCP Protocol Fields

### Extracted Fields

These fields are extracted from MCP messages for efficient querying and aggregation.

| Field              | Type           | Description                                                |
| ------------------ | -------------- | ---------------------------------------------------------- |
| `mcp_method`       | string \| null | MCP JSON-RPC method (e.g., `tools/call`, `resources/read`) |
| `mcp_tool_name`    | string \| null | Tool name from `tools/call` or `tools/list`                |
| `mcp_resource_uri` | string \| null | Resource URI from `resources/read` or `resources/list`     |
| `mcp_prompt_name`  | string \| null | Prompt name from `prompts/get` or `prompts/list`           |

### Raw Payloads

| Field                  | Type           | Description                       |
| ---------------------- | -------------- | --------------------------------- |
| `mcp_request_payload`  | string \| null | Raw MCP request JSON (formatted)  |
| `mcp_response_payload` | string \| null | Raw MCP response JSON (formatted) |

### Token Estimates

| Field                 | Type            | Description                        |
| --------------------- | --------------- | ---------------------------------- |
| `mcp_request_tokens`  | integer \| null | Estimated token count for request  |
| `mcp_response_tokens` | integer \| null | Estimated token count for response |

### Error Detection

| Field       | Type            | Description                            |
| ----------- | --------------- | -------------------------------------- |
| `has_error` | boolean \| null | Whether MCP response contains an error |

***

## Elicitation Fields

Fields for server-initiated user input requests (MCP elicitation).

| Field                    | Type           | Description                                   |
| ------------------------ | -------------- | --------------------------------------------- |
| `mcp_elicitation_mode`   | string \| null | Elicitation mode: `form` or `url`             |
| `mcp_elicitation_id`     | string \| null | Elicitation ID for URL mode correlation       |
| `mcp_elicitation_action` | string \| null | User action: `accept`, `decline`, or `cancel` |

***

## Threat Analysis

Detailed threat analysis results (when available).

| Field                               | Type           | Description                      |
| ----------------------------------- | -------------- | -------------------------------- |
| `threat_analysis.threat_score`      | float          | Threat score from 0.0 to 1.0     |
| `threat_analysis.detected_patterns` | array          | List of detected threat patterns |
| `threat_analysis.severity`          | string         | `critical`, `incident`, or `low` |
| `threat_analysis.remediation`       | string \| null | Suggested remediation action     |

***

## Session Statistics

Aggregate session statistics (for monitoring events).

| Field                               | Type    | Description                  |
| ----------------------------------- | ------- | ---------------------------- |
| `session_stats.active_sessions`     | integer | Number of active sessions    |
| `session_stats.total_created`       | integer | Total sessions created       |
| `session_stats.total_authenticated` | integer | Total authenticated sessions |
| `session_stats.total_anonymous`     | integer | Total anonymous sessions     |

***

## Internal Fields

These fields are present in audit log entries for internal processing but are excluded from external exports and the GraphQL API.

| Field         | Type           | Description                                                          |
| ------------- | -------------- | -------------------------------------------------------------------- |
| `message`     | object \| null | Raw MCP message data for internal processing                         |
| `correlation` | object \| null | Request/response correlation for internal tracking                   |
| `metadata`    | object         | Additional metadata for legacy compatibility and flexible extensions |

<Warning>
  These fields are for internal use only. They are not exposed through the GraphQL API and are excluded from export payloads to external systems (Elasticsearch, OpenTelemetry, Sentinel).
</Warning>

***

## Complete Example

**MCP Request Event:**

```json theme={null}
{
  "timestamp": "2024-01-15T10:30:45.123456+00:00",
  "event_type": "mcp_request",
  "component": "mcp_parser",
  "session_id": "sess_abc123def456",
  "gateway_id": "550e8400-e29b-41d4-a716-446655440000",
  "gateway_name": "production-gateway",
  "organization_id": "org_xyz789",
  "client_info": {
    "name": "claude-desktop",
    "version": "1.2.3"
  },
  "authentication": {
    "method": "oauth2",
    "result": "success",
    "completed_at": 1705315845123,
    "provider_type": "auth0",
    "authorization_result": "granted",
    "scopes": ["read:mcp", "write:mcp"],
    "granted_at": 1705315845123,
    "user_id": "auth0|abc123",
    "session_type": "authenticated"
  },
  "security": {
    "threat_score": 0.02,
    "threats_detected": [],
    "analyzed": true,
    "blocked": false,
    "detection_method": "llm",
    "content_size_bytes": 256,
    "inference_ms": 38.5
  },
  "upstream": {
    "host": "mcp-server.internal",
    "port": 3001,
    "name": "finance-tools"
  },
  "user": {
    "sub": "auth0|abc123",
    "authenticated": true,
    "anonymous": false
  },
  "mcp_method": "tools/call",
  "mcp_tool_name": "get_account_balance",
  "mcp_request_payload": "{\n  \"jsonrpc\": \"2.0\",\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"get_account_balance\",\n    \"arguments\": {\"account_id\": \"12345\"}\n  },\n  \"id\": 1\n}",
  "mcp_request_tokens": 45,
  "has_error": false,
  "sequence": 12345,
  "prev_hash": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "integrity_hash": "d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5"
}
```

**Security Blocked Event:**

```json theme={null}
{
  "timestamp": "2024-01-15T10:31:12.789012+00:00",
  "event_type": "mcp_request",
  "component": "security",
  "session_id": "sess_xyz789abc123",
  "gateway_name": "production-gateway",
  "security": {
    "threat_score": 0.97,
    "threats_detected": ["prompt_injection"],
    "analyzed": true,
    "blocked": true,
    "detection_method": "llm",
    "threat_category": "prompt_injection",
    "content_size_bytes": 2048,
    "inference_ms": 52.3
  },
  "threat_analysis": {
    "threat_score": 0.97,
    "detected_patterns": ["instruction_override", "role_manipulation"],
    "severity": "critical",
    "remediation": "Block request and notify security team"
  },
  "mcp_method": "tools/call",
  "mcp_tool_name": "execute_query",
  "sequence": 12346,
  "integrity_hash": "f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1"
}
```

***

## Export Destinations

Audit logs are exported to configured destinations with automatic schema mapping:

| Destination        | Index Pattern         | Documentation                                                                  |
| ------------------ | --------------------- | ------------------------------------------------------------------------------ |
| Elasticsearch      | `{prefix}-YYYY.MM.DD` | [Export to Elasticsearch](/gateway/guides/audit-trail/export-to-elasticsearch) |
| OpenTelemetry      | OTLP logs             | [Export to OpenTelemetry](/gateway/guides/audit-trail/export-to-opentelemetry) |
| Microsoft Sentinel | Custom DCR table      | [Export to Sentinel](/gateway/guides/audit-trail/export-to-sentinel)           |

<Info>
  Each destination applies field-specific transformations. For example, Elasticsearch uses daily indices while Sentinel transforms fields to PascalCase for KQL compatibility.
</Info>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Environment Variables" icon="terminal" href="/gateway/reference/environment-variables">
    Configure Golf Gateway using environment variables
  </Card>

  <Card title="YAML Configuration" icon="file-code" href="/gateway/reference/yaml-schema">
    Distributed mode configuration for GitOps deployments
  </Card>

  <Card title="Export to Elasticsearch" icon="magnifying-glass" href="/gateway/guides/audit-trail/export-to-elasticsearch">
    Set up audit log export to Elasticsearch
  </Card>

  <Card title="Export to Sentinel" icon="shield" href="/gateway/guides/audit-trail/export-to-sentinel">
    Set up audit log export to Microsoft Sentinel
  </Card>
</CardGroup>