Turbot Firehose AWS SNS

This mod provides the capability to send Turbot notifications to an AWS SNS topic. This is useful for pushing notifications from Turbot to other sources, be it email, a Security Information and Event Management (SIEM) tool, a logging tool, etc.

How It Works

First, you'll install the mod into your workspace. You'll then configure the mod by setting some policies with required information (details below). Once configured, you'll create a watch in Turbot. Watches, like the name implies, watch for notifications that match based on the criteria you specify. In the case of these watches, you'll tell them that when they find a match, to invoke a Turbot action that this mod contains. That action will in turn publish that notification to the prescribed SNS topic.

Watch -> Matching Notifications -> Firehose AWS SNS Action -> Publish to AWS SNS topic

Note that the Firehose AWS SNS mod forwards the notifications from watches, it does not correlate multiple events.

Setup

The following steps cover how to manually install and configure the mod. If you prefer Terraform, you can use this mod example for steps 2 - 5, and creating the Turbot Watch.

  1. Install the mod into your workspace if not already installed. See Installing Mods for more guidance.
  2. Create the AWS SNS topic. It can be in any account and any region. All the notifications will be forwarded to this topic.
  3. Create an AWS IAM User with access to the above SNS topic. Turbot will use this user to publish to the SNS topic. We recommend having a specific user that's only used for this mod.
  4. Generate an access key pair for the above IAM User.
  5. Set the following Turbot policies:
    • Turbot > Firehose > AWS SNS > Notification Topic - This is the topic ARN from step 2.
    • Turbot > Firehose > AWS SNS > Notification Access Key - This is the access key from step 4.
    • Turbot > Firehose > AWS SNS > Notification Secret Key - This is the secret key from step 4.

Turbot Watch

A Turbot Watch allows you to invoke an action based on Turbot notifications that match a specific filter. A watch is comprised of the following:

ParameterDescription
resource[REQUIRED] The resource to create the Watch for, either a Turbot ID or AKA.
filter[REQUIRED] A valid reverse filter to determine which notifications to process.
action[REQUIRED] The action the Watch takes when it finds a match, either a Turbot ID or URI.
options[OPTIONAL] Options for a Watch varies by action, and for the Firehose AWS SNS action there are currently no additional options.
favorite[OPTIONAL] Favorite to associate the Watch with, as a Turbot ID.

Filter

Filters are used to limit the notifications a Watch matches on to be more specific to your notification criteria. More information on filters can be found here.

Supported Filter Pivots

KeywordValueExample
controlCategoryIdTurbot ID or AKA of the Control Category.controlCategoryId:'tmod:@turbot/turbot#/control/categories/cmdbDiscovery'
controlCategoryLevellevel and / or descendantcontrolCategoryLevel:self,descendant
controlTypeIdTurbot ID or AKA of the Control Type.controlTypeId:'tmod:@turbot/aws-s3#/control/types/bucketVersioning'
controlTypeLevellevel and / or descendantcontrolTypeLevel:self,descendant
levellevel and / or descendantlevel:self
policyTypeIdTurbot ID or AKA of the Policy TypepolicyTypeId:'tmod:@turbot/aws-s3#/policy/types/bucketVersioning'
policyTypeLevelTurbot ID or AKA of the Policy TypepolicyTypeLevel:self,descendant
resourceCategoryIdTurbot ID or AKA of the Resource CategoryresourceCategoryId:'tmod:@turbot/turbot#/resource/categories/storage'
resourceCategoryLevellevel and / or descendantresourceCategoryLevel:self,descendant
resourceTypeIdTurbot ID or AKA of the Resource TyperesourceTypeId:'tmod:@turbot/aws-s3#/resource/types/bucket'
resourceTypeLevellevel and / or descendantresourceTypeLevel:self
notificationTypeSee Supported Notification TypesnotificationType:active_grants_deleted

Supported Notification Types

ItemActionNotification TypeDescription
ActionNotifyaction_notifyWhen a Turbot action invokes a notify command during a run.
ControlNotifycontrol_notifyWhen a Turbot control invokes a notify command during a run.
ControlUpdatedcontrol_updatedWhen a Turbot control is updated. Mainly, this is done to change the state of a control.
FavoriteCreatedfavorite_createdWhen a favorite is created for a resource.
FavoriteDeletedfavorite_deletedWhen a favorite is deleted for a resource.
Grant ActivationCreatedactive_grants_createdWhen a Turbot grant is activated.
Grant ActivationDeletedactive_grants_deletedWhen a Turbot grant is deleted.
GrantCreatedgrant_createdWhen a Turbot grant is created. By default in the UI "Activate for immediate use" is checked. In that case, a grant_created notification is generated followed by active_grants_created.
GrantDeletedgrant_deletedWhen a Turbot grant is deleted.
Policy SettingCreatedpolicy_setting_createdWhen a new Turbot policy setting is created.
Policy SettingDeletedpolicy_setting_deletedWhen an existing Turbot policy setting is deleted.
Policy SettingUpdatedpolicy_setting_updatedWhen an existing Turbot policy setting is updated.
Policy ValueUpdatedpolicy_value_updatedWhen a Turbot policy value is updated.
ResourceCreatedresource_createdWhen a new resource is created in Turbot.
ResourceDeletedresource_deletedWhen a resource in Turbot is deleted.
ResourceUpdatedresource_updatedWhen a resource in Turbot is updated.

