IAM Access Analyzer custom policy checks - Amazon Identity and Access Management
How custom policy checks workReference policy examples to check for new accessInspecting failed custom policy checksValidating policies with custom policy checks (console)Validating policies with custom policy checks (Amazon CLI or API)
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

IAM Access Analyzer custom policy checks

You can validate your policies against your specified security standards using Amazon Identity and Access Management Access Analyzer custom policy checks. There are two kinds of custom policy checks that you can run:

  • Check against a reference policy: When editing a policy, you can check whether the updated policy grants new access compared to a reference policy, such as an existing version of the policy. You can run this check when you edit a policy using the Amazon Command Line Interface (Amazon CLI), IAM Access Analyzer API (API), or JSON policy editor in the IAM console.

  • Check against a list of IAM actions: You can check to ensure that specific IAM actions are not allowed by your policy. You can run this check when you create or edit a policy using the Amazon CLI or the API.

A charge is associated with each custom policy check. For more details about pricing, see IAM Access Analyzer pricing.

How custom policy checks work

You can run custom policy checks on identity and resource-based policies. Custom policy checks don't rely on pattern-matching techniques or examining access logs to determine whether new or a specified access is allowed by a policy. Similar to external access findings, custom policy checks are built on Zelkova. Zelkova translates IAM policies into equivalent logical statements, and runs a suite of general-purpose and specialized logical solvers (satisfiability modulo theories) against the problem. To check for new or specified access, IAM Access Analyzer applies Zelkova repeatedly to a policy. Queries become increasingly specific to characterize classes of behaviors that the policy allows based on the content of the policy. For more information about satisfiability modulo theories, see Satisfiability Modulo Theories.

In rare cases, IAM Access Analyzer isn't able to fully determine whether a policy statement grants new or specified access. In those cases, it errs on the side of declaring a false positive by failing the custom policy check. IAM Access Analyzer is designed to provide a comprehensive policy evaluation and strives to minimize false negatives. This approach means that IAM Access Analyzer provides a high degree of assurance that a passed check means access wasn't granted by the policy. You can inspect failed checks manually by reviewing the policy statement that's reported in the response from IAM Access Analyzer.

Reference policy examples to check for new access

You can find examples for reference policies and learn how to set up and run a custom policy check for new access in the IAM Access Analyzer custom policy checks samples repository on GitHub.

Before using these examples

Before you use these sample reference policies, do the following:

  • Carefully review and customize the reference policies for your unique requirements.

  • Thoroughly test the reference policies in your environment with the Amazon Web Services that you use.

    The reference policies demonstrate the implementation and use of custom policy checks. They're not intended to be interpreted as official Amazon recommendations or best practices to be implemented exactly as shown. It is your responsibility to carefully test reference policies for their suitability to solve the security requirements for your environment.

  • Custom policy checks are environment-agnostic in their analysis. Their analysis only considers information contained within the input policies. For example, custom policy checks can't check whether an account is a member of a specific Amazon organization. Therefore, the custom policy checks can't compare new access based on condition key values for the aws:PrincipalOrgId and aws:PrincipalAccount condition keys.

Inspecting failed custom policy checks

When a custom policy check fails, the response from IAM Access Analyzer includes the statement ID (Sid) of the policy statement that caused the check to fail. Although the statement ID is an optional policy element, we recommend that you add a statement ID for every policy statement. The custom policy check also returns a statement index to help identify the reason for the check failure. The statement index follows zero-based numbering, where the first statement is referenced as 0. When there are multiple statements that cause a check to fail, the check returns only one statement ID at a time. We recommend that you fix the statement highlighted in the reason and rerun the check until it passes.

Validating policies with custom policy checks (console)

As an optional step, you can run a custom policy check when editing a policy in the JSON policy editor in the IAM console. You can check whether the updated policy grants new access compared to the existing version.

To check for new access when editing IAM JSON policies

  1. Sign in to the Amazon Web Services Management Console and open the IAM console at https://console.amazonaws.cn/iam/.

  2. In the navigation pane on the left, choose Policies.

  3. In the list of policies, choose the policy name of the policy that you want to edit. You can use the search box to filter the list of policies.

  4. Choose the Permissions tab, and then choose Edit.

  5. Choose the JSON option and make updates to your policy.

  6. In the policy validation pane below the policy, choose the Check for new access tab and then choose Check policy. If the modified permissions grant new access, the statement will be highlighted in the policy validation pane.

  7. If you don't intend to grant new access, update the policy statement and choose Check policy until no new access is detected.

    Note

    A charge is associated with each check for new access. For more details about pricing, see IAM Access Analyzer pricing.

  8. Choose Next.

  9. On the Review and save page, review Permissions defined in this policy and then choose Save changes.

Validating policies with custom policy checks (Amazon CLI or API)

You can run IAM Access Analyzer custom policy checks from the Amazon CLI or the IAM Access Analyzer API.

To run IAM Access Analyzer custom policy checks (Amazon CLI)

  • To check whether new access is allowed for an updated policy when compared to the existing policy, run the following command: check-no-new-access

  • To check whether the specified access isn't allowed by a policy, run the following command: check-access-not-granted

To run IAM Access Analyzer custom policy checks (API)

  • To check whether new access is allowed for an updated policy when compared to the existing policy, use the CheckNoNewAccess API operation.

  • To check whether the specified access isn't allowed by a policy, use the CheckAccessNotGranted API operation.