• Event Types
  • Registration
  • Identity
  • Access
  • TrustScoring
  • Audit
• Event JSON
  • Common Fields
  • Subject
  • Roles
  • TrustScore
  • Object
  • Service
  • Policy
  • Channel
  • Link

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