Event Properties & Definitions
- Updated on May 21, 2024
Events Overview
Events in Cloud Secure Edge (CSE) are classified as types (i.e., ‘Event Type’ and ‘Event Subtype’). These types are organized as ‘Private Access’ events or ‘Internet Access’ events. Typically, an Event Type will be associated with at least one Event Subtype. The type of Event can be found under the ‘Event Type’ category in the list of events as well as in the JSON of a particular Event. A description of the Event Type can be found under the ‘Message’ category in the Events list. The filter bar can be used to quickly surface specific Event Types; admins can filter by Event Type.
Event Types can be found under Home > Events in the Command Center. A comprehensive list of Event Types and their definitions can be found below.
Event Types
CSE Events are designed to help audit end users’ device activity.
The following Event types exist:
- Registration
- Identity
- Access
- TrustScoring
- Audit
- AdminLogin
- Threat
- Compliance
- NetagentRestart
- ITPStatus
Registration
Registration events are generated when an end user registers or unregisters a device using the desktop app or mobile app. The subtype is always ‘device’.
| 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 authentication attempts through an IDP and for successful authentication. The subtype is always ‘UserPrincipal’.
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 CSE 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 | CSE issued an identity token or SAML assertion |
| UserPrincipal | ERROR | Deny | CSE 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 Access Tiers 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 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 Trust Level for a device changes. The subtype is always ‘device’.
The Trust Level can change when:
- A change in the Trust Level 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 Trust Level value has been calculated for a device based on its last reported features |
| Device | WARN | Override | An external Trust Level 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. |
AdminLogin
An AdminLogin event is generated when a local admin attempts to log into a Banyan org (includes failed and successful login attempts). The subtype is always ‘local’.
Threat
A Threat event is generated when URL filtering blocks access to a particular resource.
Compliance
A Compliance event is generated when Internet Threat Protection (ITP) blocks a user from accessing a blocked domain.
NetagentRestart
A NetagentRestart event is generated when a netagent restarts.
ITPStatus
An ITPStatus event is generated when ITP is enabled or disabled on a device.
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 the Command Center (for example, state value in OpenID Connect authentication requests) |
| correlation_id | A tracing identifier that was generated in the 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 CSE 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 |
|---|---|
| User’s email address | |
| groups | List of groups for the user |
| roles | List of CSE roles for the user |
Device
| Name | Description |
|---|---|
| id | Device ID (CSE-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 the 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 |
| geo_location | Location data |
Geo Location Data Example:
"geo_location": {
"city": "Council Bluffs",
"region": "Iowa",
"country": "United States",
"continent": "North America",
"latitude": 41.2591,
"longitude": -95.8517
}
Note: Work with your CSE customer success representative to enable location data in end user logs.
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 CSE HostAgent.
Alternatively, a Workload Principal can represent a group of non-Dockerized processes that are running on the same virtual machine. CSE 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 CSE 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 CSE 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 CSE Policy that is attached to the CSE 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 the 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 | CSE Service ID of the traffic source |
| source.service_name | CSE Service Name of the traffic source |
| source.service_version | CSE 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 | CSE Service ID of the traffic destination |
| destination.service_name | CSE Service Name of the traffic destination |
| destination.service_version | CSE Service Version of the traffic destination |
| destination.host_name | Host name at the traffic destination |
| destination.ip | IP address of the traffic destination |