IAMNagBot

AWS Lambda to send out notifications about upcoming expirations for IAM resources

NagBot currently supports sending out notifications via SES emails or Slack.

Deployment

There are a pair of Terraform (TF) modules included that provide...

iam-nagbot - deployment and configuration of the IAMNagBot Lambda and supporting infrastructure
iam-selfservice - convenient way to grant IAM permissions to users to manage their own credentials

Each of the TF modules above have their own README's to describe their use and configuration. If you don't currently use Terraform to manage your infrastructure, you should still be able to look over the TF module code and glean the necessary AWS resources and steps necessary to deploy the Lambda function, and translate that into other tooling such as CloudFormation or simple CLI scripts.

Configuration

You can configure the following settings:

Setting	Description
`PasswordExpiredInDays`	Specify the maximum age of a Password. (int, defaults to 90)
`AccessKeyExpiredInDays`	Specify the maximum age of an Access Key.
`EarlyWarningInDays`	Specifies the number of days before expiration to start "early warning" notifications. (int, defaults to 5, may be 0 to disable)
Email
`EmailFrom`	By specifying a From address, you enable email support.
`DefaultEmailTo`	If email support is enabled and an IAM user does not have an email address tag, then
`AlwaysEmailTo`	If email support is enabled, this email address wil be used always regardless of an email tag on the IAM user.
Slack
`SlackOauthToken`	By specifying the the OAuth Token, you enable Slack support.
`DefaultSlackTo`	If Slack support is enabled and an IAM user does not have an slack tag, then this slack address will be used instead. Can be a channel (starts with `#`) or user (starts with `@`).
`AlwaysSlackTo`	If Slack support is enabled, this Slack address wil be used always regardless of an email tag on the IAM user. Can be a channel (starts with `#`) or user (starts with `@`).
Templates
`TemplateUrl`	A URL that resolves to content to template content for a specific notification method, category and type. Defaults to a set of built-in generic templates (packaged in the assembly). See more details below.
`NotificationCountLimit`	If set to a number greater than zero, then will stop after this number of notifications have been sent. (int, default to 0)

IAM User Tags

In order for NagBot to know where to send notifications, it looks for tags on the user objects to identify email and Slack addresses:

IAM User Tag	Description
`email`	Email address to send notifications to.
`slack`	Slack address to send notifications to. Can be a user (starts with `@`) or a channel (starts with `+` -- tags don't allow `#` characters so it will be replaced).

Notification Templates

The content of notification messages is resolved using the Scriban template language, which is very similar to the popular liquid template language but arguably more powerful and expressive.

In the context of evaluating a template, there is a model of variables that can be used to access details of the specific notification being evaluated. The model includes the following elements:

Variable	Description
`notification_method`	The method used to send the notification, at present this can be either `email` or `slack`.
`username`	The name of the IAM user that the notification is targetting.
`notification`	An object that provides additional details about the notification that are specific to the type of notification. You access these additional details by using a dotted notation on this object, e.g. `notification.property` (see below).

The `notification` Context Object

In addition to the common model details that are always available in the template context, the model object notification provides further details that are specific to the type of notification and it will contain some combination of the following elements.

These properties will always be available on the notification model object:

Property	Description
Common
`credential`	the type of credential being notified about, either `password` or `accessKey`.
`category`	the category of the notification, either `warning` or `expired`.
Type-specific
`days_expired`	for category of `expired`, the number of days the credential has been expired
`days_left`	for category of `warning`, the number of days left before expiration
`access_key_id`	for the credential type of `accessKey`, the ID of the specific Access Key that is being referenced (each user can have up to 2).

Custom Template Content

By default, the template content is resolved to an internal set of built-in generic templates (packaged as embedded resources with the assembly). You can override the templates being used by providing the TemplateUrl configuration setting (mentioned above). You can only provide a single URL to override this setting, but the URL can resolve to a different, notification-specific template for each combination of notification method, credential type and category. This is possible because the URL itself is first evaluated as a Scriban template.

So as an example, the Template URL can reference some HTTPS endpoint using these details to resolve to a different template for each notification, such as:

https://some-host-that-lambda-can-reach.com/some/path/to/templates/{{notification_method}}/{{notification.credential}}-{{notification.category}}.yml

Special Support for S3 URls

In addition to any URL that would be natively supported by the .NET platform for streaming content from, special support has been added for S3 URLs that will be accessed using the security context of the caller (i.e. the Lambda function). The format of the URL is as follows:

s3://bucket-name/path/to/object/key.ext

Template to YAML Deserialization

There is one additional aspect to notification templates that needs to be taken into account -- the template content when evaluated using the Scriban template language needs to resolve to a legal YAML object. This resolved YAML object is then deserialized to an actual method-specific data object.

This approach allows you to control many aspects of the notification in addition to the actual notification message content, for example for the email method, you can control the from email address, you can include CC and BCC addresses.

YAML Deserialization for Email

For the email notification method, the YAML content will be deserialized to an instance of the Amazon.SimpleEmail.Model.SendEmailRequest class which is documented here.

There are a number of properties that can be used to control the message being sent including both text and HTML content. Here is an example of a template resolved for an email message sending out a warning about a soon-to-be-expired password notification:

Source: "{{email_from}}"
Destination:
  ToAddresses:
    - "{{email_to}}"
Message:
  Subject:
    Data: "[IAMNagBot] Password Expiring Soon"
  Body:
    Text:
      Data: |
        Your Password for user account {{username}} will be
        expiring in {{notification.days_left}} day(s).
        
        Please sign in to your account and rotate your password before it expires.
    Html:
      Data: |
        <h1>Message from IAMNagBot</h1>
        
        <p>
          Your password for user account <b><code>{{username}}</code></b>
          will be expiring in <b>{{notification.days_left}}</b> day(s).
        </p><p>
          Please sign in to your account and rotate your password before it expires.
        </p>

YAML Deserialization for Slack

For the slack notification method, the YAML content will be deserialized and transformed to a JSON object that will be provided as a payload for invoking the Slack chat.postMessage API method. The template content should resolve to a JSON payload with this API method's arguments.

Here is an example of a template resolved for a Slack message with an expired alert for an accessKey:

channel: "{{slack_to}}"
text: |
  Your Access Key {{notification.access_key_id}} for user account {{username}}
  has been expired for {{notification.days_expired}} day(s).
  
  Please sign in to your account and rotate your Access Key today!

zyborg/IAMNagBot