This page describes how to use the VPC Service Controls violation analyzer to understandand diagnose access denials from service perimeters in your organization.

VPC Service Controls generates a unique ID and a troubleshooting token whendenying an access request. The violation analyzer lets you diagnose the accessdenial using this unique ID and troubleshooting token. VPC Service Controlslogs all the information about an access denial event in Cloud Audit Logs,including the unique ID and troubleshooting token.

You can generate a comprehensive evaluation report for an access denial in theviolation analyzer using the unique ID or troubleshooting token. This reportevaluates the access denial event at a specific point in time against allperimeter configurations that protect the resources from the evaluated accessrequest.

You can also diagnose an access denial andview its classic evaluation reportin the violation analyzer,which provides a short summary of why the access denial occurred.

You can also use the violation analyzer to diagnose access denials from the dry runconfiguration of a service perimeter.

Before you begin

• To understand the device policies in an access level and retrieve the device contextdetails, make sure that you have the required permissions in Google Workspaceto view the device details. Without the required permissions, troubleshooting accessdenials involvingdevice attributesin access levels might yield inconsistent troubleshooting results.

  To get these permissions, make sure that you have any one of the following Google Workspaceroles:

  • Super Admin, Services Admin, or Mobile Admin role.

  • Acustom administrator rolethat contains theManage Devices and Settingsprivilege. You can find this privilege underServices > Mobile Device Management.

  For more information about assigning roles, seeAssign specific admin roles.

  You can use the violation analyzer without these permissions in Google Workspace.However, the troubleshooting result might differ as specified earlier.

Required roles

To get the permissions that you need to use the violation analyzer, ask your administrator to grant you the following IAM roles:

• To diagnose an access denial event using the violation analyzer:Access Context Manager Reader (roles/accesscontextmanager.policyReader) on your organization-level access policy
• To fetch the troubleshooting token from Cloud Audit Logs:Logs Viewer (roles/logging.viewer) on the projects that have VPC Service Controls audit logs

For more information about granting roles, seeManage access to projects, folders, and organizations.

These predefined roles contain the permissions required to use the violation analyzer. To see the exact permissions that are required, expand theRequired permissions section:

You might also be able to get these permissions withcustom roles or otherpredefined roles.

Understand the troubleshooting result

Before you read the troubleshooting result of an access denial event, make sure thatyou refer to the following considerations.

Sensitive information redaction

To protect sensitive data, the violation analyzer redacts the following informationin the troubleshooting result:

• IP address: When an access request originates from a Google Cloud serviceinside an internal production network, the violation analyzer redacts the IP addressof the access request asprivate.

• Network information: The violation analyzer redacts the network information of theaccess request asredacted_network, except in the following scenarios:

  • When you are from the same organization as the network.

  • When you have the necessary permission to view the network information.

• Principal: The violation analyzer redacts the email address of a principal with... (for example,cl...o@gm...m), except in the following scenarios:

  • When you are from the same organization as the access-denied principal.

  • When the access-denied principal is a service agent or service account.

  Some Google Cloud services don't collect identity information. For example, thelegacy App Engine API doesn't collect thecaller identities.When the violation analyzer observes that the principal information is missing inthe logs, the troubleshooting result displays the principal asno information available.

Evaluation status

The violation analyzer evaluates an access denial event against all the perimeter componentsand assigns an evaluation status for each component.

The violation analyzer might display the following evaluation statuses in the troubleshooting result:

View the troubleshooting result

The troubleshooting result page provides a detailed assessment of an access denialevent. This result presents the assessment of the event at the specific point in timewhen you requested the violation analyzer to diagnose the event. The troubleshootingresult page categorizes the assessment information under different sections.

The troubleshooting result of an access denial event can have the following sections:

• Violation details

• Violation evaluation

• Restricted resources

• Restricted services

• Ingress

• Egress

• VPC accessible services

To view the assessment of a specific perimeter component, select the perimeter componentfrom the list or click thearrow_right expander arrownext to the perimeter component. For example, to view the troubleshooting assessmentfor an egress rule, select the egress rule or click thearrow_rightexpander arrow next to the egress rule.

After you review the troubleshooting result of an access denial event, you can modifythe necessary perimeter components and configuration to resolve the denial. To editthe selected perimeter, clickeditEdit enforcedconfig orEdit dry run config in the troubleshooting result page. For moreinformation, seeUpdate a service perimeter.

Violation details

TheViolation details section lists the following information about the access denial event:

• The time of the access denial event.

• The identity of the principal that requested access.

• The service for which the principal requested access.

• The service method for which the principal requested access.

• The IP address of the principal that requested access. This IP address isthe same as thecaller_ip value of the access denial event's log entry inCloud Audit Logs. For more information, seeIP address of the caller inaudit logs.

• The troubleshooting token of the access denial event.

• The unique ID of the access denial event.

• The details of the involved device and region. To view this information, clickView device info.

• The log entry details associated with the access denial event. To view thisinformation, clickView log entry.

  If the log entry exceeds the Cloud Audit Logsretention period,the violation analyzer can't display these details.

Violation evaluation

TheViolation evaluation section shows the overall assessment of the access denialevent. The assessment includes both the enforced and dry run mode troubleshootingresults of the perimeter.

