Merge pull request #82 from trussworks/smt-better-slack-messaging

[MB-7353] better slack messaging

Author: sheenamt

CHANGELOG.md

@@ -3,6 +3,15 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.3.0] - 2021-03-30
+
+### Added
+
+- New variables for INACTIVE_NOTIFICATION_TITLE and INACTIVE_NOTIFICATION_TEXT
+- Improved messaging for key expiration reasonings
+- Documentation for testing app locally
+- Required permission for iam:GetAccessKeyLastUsed
+
 ## [1.2.1] - 2021-03-04
 
 ### Added

README.md

@@ -84,12 +84,14 @@ module "iam_sleuth" {
     ENABLE_AUTO_EXPIRE  = "false"
     EXPIRATION_AGE      = 90
     WARNING_AGE         = 50
+    EXPIRE_NOTIFICATION_TITLE           = "Key Rotation Instructions"
+    EXPIRE_NOTIFICATION_TEXT            = "Please run.\n ```aws-vault rotate AWS-PROFILE```"
     INACTIVITY_AGE       = 30
     INACTIVITY_WARNING_AGE = 20
+    INACTIVE_NOTIFICATION_TITLE         = "Key Usage Instructions to prevent key auto-disable"
+    INACTIVE_NOTIFICATION_TEXT          = "Please run.\n ```aws-vault login AWS-PROFILE```"
     SLACK_URL           = data.aws_ssm_parameter.slack_url.value
     SNS_TOPIC           = ""
-    MSG_TITLE           = "Key Rotation Instructions"
-    MSG_TEXT            = "Please run.\n ```aws-vault rotate AWS-PROFILE```"
   }
 
   tags = {
@@ -107,11 +109,13 @@ The behavior can be configured by environment variables.
 |------|------------ |
 | ENABLE_AUTO_EXPIRE | Must be set to `true` for key disable action |
 | EXPIRATION_AGE | Age of key creation (in days) to disable a AWS key |
+| EXPIRE_NOTIFICATION_TITLE | Title of the notification message for keys expiring due to creation age|
+| EXPIRE_NOTIFICATION_TEXT | Instructions on key rotation |
 | WARNING_AGE | Age of key creation (in days) to send notifications, must be lower than EXPIRATION_AGE |
 | INACTIVITY_AGE | OPTIONAL, defaults to EXPIRATION_AGE, Age of last key usage (in days) to disable AWS key, must be lower than or equal to EXPIRATION_AGE |
 | INACTIVITY_WARNING_AGE | REQUIRED IF INACTIVITY_AGE is set, otherwise defaults to WARNING, Age of last key usage (in days) to send notifications, must be lower than INACTIVITY_AGE |
-| MSG_TITLE | Title of the notification message |
-| MSG_TEXT | Instructions on key rotation |
+| INACTIVE_NOTIFICATION_TITLE | Title of the notification message for keys expiring due to inactivity |
+| INACTIVE_NOTIFICATION_TEXT | Instructions on key usage to prevent expiration due to inactivity |
 | SLACK_URL | Incoming webhook to send notifications to |
 | SNS_TOPIC | Topic to send a SNS formatted message to |
 | DEBUG | If present will log additional things |
@@ -152,8 +156,81 @@ pip install -r ./sleuth/requirements.txt
 
 ### Testing
 
-To test the Python app:
+All following steps assume you have activated the virtual environment from the previous step.
+
+To run the Python app unittests:
 
 ```sh
 pytest
 ```
+
+To run the python app locally, using trussworks-ci as example account:
+
+1. Login to the trussworks-ci account
+
+   ```shell
+   aws-vault login trussworks-ci
+   ```
+
+1. Create test user(s), giving them access keys and optional KeyAutoExire tag
+
+   | UserName     | Slack ID     | Key ID               | AutoExpire |
+   |--------------|--------------|----------------------|------------|
+   | sleuth-test1 | sleuth-test1 | KEYID1 | FALSE      |
+   | sleuth-test2 | sleuth-test2 | KEYID2 | TRUE       |
+
+1. In the CLI, move to the sleuth subdirectory:
+
+   ```shell
+   cd /path/to/trussworks/terraform-aws-iam-sleuth/sleuth
+   ```
+
+1. Export the relevant variables:
+
+   To test the warnings for creation date expiration, considering a key that was made today, use:
+
+   ```shell
+   export DEBUG=true
+   export SLACK_URL=test
+   export EXPIRATION_AGE=90
+   export WARNING_AGE=0
+   ```
+
+   To test the warnings for inactivity expiration, considering a key that was made today, use:
+
+   ```shell
+   export DEBUG=true
+   export SLACK_URL=test
+   export EXPIRATION_AGE=90
+   export WARNING_AGE=1
+   export INACTIVITY_AGE=30
+   export INACTIVITY_WARNING_AGE=0
+   ```
+
+    NOTE: Creation age expiration takes precedent over activity age, so setting both `WARNING_AGE=0` and `INACTIVITY_WARNING_AGE=0` will cause only the creation date expiration warning to appear.
+
+1. Run the app
+
+   ```shell
+   aws-vault exec trussworks-ci -- python handler.py
+   ```
+
+- Example DEBUG output for creation age, notice the 'old' status:
+
+   | UserName     | Slack ID     | Key ID               | AutoExpire | Status | Age in Days | Last Access Age |
+   |--------------|--------------|----------------------|------------|--------|-------------|-----------------|
+   | sleuth-test1 | sleuth-test1 | KEYID1 | FALSE      | good   | 0           | 0               |
+   | sleuth-test2 | sleuth-test2 | KEYID2 | TRUE       | old    | 0           | 0               |
+
+- Example DEBUG output for inactivity age, notice the 'stagnant' status:
+
+   | UserName     | Slack ID     | Key ID               | AutoExpire | Status | Age in Days | Last Access Age |
+   |--------------|--------------|----------------------|------------|--------|-------------|-----------------|
+   | sleuth-test1 | sleuth-test1 | KEYID1 | FALSE      | good   | 0           | 0               |
+   | sleuth-test2 | sleuth-test2 | KEYID2 | TRUE       | stagnant    | 0           | 0               |
+
+- By exporting the SLACK_URL=test in addition to DEBUG=true, you can also view the slack message output:
+
+  ```shell
+  slack message: {'attachments': [{'title': 'AWS IAM Key Inactivity Report', 'text': ''}, {'title': 'IAM users with access keys expiring due to inactivity. \n Please login to AWS to prevent key from being disabled', 'color': '#ffff00', 'fields': [{'title': 'Users', 'value': "sleuth-test2's key expires in 30 days due to inactivity."}]}]}
+  ```

examples/simple/main.tf

@@ -58,6 +58,7 @@ data "aws_iam_policy_document" "basic_task_role_policy_doc" {
       "iam:UpdateAccessKey",
       "iam:ListAccessKeys",
       "iam:ListUserTags",
+      "iam:GetAccessKeyLastUsed",
     ]
 
     resources = ["arn:aws:iam::*:user/*"]

sleuth/handler.py

@@ -36,7 +36,7 @@
 
 from sleuth.auditor import audit
 
-VERSION = '1.2.1'
+VERSION = '1.3.0'
 
 def handler(event, context):
     """

sleuth/sleuth/auditor.py

@@ -21,7 +21,8 @@ class Key():
 
     creation_age = 0
     access_age = 0
-    valid_for = 0
+    creation_valid_for = 0
+    activity_valid_for = 0
 
     def __init__(self, username, key_id, status, created, inactivity_age):
         self.username = username
@@ -44,7 +45,7 @@ def audit(self, rotate_age, expire_age, max_inactivity_age, inactivity_warning_a
         rotate (int): Age key must be before audit_state=old
         expire (int): Age key must be before audit_state=expire
         inactivity_age (int): Age of last key usage must be before audit_state=expire
-        inactivity_warning_age (int): Age of last key usage must be before audit_state=old
+        inactivity_warning_age (int): Age of last key usage must be before audit_state=stagnant
 
         Returns:
         None
@@ -54,16 +55,22 @@ def audit(self, rotate_age, expire_age, max_inactivity_age, inactivity_warning_a
         assert(inactivity_warning_age < max_inactivity_age)
 
         # set the valid_for in the object
-        self.valid_for = expire_age - self.creation_age
+        self.creation_valid_for = expire_age - self.creation_age
+        self.activity_valid_for = max_inactivity_age - self.access_age
+
 
         # lets audit the age
         if self.creation_age >= expire_age:
             self.audit_state = 'expire'
         elif self.access_age >= max_inactivity_age:
-            self.audit_state = 'expire'
-        # audit key age and last used age
-        elif (self.creation_age >= rotate_age and self.creation_age < expire_age) or (self.access_age >= inactivity_warning_age and self.access_age < max_inactivity_age):
+            self.audit_state = 'stagnant_expire'
+        # audit key age, which is more important than inactivity age
+        elif (self.creation_age >= rotate_age and self.creation_age < expire_age):
             self.audit_state = 'old'
+        # audit activity age, set to 'stagnant' to not confuse with AWS official "Inactive" status
+        elif (self.access_age >= inactivity_warning_age and self.access_age < max_inactivity_age):
+            self.audit_state = 'stagnant'
+        # finally, if nothing requires us to alert on this key, set to good
         elif self.creation_age < rotate_age:
             self.audit_state = 'good'
 
@@ -120,7 +127,7 @@ def audit():
 
     # Check for optional env vars
     if (os.environ.get('INACTIVITY_AGE') and not os.environ.get('INACTIVITY_WARNING_AGE')) or (os.environ.get('INACTIVITY_WARNING_AGE') and not os.environ.get('INACTIVITY_AGE')):
-        raise RuntimeError('Must set env var INACTIVITY_WARNING_AGE and INACTIVITY_AGE')
+        raise RuntimeError('Must set env var INACTIVITY_WARNING_AGE and INACTIVITY_AGE together')
 
     # lets audit keys so the ages and state are set
     for u in iam_users:
@@ -140,18 +147,21 @@ def audit():
     if os.environ.get('ENABLE_AUTO_EXPIRE', False) == 'true':
         for u in iam_users:
             for k in u.keys:
-                if k.audit_state == 'expire':
+                if k.audit_state == 'expire' or k.audit_state == 'stagnant_expire':
                     disable_key(k, u.username)
     else:
         LOGGER.warn('Cannot disable AWS Keys, ENABLE_AUTO_EXPIRE set to False')
 
-    MSG_TITLE = os.environ.get('NOTIFICATION_TITLE', 'AWS IAM Key Report')
-    MSG_TEXT = os.environ.get('NOTIFICATION_TEXT', '')
+    # Default expiration headers
+    EXP_MSG_TITLE = os.environ.get('EXPIRE_NOTIFICATION_TITLE', 'AWS IAM Key Expiration Report')
+    EXP_MSG_TEXT = os.environ.get('EXPIRE_NOTIFICATION_TEXT', '')
+    STGNT_MSG_TITLE = os.environ.get('INACTIVE_NOTIFICATION_TITLE', 'AWS IAM Key Inactivity Report')
+    STGNT_MSG_TEXT = os.environ.get('INACTIVE_NOTIFICATION_TEXT', '')
 
     # lets assemble the SNS message
     if os.environ.get('SNS_TOPIC', None) is not None:
         LOGGER.info('Detected SNS settings, preparing and sending message via SNS')
-        send_to_slack, slack_msg = prepare_sns_message(iam_users, MSG_TITLE, MSG_TEXT)
+        send_to_slack, slack_msg = prepare_sns_message(iam_users, EXP_MSG_TITLE, EXP_MSG_TEXT, STGNT_MSG_TITLE, STGNT_MSG_TEXT)
 
         if send_to_slack:
             send_sns_message(os.environ['SNS_TOPIC'], slack_msg)
@@ -163,9 +173,10 @@ def audit():
     if os.environ.get('SLACK_URL', None) is not None:
         LOGGER.info('Detected Slack settings, preparing and sending message via Slack API')
         # lets assemble the slack message
-        send_to_slack, slack_msg = prepare_slack_message(iam_users, MSG_TITLE, MSG_TEXT)
-
-        if send_to_slack:
+        send_to_slack, slack_msg = prepare_slack_message(iam_users, EXP_MSG_TITLE, EXP_MSG_TEXT, STGNT_MSG_TITLE, STGNT_MSG_TEXT)
+        if os.environ.get('DEBUG', False):
+            print("slack message:", slack_msg)
+        elif send_to_slack:
             send_slack_message(os.environ['SLACK_URL'], slack_msg)
         else:
             LOGGER.info('Nothing to report')