add permission notifier module

Author: JimmyIL

permission-alert/README.md

@@ -0,0 +1,78 @@
+# IAM Role Admin Privilege Monitor
+
+This project provides an automated way to **monitor IAM roles for privilege escalation**. It leverages AWS EventBridge, Lambda, and SNS to detect when IAM role permissions change and sends an alert if administrative privileges are added.
+
+---
+
+## Overview
+
+- **Input:** One or more IAM role names to monitor.
+- **Event Trigger:** AWS EventBridge rule that listens for `IAM Role Policy` changes.
+- **Detection:** A Lambda function (written in TypeScript) inspects the target role’s:
+  - Inline policies
+  - Attached custom policies
+  - Attached managed policies
+- **Alerting:** If the role gains `AdministratorAccess` or wildcard permissions (`*` actions/resources), the Lambda publishes a message to the specified SNS topic.
+
+This helps prevent **unauthorized privilege escalation** in AWS accounts.
+
+---
+
+## Architecture
+
+1. **Terraform Module**
+   - Creates EventBridge rule for IAM role policy changes
+   - Provisions a Lambda function with detection logic
+   - Grants Lambda necessary IAM permissions
+   - Connects Lambda to SNS topic for alerts
+
+2. **Lambda Function (TypeScript)**
+   - Fetches IAM role policy details
+   - Detects admin-like privileges
+   - Publishes findings to SNS
+
+---
+
+## Project Structure
+
+.
+├── main.tf # Root module entrypoint
+├── iam.tf # IAM permissions for Lambda
+├── lambda.tf # Lambda packaging and deployment
+├── cw_events.tf # CloudWatch / EventBridge rules
+├── outputs.tf # Module outputs
+├── variables.tf # Input variables
+├── versions.tf # Provider versions
+└── lambda/
+
+---
+
+## Inputs
+
+| Variable        | Type           | Description                                                     |
+| --------------- | -------------- | --------------------------------------------------------------- |
+| `role_names`    | `list(string)` | List of IAM role names to monitor (e.g. `["role_A", "role_B"]`) |
+| `sns_topic_arn` | `string`       | ARN of an existing SNS topic to publish alerts                  |
+
+---
+
+## Outputs
+
+| Output        | Description                                          |
+| ------------- | ---------------------------------------------------- |
+| `lambda_name` | Name of the monitoring Lambda function               |
+| `rule_arn`    | ARN of the EventBridge rule that triggers the Lambda |
+
+---
+
+## Usage
+
+Example Terraform configuration:
+
+```hcl
+module "iam_role_alerts" {
+  source        = "<path_to_this_repository_and_version>"
+  sns_topic_arn = aws_sns_topic.role_policy_alerts.arn
+  role_names    = ["my-infra-apply-role", "my-infra-plan-role"]
+}
+```

permission-alert/cw_events.tf

@@ -0,0 +1,37 @@
+# EventBridge rule to react to any IAM changes that could elevate privileges
+# While this detects changes to any role, the Lambda will filter to just the target role
+resource "aws_cloudwatch_event_rule" "iam_changes" {
+  name        = "role-admin-detector-iam-events"
+  description = "Trigger when IAM role/policy changes occur"
+
+  event_pattern = jsonencode({
+    "source" : ["aws.iam"],
+    "detail-type" : ["AWS API Call via CloudTrail"],
+    "detail" : {
+      "eventSource" : ["iam.amazonaws.com"],
+      "eventName" : [
+        # Attach/detach/inline policy changes for roles
+        "AttachRolePolicy",
+        "DetachRolePolicy",
+        "PutRolePolicy",
+        "DeleteRolePolicy",
+        # Managed policy lifecycle that could affect effective perms
+        "CreatePolicy",
+        "CreatePolicyVersion",
+        "SetDefaultPolicyVersion",
+        "DeletePolicyVersion",
+        "CreatePolicyVersion",
+        # Permissions boundary or trust changes (paranoid coverage)
+        "PutRolePermissionsBoundary",
+        "DeleteRolePermissionsBoundary",
+        "UpdateAssumeRolePolicy"
+      ]
+    }
+  })
+}
+
+resource "aws_cloudwatch_event_target" "to_lambda" {
+  rule      = aws_cloudwatch_event_rule.iam_changes.name
+  target_id = "role-admin-detector"
+  arn       = aws_lambda_function.detector.arn
+}

permission-alert/iam.tf