WARNING: Creating other notifications beyond the supported notification types below will cause system instability.

You may also filter by any resource property with $., including $.turbot.tags. The $. object always represents the resource the notification is for.

NOTE: Watches do not support specifying a resourceId in the filter. If you want to monitor a resource, create the watch on that specific resource instead.

Creating Watches

There is currently no mechanism to create a watch in the UI. To create a watch, you can use the following mutation example.

mutation CreateWatch($input: CreateWatchInput!) {
createWatch(input: $input) {
filters
handler
turbot {
id
resourceId
}
}
}
{
"input": {
"resource": "185423120545381",
"action": "tmod:@turbot/firehose-aws-sns#/action/types/router",
"filters": [
"level:self,descendant notificationType:active_grants_deleted"
]
}
}

Notifications

A Notification represents an event that occurred in Turbot. The notification will include detailed information about the affected resource, control, policy value, policy setting, etc. This data includes the object detail before and after the event, standard Turbot metadata, and other details of the event.

Sample Notification

Below is a sample notification of type active_grants_deleted.

{
"notificationType": "active_grants_deleted",
"actor": {
"identity": {
"picture": "https://www.gravatar.com/avatar/cb9ff8606c24daf9cda1d82615bd7a8e",
"turbot": {
"title": "Timon Berkowitz",
"id": "186957187212252"
},
"title": "Timon Berkowitz"
}
},
"turbot": {
"id": "202473982728085",
"createTimestamp": "2020-09-10T17:34:58.063Z"
},
"oldActiveGrant": {
"grant": {
"type": {
"trunk": {
"title": "Turbot"
}
},
"level": {
"trunk": {
"title": "User > Metadata > ReadOnly"
}
},
"resource": {
"trunk": {
"title": "Turbot"
}
},
"identity": {
"trunk": {
"title": "Turbot > Turbot Local > Pumbaa Smith"
}
}
},
"resource": {
"trunk": {
"title": "Turbot"
}
}
}
}

Notification Template

The render actions will use a render template to transform the input to the format to be sent to the AWS SNS topic. These render templates are implemented as Turbot policies. You may choose to override these templates (policies) in the format that is suitable for your need.

For example, in order to update the render template for active_grants_deleted notification type, use the Turbot Policy Turbot > Firehose > AWS SNS > Notification Template > Active Grants Deleted. All supported templates can be found under the parent policy type Turbot > Firehose > AWS SNS > Notification Template.

Version
1.1.6
Released On
Jan 04, 2024
Depends On

Policy Types

Release Notes

  • Updated: Turbot > Firehose > AWS SNS > Notification Topic policy to allow gov cloud SNS endpoint.

1.1.2 (2021-08-31)

  • Fixed: added debug log when sending out notifications.

1.1.1 (2021-05-25)

  • Updated: Resource Created, Resource Updated, Resource Deleted and Control Updated templates.

1.1.0 (2021-01-29)

  • Updated: Resource Deleted template.

1.0.5 (2020-11-06)

  • Fixed: removed stray debug log.

1.0.4 (2020-11-06)

  • Fixed: removed stray debug log.

1.0.3 (2020-10-21)

  • Fixed formatting issues and hyperlinks in README

1.0.2 (2020-10-20)

  • Fixed formatting issues in README

1.0.1 (2020-09-17)

  • Fixed formatting issues in README

1.0.0 (2020-09-17)

Policy Types

Added

  • Turbot > Firehose > AWS SNS
  • Turbot > Firehose > AWS SNS > Notification Access Key
  • Turbot > Firehose > AWS SNS > Notification Secret Key
  • Turbot > Firehose > AWS SNS > Notification Template
  • Turbot > Firehose > AWS SNS > Notification Template > Action Notify
  • Turbot > Firehose > AWS SNS > Notification Template > Active Grants Created
  • Turbot > Firehose > AWS SNS > Notification Template > Active Grants Deleted
  • Turbot > Firehose > AWS SNS > Notification Template > Control Notify
  • Turbot > Firehose > AWS SNS > Notification Template > Control Updated
  • Turbot > Firehose > AWS SNS > Notification Template > Favorite Created
  • Turbot > Firehose > AWS SNS > Notification Template > Favorite Deleted
  • Turbot > Firehose > AWS SNS > Notification Template > Grant Created
  • Turbot > Firehose > AWS SNS > Notification Template > Grant Deleted
  • Turbot > Firehose > AWS SNS > Notification Template > Notification Subject
  • Turbot > Firehose > AWS SNS > Notification Template > Notification Subject Deleted
  • Turbot > Firehose > AWS SNS > Notification Template > Policy Setting Created
  • Turbot > Firehose > AWS SNS > Notification Template > Policy Setting Deleted
  • Turbot > Firehose > AWS SNS > Notification Template > Policy Setting Updated
  • Turbot > Firehose > AWS SNS > Notification Template > Policy Value Updated
  • Turbot > Firehose > AWS SNS > Notification Template > Resource Created
  • Turbot > Firehose > AWS SNS > Notification Template > Resource Deleted
  • Turbot > Firehose > AWS SNS > Notification Template > Resource Updated
  • Turbot > Firehose > AWS SNS > Notification Topic

Action Types

Added

  • Render
  • Render Resource Deleted
  • Router
  • SNS Sender