ARNscopeDocs

IAM permission check

Last updated 11 October 2026

ARNscope checks what the AWS role behind your profile is allowed to do, so it can tell you before a click fails. It uses the IAM policy simulator, which evaluates your policies without calling the services themselves. The check only reads: it calls sts:GetCallerIdentity and iam:SimulatePrincipalPolicy and never creates or changes anything in AWS.

The check is there to explain, not to block. A feature is disabled only when a policy denies it outright. When ARNscope cannot be sure, it leaves everything enabled and lets AWS answer.

The Permissions section of Settings, showing how many actions are allowed, not allowed and not confirmed for a profile.

What is checked

When you pick a profile and region, ARNscope loads its cached result at once, and runs a check in the background only if nothing is cached or the result is more than 24 hours old. It only checks the profile you are using. The steps are:

  1. Who you are. It calls sts:GetCallerIdentity for the profile.
  2. The role. The simulator needs the role, not your session. An assumed-role session such as arn:aws:sts::123456789012:assumed-role/OpsReadOnly/jane becomes the role arn:aws:iam::123456789012:role/OpsReadOnly. An IAM user is simulated as it is. The account’s root user is shown as allowed for everything. Federated users and other identity types cannot be checked, and the check says so.
  3. The simulation. One iam:SimulatePrincipalPolicy call covers every IAM action ARNscope uses, for example lambda:ListFunctions or ssm:StartSession. It runs against all resources (*), with the region you use, a secure transport flag and the current time as context. IAM is called in us-east-1 (or cn-north-1 and us-gov-west-1 for those partitions), whatever the region you browse. The call times out after 20 seconds.

Each action ends in one of four states:

State Meaning Effect in ARNscope
Allowed The simulator allows it. Nothing.
Not allowed A policy denies it with an explicit deny, an organization policy (SCP) blocks it, or the role has no allow for a list or describe call. These cannot be limited to one resource, so no allow at * really means no. The feature can be disabled or marked.
Not confirmed (limited) The role allows it only on some resources, for example one bucket or queue, or the answer depends on something the simulator cannot see. Never disabled.
Not confirmed (unknown) The answer depends on request details the check cannot know, or on a resource policy it cannot read (KMS and Kafka data-plane actions). Never disabled.

Where you see it

Denials learned while you work

ARNscope also watches real AWS responses. When a request to a service ARNscope tracks comes back with an access-denied error (for example AccessDenied, AccessDeniedException or UnauthorizedOperation), ARNscope:

Checking again replaces these marks with a fresh simulation. Denials from IAM and STS calls are ignored.

Caching

The result is cached in the app data folder on this Mac in permissions-cache.json, per account, role and region, for 24 hours. The file holds action names and decisions only, never credentials. Switching between profiles that share a role reuses the same result. Check now, the title-bar icon and a refused request all bypass or invalidate the cache.

If your sign-in has expired, nothing is checked or cached, and the icon says to sign in.

When the check itself is not allowed

Some roles cannot run the simulator. If AWS refuses iam:SimulatePrincipalPolicy, ARNscope shows “Your role cannot run the IAM policy simulator, so permissions are not checked.” Every action is then unknown, nothing is disabled, and if AWS refuses a request later, ARNscope shows AWS’s own message. The same happens if the simulator times out or does not answer, if you are signed in as a federated user, or if the caller type is not supported. Use Check now to try again.

Permissions

The check needs:

Action Used for
sts:GetCallerIdentity Finding your role. Needs no IAM permission.
iam:SimulatePrincipalPolicy Simulating your role’s policies.

A policy that allows it, scoped to your own role:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "iam:SimulatePrincipalPolicy",
    "Resource": "arn:aws:iam::123456789012:role/OpsReadOnly"
  }]
}

AWS documents these permissions in Permissions for using the policy simulator. ARNscope does not use iam:GetContextKeysForPrincipalPolicy. Because the simulator can reveal what other entities may do, AWS suggests granting it narrowly.

What the simulator cannot see

The simulator can differ from the live environment (how the simulator works). In particular:

Treat a green result as “your identity policies allow this”, not as a guarantee, and a red one as a strong hint.

Limitations

Need another way to check access? Write to [email protected] and tell us what you use.