Triggers

⚠️ Scheduled for removal after Jan 2023. Please migrate to Security Events

This API provides a list of emails that have been flagged by one of the Tessian modules.

Each row of data returned by the API represents a “trigger”: an email flagged by a Tessian module.

Each trigger will include email details, details outlining how the user responded to the Tessian warning message (if they were shown one), and other information that will vary depending on various parameters (Inbound vs Outbound, module type, etc.).

For inbound emails that trigger Defender, a single email received by multiple users is likely to result in multiple rows (i.e. one row per user). For outbound emails that trigger Guardian, Enforcer, Architect or Constructor (legacy), one outbound email may trigger multiple filters, resulting in multiple rows (i.e. one row per filter triggered). We have provided a guide and accompanying queries to help deal with this complexity in the “Calculating Statistics” section below.

The data is returned in JSON as an array of objects. Each object will contain the information appropriate for the type of trigger (Guardian, Enforcer, Defender, Architect, Constructor).

Important: if the data is not deduped, calculations of counts and other statistics will be inaccurate.

Calculating statistics

This section documents how to compute some interesting stats from the triggers that are returned by the API, using a SQL-like language for illustration.

Note that for all stats, you must first dedupe by trigger_id, as mentioned above.

Enforcer

Unauthorized emails prevented

The number of emails that Tessian Enforcer has prevented from being sent by your company’s employees.

COUNT (DISTINCT message_id) WHERE module = 'enforcer' AND unauthorized_email_prevented = 'True'

Enforcer messages shown to users

The number of Tessian Enforcer warning messages shown to users (either via the Add-in or Gateway).

COUNT WHERE module = 'enforcer' AND (alert_type = 'warn' or alert_type = 'block')

Unauthorized email attempts

The number of emails that triggered Tessian Enforcer.

COUNT (DISTINCT message_id) WHERE module = 'enforcer'

Sensitive unauthorized email attempts

The number of emails that triggered Tessian Enforcer that also contained sensitive information.

COUNT (DISTINCT message_id) WHERE module = 'enforcer' AND email_is_sensitive = 'True'

Filter triggers

The number of times any active Tessian Enforcer filters have been triggered by outbound emails.

COUNT WHERE module = 'enforcer' GROUP BY filter_name

Users with the most unauthorized emails detected

The number of unauthorized emails sent / attempted to be sent by each user.

COUNT (DISTINCT message_id) WHERE module = 'enforcer' GROUP BY user

Guardian

Misdirected emails prevented

The number of misdirected emails that Tessian Guardian prevented from being sent by your company’s employees.

COUNT (DISTINCT message_id) WHERE module = 'guardian' AND misdirected_email_prevented = 'True'

Guardian messages shown to users

The number of Tessian Guardian warning messages shown to users.

COUNT WHERE module = 'guardian' AND (alert_type = 'warn' or alert_type = 'block')

Guardian triggers

The number of times that any Tessian Guardian filters were triggered by outbound emails.

COUNT (DISTINCT message_id) WHERE module = 'guardian'

Users with the most misdirected emails detected

The number of misdirected emails that were prevented from being sent by Tessian Guardian per user.

COUNT (DISTINCT message_id) WHERE module = 'guardian' AND misdirected_email_prevented = 'True' GROUP BY user

Constructor

Filter triggers (total count)

The number of times any active constructor filters were triggered in total.

COUNT WHERE module = 'constructor'

Filter triggers (count per filter)

The number of times each active constructor filter was triggered.

COUNT WHERE module = 'constructor' GROUP BY filter_name

Defender

Malicious emails detected

The total number of emails that triggered Tessian Defender and that were classified as ‘malicious’.

COUNT (DISTINCT message_id) WHERE module = 'defender' AND threat_classification = 'malicious'

Anomalous emails detected

The total number of emails that triggered Tessian Defender and that were classified as ‘anomalous’.

COUNT (DISTINCT message_id) WHERE module = 'defender' AND threat_classification = 'anomalous'

