Notifications

Fugue offers notifications for compliance, drift, and baseline enforcement events across environments, allowing you to be alerted to infrastructure changes detected during a scan without having to log into Fugue. Email and Amazon SNS topic notifications provide visibility into changes that impact your compliance and security posture. Below is an example of a notification email that shows newly compliant and newly noncompliant resources detected during a scan:

_images/notifications-compliance.png

You can create notifications to alert you of any combination of compliance, drift, and/or enforcement events for any or all environments in your settings. Notifications are sent immediately after a scan detects changes. Each notification can alert you by email, Amazon SNS topic, or both. SNS messages will be published to an SNS topic Fugue creates for you or an existing topic of your choice, which can be connected to third-party tools such as Slack; see Example: Fugue Notifications in Slack.

_images/NotesSlack.png

For more example messages, see Example Notifications.

To jump right into creating a notification, see Setting Up Notifications.

The Notifications Tab

The Notifications tab can be accessed from the Settings page. It lists all of your existing notifications:

_images/notes-list.png

The notifications tab displays the following information:

_images/notes-list-annotated.png

Above, you’ll also see an ellipsis ... on the far right of each notification. Select the symbol to edit or delete the notification.

You can sort the notifications by name. Default is alphabetical order. Select the arrow next to the Name header to reverse direction:

_images/notifications-sort-name.png

If you have more than 10 notifications, you’ll see a dropdown menu below the table of notifications. You can choose to show 10, 20, 50, or 100 rows per page:

_images/row-dropdown.png

Setting Up Notifications

To set up a notification, navigate to the Settings page and select the Notifications tab. Then, select the Create New Notification button.

_images/notes-create-new-button.png

Follow the steps below to create a notification.

1. Definition

Enter a name for the notification in the “Name” field. In this example, we’re naming our notification Compliance and Drift - Dev Environments:

_images/notes-step-1.png

2. Environments

Select one or more environments to be notified about. You can search by environment name, environment ID, or cloud provider. Multiple search terms are supported – just use the Tab key after each term. Use Enter to search.

In this example, we’ve chosen to receive notifications for two of our three environments:

_images/notes-step-2.png

Note

To learn how Fugue handles notifications on multiple environments, see Notifications for Multiple Environments.

3. Events

Choose the event types you would like to be notified about. There are three options:

Compliance

Any changes to resource configurations that impact compliance.

Configuration Drift

Any changes to resource configurations that differ from environment baselines.

Baseline Enforcement

Fugue executing enforcement actions to enforce baseline configurations.

Below, we’ve chosen compliance and configuration drift. This means we’ll receive notifications when Fugue detects a change in compliance state or drift from baseline in either of our selected environments:

_images/notes-step-3.png

4. Delivery Methods

The two methods of notification delivery are SNS topic and email. You can use one or both methods. First, we’ll discuss SNS topic notifications. To jump ahead to email notifications, see Email Notifications.

SNS Topic Notifications

If you select SNS topic delivery, you can create SNS subscriptions however you like through the AWS Management Console or CLI. For example, you can set up an SNS subscription to send text messages to your mobile phone whenever Fugue sends a notification.

Fugue can create the SNS topic for you, or you can manually create a new topic or update an existing one.

For example messages, see Example SNS Notifications.

Note

If two notifications share the same SNS topic, the subscriptions will receive messages for both notifications. For this reason, you may wish to create a separate SNS topic for other notifications. See SNS Topic Notifications - Manual Setup.

Note

Fugue creates the topic in a non-GovCloud AWS region, but the topic can deliver notifications for any provider.

SNS Topic Notifications - Easy Setup

To sign up for SNS topic notifications and have Fugue create the topic for you, select the “Create new SNS topic” button:

_images/notes-step-4-create.png

Then, select the “Launch Stack in AWS Console” button. You’ll be brought to the CloudFormation “Create stack” page.

Note

Fugue creates the SNS topic in us-east-1 by default. To create it in a different location:

1. Select the desired region from the drop-down menu in the upper right of the AWS Console.

