@cloud-copilot/iam-lens 0.1.9 → 0.1.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +30 -17
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
## iam-lens
|
|
6
6
|
|
|
7
|
-
Get visibility into the
|
|
7
|
+
Get visibility into the IAM permissions in your AWS organizations and accounts. Use your actual AWS IAM policies (downloaded via [iam-collect](https://github.com/cloud-copilot/iam-collect)) and evaluate the effective permissions.
|
|
8
8
|
|
|
9
9
|
## Quick Start
|
|
10
10
|
|
|
@@ -28,19 +28,19 @@ iam-lens who-can --resource arn:aws:s3:::example-bucket
|
|
|
28
28
|
|
|
29
29
|
## What is iam-lens?
|
|
30
30
|
|
|
31
|
-
iam-lens uses
|
|
31
|
+
iam-lens uses the IAM data from your AWS accounts (collected via [iam-collect](https://github.com/cloud-copilot/iam-collect)) to quickly simulate requests and understand the effective permissions that apply to a principal or resource.
|
|
32
32
|
|
|
33
33
|
## Why use it?
|
|
34
34
|
|
|
35
35
|
1. **Understand** what permissions are actually in place and why. See the policies that determine the outcome of a request.
|
|
36
36
|
2. **Verify** what's allowed or not after everything is deployed.
|
|
37
|
-
3. **Discover** who can take action on a sensitive resource
|
|
37
|
+
3. **Discover** who can take action on a sensitive resource or account.
|
|
38
38
|
4. **Audit** your IAM policies and ensure they are configured correctly.
|
|
39
39
|
5. **Debug** permissions by simulating requests locally and iterate quickly without needing to deploy changes to your AWS environment.
|
|
40
40
|
|
|
41
41
|
## Getting Started
|
|
42
42
|
|
|
43
|
-
1. **Download Your Policies** with [iam-collect](https://github.com/cloud-copilot/iam-collect) to get all
|
|
43
|
+
1. **Download Your Policies** with [iam-collect](https://github.com/cloud-copilot/iam-collect) to get all policies from your AWS accounts. iam-collect is highly configurable and can be customized to collect the policies you need. It only downloads information to your file system or an S3 bucket, so you're in full control of your data.
|
|
44
44
|
|
|
45
45
|
```bash
|
|
46
46
|
npm install -g @cloud-copilot/iam-collect
|
|
@@ -48,9 +48,9 @@ iam-collect init
|
|
|
48
48
|
iam-collect download
|
|
49
49
|
```
|
|
50
50
|
|
|
51
|
-
To see the effect of SCPs and RCPs, you should download data from your management account; or an account with
|
|
51
|
+
To see the effect of SCPs and RCPs, you should download data from your management account; or an account with permission to download organization information. Download data for member accounts you want to analyze. `iam-lens` will analyze cross-account and cross-organization requests if the data is available.
|
|
52
52
|
|
|
53
|
-
You can download information for as many accounts, organizations, and regions as you like. The more data you have, the more accurate your
|
|
53
|
+
You can download information for as many accounts, organizations, and regions as you like. The more data you have, the more accurate your answers will be.
|
|
54
54
|
|
|
55
55
|
2. **Install iam-lens**
|
|
56
56
|
|
|
@@ -63,7 +63,10 @@ npm install -g @cloud-copilot/iam-lens
|
|
|
63
63
|
Simulate a request:
|
|
64
64
|
|
|
65
65
|
```bash
|
|
66
|
-
iam-lens simulate
|
|
66
|
+
iam-lens simulate \
|
|
67
|
+
--principal arn:aws:iam::123456789012:role/ExampleRole \
|
|
68
|
+
--resource arn:aws:s3:::example-bucket/secret-file.txt \
|
|
69
|
+
--action s3:GetObject
|
|
67
70
|
```
|
|
68
71
|
|
|
69
72
|
or
|
|
@@ -71,7 +74,9 @@ or
|
|
|
71
74
|
Discover who can perform an action on a resource:
|
|
72
75
|
|
|
73
76
|
```bash
|
|
74
|
-
iam-lens who-can
|
|
77
|
+
iam-lens who-can \
|
|
78
|
+
--resource arn:aws:iam::111111111111:role/ImportantRole \
|
|
79
|
+
--actions sts:AssumeRole iam:PassRole
|
|
75
80
|
```
|
|
76
81
|
|
|
77
82
|
## Commands
|
|
@@ -82,7 +87,7 @@ iam-lens who-can --resource arn:aws:iam::111111111111:role/ImportantRole --actio
|
|
|
82
87
|
iam-lens simulate [options]
|
|
83
88
|
```
|
|
84
89
|
|
|
85
|
-
Evaluates whether a principal can perform a specified action on a resource (or wildcard). Returns a decision
|
|
90
|
+
Evaluates whether a principal can perform a specified action on a resource (or account for wildcard only actions). Returns a decision: `Allowed`, `ImplicitlyDenied`, or `ExplicitlyDenied`.
|
|
86
91
|
|
|
87
92
|
**Options:**
|
|
88
93
|
|
|
@@ -90,10 +95,10 @@ Evaluates whether a principal can perform a specified action on a resource (or w
|
|
|
90
95
|
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
91
96
|
| `--principal <arn>` | The principal the request is from. Can be a user, role, session, or AWS service. |
|
|
92
97
|
| `--resource <arn>` | The ARN of the resource to simulate access to. Ignore for wildcard-only actions such as `s3:ListAllMyBuckets`. |
|
|
93
|
-
| `--resource-account <id>` | The account ID of the resource
|
|
98
|
+
| `--resource-account <id>` | The account ID of the resource. Only required if it cannot be determined from the resource ARN or the principal ARN for wildcard only actions. |
|
|
94
99
|
| `--action <service:action>` | The action to simulate; must be a valid IAM service and action such as `s3:ListBucket`. |
|
|
95
100
|
| `--context <key=value>` | One or more context keys to use for the simulation. Keys are formatted as `keyA=value1,value2 keyB=value1,value2`. Multiple keys are separated by spaces. Multiple values separated by commas. See [Context Keys](#context-keys) for what keys are set automatically |
|
|
96
|
-
| `-v, --verbose` | Enable verbose output for the simulation
|
|
101
|
+
| `-v, --verbose` | Enable verbose output for the simulation to see exactly what statements applied or not and why. |
|
|
97
102
|
| `--expect <result>` | Optional expected outcome of the simulation. Valid values are `Allowed`, `ImplicitlyDenied`, `ExplicitlyDenied`, `AnyDeny`. If the result does not match the expected value, a non-zero exit code is returned |
|
|
98
103
|
|
|
99
104
|
**Examples:**
|
|
@@ -108,7 +113,7 @@ iam-lens simulate \
|
|
|
108
113
|
# Simulate a wildcard action (ListAllMyBuckets) – this will assume the principals account
|
|
109
114
|
iam-lens simulate \
|
|
110
115
|
--principal arn:aws:iam::222222222222:user/Alice \
|
|
111
|
-
--action s3:ListAllMyBuckets
|
|
116
|
+
--action s3:ListAllMyBuckets
|
|
112
117
|
|
|
113
118
|
# Include custom context keys
|
|
114
119
|
iam-lens simulate \
|
|
@@ -132,7 +137,7 @@ iam-lens simulate \
|
|
|
132
137
|
iam-lens who-can [options]
|
|
133
138
|
```
|
|
134
139
|
|
|
135
|
-
Lists all principals in your IAM data who are allowed to perform one or more specified actions on a resource (or wildcard). If applicable it will check the resource policy to find cross-account permissions and AWS service principals.
|
|
140
|
+
Lists all principals in your IAM data who are allowed to perform one or more specified actions on a resource (or account for wildcard only actions). If applicable it will check the resource policy to find cross-account permissions and AWS service principals.
|
|
136
141
|
|
|
137
142
|
**Options:**
|
|
138
143
|
|
|
@@ -150,7 +155,7 @@ iam-lens who-can \
|
|
|
150
155
|
--resource arn:aws:s3:::my-bucket/secret-file.txt \
|
|
151
156
|
--actions s3:GetObject
|
|
152
157
|
|
|
153
|
-
# Who can list all IAM roles in
|
|
158
|
+
# Who can list all IAM roles in this account? (wildcard action – no resource)
|
|
154
159
|
iam-lens who-can \
|
|
155
160
|
--resource-account 555555555555 \
|
|
156
161
|
--actions iam:ListRoles
|
|
@@ -159,6 +164,10 @@ iam-lens who-can \
|
|
|
159
164
|
iam-lens who-can \
|
|
160
165
|
--resource arn:aws:dynamodb:us-east-1:555555555555:table/Books \
|
|
161
166
|
--actions dynamodb:Query dynamodb:UpdateItem
|
|
167
|
+
|
|
168
|
+
# Check all actions for a bucket
|
|
169
|
+
iam-lens who-can \
|
|
170
|
+
--resource arn:aws:s3:::my-bucket
|
|
162
171
|
```
|
|
163
172
|
|
|
164
173
|
### Global Options:
|
|
@@ -172,7 +181,7 @@ These options are available for all commands:
|
|
|
172
181
|
|
|
173
182
|
## Context Keys
|
|
174
183
|
|
|
175
|
-
|
|
184
|
+
iam-lens automatically populates the context keys below when simulating requests. These keys are set based on your principal, resource, and organization data. Any keys provided via `--context` will override the defaults.
|
|
176
185
|
|
|
177
186
|
### Default Context Keys
|
|
178
187
|
|
|
@@ -238,7 +247,7 @@ The following context keys are set when the principal is an AWS service (e.g., `
|
|
|
238
247
|
The OU hierarchy path for the resource’s account (if part of an organization).
|
|
239
248
|
|
|
240
249
|
- **`aws:PrincipalIsAWSService`**
|
|
241
|
-
Set to `true` for all service principals.
|
|
250
|
+
Set to `true` for all service principals.
|
|
242
251
|
|
|
243
252
|
#### Resource Context ([unless action is excluded](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resourceaccount))
|
|
244
253
|
|
|
@@ -256,7 +265,7 @@ The following context keys are set when the principal is an AWS service (e.g., `
|
|
|
256
265
|
|
|
257
266
|
### Overriding Default Context Keys
|
|
258
267
|
|
|
259
|
-
Any context keys supplied via the `--context key=value[,value2,…]`
|
|
268
|
+
Any context keys supplied via the `--context key=value[,value2,…]` argument will override the defaults described above. For example:
|
|
260
269
|
|
|
261
270
|
```bash
|
|
262
271
|
iam-lens simulate \
|
|
@@ -267,3 +276,7 @@ iam-lens simulate \
|
|
|
267
276
|
```
|
|
268
277
|
|
|
269
278
|
In this case, `aws:CurrentTime` and `aws:PrincipalTag/Env` will use the provided values instead of what iam-lens would normally derive.
|
|
279
|
+
|
|
280
|
+
## Acknowledgements
|
|
281
|
+
|
|
282
|
+
Special thanks to [Ziyad Almbasher](https://www.linkedin.com/in/ziadmo/) for testing, validating, providing feedback, and for not letting up when the author thinks "this is fine".
|