[PR #84] [MERGED] feat: add `--explain` #229

New issue

Closed

opened 2026-03-15 11:54:29 +03:00 by kerem · 0 comments

kerem commented

2026-03-15 11:54:29 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/awslabs/iam-policy-autopilot/pull/84
Author: @mschlaipfer
Created: 12/17/2025
Status: ✅ Merged
Merged: 1/15/2026
Merged by: @mschlaipfer

Base: main ← Head: feat-explain

📝 Commits (10+)

55776b2 feat: add --explain
33fae3b feat: refactor based on PR comments
07e2bb9 refactor: refactor Location
fc36e6d Refactor resource_matcher and operation
4cf972e Output explanation documentation
f59160f cargo fmt
645cdbf Documentation comments and minor refactoring
e098cdd Update changelog
ed39391 Remove FasExpansionBuilder
dbea148 Custom PartialEq, Hash for Operation to fix test

📊 Changes

38 files changed (+2700 additions, -1580 deletions)

View changed files

📝 CHANGELOG.md (+6 -0)
📝 Cargo.toml (+2 -1)
📝 iam-policy-autopilot-cli/src/main.rs (+20 -32)
📝 iam-policy-autopilot-cli/src/output.rs (+6 -54)
📝 iam-policy-autopilot-mcp-server/src/tools/generate_policy.rs (+20 -14)
📝 iam-policy-autopilot-policy-generation/Cargo.toml (+1 -0)
📝 iam-policy-autopilot-policy-generation/src/api/generate_policies.rs (+23 -30)
📝 iam-policy-autopilot-policy-generation/src/api/model.rs (+17 -5)
📝 iam-policy-autopilot-policy-generation/src/enrichment/mod.rs (+647 -15)
📝 iam-policy-autopilot-policy-generation/src/enrichment/operation_fas_map.rs (+6 -49)
📝 iam-policy-autopilot-policy-generation/src/enrichment/resource_matcher.rs (+373 -371)
📝 iam-policy-autopilot-policy-generation/src/extraction/engine.rs (+1 -1)
📝 iam-policy-autopilot-policy-generation/src/extraction/extractor.rs (+7 -20)
📝 iam-policy-autopilot-policy-generation/src/extraction/go/disambiguation.rs (+22 -20)
📝 iam-policy-autopilot-policy-generation/src/extraction/go/extractor.rs (+63 -33)
📝 iam-policy-autopilot-policy-generation/src/extraction/go/features_extractor.rs (+25 -24)
📝 iam-policy-autopilot-policy-generation/src/extraction/go/paginator_extractor.rs (+41 -41)
📝 iam-policy-autopilot-policy-generation/src/extraction/go/waiter_extractor.rs (+105 -70)
📝 iam-policy-autopilot-policy-generation/src/extraction/javascript/argument_extractor.rs (+4 -2)
📝 iam-policy-autopilot-policy-generation/src/extraction/javascript/extractor.rs (+18 -8)

...and 18 more files

📄 Description

Issue #, if available:

Description of changes: This PR adds an experimental explanation feature to the CLI (--explain) which, for every action in the generated policy, provides a reason for why it has been added, including the expression and code location where IPA found an AWS operation call that led to its inclusion. It also provides information about FAS expansion, if it occurred.

We believe that this feature, together with --service-hints, will help creating policies with fewer unwanted permissions.

Example:

"Explanations": {
    "ExplanationForAction": {
      "dynamodb:GetItem": [
        {
          "Operations": [
            {
              "Service": "dynamodb",
              "Name": "GetItem",
              "Source": {
                "Expr": "dynamodb.get_item(\n        TableName='my-table',\n        Key={'id': {'S': '123'}}\n    )",
                "Location": "iam-policy-autopilot-cli/tests/resources/test_example.py:19.5-22.6"
              }
            }
          ]
        }
      ],
      "kms:Decrypt": [
        {
          "Operations": [
            {
              "Service": "s3",
              "Name": "GetObject",
              "Source": {
                "Expr": "s3.get_object(Bucket='my-bucket', Key='my-file.txt')",
                "Location": "iam-policy-autopilot-cli/tests/resources/test_example.py:7.16-7.68"
              }
            },
            {
              "Service": "kms",
              "Name": "Decrypt",
              "Source": "FAS"
            }
          ]
        }
       ]
    },
    "Documentation": {
      "FAS": {
        "Plain": "The explanation contains an operation added due to Forward Access Sessions.",
        "URL": "https://docs.aws.amazon.com/IAM/latest/UserGuide/access_forward_access_sessions.html"
      }
    }
 }

This PR adds file and raw expression information and expands location information in multiple places throughout the extraction phase so this data is available in the SdkMethodCall. There is currently a lot of code duplication, which I have not cleaned up as part of this pull request. See https://github.com/awslabs/iam-policy-autopilot/issues/88.

During enrichment it adds the FAS expansion information. The location format follows the one here. It is clickable, so it navigates to the location in VS Code (I have not tested with other editors).

This PR removes the (hidden) --show-action-mappings command which had a similar purpose, but did not support location, expression, or FAS information.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/awslabs/iam-policy-autopilot/pull/84 **Author:** [@mschlaipfer](https://github.com/mschlaipfer) **Created:** 12/17/2025 **Status:** ✅ Merged **Merged:** 1/15/2026 **Merged by:** [@mschlaipfer](https://github.com/mschlaipfer) **Base:** `main` ← **Head:** `feat-explain` --- ### 📝 Commits (10+) - [`55776b2`](https://github.com/awslabs/iam-policy-autopilot/commit/55776b2eb3c606203bc7e83481657007b5ccf24a) feat: add `--explain` - [`33fae3b`](https://github.com/awslabs/iam-policy-autopilot/commit/33fae3b546016d85d68bef06fd9279b1a6a605a5) feat: refactor based on PR comments - [`07e2bb9`](https://github.com/awslabs/iam-policy-autopilot/commit/07e2bb9547d6578ce7279d68ae6d65450f754952) refactor: refactor Location - [`fc36e6d`](https://github.com/awslabs/iam-policy-autopilot/commit/fc36e6dbec0e0380457d92eec0cfeb780ac7f482) Refactor resource_matcher and operation - [`4cf972e`](https://github.com/awslabs/iam-policy-autopilot/commit/4cf972eba6d3e256d37d82ff32c47e10691372bd) Output explanation documentation - [`f59160f`](https://github.com/awslabs/iam-policy-autopilot/commit/f59160ff5f2ac8f50a5e68b74d1890d02545dc6b) cargo fmt - [`645cdbf`](https://github.com/awslabs/iam-policy-autopilot/commit/645cdbf91ed1ab6ed122d476dbdab4988b6796ae) Documentation comments and minor refactoring - [`e098cdd`](https://github.com/awslabs/iam-policy-autopilot/commit/e098cdd5ecc4dccdf7bcc1e687f40dbbd9c2c897) Update changelog - [`ed39391`](https://github.com/awslabs/iam-policy-autopilot/commit/ed39391c7689638fd83cf2c94772822705a7be29) Remove FasExpansionBuilder - [`dbea148`](https://github.com/awslabs/iam-policy-autopilot/commit/dbea1487b01f510cf2f0db79821f2ede016b85e6) Custom PartialEq, Hash for Operation to fix test ### 📊 Changes **38 files changed** (+2700 additions, -1580 deletions) <details> <summary>View changed files</summary> 📝 `CHANGELOG.md` (+6 -0) 📝 `Cargo.toml` (+2 -1) 📝 `iam-policy-autopilot-cli/src/main.rs` (+20 -32) 📝 `iam-policy-autopilot-cli/src/output.rs` (+6 -54) 📝 `iam-policy-autopilot-mcp-server/src/tools/generate_policy.rs` (+20 -14) 📝 `iam-policy-autopilot-policy-generation/Cargo.toml` (+1 -0) 📝 `iam-policy-autopilot-policy-generation/src/api/generate_policies.rs` (+23 -30) 📝 `iam-policy-autopilot-policy-generation/src/api/model.rs` (+17 -5) 📝 `iam-policy-autopilot-policy-generation/src/enrichment/mod.rs` (+647 -15) 📝 `iam-policy-autopilot-policy-generation/src/enrichment/operation_fas_map.rs` (+6 -49) 📝 `iam-policy-autopilot-policy-generation/src/enrichment/resource_matcher.rs` (+373 -371) 📝 `iam-policy-autopilot-policy-generation/src/extraction/engine.rs` (+1 -1) 📝 `iam-policy-autopilot-policy-generation/src/extraction/extractor.rs` (+7 -20) 📝 `iam-policy-autopilot-policy-generation/src/extraction/go/disambiguation.rs` (+22 -20) 📝 `iam-policy-autopilot-policy-generation/src/extraction/go/extractor.rs` (+63 -33) 📝 `iam-policy-autopilot-policy-generation/src/extraction/go/features_extractor.rs` (+25 -24) 📝 `iam-policy-autopilot-policy-generation/src/extraction/go/paginator_extractor.rs` (+41 -41) 📝 `iam-policy-autopilot-policy-generation/src/extraction/go/waiter_extractor.rs` (+105 -70) 📝 `iam-policy-autopilot-policy-generation/src/extraction/javascript/argument_extractor.rs` (+4 -2) 📝 `iam-policy-autopilot-policy-generation/src/extraction/javascript/extractor.rs` (+18 -8) _...and 18 more files_ </details> ### 📄 Description *Issue #, if available:* *Description of changes:* This PR adds an experimental explanation feature to the CLI (`--explain`) which, for every action in the generated policy, provides a reason for why it has been added, including the expression and code location where IPA found an AWS operation call that led to its inclusion. It also provides information about [FAS expansion](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_forward_access_sessions.html), if it occurred. We believe that this feature, together with `--service-hints`, will help creating policies with fewer unwanted permissions. Example: ```json "Explanations": { "ExplanationForAction": { "dynamodb:GetItem": [ { "Operations": [ { "Service": "dynamodb", "Name": "GetItem", "Source": { "Expr": "dynamodb.get_item(\n TableName='my-table',\n Key={'id': {'S': '123'}}\n )", "Location": "iam-policy-autopilot-cli/tests/resources/test_example.py:19.5-22.6" } } ] } ], "kms:Decrypt": [ { "Operations": [ { "Service": "s3", "Name": "GetObject", "Source": { "Expr": "s3.get_object(Bucket='my-bucket', Key='my-file.txt')", "Location": "iam-policy-autopilot-cli/tests/resources/test_example.py:7.16-7.68" } }, { "Service": "kms", "Name": "Decrypt", "Source": "FAS" } ] } ] }, "Documentation": { "FAS": { "Plain": "The explanation contains an operation added due to Forward Access Sessions.", "URL": "https://docs.aws.amazon.com/IAM/latest/UserGuide/access_forward_access_sessions.html" } } } ``` This PR adds file and raw expression information and expands location information in multiple places throughout the extraction phase so this data is available in the `SdkMethodCall`. There is currently a lot of code duplication, which I have not cleaned up as part of this pull request. See https://github.com/awslabs/iam-policy-autopilot/issues/88. During enrichment it adds the FAS expansion information. The location format follows the one [here](https://www.gnu.org/prep/standards/html_node/Errors.html). It is clickable, so it navigates to the location in VS Code (I have not tested with other editors). This PR removes the (hidden) `--show-action-mappings` command which had a similar purpose, but did not support location, expression, or FAS information. By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>