2. After the page reloads, manually change the region in the Amazon S3 URL field to the desired region (e.g., us-west-2).

You can finish setup by following the rest of the steps below.

_images/sns-topic-region.png

Select the “Next” button in the bottom right to continue.

Follow the prompts (default settings are fine) by clicking “Next” until you’re at the Review Topic Screen. Select the “Create” button at the bottom right.

Once the stack is created, if you click on the “Outputs” tab, you can copy the SNS ARN you see:

_images/NotesCfnOutput.png

Back in the Fugue notifications setup page, paste the ARN into the SNS Topic ARN field:

_images/sns-topic-arn-create.png

Next, you can sign up for email notifications if you like, or just select “Create Notification.” Fugue will create the notification and return you to the Notification Settings page, where you will see your new notification listed.

_images/NotesList.png
SNS Topic Notifications - Manual Setup

If two notifications share the same SNS topic, SNS subscriptions will receive messages for both notifications. For this reason, you may wish to manually create a new SNS topic for other notifications. Manual creation is necessary because AWS does not allow duplicate CloudFormation stack names or SNS topic names in the same account.

If you want to modify an existing SNS topic, you can follow the same process.

To sign up for SNS topic notifications and manually create or modify a topic, select the “Use existing SNS topic” button:

_images/notes-step-4-existing.png

Then, select the “Open SNS Topics in AWS Console” button or navigate directly to the console.

  • If you are creating a new topic: Select “Topics” from the links on the left, then select the “Create topic” button. On the next page, give your topic a name that is different from FugueSNSTopic. Next you’ll need to add the access policy, so click on “Access policy” and select “Advanced.”

  • If you are modifying an existing topic: Select “Topics” from the links on the left, then select the desired topic from the list and select the “Edit” button. Next you’ll need to update the access policy, so click on “Access policy.”

_images/NotesAccessPolicy.png  

The SNS topic access policy gives Fugue the permission it needs to publish notifications to the topic. Copy the JSON below and paste it into the JSON editor in AWS, then replace the bolded {variables} with your region, AWS account ID, and topic name. For example, you might replace {users-region} with us-east-1 and so on.

{
  "Version": "2012-10-17",
  "Id": "fugue_topic_policy",
  "Statement": [
    {
      "Sid": "cross_account_allow",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::370134896156:role/fugue-sns-publish"
      },
      "Action": "sns:Publish",
      "Resource": "arn:aws:sns:{users-region}:{users-account-id}:{users-topic-name}"
    },
    {
      "Sid": "cross_account_deny",
      "Effect": "Deny",
      "Principal": {
        "AWS": "arn:aws:iam::370134896156:role/fugue-sns-publish"
      },
      "NotAction": "sns:Publish",
      "Resource": "arn:aws:sns:{users-region}:{users-account-id}:{users-topic-name}"
    },
    {
      "Sid": "default_allow",
      "Effect": "Allow",
      "Principal": {
        "AWS": "*"
      },
      "Action": [
        "sns:GetTopicAttributes",
        "sns:SetTopicAttributes",
        "sns:AddPermission",
        "sns:RemovePermission",
        "sns:DeleteTopic",
        "sns:Subscribe",
        "sns:ListSubscriptionsByTopic",
        "sns:Publish"
      ],
      "Resource": "arn:aws:sns:{users-region}:{users-account-id}:{users-topic-name}",
      "Condition": {
        "StringEquals": {
          "AWS:SourceOwner": "{users-account-id}"
        }
      }
    }
  ]
}

Tip

If Fugue has already created an SNS topic for you, you can just copy the access policy from that topic.

Finally, select the “Save changes” button. You’ll be returned to the topic page. Copy the ARN in the “Details” section.

Back in the Fugue notifications setup page, paste the ARN into the SNS Topic ARN field:

_images/sns-topic-arn-existing.png

Email Notifications

Note

This section is for email notifications, where you receive an email whenever Fugue detects compliance changes in an environment. If you’re looking for a daily or weekly summary listing the overall compliance state of an environment or tenant, see Compliance Report Email.

