ATH Example: Notifications for Case Scores

This topic describes how to create an ATH playbook that sends an email or Slack message whenever a case's score exceeds a specified threshold.

Background: What Your Playbook Searches For

Before you create the playbook to notify on case scores over a threshold, it's important to understand what you're searching for. The first time a case's score passes the threshold of 50, Stellar Cyber creates a special document in the aella-syslog index with a msg_class of incident_score_change. This is the document your playbook searches for so that it can send an email or Slack message with information on the case and a link to its detail page in Stellar Cyber.

Keep in mind the following important points:

  • The threshold of 50 is hard-coded and cannot be changed.

  • The document is only created once for a given case. New documents are not created if a case's score falls below 50 and then increases above it again.

  • The document is created for a case that enters the system with a score over 50. This is considered as a score change from 0 to a score greater than 50.

Configure the Alert

We will create an alert that runs a query every 5 minutes on the Syslog index.

To create the alert:

  1. Navigate to Respond | Automation and click the Create button to add a playbook.
  2. Enter a name for the playbook. We entered Case Score Monitor.
  3. Set the Schedule type to interval.
  4. Set it to run every five minutes over all selected tenants.
  5. Leave Mute disabled.
  6. Choose the tenants and tenant groups on which to run. We chose All Tenants.
  7. Set the index to Syslog.
  8. Leave the Rule Type as Query.

Build a Query

We want a query that looks for new documents with a msg_class of incident_score_change.

To build the query:

  1. Click New Query. The screen changes to Build a Query.
  2. Enter a Query Name. We entered Score Change.
  3. Leave Condition Type set to AND and click Add Condition.
  4. Select msg_class from the Field dropdown.
  5. Leave the Operator set to is.
  6. Set Value to incident_score_change.
  7. Click Save to save your query.

Limiting the Query to Cases Over a Specified Score

So far, our query just checks for any new documents with a msg_class of incident_score_change. However, we can add a second AND query condition so that it only matches cases over a specified threshold greater than 50. The logic is like this:

  • Stellar Cyber only creates a document with a msg_class of incident_score_change for a case when its score crosses the hard-coded threshold of 50. This is the document you are searching for.

  • You can add a second AND query condition so that it only matches cases over a specified threshold greater than 50. For example, if you included AND "metadata.score" is greater than 80, the query would only match cases over a score of 80.

    The metadata.score field was renamed in the 4.3.7 release. In previous releases, it was named metadata.incident_score. Use the field name corresponding to your software version in the query configured below.

    Keep in mind that because a document with a msg_class of incident_score_change is only created once for a given case, this query will only match cases that are either initially created with a score over 80 or increased from below 50 to over 80.

Use the following additional steps:

  1. Click the Edit button for your ATH Playbook in the Respond | Automation page.

  2. Scroll to your query and click the Edit button.

  3. Click Add Condition.

  4. Set Field to metadata.score.

  5. Set Field Type to number.

  6. Set Operator to greater than.

  7. Set the Value to a number greater than 50 (for example, 80).

    The metadata.score you specify must be greater than 50 because this is the threshold where the document with a msg_class of incident_score_change is created.

  8. Click Save to save your query.

Configure a Condition

We want a condition that triggers our actions if there are any hits.

To configure this condition:

  1. Enter a Condition Name. We entered Any Hits.
  2. Select Compare Value for the Type.
  3. Set the Comparison to Total Hits, is greater than or equal to, and 1.

Configure Actions

We want an email or Slack message to be sent when our case score change is detected. See below for an example of each.

Refer to Configure Actions for details on configuring each type of action.

Configuring an Email Message as the Action

This example configures an email message as the action:

  1. Choose the trigger condition you entered. Ours is Any Hits.
  2. Choose Email for the Type.

  3. Choose Recipients. You can either type in an email address to use or choose a previously configured recipient from the dropdown list.

    Refer to Adding a Recipient for information on managing recipients globally.

  4. Enter a Subject. We entered Case Score Change.
  5. Set your Priority.
  6. Deselect the Include Interflow option.

  7. Enter your Email Body. The following sample text provides a link to the case. Note that you need to edit the text highlighted in red to use the hostname or IP address of your DP for this to work:

    The following case(s) exceeded the score threshold of {{ctx.payload.hits.hits.0._source.metadata.score_threshold}}:
    {{#ctx.payload.hits.hits}}
    Case {{_source.metadata.cust_name}}-{{_source.metadata.ticket_id}} ({{_source.metadata.name}}) reached a score of {{_source.metadata.incident_score}} at {{_source.metadata.timestamp_readable}}
    https://<dp-hostname-or-ip>/cases/case-detail/{{_source.metadata.id}}?cust_id={{_source.metadata.cust_id}}&view=graph
    {{/ctx.payload.hits.hits}}

  8. Leave Mute disabled.

    Here's how our Email action looks:

  9. Click Submit to save and immediately run the playbook. Your new playbook appears in the playbook list. You can use the Last Status option in the context menu at the far right of its entry to check how the rules are executing.

    Here is a sample email sent by our ATH Playbook, complete with a link to the case with the changed score:

Configuring a Slack Message as the Action

This example configures a Slack message as the action:

  1. Choose the trigger condition you entered. Ours is Any Hits.
  2. Choose Slack for the Type.

  3. Choose Use Recipients and select a Slack recipient from the dropdown list.

    Refer to Adding a Recipient for information on adding recipients. You will need a Slack Web URL from your Slack administrator to add a Slack repicient. Refer to the instructions on webhooks in the Slack documentation for details.

  4. Enter a Subject. We entered Case Score Change.
  5. Set your Priority.
  6. Deselect the Include Interflow option.

  7. Enter your Message. The following sample text provides a link to the case and is formatted to make it easy to see the plain text and the code. Note that you need to edit the text highlighted in red to use the hostname or IP address of your DP for this to work:

    The following case(s) exceeded the score threshold of {{ctx.payload.hits.hits.0._source.metadata.score_threshold}}:

    {{#ctx.payload.hits.hits}}

    Incident {{_source.metadata.cust_name}}-{{_source.metadata.ticket_id}} ({{_source.metadata.name}}) reached a score of {{_source.metadata.incident_score}} at {{_source.metadata.timestamp_readable}} https://<dp-hostname-or-ip>/cases/case-detail/{{_source.metadata.id}}?cust_id={{_source.metadata.cust_id}}&view=graph

    {{/ctx.payload.hits.hits}}

  8. Leave Mute disabled.

    Here's how our Slack action looks:

  9. Click Submit to save and immediately run the playbook. Your new playbook appears in the playbook list. You can use the Last Status option in the context menu at the far right of its entry to check how the rules are executing.