API Guide - Events--Event-Spec-Syntax

Event Types

Banyan events are aimed at auditing activity of end users and devices.

There are five types of Events:

  • Registration
  • Identity
  • Access
  • TrustScoring
  • Audit

Registration

Registration events are generated when an end user registers or unregisters a device using the Banyan DesktopApp or MobileApp.

SubType Level Action Description
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

Identity events are generated for end user authentications through Banyan.

Authentication consists of four steps:

  1. Device certificate validation
  2. Device compliance check with Mobile Device Manager
  3. User authentication through the Single Sign-On Identity Provider, policy/TrustScore checks
  4. 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).
SubType Level Action Description
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

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 since TIME.

SubType Level Action Description
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

TrustScoring

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 (Action=Calculate), or
  • An external override has been applied to the device (Action=Override)
SubType Level Action Description
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

Audit events are generated by a Service that is configured to log commands run by its users.

SubType Level Action Description
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.

Event JSON

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.

Common Fields

Every Event contains the following fields.

Name Description
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
org_id Organization ID
org_name Organization name
severity Event severity (ERROR, WARN, INFO, DEBUG)
action Event action (depends on event type)
type Event type (Registration, Identity, Access, Trustscoring, Audit)
sub_type Event subtype
message Indicates the authorization status, or result (success or failure) of an operation
result RESERVED
created_at Unix time in milliseconds
reported_by Describes the Banyan component that reported the event. Contains reported\_by.type (netagent, trustprovider, shield), reported\_by.host_name (name of component), reported\_by.host_ip (IP address of component)

In addition to these fields, Events may include a Subject and an Object.

Subject

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.

User Principal

A User Principal represents a human end user on a device and has three parts:

  • user
  • device
  • client

User

Name Description
email User’s email address
groups List of groups for the user
roles List of Banyan roles for the user

Device

Name Description
id Device ID (Banyan-internal)
friendly_name User-friendly device name
mac_address MAC address
serial_number Device serial number
registration_status Device registration status [Deprecated]
compromised_status [Deprecated]
compliance_status Device compliance with MDM policy [TRUE/FALSE]
oem_info Original Equipment Manufacturer info
model Device model
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

Client

Name Description
user_agent User agent HTTP header value
ip_address Source IP address of TCP connection

Workload Principal

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”.

Name Description
host_ips IP addresses on the VM
host_name VM hostname
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
tag Docker tag
labels Docker Container labels, Process Container labels
container_ips Docker Container IP addresses
app_name Application name

Roles

Each Subject can have zero, one, or multiple Banyan Roles.

Name Description
id Role ID
name Role name
version Role version
bound_by RESERVED
bound_at RESERVED

TrustScore

Each Subject can have a TrustScore.

Name Description
id TrustScore resource ID, (such as device serial number)
type TrustScore type: Device, External (override)
timestamp Unix time (nanoseconds)
score TrustScore value

Object

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

Service represents the Banyan Service that the Subject is trying to access.

Name Description
id Service ID: (service_name).(cluster_name).bnn
name Service name
type Service type: attribute-based (hosted service), IDP_FIRST (SaaS), BANYAN_FIRST (SaaS)
version Service version (increments on each update to the service spec)

Policy

Policy represents the Banyan Policy that is attached to the Banyan Service that the connection or request is trying to access.

Name Description
id Policy ID
name Policy name
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
enabled TRUE (enforcing mode) FALSE (permissive mode)

Channel

Channel describes a request that is transmitted from the Subject to the Object.

Name Description
access_level.resource connection or l7resource
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 l7resource) L7 protocol (such as HTTP)
request_data.type (only populated for l7resource) Request type (such as HTTP GET)
request_data.query_crud_types (only populated for l7resource) Create, Read, Update, Delete
request_data.query_resources (only populated for l7resource) Resource to be accessed (such as HTTP request path)

Link

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.

Name Description
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

Last modified: Apr 29, 2021