Google Cloud Storage (GCS)

8 min

Google Cloud Storage (GCS)

Edition: Enterprise + Open Source

The Google Cloud Storage integration scans objects in GCS 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).

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.

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.

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:

{ "version": "1", "bindings": [ { "role": "roles/storage.objectViewer", "members": [ "user:<user_email>" ] }, { "role": "roles/storage.bucketViewer", "members": [ "user:<user_email>" ] } ] }

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	✅