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.
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).
Enabling Access Transparency
For information about enabling Access Transparency for your Google Cloud organization, see Enabling Access Transparency.
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 Observability logging filter.
logName="projects/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 Run 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" } principalJobTitle: "Engineering" product: [ 0: "Cloud Storage" ] reason: [ detail: "Case number: bar123" type: "CUSTOMER_INITIATED_SUPPORT" ] eventId: "asdfg12345asdfg12345asdfg12345" accesses: [ 0: { methodName: "GoogleInternal.Read" resourceName: "//googleapis.com/storage/buckets/BUCKET_NAME/objects/foo123" } ] accessApprovals: [ 0: "projects/123/approvalRequests/abcdef12345" ] } logName: "projects/PROJECT_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. |
principalJobTitle |
The job family of the Google personnel making the access. |
product |
Customer's Google Cloud 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 ). |
eventId |
Unique event ID associated with a single access event justification
(for example, a single support case). All accesses logged to the same
justification have the same event_id value. |
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
, andDelete
. 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
, andUndelete
. For more information, see Custom methods. - GoogleInternal methods: The following
GoogleInternal
methods can appear in theaccesses: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. |
|
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. |
|
GoogleInternal.Delete |
Signifies 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. |
|
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. |
|
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. | Emergency access to recover from an outage on Compute Engine or Google Distributed Cloud. |
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. |
|
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. |
|
The GoogleInternal
accesses are strictly restricted to authorized personnel for justified and auditable access. The presence of a method doesn't indicate availability to all roles. Organizations seeking enhanced controls over administrative access on a project or organization can activate Access Approval to enable approval or denial of accesses based on access details. For example, Access Approval users can choose to permit only requests with the CUSTOMER_INITIATED_SUPPORT
justification for requests made by a Google employee with the Customer Support
role. For more information, see Overview of Access Approval.
If an event meets strict emergency access criteria, Access Approval can log that emergency access with the auto approved
status. Access Transparency and Access Approval are specifically designed to include uninterrupted logging for emergency access scenarios.
If you are looking for more data security control over your workloads, we recommend using Assured Workloads. Assured Workloads projects offer enhanced functionalities such as, data residency, sovereign controls, and access to features such as confidential computing in Compute Engine. It leverages Key Access Justifications for externally-managed encryption keys.
Justification reason codes
Reason | Description |
CUSTOMER_INITIATED_SUPPORT
|
Customer-initiated support, for example, "Case Number: ####". |
GOOGLE_INITIATED_SERVICE
|
Refers to Google-initiated access for system management and troubleshooting. Google personnel can make this type of access for the following reasons:
|
THIRD_PARTY_DATA_REQUEST
|
Google-initiated access in response 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 data. |
GOOGLE_INITIATED_REVIEW
|
Google-initiated access for security, fraud, abuse, or compliance
purposes, including:
|
GOOGLE_RESPONSE_TO_PRODUCTION_ALERT
|
Refers to Google-initiated access to maintain system reliability. Google personnel can make this type of access for the following reasons:
|
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.