UserEvent

Represents all telemetry data associated with a user for returning to the client.

JSON representation 
{
  "event_time": string,
  "chip": {
    object (Chip)
  },
  "filter_properties": {
    object (FilterProperties)
  },
  "is_alert": boolean,
  "event_outcome": enum (Action),
  "summary": string,
  "raw_logs_token": string,
  "principal_location": {
    object (Location)
  },
  "description": string,
  "source_udm_event_info": {
    object (UdmEventInfo)
  },
  "event_number": integer,

  // Union field event_payload can be only one of the following:
  "email": {
    object (EmailEvent)
  },
  "login": {
    object (LoginEvent)
  }
  // End of list of possible types for union field event_payload.
}
Fields
event_time

string (Timestamp format)

Date/time of the event.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
chip

object (Chip)

The chip to display.
filter_properties

object (FilterProperties)

A list of filter properties associated the event.
is_alert

boolean

Whether or not to display this event as an alert.
event_outcome

enum (Action)

Specifies the result of this event. Whether the event was allowed, blocked, etc.
summary

string

Summary data about the outcome. (e.g. why was the action blocked?)
raw_logs_token

string

A token to request raw logs, this is opaque to the client. If empty, no raw logs can be requested.
principal_location

object (Location)

The location of the principal for the user event. On a login event, this is where the login was attempted from.
description

string

Description of cause for a particular event_outcome (udm.security_result.description).
source_udm_event_info

object (UdmEventInfo)

The source UDM event info.
event_number

integer

Alert number used to identify an alert event.
Union field event_payload. Event type specific information exists inside this payload. The client will have different display logic for different event types below. event_payload can be only one of the following:
email

object (EmailEvent)

Represents an email event.
login

object (LoginEvent)

Represents a login event.

EmailEvent

A general email event that may represent different types of email events.

JSON representation 
{
  "type": enum (EmailEventType),
  "sender": string,
  "recipients": [
    string
  ],
  "email_subject": string,
  "email_id": string,
  "malicious_artifacts": [
    {
      object (ArtifactWithMetadata)
    }
  ],
  "related_artifacts": [
    {
      object (ArtifactWithMetadata)
    }
  ],
  "acting_asset": {
    object (AssetIndicator)
  }
}
Fields
type

enum (EmailEventType)

Required. Event type.
sender

string

Sender of the email. Either the sender or recipients field must be populated.
recipients[]

string

Recipients of the email. Either the sender or recipients field must be populated.
email_subject

string

Subject of the email.
email_id

string

Required. GUID of the email as determined by the product providing the logs.
malicious_artifacts[]

object (ArtifactWithMetadata)

Required. Artifacts that are considered malicious within an email.
related_artifacts[]

object (ArtifactWithMetadata)

Artifacts that aren't considered malicious within an email but are provided for more context.
acting_asset

object (AssetIndicator)

The asset which this event was initiated by. Namely, which asset sent an email or clicked on the url within an email. Often times this will be an external IP.

EmailEventType

This enum decribes what subtype the email event is.

Enums
EMAIL_EVENT_TYPE_UNSPECIFIED Default
EMAIL_TRANSACTION Represents an event where an email was detected to have mailicious components such as URLs or file hashes.
EMAIL_URL_CLICK Represents an event where a user clicked on a bad URL within an email. Note: In this case, we expect "malicious_artifacts" to be of size 1.

ArtifactWithMetadata

A distilled version of backstory.SecurityResult representing an artifact which is usually malicious. This is primarily used for UX client consumption. Contains an artifact with associated metadata. Security products may often detect malicious artifacts and provide metadata related to the artifact.

JSON representation 
{
  "artifact": {
    object (ArtifactInfo)
  },
  "security_category": [
    string
  ],
  "product_uri": string
}
Fields
artifact

object (ArtifactInfo)

Field representing the artifact.
security_category[]

string

A standardized (as determined by UDM) security category as determined by the product.
product_uri

string

A URL that a product may provide for more information about the mailicious artifact.

ArtifactInfo

