API Guide - Events--Event-Spec-Syntax
- Updated on Apr 29, 2021
Banyan events are aimed at auditing activity of end users and devices.
There are five types of Events:
Registration events are generated when an end user registers or unregisters a device using the Banyan DesktopApp or MobileApp.
|Device||INFO||Register||Device registered successfully|
|Device||ERROR||Register Failed||Device registration failed|
|Device||WARN||Unregister||Device unregistered successfully|
|Device||ERROR||Unregister Failed||Device unregistration failed|
Identity events are generated for end user authentications through Banyan.
Authentication consists of four steps:
- Device certificate validation
- Device compliance check with Mobile Device Manager
- User authentication through the Single Sign-On Identity Provider, policy/TrustScore checks
- Issuance of a Banyan ID token or SAML assertion. (Reported as either an Identity Grant (issued token/assertion) as an Identity Deny (no token/assertion issued).
|UserPrincipal||INFO||Grant||Banyan issued an identity token or SAML assertion|
|UserPrincipal||ERROR||Deny||Banyan refused to issue an identity token or SAML assertion|
|UserPrincipal||DEBUG||OCSP||Result of checking device certificate’s revocation status|
|UserPrincipal||DEBUG||MDM||Result of checking device status in Mobile Device Manager|
|UserPrincipal||DEBUG||IDP||Result of user authentication in Single Sign-On Identity Provider|
Access events are generated by Banyan AccessTiers and HostAgents.
Each Access event is for a single incoming client connection, or for a single HTTP request over an incoming client connection. The Access event indicates whether the given connection or request was authorized or unauthorized, according to the Admin-defined security policies in the Banyan Command Center.
AccessTiers and HostAgents optionally rate limit their generation of Access events. Rate limiting can be enabled, disabled, or tuned for an AccessTier or HostAgent by adjusting its configuration parameter settings. For long-lived TCP connections, a periodic access event will be generated every 10 minutes, subject to rate limiting constraints.
These periodic events have a
message field value that starts with the word
PERIODIC and reports the start time of the connection as
|Connection||INFO||Authorized||Authorized TCP connection from a client to an AccessTier or HostAgent|
|Connection||ERROR||Unauthorized||Unauthorized TCP connection from a client to an AccessTier or HostAgent|
|Resource||INFO||Authorized||Authorized L7 (HTTP) request from a client to an AccessTier or HostAgent|
|Resource||ERROR||Unauthorized||Unauthorized L7 (HTTP) request from a client to an AccessTier or HostAgent|
A TrustScoring event is generated when the TrustScore for a device changes. The TrustScore can change when:
- A change in the TrustScore features that are reported for a device result in a new calculated value (
- An external override has been applied to the device (
|Device||INFO||Calculate||A new TrustScore value has been calculated for a device based on its last reported features|
|Device||WARN||Override||An external TrustScore override has been set for a device|
Audit events are generated by a Service that is configured to log commands run by its users.
|Kubernetes||INFO||Log||A batch of Kubernetes commands were combined into an audit log. Commands are grouped together into batches every five minutes (by default) and included in a single Audit event. Please note: You will only see these events if you are using Kubernetes OIDC Authentication.|
An Event is a JSON object. The object has a set of common fields which are present in all event types. In addition, an Event can contain additional fields that describe a Subject and Object of an access.
Every Event contains the following fields.
|id||Unique ID for the event|
|external_id||A tracing identifier that was generated external to Banyan Command Center (for example, state value in OpenID Connect authentication requests)|
|correlation_id||A tracing identifier that was generated in Banyan Command Center|
|severity||Event severity (ERROR, WARN, INFO, DEBUG)|
|action||Event action (depends on event type)|
|type||Event type (Registration, Identity, Access, Trustscoring, Audit)|
|message||Indicates the authorization status, or result (success or failure) of an operation|
|created_at||Unix time in milliseconds|
|reported_by||Describes the Banyan component that reported the event. Contains
In addition to these fields, Events may include a Subject and an Object.
A Subject represents an entity that is requesting access to a resource.
There are two types of subject:
- User Principals – Represents a human end user on a device.
- Workload Principals – Represents an automated process, such as a Docker container running on a virtual machine.
A User Principal represents a human end user on a device and has three parts:
|User’s email address|
|groups||List of groups for the user|
|roles||List of Banyan roles for the user|
|id||Device ID (Banyan-internal)|
|friendly_name||User-friendly device name|
|serial_number||Device serial number|
|registration_status||Device registration status [Deprecated]|
|compliance_status||Device compliance with MDM policy [TRUE/FALSE]|
|oem_info||Original Equipment Manufacturer info|
|platform||Device platform (Windows, Darwin, iOS, Android, Linux)|
|ownership||Device ownership (Corporate Dedicated, Corporate Shared, Employee Owned, Unknown)|
|architecture||CPU architecture: amd64, arm64|
|udid||Unique Device Identifier (available on some platforms)|
|source||Device info as reported by Banyan App or MDM (such as AirWatch)|
|last_mdm_data_synced_at||Unix time (in nanoseconds) when device info was last reported|
|user_agent||User agent HTTP header value|
|ip_address||Source IP address of TCP connection|
A Workload Principal represents an automated process that issues requests to a service. For example, a Workload Principal can represent a Docker Container running on a virtual machine along with the Banyan HostAgent.
Alternatively, a Workload Principal can represent a group of non-Dockerized processes that are running on the same virtual machine. Banyan HostAgent groups processes together that have the same name and treats them as a single logical “Process Container” with a name, ID, etc.
Processes with different names can additionally be grouped as a single “Application”.
|host_ips||IP addresses on the VM|
|cluster_id||Cluster ID (same as Shield UUID)|
|port_map||Mapping of host ports to Docker Container IPs and ports|
|container_name||Docker Container name, Process Container name|
|container_id||Docker Container ID, Process Container ID|
|image||Docker Container image ID|
|repo||Docker repository name|
|labels||Docker Container labels, Process Container labels|
|container_ips||Docker Container IP addresses|
Each Subject can have zero, one, or multiple Banyan Roles.
Each Subject can have a TrustScore.
|id||TrustScore resource ID, (such as device serial number)|
|type||TrustScore type: Device, External (override)|
|timestamp||Unix time (nanoseconds)|
An Object represents a resource that a Subject is trying to access. An Object is described by Service, Policy, Channel, and Link.
Channel and Link are included only in Access Events.
Service represents the Banyan Service that the Subject is trying to access.
|version||Service version (increments on each update to the service spec)|
Policy represents the Banyan Policy that is attached to the Banyan Service that the connection or request is trying to access.
|version||Policy version (increments on each update to the policy spec)|
|attached_by||Time that the policy was attached to the service|
|attached_at||Admin user who attached the policy to the service|
Channel describes a request that is transmitted from the Subject to the Object.
|sni_data.name_requested||TLS Server Name Indication (SNI)|
|sni_data.name_matched||Domain name (possibly a wildcard domain name) that matched SNI|
|request_data.protocol||(only populated for
|request_data.type||(only populated for
|request_data.query_crud_types||(only populated for
|request_data.query_resources||(only populated for
Link is included in Access events and describes a network traffic flow (set of TCP connections) between a network source (client that starts the TCP connections) and a network destination (server that accepts the TCP connections).
In most scenarios it is not possible for Banyan AccessTier or HostAgent to determine values for all of these fields, in which case the unknown field values are left empty.
|source.container_id||Container ID of the traffic source|
|source.container_name||Container name of the traffic source|
|source.service_id||Banyan Service ID of the traffic source|
|source.service_name||Banyan Service Name of the traffic source|
|source.service_version||Banyan Service Version of the traffic source|
|source.host_name||Host name at the traffic source|
|source.ip||IP address of the traffic source|
|destination.container_id||Container ID of the traffic destination|
|destination.container_name||Container name of the traffic destination|
|destination.service_id||Banyan Service ID of the traffic destination|
|destination.service_name||Banyan Service Name of the traffic destination|
|destination.service_version||Banyan Service Version of the traffic destination|
|destination.host_name||Host name at the traffic destination|
|destination.ip||IP address of the traffic destination|