Policy Simulator

Policy Simulator lets you see how an IAM policy change might impact a member's access before you commit to making the change. You can use Policy Simulator ensure that the changes you're making won't cause a member to lose access that they need.

How Policy Simulator works

Policy Simulator helps you determine what impact a policy change might have for your users. To do this, it doesn't just compare the permissions in the current and proposed policies. Instead, it uses access logs to focus on the permission changes that would actually affect your users.

To find out how an IAM policy change might impact a member's access, Policy Simulator determines which access attempts from the last 90 days have different results under the proposed policy and the current policy. Then, it reports these results as a list of access changes.

When you simulate an IAM policy change, you provide a proposed policy with the changes that you want to test. This proposed policy can be for any resource that accepts IAM policies.

When you run a simulation, Policy Simulator does the following:

  1. Retrieves access logs for supported resource types from the last 90 days. Where these logs are collected from depends on the resource whose IAM policy you're simulating:

    • If you are simulating a policy for a project or organization, Policy Simulator retrieves the access logs for that project or organization.
    • If you are simulating a policy for a different type of resource, Policy Simulator retrieves the access logs for that resource's parent project or organization.
    • If you are simulating multiple resources' policies at once, Policy Simulator retrieves the access logs for the resources' nearest common project or organization.

    If the parent resource has not existed for 90 days, Policy Simulator retrieves all access attempts since the resource was created.

  2. Re-evaluates, or replays, the access attempts recorded in the access logs using the current IAM policies, taking into account any inherited policies and any policies set on descendant resources.

    Replaying access attempts with the current policy ensures that Policy Simulator only reports access changes that are a result of the proposed policy, and does not report changes that are the result of other policy modifications that you've made in the last 90 days.

  3. Replays the access attempts again using the proposed IAM policy, once more taking into account any inherited policies and any policies set on descendant resources.

  4. Compares the results from the two replays and reports the differences, which show how the proposed changes would affect member access.

Example: Testing policy changes

Imagine that you want to remove a user's Organization Viewer role (roles/resourcemanager.organizationViewer). You want to use Policy Simulator to confirm that this change won't affect the user's access.

You use the Cloud Console, REST API, or the gcloud command-line tool to simulate the policy change.

When you begin the simulation, Policy Simulator does the following:

  • Retrieves the access logs for your organization from the last 90 days.
  • Replays the access attempts using the organization's current policy, where the user has the Editor role.
  • Replays the access attempts again using the proposed policy, where the user has the App Engine Admin role.
  • Compares the results from the two replays and reports the differences between them.

You can then review the results to understand how the proposed change affects the user's access.

Example: Policy inheritance

Imagine that you want to simulate an IAM policy change for a folder, Engineering, in an organization with the following structure:

Sample organization structure

Note that Engineering has a parent resource, the organization example.com, that it inherits IAM policies from. It also has three child projects that can have their own IAM policies: example-prod, example-dev, and example-test.

You provide a proposed policy and run the simulation. When you begin the simulation, Policy Simulator does the following:

  • Retrieves all relevant logs for the last 90 days. Because Engineering is a folder, Policy Simulator retrieves logs from its parent organization, example.com.
  • Replays the access attempts using the folder's current policy, the policy inherited from example.com, and the policies of the child projects.
  • Replays each access attempt again using the proposed policy, the policy inherited from example.com, and the policies of the child projects.
  • Compares the results from the replays and reports the differences between them.

You can then review the results to understand how the proposed change affects the user's access.

Reviewing Policy Simulator results

Policy Simulator reports the impact of a proposed policy change as a list of access changes. An access change represents an access attempt from the last 90 days that would have a different outcome under the proposed policy than under the current policy.

Policy Simulator also lists any errors that occurred during the simulation, which helps you identify potential gaps in the simulation.

There are several different types of access changes:

Access change Details
Access revoked The member had access under the current policy, but will no longer have access after the proposed change.
Access potentially revoked

This result can occur for the following reasons:

  • The member had access under the current policy, but their access under the proposed policy is unknown.
  • The member's access under the current policy is unknown, but they will not have access after the proposed change.
Access gained The member did not have access under the current policy, but will have access after the proposed change.
Access potentially gained

This result can occur for the following reasons:

  • The member did not have access under the current policy, but their access after the proposed change is unknown.
  • The member's access under the current policy is unknown, but they will have access after the proposed change.
Access unknown The member's access under both the current policy and proposed policy is unknown, and the proposed changes might affect the member's access.
Error An error occurred during the simulation.

Unknown results

If an access result is unknown, it means that Policy Simulator did not have enough information to fully evaluate the access attempt.

There are several reasons that a result can be unknown:

  • Role info denied: The member running the simulation did not have permission to see the role details for one or more of the roles being simulated.
  • Unable to access policy: The member running the simulation did not have permission to get the IAM policy for one or more of the resources involved in the simulation.
  • Membership info denied: The member running the simulation did not have permission to view the members of one or more of the groups included in the simulated policy.
  • Unsupported condition: There is a conditional role binding in the policy that is being tested. Policy Simulator does not support conditions, so the binding could not be evaluated.

If an access result is unknown, the Policy Simulator results report the reason it was unknown, plus the specific roles, policies, membership info, and conditionals it was unable to access or evaluate.

Errors

Policy Simulator also reports any errors that occurred during the simulation. It's important to review these errors so that you understand the potential gaps in the simulation.

There are several types of errors that Policy Simulator might report:

  • Operation errors: The simulation could not be run.

    If the error message states the simulation could not be run because there are too many logs in your project or organization, then you cannot run a simulation on the resource.

    If you get this error for another reason, try running the simulation again. If you still cannot run the simulation, contact policy-simulator-feedback@google.com.

  • Replay errors: A replay of a single access attempt was unsuccessful, so Policy Simulator could not determine if the result of the access attempt would change under the proposed policy.

  • Unsupported resource type errors: The proposed policy affects permissions associated with an unsupported resource type, which Policy Simulator cannot simulate. Policy Simulator lists these permissions in the simulation results so that you know which permissions it was unable to simulate.

Maximum log replay size

The maximum number of access logs that a simulation can replay is 1,000. If there are more than 1,000 access logs for your project or organization for the past 90 days, the simulation will fail.

To learn how Policy Simulator decides which access logs to retrieve, see How the Policy Simulator works on this page.

Support levels for resource types

Policy Simulator does not support all resource types in simulations. This affects the permission changes that it is able to simulate.

Supported resource types

Policy Simulator supports only the following resource types:

Service Supported resource types
Cloud Storage
  • buckets
Pub/Sub
  • snapshots
  • subscriptions
  • topics
Cloud SQL
  • backupRuns
  • databases
  • instances
  • sslCerts
  • users
Cloud Spanner
  • backups
  • backupOperations
  • databases
  • databaseOperations
  • instanceConfigs
  • instanceOperations
  • instances
  • sessions
Resource Manager
  • folders
  • organizations
  • projects
Compute Engine
  • instances

Unsupported resource types

Unsupported resource types are resource types that Policy Simulator cannot retrieve access logs for. If Policy Simulator cannot retrieve access logs for a resource, it cannot evaluate how the proposed policy could affect those access attempts.

If a proposed policy change involves permissions for an unsupported resource type, Policy Simulator lists those permissions in the simulation results so that you know which permissions it was unable to simulate. For example, Policy Simulator does not support AI Platform models. So, if a proposed policy removes a role with the aiplatform.models.list permission, the results for that simulation state that it was unable to simulate the aiplatform.models.list permission.

What's next