From aeeb58f47865226032ebfa00ab766e180030c5eb Mon Sep 17 00:00:00 2001 From: HarshCasper Date: Fri, 3 Nov 2023 17:58:29 +0530 Subject: [PATCH] add security testing intro and IAM enforcement guide --- content/en/user-guide/aws/iam/index.md | 54 --------- .../en/user-guide/security-testing/_index.md | 17 +++ .../security-testing/iam-enforcement/index.md | 106 ++++++++++++++++++ 3 files changed, 123 insertions(+), 54 deletions(-) create mode 100644 content/en/user-guide/security-testing/_index.md create mode 100644 content/en/user-guide/security-testing/iam-enforcement/index.md diff --git a/content/en/user-guide/aws/iam/index.md b/content/en/user-guide/aws/iam/index.md index b789ce3e26..709c9ce45d 100644 --- a/content/en/user-guide/aws/iam/index.md +++ b/content/en/user-guide/aws/iam/index.md @@ -74,60 +74,6 @@ $ awslocal sts get-caller-identity You can see that the request is now running under the `test` user. -## Enforcing IAM Policies - -The Pro/Team offering provides the IAM security enforcement feature that can be used to test your security policies and create a more realistic environment that more closely resembles real AWS. The environment configuration `ENFORCE_IAM=1` is required while starting LocalStack to enable this feature. In LocalStack, IAM enforcement is disabled, and all APIs can be accessed without authentication. - -Presented below is a straightforward example showcasing the implementation of IAM policy enforcement. Initially, it involves creating a user and obtaining access/secret keys. Subsequently, an attempt is made to create a bucket using that user's credentials, which inevitably fails due to insufficient permissions. Lastly, a policy is attached to the user, granting the necessary `s3:CreateBucket` permission, thereby enabling the successful creation of the bucket. - -To follow this example, please open two separate terminal sessions: **Terminal 1** for the administrative IAM commands, which will utilize the default root IAM user, and **Terminal 2** for executing the commands under the test IAM user we're about to create. This way, we can demonstrate the differentiation in access permissions between the administrative and test users in real-time. - -In **Terminal 1**, execute the following commands: - -{{< command >}} -$ awslocal iam create-user --user-name test -... -$ awslocal iam create-access-key --user-name test -... - "AccessKeyId": "AKIA4HPFP0TZHP3Z5VI6", - "SecretAccessKey": "mwi/8Zhg8ypkJQmkdBq87UA3MbSa3x0HWnkcC/Ua", -... -{{< / command >}} - -Navigate to **Terminal 2**, where we will configure the access keys for the user `test` in the environment. Once the access keys are set, you will attempt to create an S3 bucket using these credentials. - -{{< command >}} -$ export AWS_ACCESS_KEY_ID=AKIA4HPFP0TZHP3Z5VI6 AWS_SECRET_ACCESS_KEY=mwi/8Zhg8ypkJQmkdBq87UA3MbSa3x0HWnkcC/Ua -$ awslocal s3 mb s3://mybucket -make_bucket failed: s3://mybucket An error occurred (AccessDeniedException) when calling the CreateBucket operation: Access to the specified resource is denied -{{< / command >}} - -As anticipated, the attempt to create the bucket fails with an `AccessDeniedException` error, confirming that user `test` lacks the necessary permissions for this action. - -Let's now return to **Terminal 1** and execute the following commands: - -{{< command >}} -$ awslocal iam create-policy --policy-name p1 --policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Action":"s3:CreateBucket","Resource":"*"}]}' -... -$ awslocal iam attach-user-policy --user-name test --policy-arn arn:aws:iam::000000000000:policy/p1 -{{< / command >}} - -Now, let's switch back to **Terminal 2** and observe how the bucket creation succeeds with the `test` IAM user: - -{{< command >}} -# confirm that we're using the credentials of the `test` user -$ awslocal sts get-caller-identity -... - "Arn": "arn:aws:iam::000000000000:user/test" -... -$ awslocal s3 mb s3://mybucket -make_bucket: mybucket -{{< / command >}} - -{{< alert title="Note">}} -Currently, credentials are extracted from the request, typically from the `Authorization` HTTP header. However, it's important to note that the request signature is not fully validated, with a few exceptions, such as S3-presigned URLs. -{{< /alert >}} - ## Explainable IAM The IAM policy engine logs output related to failed policy evaluation directly to the LocalStack log. You can enable `DEBUG=1` to gain visibility into these log messages, allowing you to identify the additional policies required for your request to succeed. diff --git a/content/en/user-guide/security-testing/_index.md b/content/en/user-guide/security-testing/_index.md new file mode 100644 index 0000000000..e86da040e1 --- /dev/null +++ b/content/en/user-guide/security-testing/_index.md @@ -0,0 +1,17 @@ +--- +title: "Security Testing" +linkTitle: "Security Testing" +weight: 11 +description: > + Security Testing in LocalStack allows you to test your IAM policies and permissions locally resembling the AWS environment. +cascade: + type: docs +--- + +## Introduction + +Security Testing in LocalStack enables you to enforce your IAM security enforcement allowing you to test your security policies and create a more realistic environment that more closely resembles the real AWS. Security Testing in LocalStack encompasses the following features: + +- Enforce IAM policies & permissions in your setup to test your application security. +- Retrieve IAM policy engine logs to gain visibility into the policy evaluation. +- Discover appropriate permissions using live policy streams to fix logical errors. diff --git a/content/en/user-guide/security-testing/iam-enforcement/index.md b/content/en/user-guide/security-testing/iam-enforcement/index.md new file mode 100644 index 0000000000..e02df0784c --- /dev/null +++ b/content/en/user-guide/security-testing/iam-enforcement/index.md @@ -0,0 +1,106 @@ +--- +title: "IAM Policy Enforcement" +linkTitle: "IAM Policy Enforcement" +weight: 1 +description: Get started with IAM Security Enforcement in LocalStack +--- + +## Introduction + +IAM Policy Enforcement feature can be used to test your security policies and create a more realistic environment that more closely resembles real AWS. The environment configuration `ENFORCE_IAM=1` is required while starting LocalStack to enable this feature. In LocalStack, IAM enforcement is disabled, and all APIs can be accessed without authentication. + +## Getting started + +This guide is designed for users new to IAM Policy Enforcement and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. + +Start your LocalStack container with the `DEBUG=1` and `ENFORCE_IAM=1` environment variables set: + +{{< command >}} +$ DEBUG=1 ENFORCE_IAM=1 localstack start +{{< /command >}} + +We will demonstrate IAM Policy Enforcement, by creating a user and obtaining the access/secret keys. We will make an attempt to create a bucket using the user’s credentials, which inevitably fails due to insufficient permissions. + +Lastly, a policy is attached to the user, granting the necessary `s3:CreateBucket` permission, thereby enabling the successful creation of the bucket. + +### Create a user + +To follow this guide, open two separate terminal sessions: **Terminal 1** for the administrative IAM commands, which will utilize the default root IAM user, and **Terminal 2** for executing the commands under the test IAM user you are about to create. This way, we can demonstrate the differentiation in access permissions between the administrative and test users in real-time. + +In **Terminal 1**, execute the following commands to create a `test` user and obtain the access/secret keys: + +{{< command >}} +$ awslocal iam create-user --user-name test + +{ + "User": { + "Path": "/", + "UserName": "test", + "UserId": "d7ryukg7bls4rq1ihq1d", + "Arn": "arn:aws:iam::000000000000:user/test", + "CreateDate": "2023-11-03T12:20:12.332000Z" + } +} + +$ awslocal iam create-access-key --user-name test + +{ + "AccessKey": { + "UserName": "test", + "AccessKeyId": "LKIAQAAAAAAAHFR7QTN3", + "Status": "Active", + "SecretAccessKey": "EYUHpIol7bRJpKd/28c/LI2C4bbEnp82LJCRwXRV", + "CreateDate": "2023-11-03T12:20:27Z" + } +} + +{{< / command >}} + +### Attempt to create a bucket + +Navigate to **Terminal 2**, where we will configure the access keys for the user `test` in the environment. Once the access keys are set, you will attempt to create an S3 bucket using these credentials. + +{{< command >}} +$ export AWS_ACCESS_KEY_ID=LKIAQAAAAAAAHFR7QTN3 AWS_SECRET_ACCESS_KEY=EYUHpIol7bRJpKd/28c/LI2C4bbEnp82LJCRwXRV +$ awslocal s3 mb s3://mybucket + +make_bucket failed: s3://mybucket An error occurred (AccessDeniedException) when calling the CreateBucket operation: Access to the specified resource is denied + +{{< / command >}} + +As anticipated, the attempt to create the bucket fails with an `AccessDeniedException` error, confirming that user `test` lacks the necessary permissions for this action. You can view the LocalStack logs to validate the policy enforcement: + +```bash +2023-11-03T12:21:10.971 INFO --- [ asgi_gw_1] l.s.i.p.handler : Request for service 's3' by principal 'arn:aws:iam::000000000000:user/test' for operation 'CreateBucket' denied. +2023-11-03T12:21:10.972 INFO --- [ asgi_gw_1] localstack.request.aws : AWS s3.CreateBucket => 403 (AccessDenied) +``` + +### Attach a policy to the user + +Let's now return to **Terminal 1** and execute the following commands to attach a policy to the user `test`: + +{{< command >}} +$ awslocal iam create-policy --policy-name p1 --policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Action":"s3:CreateBucket","Resource":"*"}]}' +$ awslocal iam attach-user-policy --user-name test --policy-arn arn:aws:iam::000000000000:policy/p1 +{{< / command >}} + +### Create a bucket + +Now, let's switch back to **Terminal 2** and observe how the bucket creation succeeds with the `test` IAM user: + +{{< command >}} +$ awslocal s3 mb s3://mybucket + +make_bucket: mybucket + +{{< / command >}} + +The bucket creation succeeds, confirming that the user `test` now has the necessary permissions to perform this action. You can view the LocalStack logs to validate the policy enforcement: + +```bash +2023-11-03T12:23:11.469 INFO --- [ asgi_gw_1] localstack.request.aws : AWS iam.CreatePolicy => 200 +2023-11-03T12:23:15.753 INFO --- [ asgi_gw_1] localstack.request.aws : AWS iam.AttachUserPolicy => 200 +2023-11-03T12:23:22.795 INFO --- [ asgi_gw_2] localstack.request.aws : AWS s3.CreateBucket => 200 +``` + +You can further use the IAM Policy Enforcement feature to test your Infrastructure as Code (IaC) deployments and ensure that your policies are correctly enforced. If the IAM policies are not correctly enforced, you will get an unsuccessful response from the API call, and the LocalStack logs will provide you with the necessary information to debug the issue.