Package: aws-iam-tester
Testing AWS IAM policiesIntroductionAWS IAM policies are notouriously complex, it is too easy to add some unintended permissions and it is surprisingly difficult to identify these in heavily used AWS accounts.Thankfully AWS has provided anIAM simulatorthat allows you to evaluate existing or new policies for its behavior. Which is very nice, but doing this manually is quite time consuming and it is unrealistic to test the entire environment for what you are trying to do.However, in good AWS spirit the simulator has an API and this tool provides automation on top of it. It allows you to define the complete list of actions you want to evaluate against what resources, which allows you to run these tests on a regular basis or (better) integrate it in your CI/CD pipeline.Testing approachThe testing leverages AWS'IAM simulator (api), that basically includes the same IAM evaluation logic that is applied when working in the console or using the cli. The beneits of this approach are:It takes all different levels of policies into account. Think about permission boundaries, service control policies and so on.It is an official service from AWS, so you can expect this to kept up to date over time.The actual actions are evaluated, but NOT executed. Hence no need for cleaning up resources after testing.Quick testingFor convenience, you can use this tool to quickly test whether a user has a specific permission on a particular resource:$aws-iam-testeraccess-uthe_user-a'glue:DeleteTable'Test:
Source:arn:aws:iam::208912673223:user/the_user
Action:glue:DeleteTable
Resource:*
Result:allowed

Matchedstatements:
Policy:admin_permissions
Type:IAMPolicy
Start:L3:C17
End:L8:C6Or to see who has access to a particular resource and action by omitting bothuserandrole:$aws-iam-testeraccess-a"s3:PutObject"..............

Summary:|Source|Action|Resource|Decision|Policies||----------------------------------------------------------|--------------|------------|------------|---------------------||arn:aws:iam::XXXXXXXXXXXX:user/the_user|s3:PutObject|*|allowed|admins_permissions||arn:aws:iam::xxxxxxxxxxxx:role/the_role|s3:PutObject|*|allowed|AdministratorAccess|Finding out who has access to a particular action/resource combinationIt might be useful to check your highly senstive resources and find out who exactly can access these.$aws-iam-testeraccess-a"s3:PutObject"-R"arn:aws:s3:::my-strictly-confidential-data"..............

