@cloud-copilot/iam-lens 0.1.15 → 0.1.16

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.
Files changed (2) hide show
  1. package/README.md +28 -138
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -2,10 +2,21 @@
2
2
 
3
3
  [![NPM Version](https://img.shields.io/npm/v/@cloud-copilot/iam-lens.svg?logo=nodedotjs)](https://www.npmjs.com/package/@cloud-copilot/iam-lens) [![License: AGPL v3](https://img.shields.io/github/license/cloud-copilot/iam-lens)](LICENSE.txt) [![GuardDog](https://github.com/cloud-copilot/iam-lens/actions/workflows/guarddog.yml/badge.svg)](https://github.com/cloud-copilot/iam-lens/actions/workflows/guarddog.yml) [![Known Vulnerabilities](https://snyk.io/test/github/cloud-copilot/iam-lens/badge.svg?targetFile=package.json&style=flat-square)](https://snyk.io/test/github/cloud-copilot/iam-lens?targetFile=package.json)
4
4
 
5
- ## iam-lens
6
-
7
5
  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
6
 
7
+ ## Table of Contents
8
+
9
+ 1. [Quick Start](#quick-start)
10
+ 2. [What is iam-lens?](#what-is-iam-lens)
11
+ 3. [Why use it?](#why-use-it)
12
+ 4. [Getting Started](#getting-started)
13
+ 5. [Commands](#commands)
14
+ - [simulate - Simulate a request](docs/Simulate.md)
15
+ - [who-can - Find who can perform an action on a resource](docs/WhoCan.md)
16
+ - [Global CLI Options](docs/GlobalCliOptions.md)
17
+ 6. [Contributing & Support](#contributing--support)
18
+ 7. [Acknowledgements](#acknowledgements)
19
+
9
20
  ## Quick Start
10
21
 
11
22
  ```bash
@@ -28,15 +39,15 @@ iam-lens who-can --resource arn:aws:s3:::example-bucket
28
39
 
29
40
  ## What is iam-lens?
30
41
 
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.
42
+ **iam-lens** lets you **simulate** and **audit** real IAM requests against your collected IAM data from your AWS accounts (collected via [iam-collect](https://github.com/cloud-copilot/iam-collect)) and understand the effective permissions that apply to a principal or resource.
32
43
 
33
44
  ## Why use it?
34
45
 
35
- 1. **Understand** what permissions are actually in place and why. See the policies that determine the outcome of a request.
36
- 2. **Verify** what's allowed or not after everything is deployed.
37
- 3. **Discover** who can take action on a sensitive resource or account.
38
- 4. **Audit** your IAM policies and ensure they are configured correctly.
39
- 5. **Debug** permissions by simulating requests locally and iterate quickly without needing to deploy changes to your AWS environment.
46
+ - **Understand** the permissions that are actually in place.
47
+ - **Verify** allowed and denied outcomes after all policies are deployed.
48
+ - **Discover** every principal that can access a given resource.
49
+ - **Audit** complex policy combinations across all your AWS accounts and orgs.
50
+ - **Debug** complex conditions locally without deployment or network calls.
40
51
 
41
52
  ## Getting Started
42
53
 
@@ -81,27 +92,11 @@ iam-lens who-can \
81
92
 
82
93
  ## Commands
83
94
 
84
- ### `simulate` - Simulate an IAM request
85
-
86
- ```bash
87
- iam-lens simulate [options]
88
- ```
89
-
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`.
95
+ ### `simulate` - Simulate a request
91
96
 
92
- **Options:**
97
+ 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`. All [condition keys](docs/Simulate.md#context-keys) are supported and [many context keys are set automatically](docs/Simulate.md#default-context-keys).
93
98
 
94
- | Flag | Description |
95
- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
96
- | `--principal <arn>` | The principal the request is from. Can be a user, role, session, or AWS service. |
97
- | `--resource <arn>` | The ARN of the resource to simulate access to. Ignore for wildcard-only actions such as `s3:ListAllMyBuckets`. |
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. |
99
- | `--action <service:action>` | The action to simulate; must be a valid IAM service and action such as `s3:ListBucket`. |
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 |
101
- | `-v, --verbose` | Enable verbose output for the simulation to see exactly what statements applied or not and why. |
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 |
103
-
104
- **Examples:**
99
+ [Full simulate documentation](docs/Simulate.md)
105
100
 
106
101
  ```bash
107
102
  # Simple simulate: can this role list objects in the bucket?
@@ -131,6 +126,8 @@ iam-lens simulate \
131
126
  --expect Allowed
132
127
  ```
133
128
 
129
+ [Full simulate documentation](docs/Simulate.md)
130
+
134
131
  ### `who-can` - Find who can perform an action on a resource
135
132
 
136
133
  ```bash
@@ -139,13 +136,7 @@ iam-lens who-can [options]
139
136
 
140
137
  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.
141
138
 
142
- **Options:**
143
-
144
- | Flag | Description |
145
- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
146
- | `--resource <arn>` | The ARN of the resource to check permissions for. Ignore for wildcard-only actions such as `iam:ListRoles` |
147
- | `--resource-account <id>` | The account ID of the resource, only required if it cannot be determined from the resource ARN. Required for wildcard actions such as `ec2:DescribeInstances` |
148
- | `--actions <service:action>` | One or more actions to check such as `s3:GetObject`. Specify as many actions as you want. If omitted it will analyze all valid actions for the resource. If no `--resource` is specified then actions must be entered. |
139
+ [Full who-can documentation](docs/WhoCan.md)
149
140
 
150
141
  **Examples:**
151
142
 
@@ -170,112 +161,11 @@ iam-lens who-can \
170
161
  --resource arn:aws:s3:::my-bucket
171
162
  ```
172
163
 
173
- ### Global Options:
174
-
175
- These options are available for all commands:
176
-
177
- | Flag | Description | Default |
178
- | -------------------------- | --------------------------------------------------------------------- | ------------------- |
179
- | `--collectConfigs <files>` | One or more `iam-collect` config files to use for fetching IAM data. | `iam-collect.jsonc` |
180
- | `--partition <partition>` | The AWS partition (`aws`, `aws-cn`, `aws-us-gov`). Defaults to `aws`. | `aws` |
181
-
182
- ## Context Keys
183
-
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.
185
-
186
- ### Default Context Keys
187
-
188
- - **`aws:SecureTransport`**
189
- Always set to `true` to indicate the request is using a secure channel.
190
-
191
- - **`aws:CurrentTime`**
192
- ISO 8601 timestamp of when the simulation is run (e.g., `2025-06-01T12:34:56.789Z`).
193
-
194
- - **`aws:EpochTime`**
195
- Unix epoch time in seconds (e.g., `1717290896`).
196
-
197
- #### IAM Principal Context
198
-
199
- - **`aws:PrincipalArn`**
200
- The full ARN of the principal (user, role, role session, or federated user) being simulated.
201
-
202
- - **`aws:PrincipalAccount`**
203
- The AWS account ID extracted from the principal ARN.
204
-
205
- - **`aws:PrincipalOrgId`** _(if the account is in an organization)_
206
- The Organization ID that owns the principal’s account.
207
-
208
- - **`aws:PrincipalOrgPaths`** _(if the account is in an organization)_
209
- A list containing a single string of the form `<OrgId>/<OU1>/<OU2>/…/` indicating the account’s path in the OU hierarchy.
210
-
211
- - **`aws:PrincipalTag/<TagKey>`**
212
- For each tag on the IAM principal, a context key of the form `aws:PrincipalTag/<TagKey>` with its tag value.
164
+ [Full who-can documentation](docs/WhoCan.md)
213
165
 
214
- - **`aws:PrincipalIsAWSService`**
215
- Set to `false` for all IAM principals (users, roles, federated users).
216
-
217
- - **`aws:PrincipalType`**
218
- One of: `Account`, `User`, `FederatedUser`, `AssumedRole`, indicating the type of principal.
219
-
220
- - **`aws:userid`**
221
- The unique identifier for the principal session:
222
-
223
- - For a root principal: the account ID
224
- - For a user: the IAM user’s unique ID (or `UNKNOWN` if not found)
225
- - For a federated user: `<AccountId>:<FederatedName>`
226
- - For an assumed role: `<RoleUniqueId>:<SessionName>`
227
-
228
- Setting `role-id:ec2-instance-id` for EC2 instances is not supported at this time.
229
-
230
- - **`aws:username`** _(only for IAM users)_
231
- The IAM username portion of the principal ARN (e.g. `Alice`).
232
-
233
- #### Service Principal Context
234
-
235
- The following context keys are set when the principal is an AWS service (e.g., `lambda.amazonaws.com`, `ec2.amazonaws.com`):
236
-
237
- - **`aws:PrincipalServiceName`**
238
- The service principal string (e.g. `lambda.amazonaws.com`).
239
-
240
- - **`aws:SourceAccount`**
241
- The account ID of the resource.
242
-
243
- - **`aws:SourceOrgID`**
244
- The organization ID of the resource’s account (if part of an organization).
245
-
246
- - **`aws:SourceOrgPaths`**
247
- The OU hierarchy path for the resource’s account (if part of an organization).
248
-
249
- - **`aws:PrincipalIsAWSService`**
250
- Set to `true` for all service principals.
251
-
252
- #### Resource Context ([unless action is excluded](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resourceaccount))
253
-
254
- - **`aws:ResourceAccount`**
255
- The AWS account ID of the resource.
256
-
257
- - **`aws:ResourceOrgID`**
258
- The Organization ID for the resource’s account (if part of an organization).
259
-
260
- - **`aws:ResourceOrgPaths`** _(if the resource account is in an organization)_
261
- A list containing a single string of the form `<OrgId>/<OU1>/<OU2>/…/` for the resource’s account (if part of an organization).
262
-
263
- - **`aws:ResourceTag/<TagKey>`**
264
- For each tag on the resource ARN, a context key `aws:ResourceTag/TagKey` with its tag value. **This is only for resources that are stored in your `iam-collect` data**, such as Roles, S3 Buckets, DynamoDB Tables, etc. For resources not stored in `iam-collect`, this key should be set manually.
265
-
266
- ### Overriding Default Context Keys
267
-
268
- Any context keys supplied via the `--context key=value[,value2,…]` argument will override the defaults described above. For example:
269
-
270
- ```bash
271
- iam-lens simulate \
272
- --principal arn:aws:iam::123456789012:user/Alice \
273
- --resource arn:aws:s3:::my-bucket \
274
- --action s3:GetObject \
275
- --context aws:CurrentTime=2025-01-01T00:00:00Z aws:PrincipalTag/Env=staging
276
- ```
166
+ ## Contributing & Support
277
167
 
278
- In this case, `aws:CurrentTime` and `aws:PrincipalTag/Env` will use the provided values instead of what iam-lens would normally derive.
168
+ The best way to support is to [open an issue](https://github.com/cloud-copilot/iam-lens/issues) and let us know of any bugs, feature requests, or questions you have. We're always looking for ways to improve the project and make it more useful for everyone.
279
169
 
280
170
  ## Acknowledgements
281
171
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cloud-copilot/iam-lens",
3
- "version": "0.1.15",
3
+ "version": "0.1.16",
4
4
  "description": "Visibility in IAM in and across AWS accounts",
5
5
  "keywords": [
6
6
  "aws",