Add Automation Actions

Integrating with email or mailing lists allows Red Canary to send emails as part of an automation playbook.

1. Within any playbook, click Add Action.

2. Click Email, Send Email and then click Add to Playbook.

3. Specify email recipients in the To field by entering comma-separated email addresses. These can be determined dynamically using variables, such as using $Detection.marked_acknowledged_by_user.email to send an email to the user who acknowledged a detection.

4. Specify the Reply To address for the email. This address is used when a recipient clicks the reply button in their email client and is useful for routing responses back to your security or support team.

5. Select a Template and fill in any additional message fields supported by the template.

6. Click Save.

Email templates

You don’t need to start from scratch every time you want to send an email as we provide several pre-built templates.

Custom Freeform Email

This template is a completely freeform email. Enter text in the Message field and you will receive an email with exactly that.

Here’s an example:

Which produces this email:

Threat: All threat data as JSON

This template is designed for systems that read structured JSON data from emails; ServiceNow is a common recipient for these messages. The associated threat is sent in JSON format in the email body.

Note: This template is only valid for threat-based triggers.

Here’s an example:

Which produces this email:

Threat: Published notification in HTML

This template sends information about a threat to users in a condensed, summary format that includes a brief list of identified indicators of compromise.

Note: This template is only valid for threat-based triggers.

Here’s an example:

Which produces this email:

Threat: Human-readable HTML with full timeline

This template sends information about a threat to users in a condensed, summary format with the complete timeline of the threat, including all relevant activity and identified indicators of compromise.

Note: This template is only valid for threat-based triggers.

Here’s an example:

Which produces this email:

Microsoft Sentinel is Microsoft’s security information and event manager (SIEM) platform. You can configure an Automate playbook that sends your Red Canary threats to Microsoft Sentinel for analysis by completing the following steps:

• Create an Automate playbook.

• Connect your playbook to an Automate trigger.

• Add an analysis rule to your Microsoft Sentinel workspace.

Create a playbook that sends threats to Microsoft Sentinel

1. Go to go.my.redcanary.co/automate.

2. Click Playbooks.

3. Create a new playbook by clicking Create New Playbook. You can also select an existing playbook.

4. Click Add Action, and then click Send Threat to Sentinel.

5. Enter your Microsoft Sentinel workspace ID and key. You can enter either your primary or secondary key. For instructions on obtaining these credentials, see Find your workspace ID and key.

6. Click Save.

7. Run the Playbook by clicking Run from the Actions menu on the left side of the Playbook.

8. Select the Threat on which to run the Playbook from the popup.

9. Click Run.

The Analysis rule will fail unless the playbook is run first

Follow the steps 7-9 above to run the playbook in Red Canary. This creates the necessary dependencies in Microsoft Sentinel.

Add your playbook to a trigger

1. Go to Automate in Red Canary.

2. Click Triggers.

3. Create a new trigger by clicking Configure new trigger and select When a Threat is published trigger condition. You can also select an existing When a Threat is published trigger.

4. Click Add a Playbook, and select the playbook you created earlier.

Add analysis rule to Microsoft Sentinel

To configure Microsoft Sentinel to analyze Red Canary threats:

1. Go to your Microsoft Sentinel dashboard, and select a workspace.

2. Click Analytics under the Configuration section of your workspace.

3. Click Import from the menu at the top of the page.

4. Upload the analytics rule template file. Click here to download the template file.

How do I know it's working?

After you create a playbook and trigger, and add an analysis rule to Microsoft Sentinel, any threats that activate your “When a Threat is published” trigger will create a corresponding Microsoft Sentinel incident.

Helpful Notes

Red Canary will publish with the following GUID, useful when filtering or restricting responses to only Red Canary published threats.

6d263abb-6445-45cc-93e9-c593d3d77b89

Red Canary’s Microsoft Teams integration allows Teams messages to be created as part of an automation playbook.

Configure Teams to accept an incoming webhook

1. Add a custom incoming webhook within Microsoft Teams.

2. Copy the resulting webhook URL.

Add a Teams notification to an automation playbook

1. Within any playbook click Add Action.

2. Click Microsoft Teams and then click Send Microsoft Teams Message.

3. Click Add to Playbook.

4. Enter the webhook URL from above in Microsoft Teams Webhook URL.

5. Specify the Title and Text you want to appear for each message.

   Note: You can use html tags to format text. For example, you can use the HTML line break <br> element to allow for a line break.

6. Optionally, click Add a Potential Action and specify an action name and URL that should be triggered when the action is selected (learn more about actions in Microsoft Teams messages).

