UserEvent

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

JSON representation

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`. }

{
  "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

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`) } }

{
  "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

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`. }

{
  "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

Fields
`domain`	`string` Domain name that identifies the artifact.

domain

string

Domain name that identifies the artifact.

UrlArtifact

A URL artifact.

JSON representation
{ "uri": string }

Fields

Fields
`uri`	`string` URL value that identifies the artifact.

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

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`) } }

{
  "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

Fields
`name`	`string` The application/resource name.
`uri`	`string` The url for the application/resource.
`ip`	`string` The ip address for the application/resource.

name

string

The application/resource name.

uri

string

The url for the application/resource.

ip

string

The ip address for the application/resource.