Skip to main content
Configure Google Artifact Registry to use the Package Firewall URL as the upstream source for a remote repository instead of the public package registries. Every package installation request flows through Endor Labs, so the Package Firewall can block known malicious packages before they reach your environment. The Package Firewall evaluates each package request based on the malware check and the configured Package Firewall policy conditions, and handles each request in one of three ways:
  • Block the installation and Google Artifact Registry returns HTTP 403 if the package is found in the Endor Labs malware database, or if a policy condition matches with Block. The Package Firewall records a log with the package, version, and reason.
  • Allow the installation if a policy condition matches with Warn. The Package Firewall records a warning log with the package, version, and reason.
  • Allow the installation if the package passes all checks. No log is recorded.
Google Artifact Registry returns a generic HTTP 403 when it blocks a request without surfacing the specific reason. To see why a package was blocked, review the Package Firewall logs.

​
Required Google Cloud permissions

Ensure that you have the following roles in the Google Cloud project that hosts Artifact Registry: A project Owner or Editor role covers all of these.

​
Configure the Package Firewall

Complete the following steps to integrate Google Artifact Registry with the Endor Labs Package Firewall:
  1. Create an API key for the Package Firewall.
  2. Store the API secret in Secret Manager.
  3. Configure Google Artifact Registry.
  4. Set up local package managers.
  5. Verify your setup.

​
Create an API key for the Package Firewall

Create an API key dedicated to the Package Firewall so that can authenticate to it. You can create it through one of the following methods:
  • Using the Endor Labs user interface, with the Package Firewall User role. See API keys to learn more.
  • Using endorctl, with the SYSTEM_ROLE_PACKAGE_FIREWALL role. Make sure to install and configure endorctl before you create the key.
To create the key using endorctl, run the following command and replace:
  • <namespace> with your namespace.
  • <API key name> with the name of the API key for the Package Firewall use case.
  • <YYYY-MM-DDTHH:MM:SSZ> with the API key expiration in ISO 8601 UTC format, for example 2026-12-31T23:59:59Z.
export NAMESPACE="<namespace>"
export KEY_NAME="<API key name>"

endorctl api create -r APIKey -n "$NAMESPACE" --data '{
  "meta": { "name": "'"$KEY_NAME"'" },
  "spec": {
    "permissions": { "roles": ["SYSTEM_ROLE_PACKAGE_FIREWALL"] },
    "expiration_time": "<YYYY-MM-DDTHH:MM:SSZ>"
  },
  "propagate": true
}'
From the response, save the following values in a secure location.
  • API key: spec.key
  • API secret: spec.secret

​
Store the API secret in Secret Manager

Google Artifact Registry reads the upstream password from Secret Manager, so you must store your API secret there before you configure the remote repository.
  1. Sign in to the Google Cloud console and select your project.
  2. Search for and select Secret Manager API.
  3. Click Enable. If you see Manage instead, the API is already enabled.
  4. Search for and select Secret Manager.
  5. Create a secret with a name, such as endor-pkg-firewall-secret, and set the Secret value to your API secret. Refer to Google Cloud documentation to learn how to create a secret.

​
Configure Google Artifact Registry

Configure a remote repository in Google Artifact Registry for each package type you want to route through the Package Firewall. A remote repository proxies an upstream source, so you set the Package Firewall URL as the custom upstream. Provide your API key as the username and the Secret Manager secret as the password. The remaining repository settings, such as location and cleanup policies, are specific to Google Artifact Registry. Configure them based on your requirements.
Google Artifact Registry does not support custom upstream URL for Go remote repositories, so you cannot route Go modules through the Package Firewall with this integration. To route Go modules through the Package Firewall, use JFrog Artifactory or direct integration.
  1. In the Google Cloud console, go to Artifact Registry > Repositories.
  2. Click Create Repository.
  3. Enter a repository name, such as endor-npm-repository.
  4. Choose npm as the Format.
  5. Choose Custom in Remote repository source.
  6. Enter https://factory.endorlabs.com/v1/namespaces/<namespace>/firewall/npm as the custom repository URL. Replace <namespace> with your Endor Labs namespace.
  7. Choose Authenticated in Remote repository authentication mode.
  8. Enter your API key (spec.key) as the Username for the upstream repository.
  9. Under Store your credentials in Secret Manager, select the Secret you created.
  10. Under Location type, choose Region or Multi-Region and select a location. Refer to Repository locations for details.
  11. Click Create.
  1. In the Google Cloud console, go to Artifact Registry > Repositories.
  2. Click Create Repository.
  3. Enter a repository name, such as endor-pypi-repository.
  4. Choose Python as the Format.
  5. Choose Custom in Remote repository source.
  6. Enter https://factory.endorlabs.com/v1/namespaces/<namespace>/firewall/pypi as the custom repository URL. Replace <namespace> with your Endor Labs namespace.
  7. Choose Authenticated in Remote repository authentication mode.
  8. Enter your API key (spec.key) as the Username for the upstream repository.
  9. Under Store your credentials in Secret Manager, select the Secret you created.
  10. Under Location type, choose Region or Multi-Region and select a location. Refer to Repository locations for details.
  11. Click Create.
  1. In the Google Cloud console, go to Artifact Registry > Repositories.
  2. Click Create Repository.
  3. Enter a repository name, such as endor-maven-repository.
  4. Choose Maven as the Format.
  5. Choose Custom in Remote repository source.
  6. Enter https://factory.endorlabs.com/v1/namespaces/<namespace>/firewall/maven as the custom repository URL. Replace <namespace> with your Endor Labs namespace.
  7. Choose Authenticated in Remote repository authentication mode.
  8. Enter your API key (spec.key) as the Username for the upstream repository.
  9. Under Store your credentials in Secret Manager, select the Secret you created.
  10. Under Location type, choose Region or Multi-Region and select a location. Refer to Repository locations for details.
  11. Click Create.

