Skip to content

Commit

Permalink
add security testing intro and IAM enforcement guide
Browse files Browse the repository at this point in the history
  • Loading branch information
@HarshCasper
HarshCasper committed Nov 3, 2023
1 parent e5a9ce6 commit aeeb58f
Show file tree
Hide file tree
Showing 3 changed files with 123 additions and 54 deletions.
54 changes: 0 additions & 54 deletions content/en/user-guide/aws/iam/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
17 changes: 17 additions & 0 deletions content/en/user-guide/security-testing/_index.md
View file
Original file line number Diff line number Diff line change
@@ -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.
106 changes: 106 additions & 0 deletions content/en/user-guide/security-testing/iam-enforcement/index.md
View file
Original file line number Diff line number Diff line change
@@ -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
<disable-copy>
{
"User": {
"Path": "/",
"UserName": "test",
"UserId": "d7ryukg7bls4rq1ihq1d",
"Arn": "arn:aws:iam::000000000000:user/test",
"CreateDate": "2023-11-03T12:20:12.332000Z"
}
}
</disable-copy>
$ awslocal iam create-access-key --user-name test
<disable-copy>
{
"AccessKey": {
"UserName": "test",
"AccessKeyId": "LKIAQAAAAAAAHFR7QTN3",
"Status": "Active",
"SecretAccessKey": "EYUHpIol7bRJpKd/28c/LI2C4bbEnp82LJCRwXRV",
"CreateDate": "2023-11-03T12:20:27Z"
}
}
</disable-copy>
{{< / 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
<disable-copy>
make_bucket failed: s3://mybucket An error occurred (AccessDeniedException) when calling the CreateBucket operation: Access to the specified resource is denied
</disable-copy>
{{< / 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
<disable-copy>
make_bucket: mybucket
</disable-copy>
{{< / 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.

0 comments on commit aeeb58f

Please sign in to comment.