--- title: Google Cloud Storage (GCS) slug: docs/google-cloud-storage-gcs description: Learn how to integrate Google Cloud Storage (GCS) with TruffleHog using IAM credentials or a service account file. This document provides step-by-step instructions, code examples, and configuration options for scanning buckets and objects in GCS. icon: {"faIcon":"fa-brands fa-google"} docTags: createdAt: 2024-04-17T16:33:58.352Z --- # Google Cloud Storage (GCS) :::BlockQuote **Edition:** Enterprise + Open Source ::: The Google Cloud Storage integration scans objects in [GCS](https://cloud.google.com/storage) buckets for credentials and other sensitive data. ## Configuration The GCS integration can be configured in TruffleHog under **Integrations**, or via a local configuration file (below). ### Web configuration Configure this integration from the **Integrations** page in TruffleHog. You'll need credentials for an identity with read access to the GCP project and buckets you want to scan. ### Local configuration Local configuration supports three authentication modes: - **IAM credentials (recommended)** — uses Application Default Credentials (ADC) from the standard GCP credential chain. - **Service account file** — uses a service account JSON key file on disk. - **Unauthenticated** — for public buckets that don't require authentication. The projectId field is required for all authenticated modes. Buckets the credentials can list and access are scanned automatically. To restrict the scan, use includeBuckets to specify a list, or excludeBuckets to skip specific ones. The same applies to objects via includeObjects and excludeObjects. If both include and exclude filters are specified for the same scope, the include filter takes precedence — it's recommended to use only one or the other. **IAM credentials** Use this when GCP credentials are available via Application Default Credentials (environment variables, gcloud auth, or workload identity). :::BlockQuote sources: \- connection: "@type": type.googleapis.com/sources.GCS adc: \{} projectId: my-project includeBuckets: \- bucket1 \- bucket2 excludeBuckets: \- bucket3 includeObjects: \- object1 \- object2 excludeObjects: \- object3 name: GCS scanPeriod: 12h type: SOURCE\_TYPE\_GCS verify: true ::: **Service account file** Use this when authenticating with a service account JSON key stored on the scanner host. :::BlockQuote sources: \- connection: "@type": type.googleapis.com/sources.GCS serviceAccountFile: /path/to/service-account.json projectId: my-project includeBuckets: \- bucket1 \- bucket2 excludeBuckets: \- bucket3 includeObjects: \- object1 \- object2 excludeObjects: \- object3 name: GCS scanPeriod: 12h type: SOURCE\_TYPE\_GCS verify: true ::: **Unauthenticated** Use this for public buckets only. Since enumeration requires authentication, includeBuckets is required in this mode. :::BlockQuote sources: \- connection: "@type": type.googleapis.com/sources.GCS unauthenticated: \{} includeBuckets: \- bucket1 \- bucket2 includeObjects: \- object1 \- object2 excludeObjects: \- object3 name: GCS scanPeriod: 12h type: SOURCE\_TYPE\_GCS verify: true ::: **Example IAM policy** The identity used to access GCS needs the following roles, attached either directly (for IAM credentials) or to the service account being used: :::BlockQuote \{ "version": "1", "bindings": \[ \{ "role": "roles/storage.objectViewer", "members": \[ "user:\" ] }, \{ "role": "roles/storage.bucketViewer", "members": \[ "user:\" ] } ] } ::: The storage.bucketViewer role allows listing buckets in the project. The storage.objectViewer role allows reading object contents within those buckets. ## Configuration options | Field | Type | Required | Description | | ------------------ | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------ | | projectId | string | Conditional | The GCP Project ID. Required for IAM credentials and service account modes. | | adc | object | Conditional | Empty object indicating credentials should be sourced from Application Default Credentials. Required for IAM credentials mode. | | serviceAccountFile | string | Conditional | Path to a service account JSON key file. Required for service account mode. | | unauthenticated | object | Conditional | Empty object indicating no authentication. Required for unauthenticated mode. | | includeBuckets | list | No | Explicit list of buckets to scan. Omit to scan all buckets the credentials can list. Required in unauthenticated mode. | | excludeBuckets | list | No | Buckets to skip during scanning. | | includeObjects | list | No | Objects to include. Supports glob patterns (\*). | | excludeObjects | list | No | Objects to skip during scanning. Supports glob patterns (\*). | | maxObjectSize | integer | No | Maximum object size in bytes. Objects larger than this are skipped. | ## Capabilities | Feature | Supported | | ------------------------------- | --------- | | Scan GCS objects | ✅ | | Scan archive files | ✅ | | Scan base64-encoded data | ✅ | | Scan binaries | ✅ | | Scan Microsoft Office documents | ✅ | | Include / exclude filters | ✅ | | Auto-resume | ✅ |