To sign up for email notifications, simply enter the email address(es) into the “Email Recipients” field. In the example below, we’ve specified example@email.com:

_images/notes-signup-email.png

Press the Tab key to add additional email addresses if needed and press Delete to delete an address.

Next, select “Create Notification.” Fugue will create the notification and return you to the Notification Settings page, where you will see your new notification listed.

_images/NotesList.png

Editing or Deleting a Notification

To edit or delete a notification, navigate to the Notifications tab and find the ellipsis ... next to the notification you want to edit or delete:

_images/NotesEllipsis.png

Types of Notification Events

There are three types of events you can be notified of:

  • Compliance

  • Configuration Drift

  • Baseline Enforcement

Here’s a little more about each type of event.

Compliance Events

A compliance event is any change to resource configuration that impacts compliance. For example, if a resource’s compliance state changes from noncompliant to compliant, that counts as a compliance event.

A compliance event is when a compliance state changes from:

  • Compliant to noncompliant, or vice versa

  • Missing data to compliant, or vice versa

  • Missing data to noncompliant, or vice versa

An example of a compliance event is if a security group changes from compliant to noncompliant because it now has a rule opening port 22 to the world, violating CIS AWS (v1.2.0) 4.1.

Notifications are only triggered on the following compliance events:

  • An existing resource changes from compliant to noncompliant, or vice versa

  • A newly added resource is noncompliant

Although notifications aren’t generated for “Missing data” compliance state changes, all event data is accessible from the API. In the API, a state of “Missing data” is referred to as “Unknown.” An “Unknown” compliance state can occur when a compliance control can’t be assessed because it requires a specific resource but:

  • The resource does not exist.

  • Fugue does not have the necessary permissions to assess the resource.

Note

Compliance events are not currently shown in the environment dashboard. To see a list of compliance events, you may use the Fugue API /events endpoint. To learn how to send an API request, see the API User Guide. Note that in the API, a state of Missing Data is referred to as Unknown.

Configuration Drift Events

A drift event is any change to a resource configuration that differs from the environment baseline.

A drift event is any of the following:

  • A new resource has been added

  • An existing resource has been modified

  • An existing resource has been removed

An example of a drift event is if a baselined security group has a rule allowing one IP address to access port 22 and the rule is changed to allow ingress from the world.

Note that certain resource types do not report drift and therefore will not be included in drift notifications. See Resource Types That Don’t Report Drift for details.

Baseline Enforcement Events

A baseline enforcement event is an action Fugue takes to revert any configuration drift back to the established baseline.

Currently, Fugue only supports enforcement of modified resources.

An example of a enforcement event is if Fugue returns the drifted security group in the previous example back to its baseline state, so the security group rule no longer allows ingress from the internet on port 22.

Example Notifications

Example Email Notifications

If you have configured Fugue to send an email for any event type, the email contains the following information:

  • Type of notification (compliance, drift, enforcement)

  • Environment name

  • Cloud provider account ID

  • Scan time and date (UTC)

  • Region

  • List of events for that event type, including which resource types changed and how

Here’s an example compliance email:

_images/notifications-compliance.png

Here’s an example drift email:

_images/notifications-drift.png

Here’s an example enforcement email:

_images/notifications-enforcement.png

Example SNS Notifications

If you have configured Fugue to send an SNS notification for any event type, the SNS message includes basic information such as a summary, environment name, links to more information, and more in JSON format. Each message also includes event-specific information.

To jump ahead to event-specific examples, see:

For a line-by-line explanation of each JSON field in an SNS notification, continue reading below.

SNS Notifications, Line by Line

SNS messages for all event types include the following seven fields:

summary

A short summary listing the number of events, number of resource types, environment name, and time for the given event type

scan_id

The ID of the scan in which the events were detected

detected_at

What time the event was detected (UTC)

environment_id

The ID of the environment where the events occurred

environment_name

The name of the environment

app_url

