Namespace Confusion Protection in Firewall Enterprise
Namespace confusion occurs when a public component uses the same namespace as one of your organization’s proprietary components. A package manager might then select the public component instead of the internal component.
Firewall Enterprise helps prevent this by letting you register the namespaces your organization owns. When a matching public component is fetched through a Policy Gateway proxy repository, the Security-Namespace Conflict policy can quarantine the component and refuse the request.
How Namespace Confusion Protection Works
To enable protection:
Register your organization’s namespaces with the Namespace Confusion API.
Confirm that the Security-Namespace Conflict policy from the reference policy set has a Fail action at the Proxy stage. The reference policy set uses this configuration by default.
Route public component requests through Policy Gateway proxy repositories for the formats you want to protect.
IQ maintains a separate namespace list for each format. Each list applies to every proxy repository in that format across all Policy Gateways, including Policy Gateways added later. A namespace you add or remove applies to the next request Firewall Enterprise handles. You do not need to wait for a scheduled task.
Namespace registration does not create or change policies. Without an applicable policy, Firewall Enterprise allows components. See Configure Policies for information about setting the policy action.
Important Considerations
A registered namespace can match public open-source components. If you register one, matching public components are affected too.
If your organization publishes components with a registered namespace to a public registry, those components are also refused through Policy Gateway proxy repositories. Serve them from your hosted repository, or waive the Security-Namespace Conflict violation and re-evaluate the component.
If you are unsure whether a namespace is also used by public components, do not register it.
Namespace Confusion Protection does not inspect components uploaded to hosted repositories; it applies to Policy Gateway proxy repositories. Protection does also apply when a group repository routes a request to a Policy Gateway proxy repository.
Namespaces registered for Firewall Enterprise are separate from proprietary component settings in other Sonatype products. The settings do not affect one another.
Prerequisites
Before you configure Namespace Confusion Protection, make sure you have:
A Firewall Enterprise license. Without this license, Namespace Confusion API requests return HTTP 402.
A Security-Namespace Conflict policy set to Fail at the Proxy stage.
A Policy Gateway with proxy repositories for each format you want to protect: Maven, npm, PyPI, or NuGet.
Repository managers configured to request public components through those Policy Gateway proxy repositories.
Adding and removing namespaces requires the Evaluate Individual Components permission on the Policy Gateways container. Listing namespaces requires the View IQ Elements permission on that container.
Determine Which Namespaces to Register
A namespace is determined by the repository format. The following table describes what to register and how matching works.
Format | What to Register | Matching |
|---|---|---|
Maven | A group ID, such as | Case-sensitive. |
npm | A scope, such as | Case-sensitive. A scope matches every package in that scope. A package name matches only unscoped packages. |
PyPI | A package name, such as | Case-insensitive. Names are normalized, so |
NuGet | A package ID, such as | Case-insensitive. |
You can use one asterisk (*) as a wildcard at the beginning or end of a namespace. A trailing asterisk matches names that start with the remaining string. A leading asterisk matches names that end with the remaining string.
Example | Matches |
|---|---|
| Maven groups such as |
| PyPI package names that start with |
| npm, PyPI, or NuGet package names that end with |
A leading asterisk has no effect on Maven group IDs or npm scopes. The value is accepted, but it matches nothing for those namespace types.
The API rejects a single *, an asterisk at both ends, or an asterisk in the middle of a namespace. A namespace can contain up to 300 characters. Leading and trailing spaces are removed.
Register Namespaces
Use a user with the Evaluate Individual Components permission on the Policy Gateways container. Send a JSON array of namespaces to the endpoint for the format.
The following example registers Maven group IDs:
curl -u username:password -X POST \ -H 'Content-Type: application/json' \ -d '["org.acme", "com.acme.*"]' \ https://IQ_SERVER/api/v2/firewall/enterprise/namespace_confusion/maven
Replace
username:passwordwith the IQ Server credentials for a user with the required permission.Replace
IQ_SERVERwith the IQ Server host name.
A successful request returns HTTP 204. The namespaces apply to every Policy Gateway from the next request. Repeat the request for each format you want to protect, using npm, pypi, or nuget in place of maven.
View Registered Namespaces
Use the Namespace Confusion API to list the namespaces registered for a format. The user must have the View IQ Elements permission on the Policy Gateways container.
curl -u username:password \ 'https://IQ_SERVER/api/v2/firewall/enterprise/namespace_confusion/maven?page=1&pageSize=10'
Replace
username:passwordwith the IQ Server credentials for a user with the required permission.Replace
IQ_SERVERwith the IQ Server host name.
The response contains one page of namespaces, ordered by namespace and returned as registered.
Parameter | Description |
|---|---|
| Page number, starting at 1. Defaults to 1. |
| Number of namespaces per page, from 1 to 100. Defaults to 10. |
The response includes Link headers for the first, last, next, and previous pages.
Remove Namespaces
Important
Deleting a format’s namespace list deletes ALL namespaces registered for that format.
Save any namespaces you want to keep before deleting the list, then register them again afterward.
Use a user with the Evaluate Individual Components permission on the Policy Gateways container. A successful request returns HTTP 204, including when no namespaces were registered.
curl -u username:password -X DELETE \ https://IQ_SERVER/api/v2/firewall/enterprise/namespace_confusion/maven
Removing a namespace allows matching public components to be downloaded through Policy Gateway proxy repositories, subject to policy evaluation. Components quarantined while the namespace was registered remain quarantined. For details on managing quarantined components, see the Firewall Quarantine main topic.
How Firewall Enterprise Evaluates a Fetch
When a component is requested through a Policy Gateway proxy repository, Firewall Enterprise evaluates it against the applicable policies.
If the component matches a registered namespace, Firewall Enterprise evaluates it against the Security-Namespace Conflict policy. When that policy is set to Fail and the violation is not waived, Firewall Enterprise quarantines the component and refuses the fetch with HTTP 403. The evaluation appears in Policy Gateway results.
Firewall Enterprise applies this behavior whether or not Sonatype’s data knows the component. A component that is unknown to Sonatype’s data is still evaluated as a public component when it is fetched through a proxy repository.
A registered namespace does not change package listings. For example, a matching version can still appear in npm or PyPI results; Firewall Enterprise enforces the namespace when the component is fetched.
A fetch can still be allowed if no applicable policy blocks it. For example, the Security-Namespace Conflict policy might be set to Warn, its violation might be waived, or no applicable policy might exist.