Breadcrumbs

BlastShield Remote Syslog Event Reference

This document describes the machine-readable events that BlastShield forwards to remote syslog receivers. It is intended for integrators ingesting the BlastShield event feed into a third-party system (SIEM, log aggregator, monitoring platform).

Syslog message format

Each event is sent as a UDP syslog message:

<PRI>Mmm dd hh:mm:ss blastshield-<network id> orchestrator: <payload>

  • PRI uses facility local0 (16); the severity encodes the event priority: Info (6), Warning (4), Error (3), Critical (2).

  • <network id> is the 16-character hexadecimal ID of the BlastShield network.

  • The payload is a single flat object. The tables below list the complete payload of each event.

Each syslog receiver is configured with a format and one or more scopes:

Format

Payload

json

JSON object, e.g. {"category": "endpoint", "id": "17", "name": "PLC-1", "event": "unreachable", ...}

comma

Comma-separated KEY=value pairs with uppercase keys, e.g. CATEGORY=ENDPOINT, ID=17, NAME=PLC-1, EVENT=UNREACHABLE, .... The values of CATEGORY, EVENT and ACTION are uppercased; array values are joined with |.

human

Human-readable event text only (events scope only; not covered by this document).

Scope

Content

events

Entity events: node status, endpoints, high availability, proxies, remote desktop.

audit

Configuration audit trail (create/update/delete operations).

connections

Per-connection logs from Gateways and Agents.

The audit and connections scopes are only available in the json and comma formats. Structured values such as audit changes are best consumed via the json format.

Only events with a machine-readable representation are forwarded in the json and comma formats. Purely informational entries that exist in the orchestrator event log (for example device console, DHCP, SSH and system messages) are not sent to machine-format receivers.

Most payloads contain an event field that discriminates the event type within a category. Exceptions are noted below (proxy requests and audit records). Unless stated otherwise, all field values are strings. Entity IDs are either 16-character hexadecimal node IDs (agent, gateway, orchestrator, user categories) or numeric IDs in decimal form (endpoint, proxy categories).

Scope: events

Node categories: agent, gateway, orchestrator, user

These four categories describe nodes in the BlastShield network and share a common event set. The category value reflects the type of the node the event relates to.

Status events

Event: login

Emitted when a node connects to the Orchestrator and comes online.

Severity: Info

Field

Type

Description

category

string (enum)

Type of the node: agent, gateway, orchestrator or user.

id

string

16-character hexadecimal node ID.

name

string

Display name of the node.

event

string (enum)

Always login.
Event: logout

Emitted when a node disconnects from the Orchestrator and goes offline.

Severity: Info for user nodes, Warning for all other node types (an offline gateway, agent or orchestrator is usually a fault condition).

Field

Type

Description

category

string (enum)

Type of the node: agent, gateway, orchestrator or user.

id

string

16-character hexadecimal node ID.

name

string

Display name of the node.

event

string (enum)

Always logout.
Event: register_public_key

Emitted when a newly invited node completes registration and its public key is stored by the Orchestrator. The category, id and name refer to the newly registered node.

Severity: Info

Field

Type

Description

category

string (enum)

Type of the node: agent, gateway, orchestrator or user.

id

string

16-character hexadecimal node ID.

name

string

Display name of the node.

event

string (enum)

Always register_public_key.

Location events

Event: new_transport_address

Emitted when the public (transport) IP address of a node changes, including on first connection. The location is derived from a GeoIP lookup of the address.

Severity: Info

Field

Type

Description

category

string (enum)

Type of the node: agent, gateway, orchestrator or user.

id

string

16-character hexadecimal node ID.

name

string

Display name of the node.

event

string (enum)

Always new_transport_address.

public_ip

string

The node’s new public IPv4 address in dotted-quad notation.

location

array of strings

GeoIP-resolved location as [city, region, country]. Unresolvable parts are "Unknown"; if no GeoIP data is available at all, the array is the single element ["Unknown"].

Firmware events

Event: version_change

Emitted when a node reports a software/firmware version that differs from the previously known version (typically after an upgrade). Not produced for the user category.

Severity: Info

Field

Type

Description

category

string (enum)

Type of the node: agent, gateway or orchestrator.

id

string

16-character hexadecimal node ID.

name

string

Display name of the node.

event

string (enum)

Always version_change.

previous_version

string

Version string before the change.

new_version

string

Version string reported after the change.

Category: gateway — High-Availability events

Events for gateways deployed as high-availability (HA) groups.

Event: ha_active_changed

Emitted when the active member of an HA gateway group changes (failover or failback).

Severity: Info

Field

Type

Description

category

string (enum)

Always gateway.

id

string

16-character hexadecimal node ID of the primary gateway of the HA group.

name

string

Display name of the primary gateway of the HA group.

event

string (enum)

Always ha_active_changed.

ha_active_id

string

16-character hexadecimal node ID of the newly active gateway.

ha_active_name

string

Display name of the newly active gateway.
Event: ha_state_changed