Summary:|Source|Action|Resource|Decision|Policies||----------------------------------------------------------|--------------|--------------------------------------------|------------|---------------------||arn:aws:iam::XXXXXXXXXXXX:user/the_user|s3:PutObject|arn:aws:s3:::my-strictly-confidential-data|allowed|admins_permissions||arn:aws:iam::xxxxxxxxxxxx:role/the_role|s3:PutObject|arn:aws:s3:::my-strictly-confidential-data|allowed|AdministratorAccess|Account testingHowever, the initial purpose of this tool is to check an entire account whether there are no users and/or roles having permissons which they should not have.ConfigurationIn order to run, a configuration of the tests to run is required.A sample configuration (with only one test) is shown, in various steps.First there is a global section where you define settings which are applied to all tests (unless overruled, more on that later).---user_landing_account:0123456789# ID of AWS Account that is allowed to assume roles in the test accountglobal_exemptions:# The roles and/or users below will be ignored in all tests. Regular expressions are supported-"^arn:aws:iam::(\\d{12}):user/(.*)(ADMIN|admin)(.*)$"-"^arn:aws:iam::(\\d{12}):role/(.*)(ADMIN|admin)(.*)$"-"^arn:aws:iam::(\\d{12}):role/AWSCloudFormationStackSetExecutionRole$"Then you define a list of tests, each consisting at least of a set of:actionsresourcesthe expected result (should it fail or succeed)# List of tests to execute. In general the configurations follow the rules of the AWS IAM Policy Simulator.# For more information: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_testing-policies.htmltests:-actions:# list of actions to validate-"*:*"-iam:*-iam:AddUser*-iam:Attach*-iam:Create*-iam:Delete*-iam:Detach*-iam:Pass*-iam:Put*-iam:Remove*-iam:UpdateAccountPasswordPolicy-sts:AssumeRole-sts:AssumeRoleWithSAMLexpected_result:fail# 'fail' or 'succeed'resources:# list of resources to validate against-"*"Rather than using all users and roles (without exemptions) you can also limit your test to a particular set of users and roles.The test below does that, including defining a custom context that specifies multi factor authentication is disabled when running the test. By default the context under which the simulations are run assumes MFA is enabled, but you can override that with thecustom_contextelement. For more information see theAWS documentation.-actions:# Same list of actions, but now check (with a custom context) whether-"*:*"-iam:*-iam:AddUser*-iam:Attach*-iam:Create*-iam:Delete*-iam:Detach*-iam:Pass*-iam:Put*-iam:Remove*-iam:UpdateAccountPasswordPolicy-sts:AssumeRole-sts:AssumeRoleWithSAMLexpected_result:fail# 'fail' or 'succeed'resources:# list of resources to validate against-"*"limit_to:# check this list for the admin users-"^arn:aws:iam::(\\d*):user/(.*)(ADMIN|admin)(.*)$"-"^arn:aws:iam::(\\d*):role/(.*)(ADMIN|admin)(.*)$"# test if the admins are required to use multi factor authenticationcustom_context:-context_key_name:aws:MultiFactorAuthPresentcontext_key_values:falsecontext_key_type:booleanOr if you want to do that foralltests you can use theglobal_limit_to:---user_landing_account:0123456789# ID of AWS Account that is allowed to assume roles in the test accountglobal_limit_to:# These roles and/or users below will be u. Regular expressions are supported-"^arn:aws:iam::(\\d{12}):user/(.*)(ENGINEER|engineer)(.*)$"-"^arn:aws:iam::(\\d{12}):role/(.*)(SCIENTIST|scientist)(.*)$"Below an example where an additional set of roles is exempt from testing:-actions:# list of data centric actions-redshift:GetClusterCredentials-redshift:JoinGroup-rds:Create*-rds:Delete*-rds:Modify*-rds-db:connect-s3:BypassGovernanceRetention-s3:CreateBucket-s3:DeleteBucket-s3:DeleteBucketPolicy-s3:PutBucketAcl-s3:PutBucketPolicy-s3:PutEncryptionConfiguration-s3:ReplicateDeleteexpected_result:fail# 'fail' or 'succeed'resources:# list of resources to validate against-"*"exemptions:[- "^arn:aws:iam::(\\d{12}):role/(.*)_worker$"# ignore this for the worker roles]If you want to run positive tests (i.e. tests that you need to succeed rather than fail), theseexemptionsdon't work that well.In that case you can limit your tests to a set of roles and users:-actions:-s3:PutObjectexpected_result:succeedresources:-"arn:aws:s3:::my_bucket/xyz/*"limit_to:# if you specify this, test will only be performed for the sources below-"^arn:aws:iam::(\\d{12}):role/my_worker$"Note that the exemptions are ignored when using alimit_tolist.Using a dynamic account id in the resource arnIn case youneedto specify theaccount idin the resource arn, you can specificy this as follows:-actions:-"secretsmanager:GetSecretValue"expected_result:succeedresources:-"arn:aws:secretsmanager:eu-central-1:{account_id}:secret:my-secret/*"Using regular expressions for user and role matchingRegular expressions can be used when checking the users and/or roles that need to be included in the tests. Hence they are supported for the following elements in the config file:limit_to (the filtered list of users/roles to be used for a particular test)global_limit_to (the filtered list of users/roles to be used for all tests)exemptions (the filtered list of users/roles that should be excluded from a particular test)global_exemptions (the filtered list of users/roles that should be excluded from all tests)For all other elements, regular expression matching is NOT supported!How to useAssuming you have define a config.yml in your local directory, then to run and write the outputs to the local./resultsdirectory:aws-iam-tester--write-to-fileUsing a specific config file:aws-iam-tester--config-filemy-config.ymlUsing a specific output location:aws-iam-tester--output-location/tmpOr write to s3:aws-iam-tester--output-locations3://my-bucket/my-prefixInclude only roles that can be assumed by human beings:aws-iam-tester--no-include-system-rolesNote: including system roles does NOT include the aws service roles.Or print debug output:aws-iam-tester--debugTo run a limited number of evaluations (which helps speeding things up, and avoiding API throttling issues):aws-iam-tester--number-of-runs10For more information, runaws-iam-tester --helpfor more instructions.Return codesThe tester returns the following return codes:0 upon successful completion with NO findings1 upon successful completion with findings2 (or higher) on failuresRequired permissionsObviously the client has to run under an AWS security context that has sufficient permissions to query the IAM resources and run the simulator.The following permissions are needed at the minimum:-sts:GetCallerIdentity-iam:ListAccountAliases-iam:ListRoles-iam:ListUsers-iam:SimulatePrincipalPolicyAnd if you want to write the output to an s3 location, then obviously you need write access (s3:PutObject) to that particular location as well.Unit testingpytestis being used for testing the various options.As long as theaws-iam-testermodule is installed, you can run thetests.pytest -vsx#or,alternativelypoetry run pytest -vsxAfter installingtox, you can also simply run$ tox.