Google Artifact Registry
Connect Google Artifact Registry (and public gcr.io images) to Safeguard. The IAM role the service account needs, which credentials work, and step-by-step setup.
What it does
This card (named GCP Cloud Source in the app) connects Safeguard to Docker images in Google Artifact Registry (<region>-docker.pkg.dev), and to public images on Container Registry hosts (gcr.io). Safeguard lists the repositories and tags, and each image you select becomes a project that Safeguard scans for an SBOM and vulnerability findings. It does not connect Cloud Source Repositories (source code). Find the card under Integrations on the Project/Product tab.
Public vs private
| Public | Private | |
|---|---|---|
| What you enter | An image or repository URL, such as us-docker.pkg.dev/<project>/<repository>/<image> or gcr.io/<project>/<image> | Project Name, Project ID, Region and a Service Account JSON key |
| Credential needed | None. The repository must allow public reads (allUsers with Artifact Registry Reader) | A service account key with read access |
| What you can select | The public images you add by URL | The Docker repositories and images in that project and region |
Private image scans
Safeguard uses the service account to list your repositories and tags. The scan's image pull does not use this key yet, so a private image the scanner cannot pull is reported as a failed scan with the registry's error.
Supported auth methods
| Method | Use it when | Notes |
|---|---|---|
| Service account key (JSON) | Private repositories | Sent to the registry as the _json_key user over HTTPS, and exchanged for a short-lived OAuth access token to list repositories |
| None | Public images | Anonymous read |
Workload Identity Federation and short-lived access tokens are not available yet.
Permissions required
Safeguard only reads. It never pushes, deletes or tags artifacts, and never changes repositories or IAM.
Service account key
| IAM role | Required? | What Safeguard uses it for |
|---|---|---|
Artifact Registry Reader (roles/artifactregistry.reader) | Required | Checking the key against https://<region>-docker.pkg.dev/v2/, listing repositories (artifactregistry.googleapis.com/v1/projects/<project>/locations/<region>/repositories), listing tags (/v2/<project>/<repository>/<image>/tags/list) and reading images |
The access token Safeguard requests uses Google's standard https://www.googleapis.com/auth/cloud-platform OAuth scope; what the token can do is limited by the service account's IAM roles, so keep the role read-only.
Least privilege: grant Artifact Registry Reader on the specific repositories to scan (repository-level IAM) rather than on the whole project.
Token types
| Credential type | Works? | Notes |
|---|---|---|
Service account key (JSON, "type": "service_account") with Artifact Registry Reader | Yes (recommended) | Create a dedicated service account for Safeguard |
| Service account with Artifact Registry Writer, Administrator, Editor or Owner | Works, not recommended | Safeguard never writes |
| User credentials, OAuth client JSON or an access token | No | The form accepts only a service account key file |
Base64-encoded key (_json_key_base64) | No | Upload the JSON file as Google provides it |
| Workload Identity Federation | Not available yet |
Expiry: service account keys do not expire unless your organization sets a key expiry policy. Rotate the key at least every 90 days. Google recommends avoiding long-lived keys where you can; delete the key when you disconnect.
What we never need: write, delete or admin roles on Artifact Registry, any role outside Artifact Registry, or project-level Owner or Editor.
Step-by-step setup
Create the credential in Google Cloud
- In the Google Cloud console, open IAM & Admin > Service Accounts and choose Create service account (for example
safeguard-ar-read). - Grant it Artifact Registry Reader, on the project or on each repository (Artifact Registry > Repositories > your repository > Permissions).
- Open the service account, choose Keys > Add key > Create new key, pick JSON and download the file. Google does not let you download it again.
Or with the gcloud CLI
gcloud iam service-accounts create safeguard-ar-read --project <project-id>
gcloud artifacts repositories add-iam-policy-binding <repository> \
--location <region> --project <project-id> \
--member "serviceAccount:safeguard-ar-read@<project-id>.iam.gserviceaccount.com" \
--role roles/artifactregistry.reader
gcloud iam service-accounts keys create key.json \
--iam-account safeguard-ar-read@<project-id>.iam.gserviceaccount.com
# Check it:
cat key.json | docker login -u _json_key --password-stdin https://<region>-docker.pkg.devConnect it in Safeguard
- Open Integrations and choose the Project/Product tab.
- Click Connect on the GCP Cloud Source card.
- For public images, choose Public, paste a repository URL and click Add, then Next.
- For private repositories, choose Private and fill in Project Name, Project ID and Region, then drop the key file on Service Account JSON. "Service account JSON uploaded successfully" means the file is a valid key.
- Click Next, select the images and tags, review, and choose a connect option (fast, progressive or deep scan).
Webhooks and triggers
This integration has no webhooks. Each selected image is scanned when you connect it; to rescan new tags, set a schedule under Integrations > Scheduled or rescan by hand from the project.
What we read and store
- Read: repository names, image names and tags in the project and region you choose, and the images you select for scanning.
- Stored: the connection's settings, the SBOM and findings of each scanned image, and the service account key, which is encrypted at rest and never shown again after you save it.
- Not stored: image layers. The image is read for the scan and not kept.
- No customer data from this integration is sent to third-party LLMs.
Troubleshooting
| Message you see | Cause | Fix |
|---|---|---|
Invalid service account type. Expected "service_account" | The file is not a service account key (for example an OAuth client file) | Create a JSON key for a service account |
Invalid JSON format / Please upload a JSON file | The file is not the JSON key | Upload the .json file Google gave you |
Service account JSON must contain project_id / Service account JSON must contain private_key | The key file was edited or truncated | Download a new key |
Invalid credentials - check your service account permissions | Google rejected the key (deleted or disabled) | Create a new key, or enable the service account |
Insufficient permissions. Grant 'Artifact Registry Reader' role to the service account. | The service account has no read role | Grant roles/artifactregistry.reader |
This repository is private and requires authentication. Use service account credentials for private repositories. | A private repository was added on the Public tab | Use the Private tab |
Invalid Artifact Registry URL. Must include region, project, and repository: {region}-docker.pkg.dev/{project}/{repository} | The URL is incomplete | Copy the repository path from the Artifact Registry console |
Rotation and disconnect
- Rotate: create a new key, find the connection under Project Configurations on the Project/Product tab, choose Update, upload the new key and save, then delete the old key under Keys in the console.
- Disconnect: choose Delete from the connection's menu under Project Configurations and confirm Delete configuration, then delete the key or the whole service account.
Vendor references
- Artifact Registry: access control with IAM, checked 2026-10-16.
- Artifact Registry: configure authentication to Docker repositories, checked 2026-10-16.
Apptainer / Singularity (SIF)
Scan Apptainer and Singularity images (SIF) from a library service or an OCI registry, or on an HPC host with the Safeguard CLI. Signatures checked, the access each source needs, and step-by-step setup.
IAST agents
Install the Safeguard IAST agent in your Java, Node.js or Python application. What it reports, the agent token it needs, configuration, overhead and uninstall.