Threat type statistics

The total number of emails that triggered Tessian Defender that were classified as being a particular threat type.

COUNT (DISTINCT message_id) WHERE module = 'defender' AND threat_types CONTAINS 'Domain Impersonation'

Note: CONTAINS means that the value exists in the threat_types list. Replace 'Domain Impersonation' with 'Display Name Impersonation', 'Direct Spoof Impersonation', 'Unusual Email', 'Blacklist', 'Account Takeover' to calculate these other stats. 'Unusual Email' is semantically the same as 'Other Phishing', which is used in other parts of the platform.

Defender warnings shown to users

The number of Tessian Defender warnings shown to users.

COUNT (DISTINCT user, message_id) WHERE module = 'defender' AND user_interaction NOT IN ('warning_message_not_shown', 'warning_message_not_shown_deleted', 'silently_track', 'defender_not_enabled')

Confirmed as malicious by users

The number of emails that triggered Tessian Defender and were confirmed as malicious by users clicking the “Mark as Malicious” button in the warning message.

COUNT (DISTINCT user, message_id) WHERE module = 'defender' AND user_interaction = 'marked_as_malicious'

Triggered emails manually deleted by users

The number of emails that triggered Tessian Defender and that were subsequently deleted by users.

COUNT (DISTINCT user, message_id) WHERE module = 'defender' AND user_interaction = 'deleted_email'

Marked as safe by users

The number of emails that triggered Tessian Defender but that were subsequently marked as safe by users clicking the “Mark as Safe” button in the warning message.

COUNT (DISTINCT user, message_id) WHERE module = 'defender' AND user_interaction = 'marked_as_safe'

Most targeted (malicious)

The number of emails that Tessian Defender classified as ‘malicious’ received by each user.

COUNT WHERE module = 'defender' AND threat_classification = 'malicious' GROUP BY user

Most targeted (anomalous)

The number of emails that Tessian Defender classified as ‘anomalous’ received by each user.

COUNT WHERE module = 'defender' AND threat_classification = 'anomalous' GROUP BY user

Most impersonated address

The internal addresses that Tessian Defender identified as being the most impersonated.

COUNT WHERE module = 'defender' AND impersonated_address != '' AND impersonation_type = 'internal' GROUP BY impersonated_address

Most impersonated domain

The domains that Tessian Defender identified as being the most impersonated.

COUNT WHERE module = 'defender' AND impersonated_domain != '' GROUP BY impersonated_domain

{
  "data": [
    {
      "filter_name": "Filter #1",
      "user": "example@example.com",
      "timestamp": "2018-02-14T17:58:55.253005Z",
      "recipients": [
        "example2@example.com",
        "example3@example.com",
        "example4@example.com"
      ],
      "to_recipients": [
        "example2@example.com"
      ],
      "cc_recipients": [
        "example3@example.com"
      ],
      "bcc_recipients": [
        "example3@example.com"
      ],
      "subject": "Hello, World",
      "message_id": "916ab7bb-efa2-4b61-b7f3-7f45fb9c8f72",
      "number_of_attachments": 1,
      "attachments_total_size": 1.23,
      "attachments": [
        {
          "attachment": "Untitled document"
        }
      ],
      "updated_at": "2019-10-28 10:59:54.990272",
      "trigger_id": "121555-442",
      "links": {
        "portal_url": "https://example.tessian-platform.com/0/anomalies/916ab7bb-efa2-4b61-b7f3-7f45fb9c8f72"
      },
      "salutation_extracted": "hello",
      "project_identifiers": [
        "zebra",
        "tornado"
      ],
      "check_performed_by": "Tessian Gateway",
      "tracking_id": "ABCD.1",
      "misdirected_email_prevented": true,
      "anomalous_recipient": "example2@example.com",
      "suggested_recipient": "example3@example.com",
      "anomalous_attachments": [
        "project_483_document.pdf"
      ]
    }
  ]
}