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. The user must have minimum permissions of Custom URL Management and Override Existing URLs. Additional settings need to be manually set on in Zscaler.

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

    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 User-Defined URL categories added by the 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

    Important

    Zscaler has a limit of 25,000 URLs per category. When a malicious URL category list exceeds this limit, new categories are created dynamically to accommodate a growing list of malicious URLs. You must manually enable SSL inspection for every new category that appears.

    • If a new category (for example, sonatype-npm-3-shadow-download-defense) is created to hold additional URLs, add it to the URL Category to enable SSL inspection.

    • Until SSL inspection is enabled for the new category, enforcement for URLs placed in that category can be inconsistent.

    • Sonatype recommends checking for new categories everyday. The new categories can be found unselected under the URL Categories.

      Edit_SSL_Inspection_URL_Categories.png

    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 limits on custom URLs for performance, scalability, and manageability of its security service. These limits ensure the platform can efficiently process vast amounts of internet traffic for all its 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.

The default limit for the total custom URLs/TLDs is 25K. Contact your Zscaler Account team to subscribe to up to an additional 50K custom URLs/TLDs.

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 the current limit.

    • Zscaler Custom URL Limit Exceeded → The limit is reached and there are more malicious urls to push.

Per Category Limit

In addition to the overall custom-URL limit, Zscaler enforces a fixed 25,000 URLs per URL category, and this cannot be increased. When a malicious-URL list for an ecosystem exceeds 25,000, Sonatype dynamically creates additional Zscaler categories (for example, sonatype-npm-3-shadow-download-defense) and integrates them with your tenant. Monitor for newly created categories and add each one to your SSL inspection rule.

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.