7. Click Save.

PagerDuty integration allows Red Canary to trigger PagerDuty incidents as part of an automation playbook.

1. In any playbook, click Add Action.

2. Click PagerDuty, Create PagerDuty Incident and then click Add to Playbook.

3. Specify the incident message you want to appear in each PagerDuty incident.

4. Click Save & Connect with PagerDuty.

5. You will be redirected to the PagerDuty site and asked to authorize Red Canary. Following that, you will be returned to Red Canary.

When the playbook is triggered, a PagerDuty incident will appear.

What details are included in the PagerDuty incident?

Custom details may be specified for each incident using the PagerDuty API. Red Canary adds several fields when a PagerDuty incident is triggered.

For audit logs:

• actor is set to the name and email of the user triggering the audit log.

• timestamp is set to the time the audit log was created.

• action_name is set to the name of the action that occurred.

For activity monitors:

• activity_monitor is set to the activity monitor’s name.

• num_matches_found is set to the number of matches that were found recently, or were found in this notification.

For threats: 

• severity is set to the detection’s severity.

• classification is set to the detection’s root classification.

• subclassifications is set to a comma-separated list of the detection’s subclassifications.

• A PagerDuty link is included that links to the confirmed threat in Red Canary.

Resolve PagerDuty Incidents

Each Red Canary incident has an incident key associated with the underlying resource that triggered the automation, such as an audit log, detection, or endpoint. These incidents can also be resolved by Red Canary automation.

For example, a playbook may use Create PagerDuty Incident when a detection is published, and may then use Resolve PagerDuty Incident when a detection is acknowledged. This works because the same detection triggers both the incident creation and resolution actions.

Use an automation playbook to set up a phone integration that will call specified phone numbers based on trigger criteria. The automation will call the phone numbers listed in the playbook by order until the recipient acknowledges the alert by pressing 1 or 10 retries are exhausted. 

For example, if three phone numbers are listed, they will be called in the following order:

1. Call phone number 1.

2. If unanswered or the recipient presses 2 to ignore the message, call phone number 2.

3. If unanswered or the recipient presses 2 to ignore the message, call phone number 3.

4. If unanswered or the recipient presses 2 to ignore the message, call phone number 1 again. 

5. Repeat this up to 10 times.

Add a phone call to your automation playbook that will call specified phone numbers either when the playbook runs or when all actions in a playbook have been successfully completed. These phone numbers are called in sequential order until a recipient acknowledges the call by pressing 1. At this time, there isn't a limit on the number of phone numbers that can be added.

1. From the navigation menu, click Automations.

2. Click Playbooks, and then click into a playbook.

3. Click one of the two Add Action buttons depending on when the phone number should be triggered.

   For example, click Add Action under When this playbook is run, the following actions will be performed in no particular order to trigger the phone calls whenever the playbook is run.

4. From Phone Call, click Call Phone Numbers, and then click Add to Playbook.

5. Enter one or more comma-separated phone numbers that should receive the phone call. Add phone numbers using the 164 format, including + and the country code. For example, +16175551212.

   Note: These can be determined dynamically using variables, such as using $Detection.marked_acknowledged_by_user.phone to call the user who acknowledged a threat.

6. Enter the Message for the recipient. 

7. Specify the number of seconds to wait before calling the next number.

8. Optionally, select Require approval.

9. Click Save.

SMS integration allows Red Canary to send SMS messages as part of an automation playbook.

1. In any playbook, click Add Action.

2. Click SMS and then click Send SMS Message. 

3. Click Add to Playbook.

4. Enter one or more comma-separated phone numbers that should receive the SMS message. Use the complete '+' and country code, for example: +16175551212.

   You can change the phone number dynamically using variables. For example, you can use the variable $Detection.marked_acknowledged_by_user.phone to message the user who acknowledged a threat.

5. Enter the message you want to send.

   

6. Click Save.

When the playbook is triggered, Red Canary will send your message to the specified phone number.

What if SMS messages are not being delivered?

SMS delivery is carrier and phone dependent, so exercise caution when entering certain Unicode or reserved characters, or interpolating with fields that might contain special characters like filenames. 

What if I do not receive the messages?

Be sure to check your Spam or Junk folder, and then troubleshoot as necessary by adjusting message contents or sending to a different number or carrier.

Red Canary uses a highly reliable service provider to deliver SMS codes through carriers around the world. Almost all cases of messages not being delivered are the result of a carrier blocking certain messages. Check your phone or carrier's unknown SMS or spam SMS blocking settings.

Red Canary’s syslog integration allows you to send syslog messages to a syslog receiver as part of an automation playbook.

