Normalize structure: Generate IAM Policies with IAM Policy (#258)

Co-authored-by: totesforlife <toteally.notifications@gmail.com>

Author: sccalabr

public/images/aws/iam-policy-stream-architecture.png

@@ -48,6 +48,20 @@ 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 Architecture](/images/aws/iam-policy-stream-architecture.png)
+
+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 +267,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.