The URL in Fugue where you can review details of the events (drift, enforcement events) or current compliance state per resource (compliance events)

api_url

The Fugue API path where you can retrieve the event details (all event types); see the API Reference for details

Depending on the event type, SNS messages also include fields with compliance, drift, and baseline enforcement information.

SNS Notifications - Compliance

Compliance notifications sent via SNS include the following additional JSON fields:

  • compliance_by_resource_type: A list of compliance changes for each resource type that changed. Includes the following fields for each resource type:

    • resource_type: The type of resource affected (e.g., "AWS.IAM.Policy")

    • newly_compliant: Within the given resource type, the number of resources that changed to a compliant state from any other state

    • newly_noncompliant: The number of resources that changed to a noncompliant state from any other state

    • newly_unknown: The number of resources that changed to an unknown state from any other state

    • removed: The number of resources that were removed since the last scan and therefore have no compliance state; this number is not included in the summary of compliance changes

Here’s a short example of a compliance notification with all the fields put together:

{
    "summary": "Fugue detected 3 compliance events across 1 resource type in Dev us-west-2 at 06/24/2019, 09:45 PM UTC.",
    "scan_id": "b0ecdbb9-192a-4fa2-8261-000000000000",
    "detected_at": "2019-06-24T21:45:21+00:00",
    "environment_id": "4d18a1d3-75bd-4456-8a20-000000000000",
    "environment_name": "Dev us-west-2",
    "app_url": "https://riskmanager.fugue.co/environments/4d18a1d3-75bd-4456-8a20-000000000000/compliance/types",
    "api_url": "https://api.riskmanager.fugue.co/v0/events?environment_id=4d18a1d3-75bd-4456-8a20-000000000000&range_from=1561412721&range_to=1561412721",
    "compliance_by_resource_type": [
        {
            "resource_type": "AWS.IAM.Policy",
            "newly_compliant": 2,
            "newly_noncompliant": 1,
            "newly_unknown": 0,
            "removed": 0
        }
    ]
}

SNS Notifications - Drift

Drift notifications sent via SNS include the following additional JSON fields:

  • drift_by_resource_type: A list of drift changes for each resource type that changed. Includes the following fields for each resource type:

    • resource_type: The type of resource affected (e.g., "AWS.EC2.SecurityGroup")

    • added_resources: The number of resources that have been added since the last scan

    • modified_resources: The number of existing resources that have been modifed since the last scan

    • removed_resources: The number of existing resources that have been removed since the last scan

Here’s a short example of a drift notification with all the fields put together:

{
    "summary": "Fugue detected 1 drift event across 1 resource type in Dev us-west-2 at 06/24/2019, 08:37 PM UTC: 0 resources were added, 1 resource was modified, and 0 resources were removed.",
    "scan_id": "0951de67-5aed-48ca-8806-000000000000",
    "detected_at": "2019-06-24T20:37:51+00:00",
    "environment_id": "4d18a1d3-75bd-4456-8a20-000000000000",
    "environment_name": "Dev us-west-2",
    "app_url": "https://riskmanager.fugue.co/environments/4d18a1d3-75bd-4456-8a20-000000000000/events?type=drift",
    "api_url": "https://api.riskmanager.fugue.co/v0/events?environment_id=4d18a1d3-75bd-4456-8a20-000000000000&range_from=1561408671&range_to=1561408671",
    "drift_by_resource_type": [
        {
            "resource_type": "AWS.EC2.SecurityGroup",
            "added_resources": 0,
            "modified_resources": 1,
            "removed_resources": 0
        }
    ]
}

SNS Notifications - Baseline enforcement

Baseline enforcement notifications sent via SNS include the following additional JSON fields:

  • remediation_by_resource_type: A list of enforcement changes for each resource type that changed. Includes the following fields for each resource type:

    • resource_type: The type of resource affected (e.g., "AWS.EC2.Vpc")

    • remediated_resources: The number of resources that were enforced

    • errors: The number of errors Fugue encountered during enforcement, if any

Here’s a short example of an enforcement notification with all the fields put together:

