Understanding and using Access Transparency logs

This page describes the contents of Access Transparency log entries and how to view and use them.

Access Transparency logs in detail

Access Transparency logs can be integrated with your existing security information and event management (SIEM) tools to automate your audits of Google personnel when they access your content. Access Transparency logs are available in the Google Cloud Console alongside your Cloud Audit Logs logs.

Access Transparency log entries include the following types of details:

  • The affected resource and action.
  • The time of the action.
  • The reasons for the action (for example, the case number associated with a customer support request).
  • Data about who is acting on the content (for example, the Google personnel's location).

Configuring Access Transparency

To configure Access Transparency logs, see the Access Transparency overview.

Viewing Access Transparency logs

After you've configured Access Transparency for your Google Cloud organization, you can set controls for who can access the Access Transparency logs by assigning a user or group the Private Logs Viewer role. See the Cloud Logging access control guide for details.

To view Access Transparency logs, use the following Google Cloud's operations suite logging filter.

logName="projects/<your-project-id>/logs/cloudaudit.googleapis.com%2Faccess_transparency"

To learn how to see your Access Transparency logs in the Logs Explorer, see Using the Logs Explorer.

You can also monitor the logs by using the Cloud Monitoring API or using Cloud Functions. To get started, see the Cloud Monitoring documentation.

Optional: Create a logs-based metric and then set up an alerting policy to give you timely awareness of issues surfaced by these logs.

Sample Access Transparency log entry

The following is an example of an Access Transparency log entry:

{
 insertId:  "abcdefg12345"
 jsonPayload: {
  @type:  "type.googleapis.com/google.cloud.audit.TransparencyLog"
  location: {
   principalOfficeCountry:  "US"
   principalEmployingEntity:  "Google LLC"
   principalPhysicalLocationCountry:  "CA"
  }
  product: [
   0:  "Cloud Storage"
  ]
  reason: [
    detail:  "Case number: bar123"
    type:  "CUSTOMER_INITIATED_SUPPORT"
  ]
  accesses: [
   0: {
    methodName: "GoogleInternal.Read"
    resourceName: "//googleapis.com/storage/buckets/BUCKET_NAME/objects/foo123"
    }
  ]
  accessApprovals: [
   0: "projects/123/approvalRequests/abcdef12345"
  ]
 }
 logName:  "projects/PRO_ID/logs/cloudaudit.googleapis.com%2Faccess_transparency"
 operation: {
  id:  "12345xyz"
 }
 receiveTimestamp:  "2017-12-18T16:06:37.400577736Z"
 resource: {
  labels: {
   project_id:  "1234567890"
  }
  type:  "project"
 }
 severity:  "NOTICE"
 timestamp:  "2017-12-18T16:06:24.660001Z"
}

Log field descriptions

Field Description
insertId Unique identifier for the log.
@type Access Transparency log identifier.
principalOfficeCountry ISO 3166-1 alpha-2 country code of country in which the accessor has a permanent desk, ?? if location not available, or 3-character continent identifier where Google personnel are in a low-population country.
principalEmployingEntity The entity that employs the Google personnel making the access (for example, Google LLC).
principalPhysicalLocationCountry ISO 3166-1 alpha-2 country code of country from which access was made, ?? if location not available, or 3-character continent identifier where Google personnel are in a low-population country.
product Customer's GCP product that was accessed.
reason:detail Details of the reason, for example, a support ticket ID.
reason:type Access reason type (for example, CUSTOMER_INITIATED_SUPPORT).
accesses:methodName What type of access was made. For example, GoogleInternal.Read. For more information about the methods that can appear in the methodName field, see Values for accesses: methodName field.
accesses:resourceName Name of resource that was accessed.
accessApprovals Includes the resource names of Access Approval requests that approved the access. These requests are subject to exclusions and supported services.

This field is populated only if Access Approval is enabled for the accessed resources. Access Transparency logs published before the date March 24, 2021 won't have this field populated.
logName Name of the log location.
operation:id Log cluster ID.
receiveTimestamp Time the access was received by the logging pipeline.
project_id Project associated with the resource that was accessed.
type Type of resource that was accessed (for example, project).
severity Log severity.
timestamp Time the log was written.

Values for accesses:methodNames field

The following methods can appear in the accesses:methodNames field in Access Transparency logs:

  • Standard methods: These methods are List, Get, Create, Update, and Delete. For more information, see Standard methods.
  • Custom methods: Custom methods refer to API methods besides the 5 standard methods. Common custom methods include Cancel, BatchGet, Move, Search, and Undelete. For more information, see Custom methods.
  • GoogleInternal methods: The following GoogleInternal methods can appear in the accesses:methodNames field:
Method name Description Examples
GoogleInternal.Read Signifies a read action performed on customer content with a valid business justification. The read action occurs using an internal API that is specifically designed for administering Google Cloud services. This method doesn't mutate customer content. Reading IAM permissions.
GoogleInternal.Write Signifies a write action performed on customer content with a valid business justification. The write action occurs using an internal API that is specifically designed for administering Google Cloud services. This method can update customer content and/or configurations.
  • Setting IAM permissions for a resource.
  • Suspending a Compute Engine instance.
GoogleInternal.Create Signifies a create action performed on customer content with a valid business justification. The create action occurs using an internal API that is specifically designed for administering Google Cloud services. This method creates new customer content.
  • Creating a Cloud Storage bucket.
  • Creating a Pub/Sub topic.
GoogleInternal.Delete Signifies a a delete action performed on customer content using an internal API specifically designed for administering Google Cloud services. This method mutates customer content and/or configurations.
  • Deleting a Cloud Storage object.
  • Deleting a BigQuery table.
GoogleInternal.List Signifies a list action performed on customer content with a valid business justification. The list action occurs using an internal API that is specifically designed for administering Google Cloud services. This method doesn't mutate customer content or configurations.
  • Listing a customer's Compute Engine instances.
  • Listing a customer's Dataflow jobs.
GoogleInternal.SSH Signifies an SSH action performed on a customer's virtual machine with a valid business justification. The SSH access occurs using an internal API that is specifically designed for administering Google Cloud services. This method can mutate customer content and configurations.
  • SSH access to a customer's Compute Engine instance.
  • SSH access to a customer's Cloud SQL instance.
GoogleInternal.Update Signifies a modification performed on customer content with a valid business justification. The update action occurs using an internal API that is specifically designed for administering Google Cloud services. This method mutates customer content and/or configurations. Updating HMAC keys in Cloud Storage.
GoogleInternal.Get Signifies a get action performed on customer content with a valid business justification. The get action occurs using an internal API that is specifically designed for administering Google Cloud services. This method doesn't mutate customer content or configurations.
  • Retrieving IAM policy for a resource.
  • Retrieving a customer's Dataflow job.
GoogleInternal.Query Signifies a query action performed on customer content with a valid business justification. The query action occurs using an internal API that is specifically designed for administering Google Cloud services. This method doesn't mutate customer content or configurations.
  • Running a BigQuery query.
  • AI Platform debugging console lookup on customer content.

Justification reason codes

Reason Description
CUSTOMER_INITIATED_SUPPORT Customer-initiated support, for example, Case Number: ####
GOOGLE_INITIATED_SERVICE Google-initiated access, for example, to perform system management and troubleshooting, which includes:
  • Backup and recovery from outages and system failures
  • Investigation to confirm that the customer is not affected by suspected service issues
  • Remediation of technical issues, such as storage failure or data corruption
THIRD_PARTY_DATA_REQUEST Customer-initiated access by Google to respond to a legal request or legal process, including when responding to legal process from the customer that requires Google to access the customer's own content. Note that Access Transparency logs in this case may not be available if Google cannot legally inform the customer of such a request or process.
GOOGLE_INITIATED_REVIEW Google-initiated access for security, fraud, abuse, or compliance purposes, including:
  • Ensuring the safety and security of customer accounts and content
  • Confirming whether content is affected by an event that may impact account security (for example, malware infections)
  • Confirming whether customer is using Google services in compliance with Google Terms of Service
  • Investigating complaints by other users and customers, or other signals of abusive activity
  • Checking that Google services are being used consistently with relevant compliance standards (for example, anti-money laundering regulations)

Monitoring Access Transparency logs

You can monitor Access Transparency logs by using the Cloud Monitoring API. To get started, see the Cloud Monitoring documentation.

You can set up a logs-based metric and then set up an alerting policy to give you timely awareness of issues surfaced by these logs. For example, you can create a logs-based metric that captures Google personnel accesses of your content and then create an alerting policy in Monitoring that lets you know if the number of accesses in a given period exceeds a specified threshold.