Skip to main content

Sonatype Repository Firewall API

The Sonatype Repository Firewall API exposes HTTP endpoints for managing the connection details to the Repository Firewall service. The Managing Audit for Proxy Repositories section is for enabling the audit and quarantine on your proxy repositories.

See the Manage Sonatype Repository Firewall configuration in Administration under System → API of your Nexus Repository instance for information on this API including sample requests and responses.

Note

In the Nexus Repository release 3.53.0, we renamed the IQ API to Sonatype Repository Firewall API.

This is a UI update only and will not impact the API endpoints.

  • 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"

Note

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

The connection between Nexus Repository and the Repository Firewall may become interrupted due to the systems not being accessible across the network. Should this occur, you may configure the Repository Firewall to the "fail open" mode; to allow developers to download new components that have not been quarantined. With the fail-open mode disabled, attempts to download new components will fail to protect the integrity of the repository.

Important

The fail-open mode is configured via the Sonatype Repository Firewall API. Updating the configuration through the UI will reset 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 highly 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
}'