Skip to main content

Integrate Firewall with Zscaler

Zscaler is a cloud-native cybersecurity platform to securely connect users, devices, and applications, regardless of their location. Think of it as a security checkpoint in the cloud that all your organization's traffic can pass through for inspection and protection.

Sonatype's Repository Firewall integrates with Zscaler to block actively verified malware components from being directly downloaded from public repositories. This integration protects your organization from malware found in the shadow downloads of users bypassing your Nexus Repository.

See Shadow Downloads Best Practices

Requirements

The configuration for blocking malware is automatic once the Repository Firewall and Zscaler integration is configured.

This integration must be configured by an IQ Server Administrator user. From IQ version 201+, the Zscaler user must have minimum permissions of Custom URL Management and Override Existing URLs. IQ versions 195 - 200 require that you complete setup with a Zscaler account that has the Super Admin role.

Note

The Zscaler integration is not supported with Firewall Pro.

To complete the setup, take the following steps:

  1. Set the URL filtering policy

    A policy must be manually added to block the verified malware components managed by the integration. Add a new URL filtering policy under the Policy → Web → URL and Cloud App Control menu.

    1. Action: BLOCK

    2. Groups: Credentials using the client connector

    3. Request Methods: Accept all applicable HTTP request methods

    4. URL Categories: The URL categories that must be blocked are added automatically by integration. The URL categories may appear in the below format.

      For IQ versions before 198

      sonatype-maven-shadow-download-defense
sonatype-npm-shadow-download-defense
sonatype-pypi-shadow-download-defense
sonatype-nuget-shadow-download-defense

      For IQ version 198 and later

      sonatype-maven-0-shadow-download-defense
sonatype-npm-2-shadow-download-defense
sonatype-pypi-1-shadow-download-defense
sonatype-nuget-3-shadow-download-defense

    Note

    Note that Zscaler does have a limit of up to 25,000 custom URLs or IP addresses (across all policies that use custom URLs or IP addresses), and up to 64 custom categories.

    See Configuring URL Filtering Policy

    fw-zscaler-url-filtering-policy.png
  2. Enable SSL inspection on traffic

    A policy must be manually added to inspect SSL traffic coming from the client connectors to see the actual requested paths of the malware components.

    Add a new URL filtering policies under the Policy → Web → SSL Inspection menu.

    fw-zscaler-ssl-inspection-policy.png

    1. Action: INSPECT

    2. Groups: Credentials using the client connector

    3. Request Methods: Accept all applicable HTTP request methods

    4. Destination Groups: Including the qualified domain names of your target format registries.

      maven2-registries: repo1.maven.org, repo.maven.apache.org
npm-registries: registry.npmjs.org
pypi-registries: pypi.org
nuget-registries: nuget.org

    5. URL Categories: Include the custom URL categories added by the integration. The URL categories may appear in the below format.

      Note

      Note that Zscaler does have a limit of up to 25,000 custom URLs or IP addresses (across all policies that use custom URLs or IP addresses), and up to 64 custom categories.

      For IQ versions before 198

      sonatype-maven-shadow-download-defense
sonatype-npm-shadow-download-defense
sonatype-pypi-shadow-download-defense
sonatype-nuget-shadow-download-defense

      For IQ version 198 and later

      sonatype-maven-0-shadow-download-defense
sonatype-npm-2-shadow-download-defense
sonatype-pypi-1-shadow-download-defense
sonatype-nuget-3-shadow-download-defense

    Important

    You must manually enable SSL inspection for any new category that a user might create.

    You can see which categories have SSL enabled or disabled by opening the Edit SSL Inspection Rule modal and inspecting the list of User-Defined section of the URL Categories list.

    Edit_SSL_Inspection_URL_Categories.png

    Those with the checkbox selected have SSL inspection enabled; those without a selected checkbox do not have SSL inspection enabled.

    Sonatype recommends checking routinely for new user-defined categories in order to enable SSL inspection on these categories.

    For more details, see About SSL Inspection

  3. Install Zscaler certificates on your developers' machines.

    See Adding Root Certificates

    fw-zscaler-intermediate-ca-certificate.png

Configuration

An administrator account is required to configure the Zscaler integration. The settings are found in the settings menu for Repository Firewall.

See Getting Started Zia API

fw-zscaler-configuration.png

Credentials

Provide your Zscaler administrator account credentials.

Hostname

The hostname is the URL for your zscaler deployment.

API Keys

Generating a Zscaler API Key involves accessing the API Management section within the specific Zscaler Admin Portal you are using. The exact navigation path and some options might differ slightly depending on the Zscaler product. Consult the Zscaler Help Portal for the specific product you are using.

See Zscaler Help Portal

Configured Formats

Set the formats to be covered with Zscaler. Included formats use more available Zscaler custom URLs.

fw-zscaler-configuration-formats.png

Trigger an Update to Zscaler

There is up to a 24-hour delay when configuring ZScaler before data is sent to the service. You may trigger the service to update immediately using the API.

fw-zscaler-api-update.png
POST /api/v2/config/zscaler/update

Zscaler Custom URLs

The Zscaler integration uses custom URLs to restrict access to the active verified malware components covered by your configured formats. These are added as User Defined categories under the Zia Administrator → Resources → URL Categories with the following naming:

For IQ versions before 198

sonatype-{format}-shadow-download-defense

For IQ version 198 and later

sonatype-{format}-{index}-shadow-download-defense

Zscaler has a limit of 25,000 custom URLs or IP addresses (across all policies that use custom URLs or IP addresses) for performance, scalability, and manageability of its security service. This limit ensures that the platform can efficiently process vast amounts of internet traffic for all users without degradation. When Zscaler does not have enough available custom URLs to catalog the known malware for a specific ecosystem, you are not fully protected.

See Zscaler Documentation

fw-zscaler-customer-url-limits.png
  • Total Purchased

    The number of custom URLs allowed with your subscription.

  • Remaining

    The number of custom URLs remaining.

  • Status

    The status of the Repository Firewall integration.

    • Not Configured → The integration has not yet been configured and verified.

    • OSS Malware Catalog Synced → Zscaler is configured and malicious urls are under your subscription limit.

    • Zscaler Custom URL Limit Exceeded → You've reached the custom URL limit, and there are still more malicious urls to push.

Usage Notes

  • The Zscaler integration is supported for the following formats for automatic Malware detection:

    maven, npm, PyPi, nuget

  • Repository Firewall create custom User Define URL categories by component format. These endpoints are updated once daily.

  • Sonatype recommends IQ Server 198 or later for reliable operation of Zscaler integration. Earlier versions may fail to populate certain URL categories (such as npm) when the Zscaler tenant supports URL limits higher than the default.