UserEvent

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

JSON representation 
{
  "eventTime": string,
  "chip": {
    object (Chip)
  },
  "filterProperties": {
    object (FilterProperties)
  },
  "isAlert": boolean,
  "eventOutcome": enum (Action),
  "summary": string,
  "rawLogsToken": string,
  "principalLocation": {
    object (Location)
  },
  "description": string,
  "sourceUdmEventInfo": {
    object (UdmEventInfo)
  },
  "eventNumber": 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
eventTime

string (Timestamp format)

Date/time of the event.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
chip

object (Chip)

The chip to display.
filterProperties

object (FilterProperties)

A list of filter properties associated the event.
isAlert

boolean

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

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?)
rawLogsToken

string

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

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 eventOutcome (udm.security_result.description).
sourceUdmEventInfo

object (UdmEventInfo)

The source UDM event info.
eventNumber

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
  ],
  "emailSubject": string,
  "emailId": string,
  "maliciousArtifacts": [
    {
      object (ArtifactWithMetadata)
    }
  ],
  "relatedArtifacts": [
    {
      object (ArtifactWithMetadata)
    }
  ],
  "actingAsset": {
    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.
emailSubject

string

Subject of the email.
emailId

string

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

object (ArtifactWithMetadata)

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

object (ArtifactWithMetadata)

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

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 "maliciousArtifacts" 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)
  },
  "securityCategory": [
    string
  ],
  "productUri": string
}
Fields
artifact

object (ArtifactInfo)

Field representing the artifact.
securityCategory[]

string

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

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:
  "domainArtifact": {
    object (DomainArtifact)
  },
  "uriArtifact": {
    object (UrlArtifact)
  },
  "ipArtifact": {
    object (IpArtifact)
  },
  "fileArtifact": {
    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:
domainArtifact

object (DomainArtifact)

A domain artifact.
uriArtifact

object (UrlArtifact)

A URL artifact.
ipArtifact

object (IpArtifact)

An IP artifact.
fileArtifact

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 
{
  "ipAddress": string,
  "asOwner": string,
  "asn": string,
  "country": string,
  "ipSubnetRange": string,
  "registrar": string
}
Fields
ipAddress

string

IP address that identifies the artifact.
asOwner

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

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 
{
  "fileNames": [
    string
  ],
  "sha1": string,
  "sha256": string,
  "md5": string
}
Fields
fileNames[]

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 
{
  "loginType": enum (LoginEventType),
  "authType": [
    string
  ],
  "sourceAsset": {
    object (AssetIndicator)
  },
  "sourceUser": {
    object (UserIndicator)
  },
  "targetAsset": {
    object (AssetIndicator)
  },
  "targetUser": {
    object (UserIndicator)
  },
  "targetApplication": {
    object (Application)
  }
}
Fields
loginType

enum (LoginEventType)

The type of the login event.
authType[]

string

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

object (AssetIndicator)

The source asset of this login activity.
sourceUser

object (UserIndicator)

The source user of this activity.
targetAsset

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

object (UserIndicator)

Target user for the login. See previous comment.
targetApplication

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.