From 3bcb6ed820c441f840a42b620ce9ef9804f4e0fe Mon Sep 17 00:00:00 2001 From: totesforlife Date: Fri, 3 Oct 2025 20:56:42 -0700 Subject: [PATCH 1/2] Normalize structure: Generate IAM Policies with IAM Policy --- .../docs/aws/tutorials/iam-policy-stream.mdx | 196 ++++++++++++++++++ 1 file changed, 196 insertions(+) diff --git a/src/content/docs/aws/tutorials/iam-policy-stream.mdx b/src/content/docs/aws/tutorials/iam-policy-stream.mdx index 1db60e4c..b2f32d94 100644 --- a/src/content/docs/aws/tutorials/iam-policy-stream.mdx +++ b/src/content/docs/aws/tutorials/iam-policy-stream.mdx @@ -48,6 +48,61 @@ Additionally, it serves as a useful learning tool, helping users understand the - [LocalStack Web Application account](https://app.localstack.cloud/sign-up) - [`jq`](https://jqlang.github.io/jq/download/) +## Architecture diagram + +The following diagram illustrates the architecture of this tutorial: + +``` +┌─────────────────────────────────────────────────────────────┐ +│ LocalStack Environment │ +│ │ +│ ┌──────────────┐ │ +│ │ S3 Bucket │ │ +│ │ (s3-event- │ │ +│ │ notification-│ │ +│ │ bucket) │ │ +│ └──────┬───────┘ │ +│ │ │ +│ │ Event Notification │ +│ │ (requires IAM policy) │ +│ │ │ +│ ▼ │ +│ ┌──────────────┐ │ +│ │ SQS Queue │ │ +│ │(s3-event-not-│ │ +│ │ification- │ │ +│ │ queue) │ │ +│ └──────────────┘ │ +│ │ +│ │ │ +│ │ API Calls & IAM Violations │ +│ ▼ │ +│ ┌────────────────────────────────────┐ │ +│ │ IAM Enforcement Engine │ │ +│ │ (IAM_SOFT_MODE=1) │ │ +│ └────────────────────────────────────┘ │ +│ │ │ +└─────────┼────────────────────────────────────────────────────┘ + │ + │ Policy Stream + ▼ + ┌──────────────────────────────────────┐ + │ LocalStack Web Application │ + │ IAM Policy Stream Dashboard │ + │ - View API calls │ + │ - See IAM violations │ + │ - Generate policies │ + └──────────────────────────────────────┘ +``` + +In this architecture: +1. An **S3 bucket** is configured to send event notifications when objects are created +2. An **SQS queue** receives these notifications +3. The **IAM Enforcement Engine** intercepts API calls and checks for proper permissions +4. The **IAM Policy Stream Dashboard** captures all API requests and generates the necessary IAM policies +5. When a file is uploaded to the S3 bucket, S3 attempts to send a message to SQS, which initially fails due to missing permissions +6. The IAM Policy Stream automatically generates the required policy, which can then be applied to resolve the violation + ## Tutorial: Configure an S3 bucket for event notifications using SQS In this tutorial, you will configure a LocalStack S3 bucket to send event notifications to an SQS queue. @@ -253,6 +308,147 @@ For larger AWS applications, you would be able to find multiple roles and multip ![Required resource based policy](/images/aws/require-resource-based-policy.png) +## Testing the application + +This section demonstrates how to test your IAM policies and verify both deny and allow scenarios using LocalStack's IAM enforcement. + +### Testing Scenario 1: Deny (Without IAM Policy) + +When you first upload a file to the S3 bucket without the proper SQS queue policy in place, the S3 service will be denied permission to send messages to the SQS queue. + +**Upload a test file:** + +```bash +echo "Test file content" > test-file.log +awslocal s3 cp test-file.log s3://s3-event-notification-bucket/ +``` + +**Expected output - IAM Violation in LocalStack logs:** + +```shell +2024-07-09T05:30:33.583 INFO --- [et.reactor-4] l.s.i.p.handler : Request for service 'sqs' by principal 's3.amazonaws.com' for operation 'SendMessage' denied. +2024-07-09T05:30:33.583 DEBUG --- [et.reactor-4] l.s.i.p.handler : Necessary permissions for this action: ["Action 'sqs:SendMessage' for 'arn:aws:sqs:us-east-1:000000000000:s3-event-notification-queue'"] +2024-07-09T05:30:33.583 DEBUG --- [et.reactor-4] l.s.i.p.handler : 0 permissions have been explicitly denied: [] +2024-07-09T05:30:33.583 DEBUG --- [et.reactor-4] l.s.i.p.handler : 0 permissions have been explicitly allowed: [] +2024-07-09T05:30:33.583 DEBUG --- [et.reactor-4] l.s.i.p.handler : 1 permissions have been implicitly denied: ["Action 'sqs:SendMessage' for 'arn:aws:sqs:us-east-1:000000000000:s3-event-notification-queue'"] +``` + +**IAM Policy Stream Dashboard showing the violation:** + +![IAM Policy Stream showcasing an IAM violation](/images/aws/iam-policy-stream-violation.png) + +The dashboard clearly shows: +- **Action**: `SQS.SendMessage` +- **Status**: `Denied` (shown in red) +- **Principal**: `s3.amazonaws.com` +- **Resource**: `arn:aws:sqs:us-east-1:000000000000:s3-event-notification-queue` + +**Attempting to receive messages from the queue:** + +```bash +awslocal sqs receive-message \ + --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/s3-event-notification-queue +``` + +**Expected output - No messages (because S3 was denied):** + +```json +{ + "Messages": [] +} +``` + +Or you may receive no output at all, indicating an empty queue. + +### Testing Scenario 2: Allow (With IAM Policy) + +After applying the IAM policy generated by the Policy Stream to your SQS queue, the S3 service will be granted permission to send messages. + +**The required policy (already applied via Terraform):** + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "Test22bf6867", + "Effect": "Allow", + "Action": "sqs:SendMessage", + "Resource": "arn:aws:sqs:us-east-1:000000000000:s3-event-notification-queue", + "Principal": { + "Service": [ + "s3.amazonaws.com" + ] + }, + "Condition": { + "ArnEquals": { + "aws:SourceArn": "arn:aws:s3:::s3-event-notification-bucket" + } + } + } + ] +} +``` + +**Upload another test file:** + +```bash +echo "Test file with policy" > test-file-2.log +awslocal s3 cp test-file-2.log s3://s3-event-notification-bucket/ +``` + +**Expected output - Success (no IAM violation):** + +```shell +upload: ./test-file-2.log to s3://s3-event-notification-bucket/test-file-2.log +``` + +**LocalStack logs showing successful permission:** + +```shell +2024-07-09T05:35:22.123 DEBUG --- [et.reactor-2] l.s.i.p.handler : Request for service 'sqs' by principal 's3.amazonaws.com' for operation 'SendMessage' allowed. +2024-07-09T05:35:22.123 DEBUG --- [et.reactor-2] l.s.i.p.handler : 1 permissions have been explicitly allowed: ["Action 'sqs:SendMessage' for 'arn:aws:sqs:us-east-1:000000000000:s3-event-notification-queue'"] +``` + +**IAM Policy Stream Dashboard showing no violations:** + +![IAM Policy Stream showcasing no violations](/images/aws/iam-policy-stream-no-violations.png) + +The dashboard shows all actions with green checkmarks, indicating successful execution. + +**Receive the message from the queue:** + +```bash +awslocal sqs receive-message \ + --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/s3-event-notification-queue +``` + +**Expected output - Message successfully received:** + +```json +{ + "Messages": [ + { + "MessageId": "7c9d6b22-cb35-4a66-98dc-6f48dfc78f33", + "ReceiptHandle": "MTM4ZTg2NTYtMGIwNC00ZWE2LWIyM2EtNWNlZTIyOTZmOGE1IGFybjphd3M6c3FzOnVzLWVhc3QtMTowMDAwMDAwMDAwMDA6czMtZXZlbnQtbm90aWZpY2F0aW9uLXF1ZXVlIDdjOWQ2YjIyLWNiMzUtNGE2Ni05OGRjLTZmNDhkZmM3OGYzMyAxNzIwNTAzNjEyLjU2NDEyOTQ=", + "MD5OfBody": "10eacb105ec11badc56f7e0198e0c4ad", + "Body": "{\"Service\": \"Amazon S3\", \"Event\": \"s3:TestEvent\", \"Time\": \"2024-07-09T05:29:55.923Z\", \"Bucket\": \"s3-event-notification-bucket\", \"RequestId\": \"bfa882c0-a3b0-4549-b4c5-ac34167b3076\", \"HostId\": \"eftixk72aD6Ap51TnqcoF8eFidJG9Z/2\"}" + } + ] +} +``` + +The message body contains the S3 event notification with details about the uploaded file, confirming that the IAM policy is working correctly. + +### Verification Checklist + +To ensure your IAM policies are correctly configured: + +- ✅ **No IAM violations** appear in the IAM Policy Stream dashboard +- ✅ **Messages are successfully delivered** to the SQS queue +- ✅ **LocalStack logs show "allowed"** for the `SendMessage` operation +- ✅ **All API calls display green checkmarks** in the Policy Stream dashboard + ## Conclusion IAM Policy Stream streamlines your development process by minimizing the manual creation of policies and confirming the necessity of granted permissions. From 80a128e68fc44c55a10770b4fe2c182e4ebfb32e Mon Sep 17 00:00:00 2001 From: totesforlife Date: Fri, 3 Oct 2025 21:00:08 -0700 Subject: [PATCH 2/2] Normalize structure: Generate IAM Policies with IAM Policy --- src/content/docs/aws/tutorials/iam-policy-stream.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/aws/tutorials/iam-policy-stream.mdx b/src/content/docs/aws/tutorials/iam-policy-stream.mdx index b2f32d94..dc6cd1bd 100644 --- a/src/content/docs/aws/tutorials/iam-policy-stream.mdx +++ b/src/content/docs/aws/tutorials/iam-policy-stream.mdx @@ -444,10 +444,10 @@ The message body contains the S3 event notification with details about the uploa To ensure your IAM policies are correctly configured: -- ✅ **No IAM violations** appear in the IAM Policy Stream dashboard -- ✅ **Messages are successfully delivered** to the SQS queue -- ✅ **LocalStack logs show "allowed"** for the `SendMessage` operation -- ✅ **All API calls display green checkmarks** in the Policy Stream dashboard +- **No IAM violations** appear in the IAM Policy Stream dashboard +- **Messages are successfully delivered** to the SQS queue +- **LocalStack logs show "allowed"** for the `SendMessage` operation +- **All API calls display green checkmarks** in the Policy Stream dashboard ## Conclusion