Skip to content

aws-actions/terraform-aws-iam-policy-validator

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Policy Validator for AWS IAM Policies in Terraform Templates

A GitHub Action that takes an Terraform template, parses the IAM policies attached to IAM roles, users, groups, and resources then runs them through IAM Access Analyzer policy validation and (optionally) custom policy checks. Note that a charge is associated with each custom policy check. For more details about pricing, see IAM Access Analyzer pricing.

Inputs

See action.yml for the full documentation for this action's inputs and outputs.

Inputs Description Options Required Applies To which policy-check-type
VALIDATE_POLICY CHECK_NO_NEW_ACCESS CHECK_ACCESS_NOT_GRANTED CHECK_NO_PUBLIC_ACCESS
policy-check-type Name of the policy check.
Note: Each value corresponds to an IAM Access Analyzer API.
- ValidatePolicy
- CheckNoNewAccess
- CheckAccessNotGranted
- CheckNoPublicAccess
VALIDATE_POLICY, CHECK_NO_NEW_ACCESS, CHECK_ACCESS_NOT_GRANTED, CHECK_NO_PUBLIC_ACCESS. Yes
template-path The path to the CloudFormation template. FILE_PATH.json Yes
region The destination region the resources will be deployed to. REGION Yes
ignore-finding Allow validation failures to be ignored. Specify as a comma separated list of findings to be ignored. Can be individual finding codes (e.g. "PASS_ROLE_WITH_STAR_IN_RESOURCE"), a specific resource name (e.g. "MyResource"), or a combination of both separated by a period.(e.g. "MyResource.PASS_ROLE_WITH_STAR_IN_RESOURCE"). Names of finding codes may change in IAM Access Analyzer over time. FINDING_CODE,RESOURCE_NAME,RESOURCE_NAME.FINDING_CODE No
actions List of comma-separated actions. Example format - ACTION,ACTION,ACTION.

This attribute is only considered when policy-check-type is "CHECK_ACCESS_NOT_GRANTED". At least one of "actions" or "resources" must be provided
ACTION,ACTION,ACTION No
resources List of comma-separated resource ARNs. Example format - RESOURCE,RESOURCE,RESOURCE.

This attribute is only considered when policy-check-type is "CHECK_ACCESS_NOT_GRANTED". At least one of "actions" or "resources" must be provided
RESOURCE,RESOURCE,RESOURCE No
reference-policy A JSON formatted file that specifies the path to the reference policy that is used for a permissions comparison.

This attribute is only considered and required when policy-check-type is "CHECK_NO_NEW_ACCESS".
FILE_PATH.json No
reference-policy-type The policy type associated with the IAM policy under analysis and the reference policy. Valid values: IDENTITY, RESOURCE.

This attribute is only considered and required when policy-check-type is "CHECK_NO_NEW_ACCESS"
REFERENCE_POLICY_TYPE No
treat-finding-type-as-blocking Specify which finding types should be treated as blocking. Other finding types are treated as non blocking. If the tool detects any blocking finding types, it will exit with a non-zero exit code. If all findings are non blocking or there are no findings, the tool exits with an exit code of 0. Defaults to "ERROR" and "SECURITY_WARNING". Specify as a comma separated list of finding types that should be blocking. Pass "NONE" to ignore all findings.

This attribute is only considered when policy-check-type is "VALIDATE_POLICY".
ERROR,SECURITY_WARNING,WARNING,SUGGESTION,NONE No
treat-findings-as-non-blocking By default, the tool will exit with a non-zero exit code when it detects any findings. Set this flag to exit with an exit code of 0 when it detects findings. You can use this to run new checks in a shadow or log only mode before enforcing them.

