# Audit

The gateway produces audit logs for every policy decision that is not `allow`, connection event, API access, bundle management action, and trace. Audit logs are intended for SIEM integration and support multiple output formats.

## Event types

| Event                      | Description                                                            |
| -------------------------- | ---------------------------------------------------------------------- |
| `connection.start`         | client or leafnode connected                                           |
| `connection.end`           | client or leafnode disconnected                                        |
| `policy.action`            | rule evaluation produced a `deny`, `error`, or `suspend` action        |
| `management.api`           | mutating management API was accessed                                   |
| `management.informational` | read-only management API was accessed (info, stats, list endpoints)    |
| `management.policy`        | policy management API was accessed                                     |
| `management.bundle`        | bundle was installed, uninstalled, activated, deactivated, or upgraded |
| `log.protocol`             | raw protocol data logged by a `log` rule action                        |
| `trace.start`              | trace capture started on a connection                                  |
| `trace.end`                | trace capture ended                                                    |

## Configuration

Audit logging is configured in the `audit` section of the gateway config. It requires a log file directory, a trace directory, and at least one processor:

```
audit:

  log_file_dir: logs

  client_trace_dir: traces

  processors:

    - name: all_events

      type: file

      format: text

      config:

        file: logs/audit.log
```

### Multiple processors

Multiple processors can run simultaneously, each with different formats and event filters. This allows routing different event types to different outputs:

```
audit:

  log_file_dir: logs

  client_trace_dir: traces

  processors:

    - name: all_events

      type: file

      format: text

      config:

        file: logs/audit.log



    - name: connections_cef

      type: file

      format: cef

      events:

        - connection.start

        - connection.end

      config:

        file: logs/connections.log



    - name: policy_json

      type: file

      format: json

      events:

        - policy.action

      config:

        file: logs/policy.log



    - name: siem

      type: nats

      format: json

      config:

        urls:

          - nats://siem-collector:4222

        credentials:

          user_name: audit

          password: secret
```

### Processor types

| Type   | Description                     |
| ------ | ------------------------------- |
| `file` | write events to a file          |
| `log`  | write events to stdout          |
| `nats` | publish events to a NATS server |

### Output formats

| Format | Description                                               |
| ------ | --------------------------------------------------------- |
| `text` | key=value pairs, human-readable                           |
| `json` | one JSON object per line, suitable for machine processing |
| `cef`  | Common Event Format (ArcSight), suitable for SIEM systems |

#### Text format

```
time=2026-04-07T19:22:33.647+00:00 type=com.synadia.protect.v1.policy.action id=7YepgNmVxR1MBbzId8iCGH device=my_gateway protocol=client ts=2026-04-07T19:22:33.647Z port=clients src=127.0.0.1 spt=61691 dst=192.168.1.88 dpt=61692 cuuid=7YepgNmVxR1MBbzId8iCBF cid=1 rid=34728723 action=suspend reason=message header matches suspend rules policy_ref=suspend-test@1.0.0/rules/builtins/com_synadia_protect_builtins_v1_suspend_header_message.yaml#1
```

#### JSON format

```
{

  "type": "com.synadia.protect.v1.policy.action",

  "id": "7bxjY3UTuqk3Xfl1uPvvhw",

  "device": "my_gateway",

  "protocol": "client",

  "ts": "2026-04-07T19:38:46.702Z",

  "port": "clients",

  "src": "127.0.0.1",

  "spt": 49315,

  "dst": "192.168.1.88",

  "dpt": 49316,

  "cuuid": "7bxjY3UTuqk3Xfl1uPvvby",

  "cid": 2,

  "rid": 34773032,

  "action": "suspend",

  "reason": "message header matches suspend rules",

  "policy": {

    "policy_ref": "suspend-test@1.0.0/rules/builtins/com_synadia_protect_builtins_v1_suspend_header_message.yaml#1",

    "signature": "b20e37bc12b1dfce90e52cdf0e32617aa17a83a584fa011c5caec3a25ee4f84f"

  }

}
```

#### CEF format

```
CEF:0|Synadia|Protect|1.0.0|POLICY|Protect Policy Action|8|rt=1775590726702 dvchost=my_gateway externalId=7bxjY3UTuqk3Xfl1uPvvhw cs7=clients cs7Label=PortName src=127.0.0.1 spt=49315 dst=192.168.1.88 dpt=49316 cs1=client cs1Label=NATSProtocol cs4=7bxjY3UTuqk3Xfl1uPvvby cs4Label=NATSConnUUID act=suspend cs2=suspend-test@1.0.0/rules/builtins/com_synadia_protect_builtins_v1_suspend_header_message.yaml#1 cs2Label=NATSPolicyRef reason=message header matches suspend rules cn3=2 cn3Label=NATSConnID cn2=34773032 cn2Label=NATSRemoteConnID
```

The CEF format uses labeled extension fields (`cs1`-`cs13`, `cn2`, `cn3`) following the ArcSight Common Event Format specification.

### Event filtering

Omit the `events` field to capture all events. Specify a list to capture only specific types:

```
processors:

  - name: policy_only

    type: file

    format: json

    events:

      - policy.action

    config:

      file: logs/policy.log
```

Use `exclude_events` to capture everything except specific types:

```
processors:

  - name: no_protocol_logs

    type: file

    format: json

    exclude_events:

      - log.protocol

    config:

      file: logs/audit.log
```

`events` and `exclude_events` are mutually exclusive.

## Event fields

Every event includes a unique event ID, device name (gateway name), and timestamp. Connection-related events include source/destination IPs and ports, connection UUID, and CID/RID.

### connection.start

Logged when a client or leafnode connects:

```
time=2026-04-07T16:46:52.659+00:00 type=com.synadia.protect.v1.connection.start id=s821ydrHgm0IJwcXVAeoKl device=my_gateway protocol=client ts=2026-04-07T16:46:52.659Z port=clients src=127.0.0.1 spt=53714 dst=192.168.1.88 dpt=53715 cuuid=s821ydrHgm0IJwcXVAeoH5 cid=173 rid=0 start=2026-04-07T16:46:52.614Z
```

| Field        | Description                                                        |
| ------------ | ------------------------------------------------------------------ |
| `id`         | unique event ID                                                    |
| `device`     | gateway name                                                       |
| `protocol`   | `client` or `leaf`                                                 |
| `port`       | gateway port name                                                  |
| `src`, `spt` | client source IP and port                                          |
| `dst`, `dpt` | backend destination IP and port                                    |
| `cuuid`      | connection UUID (persistent across events for the same connection) |
| `cid`        | gateway connection ID                                              |
| `rid`        | remote connection ID on the backend (0 if not yet assigned)        |

### connection.end

Logged when a connection closes. Includes traffic counters:

```
time=2026-04-07T16:48:50.527+00:00 type=com.synadia.protect.v1.connection.end id=s821ydrHgm0IJwcXVAeunb device=my_gateway protocol=client ts=2026-04-07T16:48:50.527Z port=clients src=127.0.0.1 spt=53714 dst=192.168.1.88 dpt=53715 cuuid=s821ydrHgm0IJwcXVAeoH5 cid=173 rid=34312065 bytes_in=150167 bytes_out=0 messages_in=399 messages_out=0 start=2026-04-07T16:46:52.614Z end=2026-04-07T16:48:50.527Z
```

Additional fields beyond `connection.start`:

| Field                         | Description                                                                                                                                                                                       |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bytes_in`, `bytes_out`       | total protocol bytes for data messages (`MSG`, `HMSG`, `PUB`, `HPUB`) — includes verb, subject, reply-to, headers, and payload. Does not count `SUB`, `UNSUB`, `PING`/`PONG`, or `CONNECT`/`INFO` |
| `messages_in`, `messages_out` | total data messages transferred (same message types as bytes)                                                                                                                                     |
| `start`, `end`                | connection lifetime                                                                                                                                                                               |

### policy.action

Logged when a rule evaluation produces a `deny`, `error`, or `suspend` action. `allow` actions are silent. `log` actions produce a separate `log.protocol` event instead.

note

`policy.action` events are generated by rule evaluations only. Admin operations like `protect admin disconnect` and `protect admin suspend` are logged as `management.api` events (e.g., `request=client_suspend`).

```
time=2026-04-07T16:12:25.124+00:00 type=com.synadia.protect.v1.policy.action id=s821ydrHgm0IJwcXVAd0I7 device=my_gateway protocol=client ts=2026-04-07T16:12:25.124Z port=clients src=127.0.0.1 spt=61485 dst=192.168.1.88 dpt=61486 cuuid=s821ydrHgm0IJwcXVAd0ER cid=167 rid=34221861 action=deny reason=message payload matches denied pattern message= policy_ref=first-bundle@1.0.0/rules/builtins/com_synadia_protect_builtins_v1_deny_payload_message.yaml#1 policy_signature=850cfeb8e20055d55e5905a6900a8831f338ca0a68d9c470becba4238ef142cf
```

| Field              | Description                                                  |
| ------------------ | ------------------------------------------------------------ |
| `action`           | `deny`, `error`, or `suspend`                                |
| `reason`           | why the action was taken                                     |
| `policy_ref`       | bundle name, version, and rule file that produced the action |
| `policy_signature` | checksum of the rule                                         |

The event ID in a `policy.action` matches the error ID returned to the client on deny — this is how you correlate a client error to the audit trail.

### management.api

Logged for mutating management API requests (disconnect, suspend, install, etc.):

```
time=2026-04-07T16:52:08.544+00:00 type=com.synadia.protect.v1.management.api id=s821ydrHgm0IJwcXVAf5iF device=my_gateway ts=2026-04-07T16:52:08.544Z request=client_disconnect start=2026-04-07T16:52:08.544Z request_id=s821ydrHgm0IJwcXVAf5gP end=2026-04-07T16:52:08.544Z status=200
```

| Field          | Description            |
| -------------- | ---------------------- |
| `request`      | API operation name     |
| `request_id`   | request correlation ID |
| `start`, `end` | request duration       |
| `status`       | HTTP-style status code |

### management.informational

Logged for read-only management API requests (server_info, server_stats, bundle_list, bundle_source, port_list, profiles_list, fleet_status, builtin_rules). Same structure as `management.api` but logged at debug level on the server:

```
time=2026-04-07T16:52:08.544+00:00 type=com.synadia.protect.v1.management.informational id=s821ydrHgm0IJwcXVAf5iF device=my_gateway ts=2026-04-07T16:52:08.544Z request=profiles_list start=2026-04-07T16:52:08.544Z request_id=s821ydrHgm0IJwcXVAf5gP end=2026-04-07T16:52:08.544Z status=200
```

### management.bundle

Logged for bundle lifecycle operations (install, uninstall, activate, deactivate, upgrade).

### trace.start / trace.end

Logged when a trace capture starts or stops on a connection. Includes the trace profile ID and connection details.

## Correlation

Every event has a unique `id`. Connection events share a `cuuid` (connection UUID) that persists across `connection.start`, `policy.action`, `trace.start`, and `connection.end` for the same connection — enabling full session reconstruction.

The event ID in a `policy.action` is the same ID returned to the client in the deny error message, linking the client-side error to the server-side audit entry.

See the [Configuration Reference](/protect/1.0/reference/configuration.md#audit) for all processor configuration options.