The troubleshooting results for an access denial event can vary over time if thereare changes in service perimeters or access policies after VPC Service Controls logsthe access denial event. This behavior is due to the fact that the violation analyzerfetches the latest information from the relevant service perimeters and access policiesfor assessment.

Outcome

TheOutcome section shows the assessment of the access denial event against allthe perimeters involved. The value can beGranted,Denied, orNot applicable.

Protected resources accessed

TheProtected resources accessed section lists the perimeters with the correspondingevaluation status against the access denial event. In this section, you can viewthe following information:

• A list of all resources involved in this access denial event:

  • TheResources accessed column displays all involved resources protectedby the perimeter.

  • When you don't have sufficient permissions to view the restricted resources,theProtected resources accessed section doesn't list the perimeter nameand theResources accessed column displays the involved project witha warning icon.

  • TheOther resources accessed section lists all the other involved resources,grouped under one of the following states:

    State	Description
    Unrestricted	This state indicates that the resource is not protected by any service perimeter.
    Info denied	This state indicates that you don't have sufficient permissions to view the service perimeters protecting the resource.
    Error	This state indicates that an internal error has occurred while trying to view the service perimeters protecting the resource.

• When you select a perimeter from the list, you can view the troubleshootingresult for the access denial event against the selected perimeter.

• You can view the troubleshooting results for different enforcement modes ofthe perimeter as well. By default, the troubleshooting result page displaystheEnforced mode troubleshooting result. If you want to view the dryrun mode troubleshooting result, clickDry run. For more informationabout the perimeter enforcement modes, seeService perimeter details andconfiguration.

  Because the enforced mode and dry run mode configurations of a perimeter canbe different, the violation analyzer can generate different troubleshootingresults for the enforced mode and dry run mode configurations.

Restricted resources

In this section, you can view the following information:

• TheInvolved in evaluation row shows only the resources involved in thisviolation and protected by the selected perimeter.

• TheRestricted by perimeter row shows all the resources that are protectedby the selected perimeter.

Restricted services

In this section, you can view the following information:

• TheInvolved in evaluation row shows only the services involved in thisviolation and protected by the selected perimeter.

  Even if you have already removed the violating service from the perimeter, theInvolved in evaluation row still lists the service and displays a warningmessage.

• TheRestricted by perimeter row shows all the services that are protectedby the selected perimeter.

Ingress

TheIngress section shows the assessment of the access denial event againstall the ingress rules and access levels involved. For each access request, theviolation analyzer evaluates the service agents or networks and the correspondingtarget resources against the ingress rules and access levels.

The violation analyzer groups and displays the ingress rule assessmentinformation based on the ingress rules and access levels. Clicking each rule oraccess level in this section expands it to display the target resource names assessedagainst that rule or access level.

If you want to resolve a denial by modifying an existing ingress rule, clickeditEdit next to the rule in thetroubleshooting result page. For information about the ingress rule attributes,seeIngress rules reference.

Egress

TheEgress section shows the assessment of the access denial event againstall the egress rules involved. The violation analyzer evaluates the source andtarget resource pairs of the access request against the egress rules.

The violation analyzer groups and displays the egress rule assessment informationbased on the egress rules. Clicking each rule in this section expands it to displaythe detailed assessment of the resources against that rule.

If you want to resolve a denial by modifying an existing egress rule, clickeditEdit next to the rule in thetroubleshooting result page. For information about the egress rule attributes,seeEgress rules reference.

VPC accessible services

TheVPC accessible services section shows the status of the services thatare accessible from network endpoints inside the perimeter. These statusescorrespond to the time when the access denial event occurred. If the evaluationstatus for a service isDenied, you can't access the service from networkendpoints inside the perimeter.

In this section, you can view the following information:

• TheInvolved in evaluation row shows only the services involved in thisviolation and not accessible from network endpoints inside the selected perimeter.This row also displays services that are not on the perimeter's list of VPCaccessible services, either because these services were removed or werenever included.

• TheAccessible within perimeter row shows all the services that are accessiblefrom network endpoints inside the selected perimeter.

For more information, seeVPC accessible services.

Compare the enforced and dry run mode results

You can compare the troubleshooting results of an access denial event betweenthe enforced and dry run modes of the selected perimeter. To compare thetroubleshooting results, clickcompare_arrowsCompare to dry run on the enforced mode troubleshooting result page of a perimeter.

If the dry run mode inherits the configuration from the enforced mode of the perimeter,the dry run mode also inherits the enforced mode troubleshooting result.

• You must use the violation analyzer only at the organization scope, and the violation analyzeris not accessible at the project scope.

• The violation analyzer fetches the latest information from the relevant serviceperimeters and access policies for assessment. So the troubleshooting resultsfor an access denial event can vary over time if there are changes in serviceperimeters or access policies after VPC Service Controls logs the access denialevent.

  • Also, if you diagnose an access denial event multiple times, the troubleshootingresults might vary for each diagnosis if the access policy has changed.

• The troubleshooting result of an access denial event might differ in the following scenarios:

  • When you have defineddevice attributebased conditions in an access level and used the access level in your service perimeter,but you don't have thepermissions required to view the device details.

  • When an ingress or egress rule of the service perimeter usesidentity groupsor third-party identities.

  • When you have configured acredential strength policyin the access level.

  • When aningress or egress ruleof the service perimeter uses a service permission as an API operation condition.

What's next

• Diagnose an access denial and view the classic report
• Debugging requests blocked by VPC Service Controls