This attribute is considered only when policy-check-type is "CHECK_NO_NEW_ACCESS", "CHECK_ACCESS_NOT_GRANTED", or "CHECK_NO_PUBLIC_ACCESS.
No
allow-external-principals A comma separated list of external principals that should be ignored. Specify as a comma separated list of a 12 digit AWS account ID, a federated web identity user, a federated SAML user, or an ARN. Specify "*" to allow anonymous access. (e.g. 123456789123,arn:aws:iam::111111111111:role/MyOtherRole,graph.facebook.com). ACCOUNT,ARN No
allow-dynamic-ref-without-version Override the default behavior and allow dynamic SSM references without version numbers. The version number ensures that the SSM parameter value that was validated is the one that is deployed. No
exclude-resource-types List of comma-separated resource types. Resource types should be the same as Cloudformation template resource names such as AWS::IAM::Role, AWS::S3::Bucket. Valid option syntax: AWS::SERVICE::RESOURCE. AWS::SERVICE::RESOURCE, AWS::SERVICE::RESOURCE No

Example Usage

Before each of the following examples, make sure to include the following:

  • Setting up the role: Role used in the GitHub workflow should have necessary permissions required
    • to be called from the GitHub workflows - setup OpenID Connect(OIDC) provider and IAM role & Trust policy as described in step 1 & 2 in this blog
    • to call the AWS APIs for the policy checks - ValidatePolicy, CheckNoNewAccess, CheckAccessNotGranted, CheckNoPublicAccess. Refer this page for more details
    - name: Checkout Repo
        uses: actions/checkout@v4
      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.POLICY_VALIDATOR_ROLE }} # Role with permissions to invoke access-analyzer:ValidatePolicy,access-analyzer:CheckNoNewAccess, access-analyzer:CheckAccessNotGranted, access-analyzer:CheckNoPublicAccess
          aws-region: aws-example-region

Getting started using starter workflows

To get started quickly, add a starter workflow to the .github/workflows directory of your repository. In order to do that, do the following -

  • Navigate to Actions tab of the GitHub repository
  • Click on New Workflow button
  • Search for Policy Validator for Terraform in the search bar
  • Click on Configure button
  • Pass the appropriate inputs to the workflow and modify it accordingly
  • Click on Commit changes to commit your changes
  • Start using the GitHub actions!

Please find the starter workflow here

Using VALIDATE_POLICY CHECK

      - name: Run VALIDATE_POLICY Check
        id: run-validate-policy
        uses: aws-actions/terraform-aws-iam-policy-validator@v1.0.1
        with:
          policy-check-type: 'VALIDATE_POLICY'
          template-path: file-path-to-the-cfn-templates
          region: aws-example-region

Using for the CHECK_NO_NEW_ACCESS CHECK

      - name: Run CHECK_NO_NEW_ACCESS check
        id: run-check-no-new-access
        uses: aws-actions/terraform-aws-iam-policy-validator@v1.0.1
        with:
          policy-check-type: 'CHECK_NO_NEW_ACCESS'
          template-path: file-path-to-the-cfn-templates
          reference-policy: file-path-to-the-reference-policy
          reference-policy-type: policy-type-of-reference-policy
          region: aws-example-region

Using for the CHECK_ACCESS_NOT_GRANTED CHECK

      - name: Run CHECK_ACCESS_NOT_GRANTED check 
        id: run-check-access-not-granted
        uses: aws-actions/terraform-aws-iam-policy-validator@v1.0.1
        with:
          policy-check-type: 'CHECK_ACCESS_NOT_GRANTED'
          template-path: file-path-to-the-cfn-templates
          actions: "action1, action2.."
          resources: "resource1, resource2.."
          region: aws-example-region

Using for the CHECK_NO_PUBLIC_ACCESS CHECK

      - name: Run CHECK_NO_PUBLIC_ACCESS check 
        id: run-check-no-public-access
        uses: aws-actions/cloudformation-aws-iam-policy-validator@v1.0.1
        with:
          policy-check-type: 'CHECK_NO_PUBLIC_ACCESS'
          template-path: file-path-to-the-cfn-templates
          region: aws-example-region

Security

See CONTRIBUTING for more information.

License

This library is licensed under the MIT-0 License. See the LICENSE file.