Skip to main content

Sonatype Repository Firewall API

The Repository Firewall API exposes HTTP endpoints for managing the connection details to the Repository Firewall service.

Authorization required, required permissions for endpoints should be applied (nexus:settings:**)

Endpoints

The REST API endpoints are used for the following:

  • Manage Repository Firewall configuration

    • Get the configuration

    • Update the configuration

      • Setting the fail-open mode

    • Disable/Enable the configuration

    • Verify the configuration

  • Manage Firewall: Audit and Quarantine configuration for proxy repositories

    • Get the audit status for all proxy repositories

    • Get the audit status by proxy repository name

    • Set the audit status for a proxy repository

    • Set the quarantine status for a proxy repository

Get the Repository Firewall configuration

Required user permissions (nexus:settings:read)

GET /service/rest/v1/iq

Example Request

curl -X GET -u <nexus_username>:<nexus_password> "<nexus_base_url>/service/rest/v1/iq"

Getting the configuration includes #~NXRM~PLACEHOLDER~PASSWORD~# instead of the password for security.

Verify the configuration

Test that the connection is configured correctly.

POST /service/rest/v1/iq/verify-connection

Example Request

curl -X GET -u <nexus_username>:<nexus_password> "<nexus_base_url>/service/rest/v1/iq/verify-connection"

The response will return 200 with the success parameter being true or false.

{
  "success": true,
  "reason": "IQ Server reported applications: Sandbox Application"
}

Update the Repository Firewall configuration

Required user permissions (nexus:settings:edit)

PUT /service/rest/v1/iq

This request requires a body with the server access parameters.

{
  "enabled": true, 
  "showLink": true,
  "url": "<iq_base_url>",
  "authenticationType": "USER", 
  "username": "<iq_username>", 
  "password": "<iq_password>",
  "useTrustStoreForUrl": true,
  "timeoutSeconds": 3600, 
  "failOpenModeEnabled": true
}

Example Request

curl -X PUT -u <nexus_username>:<nexus_password> -H 'Content-Type: application/json' -d '{"enabled": true, "showLink": true, "url": "<iq_base_url>","authenticationType": "USER","username": "admin","password": "admin123","useTrustStoreForUrl": true,"timeoutSeconds": 3600, "failOpenModeEnabled": true}' "<nexus_base_url>/service/rest/v1/iq"

Configure the Repository Firewall Fail-Open Mode

Repository Firewall may be configured to allow developers to continue to download new components that have not been reviewed for policy violations when Nexus Repository is not able to connect to the IQ Server due to network issues.

This configuration is called fail-open mode.

The fail-open mode is configured via the Repository Firewall API. Updating the configuration through the UI resets the fail-open mode configuration.

Enable the Configuration

The connection to the FIrewall service may be quickly enabled or disabled without removing the configuration and losing the stored credentials.

POST /service/rest/v1/iq/enable

The enable may be switched out with disable to disconnect the service.

Managing the Audit for Proxy Repositories

Required user permissions (nexus:settings:read,update) in Nexus Repository version 3.70 or greater

Get the Proxy Repository Audit Configuration

Get a list of all proxy repositories and their audit configuration.

GET /service/rest/v1/iq/audit

Including the repository name will retrieve the settings for a single repository.

GET /service/rest/v1/iq/audit/{repositoryName}

Example Response

[
  {
    "enabled": false,
    "repositoryName": "maven-central",
    "enabledQuarantine": false
  },
  {
    "enabled": false,
    "repositoryName": "nuget.org-proxy",
    "enabledQuarantine": false
  }
]

Set the Proxy Repository Audit Configuration

Updating the audit configuration for a proxy repository.

PUT /service/rest/v1/iq/audit

Send the configuration in the request body.

{
  "enabled": true,
  "repositoryName": "string",
  "enabledQuarantine": true
}

The repository name is required however you only need to include the audit and quarantine when setting the value.

  • enabled: set Repository Firewall to audit the proxy repository

  • enabledQuarantine: turn on enforcement for Repository Firewall

  • repositoryName (required): name of the proxy repository

Quarantine policies are managed from the Firewall service. We recommend enabling quarantine on all proxy repositories and managing the enforcement from the IQ Server.

Example Request

curl -X 'PUT' \
  'http://localhost:8081/service/rest/v1/iq/audit' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "enabled": true,
  "repositoryName": "maven-central",
  "enabledQuarantine": true
}'