Skip to main content

Namespace Confusion Protection

Namespace Confusion (also known as Dependency Confusion) is a Software Supply Chain Attack where malicious packages are installed using weaknesses common in dependency management practices. Repository Firewall offers protection from dependency confusion with features targeting different types of attacks.

What are Namespace Confusion attacks?

When downloading dependencies from your repository manager, it is common to use a group or virtual repository that includes a mix of internal and external repositories. This is easier to do during the build process instead of having to switch between multiple repositories when the required components are located in different sources.

A Namespace Confusion attack is a software supply chain attack that attempts to trick a package manager into downloading a malicious component instead of a proprietary one. Bad actors upload components with the same name as proprietary components to an ecosystem in hopes that either a specific target or a random target will mistakenly download the malicious component.

A common practice with Javascript and Python development teams is to request the latest version of the component that is available. When requesting internal proprietary components, the default repository manager configuration will search both internal repositories as well as remote repositories for the highest version of the component to use. This opens the supply chain to significant external risk. Bad actors publish higher versions in the public repository so that their malicious package is selected instead of the correct one. Repository Firewall's Namespace Confusion Protection is designed to protect you from threats like this.

Types of Namespace Confusion Attacks

Here are some common dependency confusion-type attacks:

  • Namespace Confusion
    • Attackers upload packages with the same name as internal packages to a public package repository, often with a higher version than has been published to this point.

    • The goal is to trick package managers into pulling the highest version from the public repository instead of the internal repository

    • This attack takes advantage of the common practice of using version ranges instead of pinned versions in the project manifest.

  • Package Import Confusion
    • Sometimes packages are imported into a software project with a different name than the public package.

    • When a developer unknowingly or accidentally installs a package using the import name instead of the actual package name, they may download a malicious package instead.

    • An example of a package with a different name than the import name is the PyPI package beautifulsoup4, which is imported as bs4.

  • Typosquatting
    • In this attack, a malicious package is uploaded to a public repository with a similar name to a popular package.

    • If a developer makes a typo when attempting to install the popular package, the malicious package is downloaded instead.

Preventing Namespace Confusion

Repository Firewall prevents namespace confusion attacks by building a list of internal namespaces for your proprietary or internal components. The list of namespaces is generated from the hosted repositories you select that contain your proprietary components. The namespaces (the component name or Group ID) are added to a global list in IQ Server. This list is used to block components from being downloaded from external proxy repositories protected by Firewall.

  1. Select hosted repositories are used to generate the proprietary namespaces

    1. using the Guided Setup repository configuration

    2. using the manual repository configuration

  2. The policy, Security-Namespace Conflict, is set to fail at the proxy stage

  3. Firewall audit and quarantine is configured on external proxy repositories

  4. All public instances of a component with the same namespace will be quarantined

We recommend that you move all open-source or third-party components into a separate repository from your proprietary components before enabling this feature. This includes patched and rebuilt versions of public open-source components.

Repository Firewall will include the namespace of those open-source components when mapping your proprietary namespace. When this happens, all versions of those open-source components will be blocked from download through the public proxy.


If you are unsure if your hosted repository contains public open-source components, do not enable this feature.

See the Removing Namespaces section for details.


  • Have the policy, Security-Namespace Conflict configured in the IQ Server

    • Have the policy action set to Fail at the proxy stage

  • Repository managers connected to IQ Server:

    • Nexus Repository 3.30 or greater

    • JFrog Artifactory version 2.4.4 or greater

      • Repository Firewall for JFrog Artifactory plugin and license

Configuring Namespace Confusion Protection

The first time you configure the Repository Firewall in your repository manager will trigger the Guide Setup process. This is the easiest way to select the hosted repositories to use with Namespace confusion protection.

Components quarantined to prevent namespace confusion can be viewed and released like any other quarantined component.

See Managing the Quarantine for more information.


To reduce overhead, the repository manager updates Firewall with proprietary names to protect are by way of a scheduled task that runs by default every 2 hours.

Ensure that enough time has past before attempting to test Namespace Confusion Protection.

Determining Namespaces depending on the repository format:

  • Default behavior

    1. Uses the namespace (e.g., a Maven group, npm scope)

    2. If no namespace is available, then Firewall uses the name of the component (e.g., Maven artifact, name for npm)

  • For Apt, Conda, R, Conan, RubyGems (New in 3.68.0), and PyPI (New in 3.68.0) - the namespace is determined by the component's name.

Configure Nexus Repository 3

To protect a repository from dependency/namespace confusion in Nexus Repository 3:

  1. Navigate to Nexus Repository 3 and sign in

  2. Select gear from the navigation bar to go to the administration menu

  3. Select Repositories from the sidebar.

  4. Select the hosted repository with your proprietary components

  5. Select the checkbox under Proprietary Components

  6. Select Save

Configure jFrog Artifactory

To protect a repository from dependency/namespace confusion in jFrog Artifactory:

  1. Configure the local repository in the file as proprietary

  2. See JFrog Artifactory setup for more information

Manually Configuring Namespaces

You can manually configure the namespace confusion protection for individual component namespaces in the IQ Server.

To configure, follow the instructions below.

  1. Log into IQ Server with a user that has the Edit IQ Elementspermission.

  2. Click on the Orgs and Policies in the leftmost navigation bar and click Repositories.

  3. Scroll down the Repositories page to view the Namespace Confusion Protection section.

    1. see the Namespace Confusion Protectionsection in Repository Management

  4. Namespace confusion protection configuration can be enabled or disabled using the toggle under the Enabled column.

    1. If a component namespace is disabled, then it will not be used for Namespace Confusion Protection

Removing Namespaces

Component namespaces can be removed from the namespace confusion list. Removing a component from this list will allow you to download public versions of the removed component. This is useful if you uploaded a 3rd party component to a protected repository.

To remove a component from the Namespace Confusion List:

  1. Disable proprietary components for the repository. This prevents the component from being re-added to the list.

  2. Obtain the node-id of the repository instance. On a jFrog Artifactory instance the node-id can be found in the property in the file. To find the node-id of a Nexus Repository 3 instance:

    1. Log in to the Nexus Repository 3 UI as an administrator

    2. Select the Administration tab

    3. Select System Information on the sidebar under Support

    4. Record the node-Id

  3. Obtain your repository Id, e.g npm-hosted

  4. Delete the component using the DELETE REST API route.

    1. Send the request at /repositories/{repositoryManageNodeId}/{repositoryId}/proprietary/names. Successful requests return the HTTP 204 response.


      curl -u username:password -v -X DELETE http://localhost:8070/rest/integration/repositories/3EFF78A1-5F819609-7BC13C89-B90B90DF-DEF32AD1/maven-releases/proprietary/names
  5. Re-enable proprietary repository protection