Google Artifact Registry

13 min

Edition: Enterprise and Open source

You can scan Google Artifact Registery (GAR) using our Docker integration. The recommended setup is to run the Enterprise scanner on a GCP host with an attached IAM role for GAR access. Keeping docker login and the scan on the same host is the simplest, most reliable configuration.

Important

Note: GCP access tokens expire after about 60 minutes.

For long scanPeriod intervals, use Docker keychain authentication or refresh the token before it expires via a cron job.

Image references

GAR images use this format:

LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

Example:

us-central1-docker.pkg.dev/my-project/my-repo/api-server:v1.2.0

Walkthrough

1. Create the scanner in the dashboard and download the config.yml to your host.

2. Create a GCP service account and attach the pre-defined policy artifactregistry.reader.

3. Authenticate to GAR.

gcloud auth configure-docker <your-region>.docker.pkg.dev

4. Confirm you have the correct docker container repo address

us-central1-docker.pkg.dev/my-project/my-repo/api-server:v1.2.0

Example

gcloud auth --configure-docker us-central1-docker.pkg.dev

Note: This stores the credential in ~/.docker/config.json of the user who ran it (e.g. /root/.docker/config.json or /home/ec2-user/.docker/config.json), base64-encoded.

5. Add the Docker source to config.yml

Configuration

The Docker integration is configured via a local configuration file. Web configuration in TruffleHog is not available for this source.

Local configuration

Local configuration supports four authentication methods:

Unauthenticated — for public images that don't require authentication.

Docker keychain — uses credentials from your local Docker login (gcloud auth configure-docker).

Basic authentication — uses oauth2accesstoken as the username and a GCP access token as the password.

Bearer token — uses a GCP OAuth access token.

Images can be specified with or without a tag. If no tag is provided, latest is assumed.

Unauthenticated

Use this for public images that don't require registry authentication.

sources: - connection: "@type": type.googleapis.com/sources.Docker images: - us-docker.pkg.dev/public-project/public-repo/public-image:latest unauthenticated: {} name: Google Artifact Registry scanPeriod: 12h type: SOURCE_TYPE_DOCKER verify: true

Docker keychain

Use this when you've already authenticated to Artifact Registry locally. Configure the gcloud credential helper, then TruffleHog reads credentials from your Docker keychain.

gcloud auth login gcloud auth configure-docker us-central1-docker.pkg.dev,us-docker.pkg.dev

sources: - connection: "@type": type.googleapis.com/sources.Docker dockerKeychain: true images: - us-central1-docker.pkg.dev/my-project/my-repo/api-server:latest - us-central1-docker.pkg.dev/my-project/my-repo/worker:v2.1.0 name: Google Artifact Registry scanPeriod: 12h type: SOURCE_TYPE_DOCKER verify: true

Basic authentication

Use this for registries where you supply username and password credentials. For GAR, the username is always oauth2accesstoken and the password is a GCP access token.

Generate a token:

gcloud auth print-access-token

sources: - connection: "@type": type.googleapis.com/sources.Docker basicAuth: username: oauth2accesstoken password: ya29.XXXXXXXXXXXXXXXXXXXXXXXX images: - us-central1-docker.pkg.dev/my-project/my-repo/api-server:latest name: Google Artifact Registry scanPeriod: 12h type: SOURCE_TYPE_DOCKER verify: true

Bearer token

Use this for registries that accept bearer tokens. Pass a GCP OAuth access token from gcloud auth print-access-token.

sources: - connection: "@type": type.googleapis.com/sources.Docker bearerToken: ya29.XXXXXXXXXXXXXXXXXXXXXXXX images: - us-central1-docker.pkg.dev/my-project/my-repo/api-server:latest name: Google Artifact Registry scanPeriod: 12h type: SOURCE_TYPE_DOCKER verify: true

Note: GCP access tokens expire after about 60 minutes. For long scanPeriod intervals, use Docker keychain authentication or refresh the token before it expires via a cron job.

Configuration options

Field	Type	Required	Description
images	list	Yes	Explicit list of GAR images to scan. Images without a tag default to latest.
unauthenticated	object	Conditional	Empty object indicating no authentication. Required for unauthenticated mode.
dockerKeychain	boolean	Conditional	Use credentials from the local Docker keychain. Required for keychain mode.
basicAuth.username	string	Conditional	Registry username. Use oauth2accesstoken for GAR.
basicAuth.password	string	Conditional	GCP OAuth access token. Required for basic auth mode.
bearerToken	string	Conditional	GCP OAuth access token. Required for bearer token mode.

Capabilities

Feature	Supported
Scan archive files	✅
Scan base64-encoded data	✅
Scan binaries	✅

Notes

Images must be listed explicitly in the images field. Image enumeration (e.g., scanning all images in a project or repository) is not supported.

Only images built for the linux/amd64 platform are scanned. Images built for other architectures (such as linux/arm64 or windows/amd64) are not supported.

GAR hostnames are region-specific. Each image reference must include the correct LOCATION-docker.pkg.dev prefix.

The scanning principal needs roles/artifactregistry.reader (or equivalent repository-level read access) to pull images.

Legacy Google Container Registry (gcr.io) images can also be scanned with the same configuration. Authenticate with gcloud auth configure-docker gcr.io.

Docker

Configure authentication to Artifact Registry for Docker

Repository and image names