@@ -0,0 +1,62 @@
+data "aws_iam_policy_document" "detector_lambda_assume" {
+  statement {
+    effect = "Allow"
+    principals {
+      type        = "Service"
+      identifiers = ["lambda.amazonaws.com"]
+    }
+    actions = ["sts:AssumeRole"]
+  }
+}
+
+resource "aws_iam_role" "detector_lambda" {
+  name               = "iam-admin-detector-role"
+  assume_role_policy = data.aws_iam_policy_document.detector_lambda_assume.json
+}
+
+# Permissions for:
+# - Reading IAM role policies (attached + inline)
+# - Publishing to SNS
+# - Writing CloudWatch Logs
+data "aws_iam_policy_document" "detector_permissions" {
+  statement {
+    sid    = "IamRead"
+    effect = "Allow"
+    actions = [
+      "iam:GetPolicy",
+      "iam:GetPolicyVersion",
+      "iam:GetRolePolicy",
+      "iam:ListRolePolicies",
+      "iam:ListAttachedRolePolicies"
+    ]
+    resources = ["*"]
+  }
+
+  statement {
+    sid       = "AllowPublishToTopic"
+    effect    = "Allow"
+    actions   = ["sns:Publish"]
+    resources = [var.sns_topic_arn]
+  }
+
+  statement {
+    sid    = "Logs"
+    effect = "Allow"
+    actions = [
+      "logs:CreateLogGroup",
+      "logs:CreateLogStream",
+      "logs:PutLogEvents"
+    ]
+    resources = ["arn:aws:logs:*:*:*"]
+  }
+}
+
+resource "aws_iam_policy" "detector_inline" {
+  name   = "iam-admin-detector-inline"
+  policy = data.aws_iam_policy_document.detector_permissions.json
+}
+
+resource "aws_iam_role_policy_attachment" "detector_inline_attach" {
+  role       = aws_iam_role.detector_lambda.name
+  policy_arn = aws_iam_policy.detector_inline.arn
+}

permission-alert/lambda.tf

@@ -0,0 +1,48 @@
+# Build the TypeScript Lambda locally using esbuild
+resource "null_resource" "build_lambda" {
+  triggers = {
+    src_hash      = filesha256("${path.module}/lambda/src/index.ts")
+    pkg_hash      = filesha256("${path.module}/lambda/package.json")
+    lock_hash     = fileexists("${path.module}/lambda/package-lock.json") ? filesha256("${path.module}/lambda/package-lock.json") : ""
+    tsconfig_hash = filesha256("${path.module}/lambda/tsconfig.json")
+  }
+
+  provisioner "local-exec" {
+    command = "cd ${path.module}/lambda && npm ci && npm run build"
+  }
+}
+
+data "archive_file" "detector_zip" {
+  type        = "zip"
+  source_file = "${path.module}/lambda/dist/index.js"
+  output_path = "${path.module}/lambda/detector.zip"
+
+  depends_on = [null_resource.build_lambda]
+}
+
+resource "aws_lambda_function" "detector" {
+  function_name = "role-admin-detector"
+  role          = aws_iam_role.detector_lambda.arn
+  handler       = "index.handler"
+  runtime       = "nodejs20.x"
+
+  filename         = data.archive_file.detector_zip.output_path
+  source_code_hash = data.archive_file.detector_zip.output_base64sha256
+
+  environment {
+    variables = {
+      SNS_TOPIC_ARN = var.sns_topic_arn
+      TARGET_ROLES  = join(",", var.role_names)
+    }
+  }
+
+  timeout = 30
+}
+
+resource "aws_lambda_permission" "allow_events" {
+  statement_id  = "AllowExecutionFromEventBridge"
+  action        = "lambda:InvokeFunction"
+  function_name = aws_lambda_function.detector.function_name
+  principal     = "events.amazonaws.com"
+  source_arn    = aws_cloudwatch_event_rule.iam_changes.arn
+}

permission-alert/lambda/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "iam-admin-detector",
+  "version": "1.0.0",
+  "private": true,
+  "type": "commonjs",
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --target=node20 --format=cjs --outfile=dist/index.js"
+  },
+  "dependencies": {
+    "@aws-sdk/client-iam": "^3.609.0",
+    "@aws-sdk/client-sns": "^3.609.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.23.0",
+    "typescript": "^5.6.2",
+    "@types/node": "^22.5.4",
+    "@types/aws-lambda": "^8.10.137"
+  }
+}