feat: add `--explain` #84

mschlaipfer · 2025-12-17T18:05:12Z

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:

    {
      "Action": "kms:Decrypt",
      "Reasons": [
        {
          "Operation": {
            "Name": "get_object",
            "Service": "s3",
            "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"
          },
          "FAS": {
            "Explanation": "https://docs.aws.amazon.com/IAM/latest/UserGuide/access_forward_access_sessions.html",
            "Expansion": [
              "s3:GetObject",
              "kms:Decrypt"
            ]
          }
        },
        {
          "Operation": {
            "Name": "get_item",
            "Service": "dynamodb",
            "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.5"
          },
          "FAS": {
            "Explanation": "https://docs.aws.amazon.com/IAM/latest/UserGuide/access_forward_access_sessions.html",
            "Expansion": [
              "dynamodb:GetItem",
              "kms:Decrypt"
            ]
          }
        }
      ]
    },

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 #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.

mschlaipfer · 2025-12-18T14:39:42Z

I've created a separate Issue to document the feature once this PR is merged: #90

iam-policy-autopilot-policy-generation/src/api/generate_policies.rs

iam-policy-autopilot-policy-generation/src/enrichment/mod.rs

iam-policy-autopilot-policy-generation/src/enrichment/resource_matcher.rs

weibenz1 · 2025-12-18T23:22:53Z

iam-policy-autopilot-policy-generation/src/enrichment/resource_matcher.rs

                                // Only add if we haven't seen this operation before
-                                if !operations.contains(additional_op) {
-                                    newly_discovered.insert(additional_op.clone());
+                                if !operations.contains(&new_op_with_prov) {


shall we move this condition up to wrap this entire code block?

We need the operation with FAS chain first, to check contains, so we are computing the chain first. We use a custom hash implementation, that just hashes the operation, though. This is a bit ugly, I'll see if I can come up with something better.

I pushed a new commit, but I didn't change this. Open for suggestions.

iam-policy-autopilot-policy-generation/src/enrichment/resource_matcher.rs

adpaco-aws

Please don't forget to add a line to the changelog too.

iam-policy-autopilot-policy-generation/src/enrichment/mod.rs

adpaco-aws · 2026-01-05T19:10:19Z

iam-policy-autopilot-policy-generation/src/enrichment/mod.rs

+    #[serde(rename_all = "PascalCase")]
+    Provided {
+        /// Provided name
+        name: String,


OperationView could just be a struct with name, service and optional metadata.

I'm guessing @mschlaipfer wanted to achieve oneOf.

What about a struct with name and service along with an enum OperationSource: [Extracted, Provided, FasExpansion]?

adpaco-aws · 2026-01-05T19:25:35Z

iam-policy-autopilot-policy-generation/src/enrichment/mod.rs

+    /// The reasons this action was added (can have multiple reasons for the same action)
+    pub reasons: Vec<Reason>,


Could we end up with the same reason multiple times?

Not after applying merge, but I think making this a set makes sense.

adpaco-aws · 2026-01-05T19:30:49Z

iam-policy-autopilot-policy-generation/src/extraction/javascript/shared.rs

+/// Result of finding a command/function instantiation with its arguments
+#[derive(Debug, Clone)]
+pub(crate) struct CommandUsage<'a> {


I'm confused: Why do we need this? Why didn't we need it until now?

I believe I've introduced it due to the complex return type of find_command_instantiation_with_args

weibenz1 · 2026-01-05T22:20:02Z

iam-policy-autopilot-policy-generation/src/enrichment/mod.rs

+#[derive(Debug, Clone, Serialize, PartialEq, Eq, Hash, JsonSchema)]
+#[serde(rename_all = "PascalCase")]
+#[serde(untagged)]
+pub enum OperationView {


nit: OperationSource?

If we name it as OperationSource, can we embed FasInfo inside this enum instead?

weibenz1 · 2026-01-05T22:22:58Z

iam-policy-autopilot-policy-generation/src/enrichment/mod.rs

+    #[serde(rename_all = "PascalCase")]
+    Provided {
+        /// Provided name
+        name: String,


I'm guessing @mschlaipfer wanted to achieve oneOf.

What about a struct with name and service along with an enum OperationSource: [Extracted, Provided, FasExpansion]?

weibenz1 · 2026-01-05T22:23:49Z

iam-policy-autopilot-policy-generation/src/enrichment/mod.rs

+        name: String,
+        resources: Vec<Resource>,
+        conditions: Vec<Condition>,
+        explanation: Explanation,


weibenz1 · 2026-01-05T22:28:58Z

iam-policy-autopilot-policy-generation/src/enrichment/mod.rs

+/// metadata to provide complete resource information for IAM policies.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub(crate) struct Resource {
+    /// The resource type name (e.g., "bucket", "object", "*")


this confuses me a little bit - is it field modelling resource type or the name?

weibenz1 · 2026-01-05T22:30:01Z

iam-policy-autopilot-policy-generation/src/enrichment/resource_matcher.rs

+/// Represents an operation with its provenance chain (how we reached this operation via FAS expansion)
+#[derive(Debug, Clone)]
+struct OperationWithFasExpansion {
+    operation: FasOperation,


If we had GeneratedAction, we don't need these different structs for modeling this variant of operation.

weibenz1 · 2026-01-05T22:35:30Z

iam-policy-autopilot-policy-generation/src/enrichment/mod.rs

+    pub(crate) explanation: Explanation,
 }

 impl Action {


Not for this PR - I'm starting to feel that we really should have just a struct for all generated operation/action like GeneratedAction/GeneratedOperation, and have fields like source annotating additional information and use this single struct only to model all operations.

Probably will make our code more maintainable and clearer.

What do you think?

mschlaipfer requested a review from adpaco-aws December 17, 2025 18:05

weibenz1 reviewed Dec 18, 2025

View reviewed changes

mschlaipfer force-pushed the feat-explain branch from eebf9ee to 86b7b64 Compare December 19, 2025 16:28

mschlaipfer force-pushed the feat-explain branch from 7729d9d to c36dd50 Compare January 5, 2026 13:20

mschlaipfer added 2 commits January 5, 2026 13:35

feat: add --explain

55776b2

feat: refactor based on PR comments

33fae3b

mschlaipfer force-pushed the feat-explain branch from c36dd50 to 33fae3b Compare January 5, 2026 13:44

adpaco-aws reviewed Jan 5, 2026

View reviewed changes

weibenz1 reviewed Jan 5, 2026

View reviewed changes

		/// The reasons this action was added (can have multiple reasons for the same action)
		pub reasons: Vec<Reason>,

feat: add --explain #84

Are you sure you want to change the base?

feat: add --explain #84

Uh oh!

Conversation

mschlaipfer commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mschlaipfer commented Dec 18, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

adpaco-aws left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat: add `--explain` #84

feat: add `--explain` #84

mschlaipfer commented Dec 17, 2025 •

edited

Loading