REST Resource: projects.locations.instances.events

Resource: Event

Event is a resource that contains information about a telemetry event.

JSON representation 
{
  "name": string,
  "udm": {
    object (UDM)
  }
}
Fields
name

string

The resource name of the event. Format: projects/{project}/locations/{location}/instances/{instance}/events/{event} where 'event' is URL-encoded Base64. The unencoded value of 'event' can also be found in udm.metadata.id.
udm

object (UDM)

Event data in UDM format.

UDM

A Unified Data Model event.

JSON representation 
{
  "metadata": {
    object (Metadata)
  },
  "additional": {
    object
  },
  "principal": {
    object (Noun)
  },
  "src": {
    object (Noun)
  },
  "target": {
    object (Noun)
  },
  "intermediary": [
    {
      object (Noun)
    }
  ],
  "observer": {
    object (Noun)
  },
  "about": [
    {
      object (Noun)
    }
  ],
  "security_result": [
    {
      object (SecurityResult)
    }
  ],
  "network": {
    object (Network)
  },
  "extensions": {
    object (Extensions)
  },
  "extracted": {
    object
  }
}
Fields
metadata

object (Metadata)

Event metadata such as timestamp, source product, etc.
additional

object (Struct format)

Any important vendor-specific event data that cannot be adequately represented within the formal sections of the UDM model.
principal

object (Noun)

Represents the acting entity that originates the activity described in the event. The principal must include at least one machine detail (hostname, MACs, IPs, port, product-specific identifiers like an EDR asset ID) or user detail (for example, username), and optionally include process details. It must NOT include any of the following fields: email, files, registry keys or values.
src

object (Noun)

Represents a source entity being acted upon by the participant along with the device or process context for the source object (the machine where the source object resides). For example, if user U copies file A on machine X to file B on machine Y, both file A and machine X would be specified in the src portion of the UDM event.
target

object (Noun)

Represents a target entity being referenced by the event or an object on the target entity. For example, in a firewall connection from device A to device B, A is described as the principal and B is described as the target. For a process injection by process C into target process D, process C is described as the principal and process D is described as the target.
intermediary[]

object (Noun)

Represents details on one or more intermediate entities processing activity described in the event. This includes device details about a proxy server or SMTP relay server. If an active event (that has a principal and possibly target) passes through any intermediaries, they're added here. Intermediaries can impact the overall action, for example blocking or modifying an ongoing request. A rule of thumb here is that 'principal', 'target', and description of the initial action should be the same regardless of the intermediary or its action. A successful network connection from A->B should look the same in principal/target/intermediary as one blocked by firewall C: principal: A, target: B (intermediary: C).
observer

object (Noun)

Represents an observer entity (for example, a packet sniffer or network-based vulnerability scanner), which is not a direct intermediary, but which observes and reports on the event in question.
about[]

object (Noun)

Represents entities referenced by the event that are not otherwise described in principal, src, target, intermediary or observer. For example, it could be used to track email file attachments, domains/URLs/IPs embedded within an email body, and DLLs that are loaded during a PROCESS_LAUNCH event.
security_result[]

object (SecurityResult)

A list of security results.
network

object (Network)

All network details go here, including sub-messages with details on each protocol (for example, DHCP, DNS, or HTTP).
extensions

object (Extensions)

All other first-class, event-specific metadata goes in this message. Do not place protocol metadata in Extensions; put it in Network.
extracted

object (Struct format)

Flattened fields extracted from the log.

Extensions

Extensions to a UDM event.

JSON representation 
{
  "auth": {
    object (Authentication)
  },
  "vulns": {
    object (Vulnerabilities)
  }
}
Fields
auth

object (Authentication)

An authentication extension.
vulns

object (Vulnerabilities)

A vulnerability extension.

Authentication

The Authentication extension captures details specific to authentication events. General guidelines for authentication events: * Details about the source of the authentication event (for example, client IP or hostname), should be captured in principal. The principal may be empty if we have no details about the source of the login. * Details about the target of the authentication event (for example, details about the machine that is being logged into or logged out of) should be captured in target. * Some authentication events may involve a third-party. For example, a user logs into a cloud service (for example, Chronicle) via their company's SSO (the event is logged by their SSO solution). In this case, the principal captures information about the user's device, the target captures details about the cloud service they logged into, and the intermediary captures details about the SSO solution.

JSON representation 
{
  "type": enum (AuthType),
  "mechanism": [
    enum (Mechanism)
  ],
  "auth_details": string
}
Fields
type

enum (AuthType)

The type of authentication.
mechanism[]

enum (Mechanism)

The authentication mechanism.
auth_details

string

The vendor defined details of the authentication.

AuthType

Type of system the authentication event is associated with.

Enums
AUTHTYPE_UNSPECIFIED The default type.
MACHINE A machine authentication.
SSO An SSO authentication.
VPN A VPN authentication.
PHYSICAL A Physical authentication (e.g. "Badge reader").
TACACS A TACACS family protocol for networked systems authentication (e.g. TACACS, TACACS+).

Mechanism

Mechanism(s) used to authenticate.

Enums
MECHANISM_UNSPECIFIED The default mechanism.
USERNAME_PASSWORD Username + password authentication.
OTP OTP authentication.
HARDWARE_KEY Hardware key authentication.
LOCAL Local authentication.
REMOTE Remote authentication.
REMOTE_INTERACTIVE RDP, Terminal Services, or VNC.
MECHANISM_OTHER Some other mechanism that is not defined here.
BADGE_READER Badge reader authentication
NETWORK Network authentication.
BATCH Batch authentication.
SERVICE Service authentication
UNLOCK Direct human-interactive unlock authentication.
NETWORK_CLEAR_TEXT Network clear text authentication.
NEW_CREDENTIALS Authentication with new credentials.
INTERACTIVE Interactive authentication.
CACHED_INTERACTIVE Interactive authentication using cached credentials.
CACHED_REMOTE_INTERACTIVE Cached Remote Interactive authentication using cached credentials.
CACHED_UNLOCK Cached Remote Interactive authentication using cached credentials.
BIOMETRIC Biometric device such as a fingerprint reader.
WEARABLE Wearable such as an Apple Watch.

Vulnerabilities

The Vulnerabilities extension captures details on observed/detected vulnerabilities.

JSON representation 
{
  "vulnerabilities": [
    {
      object (Vulnerability)
    }
  ]
}
Fields
vulnerabilities[]

object (Vulnerability)

A list of vulnerabilities.

Methods

batchGet

 Gets a batch (list) of events given a list of names and a parent.

get

 Gets an event given a name.

import

 ImportEvents import the events.