Emitted when the overall state of an HA gateway group changes, based on how many members of the group are online.

Severity: Info (online), Warning (degraded), Error (offline)

Field

Type

Description

category

string (enum)

Always gateway.

id

string

16-character hexadecimal node ID of the primary gateway of the HA group.

name

string

Display name of the primary gateway of the HA group.

event

string (enum)

Always ha_state_changed.

state

string (enum)

New group state. One of: online (all members online), degraded (some members offline), offline (all members offline).

online_count

integer

Number of group members currently online.

total_count

integer

Total number of members in the HA group.

Category: endpoint

Events for protected endpoints (devices behind a Gateway). Reachability and MAC address information originates from the Gateway currently serving the endpoint.

Status events

Event: reachable

Emitted when a previously unreachable endpoint becomes reachable from its Gateway.

Severity: Info

Field

Type

Description

category

string (enum)

Always endpoint.

id

string

Numeric endpoint ID in decimal form.

name

string

Configured name of the endpoint.

event

string (enum)

Always reachable.

address

string

The endpoint’s IPv4 address.

active_gateway_id

string

16-character hexadecimal node ID of the Gateway (the active member of an HA group) that observed the endpoint.
Event: unreachable

Emitted when an endpoint stops being reachable. This happens either because the serving Gateway can no longer reach the endpoint on the network, or because the Orchestrator determines that the endpoint can no longer be reached (Gateway offline, endpoint moved, endpoint disabled). In the latter case the additional reason field is present.

Severity: Warning

Field

Type

Description

category

string (enum)

Always endpoint.

id

string

Numeric endpoint ID in decimal form.

name

string

Configured name of the endpoint.

event

string (enum)

Always unreachable.

address

string

The endpoint’s IPv4 address.

active_gateway_id

string

16-character hexadecimal node ID of the Gateway responsible for the endpoint at the time of the event.

reason

string (enum)

Optional. Present only when the Orchestrator marked the endpoint unreachable. One of: Gateway offline, Endpoint moved to other gateway, Endpoint disabled. Absent when the Gateway itself reported the endpoint as unreachable.

MAC Address events

Event: mac_address_change

Emitted when the Gateway observes a different MAC address for an endpoint’s IP address than previously recorded. This can indicate hardware replacement — or ARP spoofing — and is therefore logged as a warning.

Severity: Warning

Field

Type

Description

category

string (enum)

Always endpoint.

id

string

Numeric endpoint ID in decimal form.

name

string

Configured name of the endpoint.

event

string (enum)

Always mac_address_change.

address

string

The endpoint’s IPv4 address.

active_gateway_id

string

16-character hexadecimal node ID of the Gateway that observed the change.

old_mac_address

string

Previously recorded MAC address.

new_mac_address

string

Newly observed MAC address.

Category: proxy

Events for HTTP proxies published through BlastShield.

Event: proxied HTTP request

Emitted for each HTTP request forwarded through a BlastShield proxy by an Agent.

Note: this payload has no event discriminator field. Consumers can identify it by category = proxy together with the presence of the request field.

Severity: Info

Field

Type

Description

category

string (enum)

Always proxy.

id

string

Numeric proxy ID in decimal form.

name

string

Configured name of the proxy.

request

string

The proxied request line: <METHOD> http://<host><path> for plain HTTP requests, or CONNECT <host> for tunneled (HTTPS) requests.

client

string

Display name of the BlastShield node (user or agent) that issued the request.

proxy_agent_id

string

16-character hexadecimal node ID of the Agent that forwarded the request.

proxy_agent_name

string

Display name of the Agent that forwarded the request.

Categories: agent, endpoint — Remote Desktop (BlastAccess) events

Events for hosts accessed via BlastAccess remote desktop. A remote desktop host is either an Agent or an Endpoint; the category, id and name fields identify the host and are shared by all events in this section:

  • category (string, enum): agent or endpoint — type of the remote desktop host.

  • id (string): 16-character hexadecimal node ID for agent, numeric ID in decimal form for endpoint.

  • name (string): display name of the host.

Event: certificate_issued

Emitted when the BlastAccess controller issues a new TLS certificate to the remote desktop agent running on a host.

Severity: Info

Field

Type

Description

category

string (enum)

agent or endpoint — type of the remote desktop host.

id

string

Host ID (see above).

name

string

Display name of the host.

event

string (enum)

Always certificate_issued.

issued_for

string

IPv4 address the certificate was issued for.
Event: state_change

Emitted when the state of the remote desktop agent on a host changes.

Severity: Info (online), Warning (offline), Error (cert_mismatch)

Field

Type

Description

category

string (enum)

agent or endpoint — type of the remote desktop host.

id

string

Host ID (see above).

name

string

Display name of the host.

event

string (enum)

Always state_change.

previous_state

string (enum)

State before the change. One of: online, offline, cert_mismatch.

new_state

string (enum)

State after the change. Same values as previous_state. cert_mismatch means the agent presented an unexpected certificate.
Event: new_session