An Artifact can be a domain, a URL, an ip address, a submission, or a file sha256 id with a list of filenames.

JSON representation 
{
  "id": string,

  // Union field data can be only one of the following:
  "domain_artifact": {
    object (DomainArtifact)
  },
  "uri_artifact": {
    object (UrlArtifact)
  },
  "ip_artifact": {
    object (IpArtifact)
  },
  "file_artifact": {
    object (FileArtifact)
  }
  // End of list of possible types for union field data.
}
Fields
id

string

A VT artifact id. (e.g. a SHA256 of a file or URL that VT uses to identify the file or URL)
Union field data. Artifact can be one-of the following data types. data can be only one of the following:
domain_artifact

object (DomainArtifact)

A domain artifact.
uri_artifact

object (UrlArtifact)

A URL artifact.
ip_artifact

object (IpArtifact)

An IP artifact.
file_artifact

object (FileArtifact)

A file artifact.

DomainArtifact

A domain artifact.

JSON representation 
{
  "domain": string
}
Fields
domain

string

Domain name that identifies the artifact.

UrlArtifact

A URL artifact.

JSON representation 
{
  "uri": string
}
Fields
uri

string

URL value that identifies the artifact.

IpArtifact

An IP artifact.

JSON representation 
{
  "ip_address": string,
  "as_owner": string,
  "asn": string,
  "country": string,
  "ip_subnet_range": string,
  "registrar": string
}
Fields
ip_address

string

IP address that identifies the artifact.
as_owner

string

AS Owner that this IP Address belongs to.
asn

string

ASN Id that this IP Address belongs to.
country

string

Country code of this IP address.
ip_subnet_range

string

Registered human readable IP subnet range, this IP belongs to. E.g.: 123.59.32.0/19.
registrar

string

The organization that managed allocation of these IP addresses. E.g.: LACNIC

FileArtifact

A file artifact with all relevant information related to files.

JSON representation 
{
  "file_names": [
    string
  ],
  "sha1": string,
  "sha256": string,
  "md5": string
}
Fields
file_names[]

string

List of related file names associated with this artifact.
sha1

string

Hash information of artifact. Sha1 hash for this file artifact.
sha256

string

Sha256 hash for this file artifact.
md5

string

md5 for this file artifact.

LoginEvent

A general login event that may represent different types of email events.

JSON representation 
{
  "login_type": enum (LoginEventType),
  "auth_type": [
    string
  ],
  "source_asset": {
    object (AssetIndicator)
  },
  "source_user": {
    object (UserIndicator)
  },
  "target_asset": {
    object (AssetIndicator)
  },
  "target_user": {
    object (UserIndicator)
  },
  "target_application": {
    object (Application)
  }
}
Fields
login_type

enum (LoginEventType)

The type of the login event.
auth_type[]

string

Required. What the login mechanism was: OTP, hardware key, or password. There may be multiple auth types, for example password and hardware key.
source_asset

object (AssetIndicator)

The source asset of this login activity.
source_user

object (UserIndicator)

The source user of this activity.
target_asset

object (AssetIndicator)

For a MACHINE login, we'd expect to see either target asset or target user or both. For a SSO login, we'd expect to see only a target user. For a VPN login, we'd expect to see target asset which would be the VPN server.
target_user

object (UserIndicator)

Target user for the login. See previous comment.
target_application

object (Application)

A target application is optional. We don't expect it to be present unless the LoginEventType is SSO in which case it is required.

LoginEventType

Enum representing different types of logins.

Enums
LOGIN_EVENT_TYPE_UNSPECIFIED Default.
MACHINE Represents a user logging into a machine. It may be local or remote.
SSO Represents a user using an SSO product to login, perhaps to access an application.
VPN Represents a user using a VPN server to request an internal IP.

Application

Often times, users will login to use a particular application/resource. In such cases, the products will provide information on what application the user was attempting to access.

JSON representation 
{
  "name": string,
  "uri": string,
  "ip": string
}
Fields
name

string

The application/resource name.
uri

string

The url for the application/resource.
ip

string

The ip address for the application/resource.