How to Set Up Notifications Using Spyctl

Configure Notifications using Spyctl to receive alerts for significant Security or Operations events.

Prerequisites

Overview

Spyderbat's notification system has 3 main components:

Notification Targets: Named destinations to where notifications can be sent.
Notification Templates: Pre-built templates containing most of the information required to create a Notification Config. These templates simplify the configuration process.
Notifications: Allows to you configure notifications to the targets for the Notifiable Objects.

For the the full documentation of the Spyderbat Notifications System refer to this section.

How to Set Up Notifications

Spyderbat allows you to configure notifications for a variety of resources and targets, enabling you to streamline your workflow and stay informed about important events. Here’s how you can set up notifications for different targets:

Step 1: Identify Notification Targets/Target Template.

Before you can configure notifications, you need to decide where to send them. Spyderbat supports several Notification Targets, such as:

Email
Slack Channel
Webhook
PagerDuty

Ensure that you have already configured the Notification Targets for these destinations before proceeding.

All of the commands to manage Notification Targets using Spyctl can be found here.

Each Notification Target can be mapped to an optional Custom Notification Template, which defines the structure of the notification. Pre-configured templates help streamline the setup process.

All of the commands to manage Notification Templates using Spyctl can be found here.

If no template is specified, Spyderbat applies its default template.

Step 2: Access Notification Command Help

To learn more about the spyctl notifications commands and their usage, run the following command:

  spyctl notifications -h

This will display the following help message:

Usage: spyctl notifications [OPTIONS] COMMAND [ARGS]...

Configure notifications for a Spyderbat resource.

Commands:
  configure  Configure notifications for a Spyderbat resource.
  disable    Disable notifications for a Spyderbat resource.
  enable     Enable notifications for a Spyderbat resource.
  list       List notifications on a Spyderbat resource.

Notification command allows you to Configure, disable, enable, list Notifications. Let's learn them one by one below.

Use spyctl notifications <command> --help for more information about a given command.

Step 3: Configure Notifications for a Resource

You can configure notifications for 3 resources within Spyderbat's Spyctl CLI, mainly Saved Queries, Custom flags, and Agent Health.

In this section we'll learn about Configuring Notifications for Saved Queries and Custom flags.

To Configure Notifications for Agent Health Refer here

To begin, use the spyctl notifications configure command. Below are the available commands and options:

View Help for Notifications Command:

To view the available options for configuring notifications, use the following command:

 spyctl notifications -h

This will display the following help message:

Configure notifications for a Spyderbat resource.

Commands:
  custom-flag  Configure notifications for a custom flag.
  saved-query  Configure notifications for a saved query.
  agent-health Configure notificatons for agent heatlh.

Usage:
  spyctl notifications configure [OPTIONS] COMMAND [ARGS]...

For a Saved Query:

To configure notifications for a saved query, use the following command:

 spyctl notifications configure saved-query -h

This will show the usage and options for configuring notifications for a saved query:

Usage: spyctl notifications configure saved-query [OPTIONS] NAME_OR_UID

  Configure notifications for a saved query.

Options:
  --target-map    Map target names to template names. Can be used multiple times. 
                  Usage: --target-map TGT_NAME=TEMPLATE_NAME
  --targets       The Name or UID of targets to send notifications to.
  --cooldown-by   The cooldown by field(s).
  --cooldown      The cooldown period in seconds.
  --is-disabled   Disable notifications.

To configure a saved query with a target, use the following command:

spyctl notifications configure saved-query query:uOabbGEeJ \
--targets "email-target"

In this example:

--targets specifies the target (e.g., email) for sending notifications.
You can also customize settings like --cooldown or --is-disabled.

Note: You can configure notifications for multiple targets separated by comma.

For a Custom Flag:

To configure notifications for a custom flag, use the following command:

spyctl notifications configure custom-flag -h

This will display the usage and options for configuring notifications for a custom flag:

Usage: spyctl notifications configure custom-flag [OPTIONS] NAME_OR_UID

  Configure notifications for a custom flag.

Options:
  --target-map    Map target names to template names. Can be used multiple times. 
                  Usage: --target-map TGT_NAME=TEMPLATE_NAME
  --targets       The Name or UID of targets to send notifications to.
  --cooldown-by   The cooldown by field(s).
  --cooldown      The cooldown period in seconds.
  --is-disabled   Disable notifications.

To configure a custom flag with a target, run:

spyctl notifications configure custom-flag flag:teauh \
--targets "pagerduty-target"

This command configures notifications for a custom flag, sending them to the specified target (e.g., PagerDuty).

With these commands, you can easily configure notifications for saved queries and custom flags, specifying targets, templates, and additional options like cooldown periods

Step 4: Test Notifications

After configuring notifications, you can test whether they are properly set up using the below command. This can be done before enabling the notifications.

spyctl test-notification --target "email-alerts" \
--template "default-template"

This command sends a test notification to the specified target using the provided template. You can have to provide a JSON record file for the template values:

Example: For a Custom Flag (Redflag) - Provide the Redflag record For a Custom Flag (Opsflag) - Provide the Opsflag record For a Saved QUery - Provide the object record for which query is saved.

spyctl test-notification --target "slack-channel" \
--template "custom-template" \
--record-file test_record.json

Option

Description

-T, --target

Target name or UID to send a test notification to. (Required)

-P, --template

Template name or UID of the same type as the target. (Required)

-f, --record-file

File containing a JSON record used to build the notification. (Required)

You should be able to get a test notification in some-time after setting it up.

Step 5: Enable or Disable Notifications

After configuring and testing the notifications, you can toggle their status with the following commands to receive actual real-time Notfications:

Enable notifications:

spyctl notifications enable [OPTIONS] COMMAND [ARGS]...

Example:

spyctl notifications enable saved-query query:PpEjGdOSUJ

Disable notifications:

spyctl notifications disable [OPTIONS] COMMAND [ARGS]...

Example:

spyctl notifications disable saved-query query:PpEjGdOSUJ

Last updated 3 months ago

Was this helpful?