{
    "summary": "Fugue remediated 1 resource in GovCloud West - Dev at 06/25/2019, 04:39 PM UTC.",
    "scan_id": "9ab41af4-f295-4c72-bde4-000000000000",
    "detected_at": "2019-06-25T16:39:23+00:00",
    "environment_id": "8f12957b-9aec-40d2-9e4a-7b64e8d9900b",
    "environment_name": "GovCloud West - Dev",
    "app_url": "https://riskmanager.fugue.co/environments/8f12957b-9aec-40d2-9e4a-000000000000/events?type=remediation",
    "api_url": "https://api.riskmanager.fugue.co/v0/events?environment_id=8f12957b-9aec-40d2-9e4a-000000000000&range_from=1561480763&range_to=1561480763",
    "remediation_by_resource_type": [
        {
            "resource_type": "AWS.EC2.Vpc",
            "remediated_resources": 1,
            "errors": 0
        }
    ]
}

Notifications FAQ

What kind of events can Fugue notify me about?

Fugue can send notifications for compliance, drift, and baseline enforcement events.

What kind of drift events can Fugue notify me about?

You are notified for all drift events (i.e., added, modified, and removed).

Note that certain resource types do not report drift and therefore will not be included in drift notifications. See Resource Types That Don’t Report Drift for details.

When are notifications sent?

If compliance, drift, or enforcement events are detected during a scan, the relevant notifications are sent immediately after the scan.

Do you generate compliance events for newly scanned resources?

Yes. If there are 100 new resources (60 compliant and 40 noncompliant) detected during a scan, then Fugue generates 100 compliance events: 60 with compliant state and 40 with noncompliant state.

What region does the CloudFormation stack create the SNS topic in?

If you choose to have Fugue create the SNS topic for you, the topic is created by default in us-east-1 (N. Virginia). To create it in a different region, see this note.

If I get a notification that a resource has become noncompliant or drifted, and the resource is still noncompliant or drifted in the next scan, will I receive a second notification?

You will only receive an event notification for a resource if it has changed from the previous scan. For example, if a compliant resource becomes noncompliant in Scan 1 and remains noncompliant in Scan 2 and after, you’ll only be notified after Scan 1. The same is true for drift events. This is to prevent duplicate notifications and alert fatigue.

If the resource changes state again, Fugue sends you a notification.

How do notifications work for multiple environments?

A single notification generates separate emails or messages per event type. For example, if Fugue scans an environment configured to alert on compliance, drift, and enforcement events, you’ll receive one message for compliance events, one for drift events, and one for enforcement events.

One notification can be configured to send alerts for multiple environments, and each environment will have its own set of emails for events detected during its own scan. For instance, suppose you configure a notification for drift and enforcement events in two environments. When one environment is scanned, you’ll receive a message for drift events and another message for enforcement events. When the other environment is scanned, you’ll receive two more messages.

What’s the “Permissions check” SNS message I received?

If you edit a notification and update the SNS topic ARN in the “SNS Topic ARN” field, Fugue sends a test message to the topic to ensure the permissions are correct. If the topic has subscriptions, the subscriptions will receive the test message. The message says:

Permissions check from Fugue

You can safely disregard this message. If Fugue determines that the updated SNS topic does not have the correct permissions, Fugue displays the following error message and returns you to Notifications tab:

An error occurred while updating notification “Compliance and Drift-Dev Environments”. Please try again.

Does an event list what compliance controls passed or failed for a resource?

Yes, but only through the Fugue API /events endpoint. To learn how to send an API request, see the API User Guide.

Can I use the Fugue API to create, update, delete, or list notifications?

Yes, you can use the Fugue API to work with notifications. Follow the links below for documentation:

Can I configure notifications for my Azure environments?

Yes, you can configure notifications for Azure environments. Setup is the same. Additionally, notifications can include environments from different providers, so you can track Azure, AWS, and AWS GovCloud events within the same notification.

Does Fugue support encrypted SNS topics?

Fugue does not currently support encryption in SNS.