Notifications

Fugue offers notifications for compliance, drift, and baseline enforcement (auto-remediation) events across environments, allowing you to be alerted to infrastructure changes detected during a scan without having to log into Fugue. Email and AWS 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/NotesEmail.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 organization settings. Each notification can alert you by email, AWS 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 Organization Settings page. It lists all of your existing notifications:

_images/NotesList.png

The notifications tab displays the following information:

_images/NotesListAnnotated.png

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

Setting Up Notifications

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

_images/NotesCreateNewButton.png

You’ll see the Create New Notification modal. Follow the steps below to complete the workflow.

1. Enter the Name of the Notification

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

_images/NotesStep1.png

2. Select Environment(s)

Select the environment or environments you want to be notified about. You can select any or all. For details about notifications on multiple environments, see Notifications for Multiple Environments.

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

_images/NotesStep2.png

3. Select the Event Types

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 (Auto-remediation)

Fugue executing auto-remediation actions to enforce baseline configurations.

Below, we’ve chosen compliance and 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/NotesStep3.png

4. Select Notification Delivery Method

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/NotesStep4Create.png

Then, select the “Launch Stack in AWS Console” button. You’ll be brought to the CloudFormation “Create stack” page. 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/NotesSNSArn.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/NotesExistingTopic.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/NotesSNSArn.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, see Compliance Report Email.

To sign up for email notifications, simply enter the email address(es) into the “Email Recipients” field:

_images/NotesSignUpEmail.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 (Auto-remediation)

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

  • Unknown to compliant, or vice versa

  • Unknown to noncompliant, or vice versa

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.

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 4-1.

Note

Compliance events are not yet 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.

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.

Baseline Enforcement (Auto-remediation) Events

A baseline enforcement (auto-remediation) 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 an auto-remediation 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/NotesEmail.png

Here’s an example drift email:

_images/NotesEmailDrift.png

Here’s an example enforcement (auto-remediation) email:

_images/NotesEmailEnforcement.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 auto-remediation 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 - Auto-remediation

Auto-remediation (enforcement) notifications sent via SNS include the following additional JSON fields:

  • remediation_by_resource_type: A list of auto-remediation 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 remediated

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

Here’s a short example of an auto-remediation 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 auto-remediation (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).

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.

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 remediation events, you’ll receive one message for compliance events, one for drift events, and one for remediation 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 remediation events in two environments. When one environment is scanned, you’ll receive a message for drift events and another message for remediation 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.