​
Set up local package managers

Configure your local package managers to use the Google Artifact Registry repository as their source, and authenticate with your Google Cloud credentials. Refer to Google’s client setup documentation for npm, Python, and Maven.

​
Verify your setup

To verify your setup, install a package that Endor Labs has classified as malware. The Package Firewall should block the installation and return an HTTP 403. The following are examples of packages classified as malware by Endor Labs.
Run the following command to test the Package Firewall with npm.
npm install endor-firewall-test
When the Package Firewall blocks the package, the output looks similar to the following. The E403 error code and 403 Forbidden response confirm that the firewall blocked the package.
npm error code E403
npm error 403 403 Forbidden - GET https://us-central1-npm.pkg.dev/johndoe-project/johndoe-npm/endor-firewall-test/-/endor-firewall-test-1.0.0.tgz - 403 Forbidden error returned by the external repository... this typically means your upstream credentials are invalid; url="https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/npm/endor-firewall-test/-/endor-firewall-test-1.0.0.tgz"
npm error 403 In most cases, you or one of your dependencies are requesting
npm error 403 a package version that is forbidden by your security policy, or
npm error 403 on a server you do not have access to.
Run the following command to test the Package Firewall with PyPI.
pip install endor-firewall-test
When the Package Firewall blocks the package, the output looks similar to the following. The 403 response confirms that the firewall blocked the package.
Looking in indexes: https://pypi.org/simple, https://oauth2accesstoken:****@us-central1-python.pkg.dev/johndoe-project/johndoe-pypi/simple/
Collecting endor-firewall-test
ERROR: HTTP error 403 while getting https://us-central1-python.pkg.dev/johndoe-project/johndoe-pypi/endor-firewall-test/endor_firewall_test-1.0.0-py3-none-any.whl#sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 (from https://us-central1-python.pkg.dev/johndoe-project/johndoe-pypi/simple/endor-firewall-test/) (requires-python:>=3.7)

ERROR: Could not install requirement endor-firewall-test from https://us-central1-python.pkg.dev/johndoe-project/johndoe-pypi/endor-firewall-test/endor_firewall_test-1.0.0-py3-none-any.whl#sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 because of HTTP error 403 Client Error: Forbidden for url: https://us-central1-python.pkg.dev/johndoe-project/johndoe-pypi/endor-firewall-test/endor_firewall_test-1.0.0-py3-none-any.whl for URL https://us-central1-python.pkg.dev/johndoe-project/johndoe-pypi/endor-firewall-test/endor_firewall_test-1.0.0-py3-none-any.whl#sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 (from https://us-central1-python.pkg.dev/johndoe-project/johndoe-pypi/simple/endor-firewall-test/) (requires-python:>=3.7)
Add io.github.endorlabs:endor-java-webapp-demo:4.1 as a dependency in your pom.xml, then run the following command to test the Package Firewall with Maven.
mvn dependency:resolve -s settings.xml
When the Package Firewall blocks the package, the output looks similar to the following. The 403 Forbidden response confirms that the firewall blocked the package.
Downloading from endor-firewall-gar: https://us-central1-maven.pkg.dev/johndoe-project/johndoe-maven/io/github/endorlabs/endor-java-webapp-demo/4.1/endor-java-webapp-demo-4.1.pom
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal on project endor-firewall-maven-test: Could not resolve dependencies for project com.example:endor-firewall-maven-test:jar:1.0.0: Failed to collect dependencies at io.github.endorlabs:endor-java-webapp-demo:jar:4.1: Failed to read artifact descriptor for io.github.endorlabs:endor-java-webapp-demo:jar:4.1: Could not transfer artifact io.github.endorlabs:endor-java-webapp-demo:pom:4.1 from/to endor-firewall-gar (https://us-central1-maven.pkg.dev/johndoe-project/johndoe-maven): authorization failed for https://us-central1-maven.pkg.dev/johndoe-project/johndoe-maven/io/github/endorlabs/endor-java-webapp-demo/4.1/endor-java-webapp-demo-4.1.pom, status: 403 Forbidden -> [Help 1]
After you confirm that the Package Firewall blocks malware, you can view the recorded events. See View Package Firewall logs to learn more.

​
Troubleshooting and FAQ

Google Artifact Registry validates the upstream URL and credentials when you create a remote repository, and creates it only if the test passes. If it fails, check that the custom repository URL, upstream username, and Secret Manager secret are correct.To skip the check, select Disable upstream validation on the form.
If Endor Labs flags a package as malware after Google Artifact Registry cached it, Google Artifact Registry continues to serve it until the cache expires. Use a short cache duration to reduce that window.
  • Verify that the Package Firewall URL set as the custom upstream is correct.
  • Ensure network connectivity from Google Artifact Registry to the Package Firewall.
  • Ensure the firewall rules allow outbound connections from Google Artifact Registry.
  • Verify the API key and secret are correct and that the key has the Package Firewall User role.
  • Verify that the Secret Manager secret holds the API secret and that the repository can access it.
  • Set cache expiration to short durations so that more requests hit the Package Firewall.
  • Check the cache hit and miss rates. Clear the cache if you need to test with a fresh request.