Emitted when a remote desktop session to the host is started.

Severity: Info

Field

Type

Description

category

string (enum)

agent or endpoint — type of the remote desktop host.

id

string

Host ID (see above).

name

string

Display name of the host.

event

string (enum)

Always new_session.

client_id

string

16-character hexadecimal node ID of the user starting the session.

client

string

Display name of the user starting the session.

client_public_ip

string

Public IPv4 address of the user.

client_location

array of strings

GeoIP-resolved location of the user, same format as new_transport_address.

permissions

array of strings

Permissions granted for the session. Values: control, clipboard, upload, download, printer.

record

boolean

Whether the session is being recorded.
Event: recording_skipped_no_storage

Emitted when a session was configured to be recorded but no session-recording storage is configured; the session runs unrecorded.

Severity: Warning

Field

Type

Description

category

string (enum)

agent or endpoint — type of the remote desktop host.

id

string

Host ID (see above).

name

string

Display name of the host.

event

string (enum)

Always recording_skipped_no_storage.

client_id

string

16-character hexadecimal node ID of the session’s user.

client

string

Display name of the session’s user.
Events: recording_deleted_retention, recording_deleted_manual

Emitted when a session recording is deleted, either automatically by the retention policy (recording_deleted_retention) or manually by an administrator (recording_deleted_manual).

Severity: Info

Field

Type

Description

category

string (enum)

agent or endpoint — type of the remote desktop host.

id

string

Host ID (see above).

name

string

Display name of the host.

event

string (enum)

recording_deleted_retention or recording_deleted_manual.

session_id

string

Identifier of the recorded session.

start_time

integer

Recording start as a Unix timestamp (seconds).

end_time

integer

Recording end as a Unix timestamp (seconds).

users

array of strings

Display names of the users that participated in the recorded session.

total_size

integer

Total size of the deleted recording in bytes.

deleted_by

string

Only for recording_deleted_manual. Name of the administrator that deleted the recording.

Scope: audit

Category: audit

One record per configuration change made through the BlastShield API or UI. Audit payloads have no id/name fields and no event discriminator; consumers can identify them by category = audit, with action discriminating the operation.

Severity: Info

Field

Type

Description

category

string (enum)

Always audit.

action

string (enum)

The operation performed: create, update or delete.

actor_name

string

Name of the user or API key that performed the operation.

actor_id

string

ID of the actor; empty string if not applicable.

resource_type

string (enum)

Type of the affected resource. One of: agent, apikey, egresspolicy, endpoint, eventlogrule, gateway, group, orchestrator, policy, proxy, service, settings, user.

resource_id

string

ID of the affected resource.

resource_name

string

Optional. Display name of the affected resource, when it has one.

changes

object

Optional. Only for update operations: changed fields keyed by field name. Scalar fields change to {"before": ..., "after": ...}; list fields to {"removed": [...], "added": [...]}. If the changes would make the message exceed the maximum UDP payload size, this field is replaced with the string Omitted: Changes exceed maximum payload size.

Scope: connections

Category: connection

One record per connection through the BlastShield overlay network, reported by the Gateway or Agent that carried the connection. Connection payloads have no id/name fields; the event field discriminates the connection lifecycle event.

Severity: Info

Field

Type

Description

category

string (enum)

Always connection.

event

string (enum)

One of: connection_established, connection_ended, terminated_by_policy, connection_refused, connection_timed_out.

client

string

Display name of the client (node or endpoint) that initiated the connection.

client_port

integer

Source port of the connection.

client_public_ip

string | null

Public IPv4 address of the client’s node; null when unknown.

client_location

array of strings

GeoIP-resolved location of the client’s node, same format as new_transport_address.

server

string

Display name of the destination (endpoint or node).

server_port

integer

Destination port of the connection.

received

integer

Bytes received by the client over the connection.

sent

integer

Bytes sent by the client over the connection.

Quick reference

Scope

Category

event

Severity

events

agent / gateway / orchestrator / user

login

Info

events

agent / gateway / orchestrator / user

logout

Info (user) / Warning

events

agent / gateway / orchestrator / user

register_public_key

Info

events

agent / gateway / orchestrator / user

new_transport_address

Info

events

agent / gateway / orchestrator

version_change

Info

events

gateway

ha_active_changed

Info

events

gateway

ha_state_changed

Info / Warning / Error

events

endpoint

reachable

Info

events

endpoint

unreachable

Warning

events

endpoint

mac_address_change

Warning

events

proxy

(no event field)

Info

events

agent / endpoint

certificate_issued

Info

events

agent / endpoint

state_change

Info / Warning / Error

events

agent / endpoint

new_session

Info

events

agent / endpoint

recording_skipped_no_storage

Warning

events

agent / endpoint

recording_deleted_retention

Info

events

agent / endpoint

recording_deleted_manual

Info

audit

audit

(no event field; see action)

Info

connections

connection

connection_established / connection_ended / terminated_by_policy / connection_refused / connection_timed_out

Info