The most common use of the syslog action is sending data to a SIEM or log collection platform, though we recommend using webhooks whenever possible because they are more modern, customizable, and reliable.

1. Within any playbook, click Add Action.

2. Click Syslog and then click Send Syslog Message.

3. Click Add to Playbook.

4. Specify the Server Domain/IP that is configured to receive messages. If you use source restriction, the IP addresses from which communications must be authorized are listed.

5. Specify the Server Port that messages should be sent to.

6. Specify whether connections to untrusted servers will be allowed or not.

7. Select the protocol for sending.

8. Select the Syslog Program, Syslog Facility, and Syslog Severity that you want messages from Red Canary to use.

9. Specify the syslog Message that you want sent to the syslog receiver.

10. Click Save.

What if my syslog server doesn’t support TLS/SSL?

Be very careful about the security of any application that is exposed to the internet. At a minimum, use IP source restrictions to only allow traffic from trusted sources (the IP addresses used by Red Canary are specified on the syslog action configuration form).

To disable Red Canary’s TLS/SSL requirement, set the Protocol to TCP or UDP.

Red Canary’s webhook integration allows you to trigger any HTTP listener as part of an automation playbook. Common uses of webhooks include the following:

• Creating tickets in ticket-tracking systems such as ServiceNow or JIRA.

• Posting data to Security information and event management (SIEM) / log collection platforms like Splunk or SumoLogic.

• Triggering incidents in paging systems such as OpsGenie or VictorOps (PagerDuty has a distinct integration action).

• Sending data to a custom business application you have exposed to the internet as custom software, an Azure function, or an AWS endpoint.

Webhooks are highly customizable and allow you to configure which HTTP method is used and specify HTTP headers that are used for authorization, routing, and so on.

1. Within any playbook, click Add Action.

2. Click Webhook/API and then click Invoke Webhook or API.

3. Click Add to Playbook.

4. Select an HTTP Method that should be used.

5. Enter the URL that should be invoked.

6. Optionally, enter one or more HTTP headers that should be included in the HTTP request.

   Note: By default, no HTTP headers are sent.

7. Specify a Payload type (learn more about these below).

   Note: Payloads are applicable to the POST, PUT, and PATCH HTTP methods.

8. Click Save.

Note: For Splunk, a HTTP Event Collector (HEC) token is required in the HTTPS Headers section, with this format: Authorization= Splunk [token]

Note: Related IP addresses for webhooks and other Transmission Control Protocol (TCP) ingress are provided on your Getting Help page.

What are payloads?

A webhook’s payload is the content contained in the body of the HTTP request to the specified URL. These payloads can be customized based on your needs and the API you’re integrating with.

All attributes as JSON 

This payload type sends all of the objects and attributes that triggered the action to the webhook URL as the body of a JSON post.

If the receiving application requires the Content-Type header to properly process the message, ensure you specify Content-Type=application/json in the HTTP Headers section.

Custom payload

This payload type allows you to specify a fully custom webhook payload. This content can be JSON, text, and so on.

If required by the receiving application, ensure you send the appropriate HTTP headers using the HTTP Headers section.

What happens if my payload fails?

If your application returns an HTTP status code other than 200, we will send an email to your technical contacts with details about the failure to assist you in troubleshooting.

To prevent flooding your inbox, we will send only one Webhook Failure email per playbook every 24 hours. In addition to this, we will create an Audit Log with Action: Automate Action Executed, and include details about the error in the Details section. We will create this AuditLog every time the Webhook fails. At the moment, we do not allow these AuditLogs to trigger playbooks.

Integrating with Slack allows Red Canary to send Slack messages as part of an automation playbook.

Note: You will need to update your webhooks on both the Red Canary and Slack side once Slack sunsets their legacy webhook feature. Red Canary will develop new documentation once this event happens in Slack. 

Configure Slack to accept an incoming webhook

1. Go to Slack-Incoming webhook.

2. Select the channel you want messages posted in and then click Add Incoming WebHooks integration.

3. Copy the webhook URL.

Add a Slack notification to an automation playbook

1. Within any playbook, click Add Action.

2. Click Slack, Send Slack Message and then click Add to Playbook.

3. Paste your webhook URL in Slack Webhook URL.

4. Specify the Channel where messages should be posted.

5. Specify the title you want to appear for each message, using interpolated values for customization.

6. Optionally, specify a Title Link as the URL the message should link to when clicked.

7. Select one of the Slack-supported colors for the left stripe of the message.

8. Optionally, specify custom fields that should appear in the message body.

9. Click Save.