JFrog Artifactory Setup

The Sonatype Repository Firewall for JFrog Artifactory solution protects your development environment from risky or undesirable components. The plugin uses policies configured in Sonatype IQ Server to prevent proxy repositories from serving unwanted components.

Prerequisites

Sonatype IQ Server version 119 or higher
Plugin version 2.2 or later
A service account in IQ Server configured with the "Component Evaluator" role
A license for Repository Firewall for JFrog Artifactory

Unsupported JFrog Artifactory versions

jFrog Artifactory SaaS is not supported
unsupported because of a cluster synchronization bug: 7.49.3 | 7.49.5 | 7.49.8 | 7.55.2
reached the "Artifactory end of life" date

Installation

Stop the JFrog Artifactory server
Download the latest version of the Firewall for Artifactory plugin
Extract the plugin zip file into JFrog Artifactory's /plugins directory
1. The archive includes an example configuration and necessary files
Rename firewall.properties.example to firewall.properties
Configure and enable your repositories in the firewall.properties file
1. NEW IN 2.4.8 The Configuration API may be used to update and reload configuration
Start the JFrog Artifactory server

After restart:

JFrog Artifactory reads the configuration file and connects to IQ Sever.
Configured repositories are displayed in 'Repositories' under 'Organization and Policies' in IQ Server.
Components already existing in proxy repositories can be downloaded from the proxy repository.
When in Quarantine mode
1. Components downloaded after enabling Firewall's quarantine feature will be blocked.
2. Firewall prevents new components that violate policy from being served from the remote repository.
When in Audit mode
1. New components added to remote repositories are evaluated against IQ policy and available in the repository results.

High Availability

Install the plugin zip and the firewall.properties in the primary node of your JFrog Artifactory high availability system.
JFrog Artifactory HA will automatically synchronize the plugin and its configuration to the remaining nodes.
Update the plugin configuration for JFrog Artifactory HA as documented here.

Folder Configuration

The final folder structure should resemble:

JFrog Artifactory 7.x

${ARTIFACTORY_HOME}
   /var
      /etc
         /artifactory
            /plugins
               nexusFirewallForArtifactoryPlugin.groovy
               firewall.properties
               /lib
                  nexus-iq-artifactory-plugin.jar

JFrog Artifactory 6.x

${ARTIFACTORY_HOME}
   /etc
      /plugins
         nexusFirewallForArtifactoryPlugin.groovy
         firewall.properties
         /lib
            nexus-iq-artifactory-plugin.jar

Upgrading

To upgrade the plugin, repeat the installation steps
Overwrite the following files
1. nexusFirewallForArtifactoryPlugin.groovy
2. lib/nexus-iq-artifactory-plugin.jar
The sample configuration file, firewall.properties.example is not required

1.x to 2.0 Migration

Repository Firewall for JFrog Artifactory 2.0 fixes an issue in the 1.x series where the 'repository manager' column in the 'Repositories' view in IQ displayed a hash value instead of the repository name.

1.x plugin

2.0 plugin

Do the following to complete the migration and display the repository identifier:

Install Sonatype IQ Server
Install the Sonatype Repository Firewall for JFrog Artifactory plugin
Update the firewall.properties file and configure the firewall.repository.manager.id property

The migration will automatically begin on JFrog Artifactory startup after completing the above steps.

Omitting a step will result in the repository manager identifier displayed as a hash value.

Configuration

All plugin configuration is managed by the firewall.properties file.

# These properties are to configure the connection to the IQ server.
# The values below are example values and should be updated with your own.
firewall.iq.url=http://iq.example.com:8070
firewall.iq.username=exampleusername
firewall.iq.password=examplepassword

# This identifies this JFrog Artifactory instance in the IQ 'Repositories' view
firewall.repository.manager.id=artifactory-instance-1

# The URL that users will use to connect to the IQ Server.
# This URL will be prepended to the Repository Results view URI.
# For example, a complete Repository Results view URL:
#   http://iq.public.com:8070/ui/links/repository/0396e6d401d143399d53493e57c106e8/result
firewall.iq.public.url=http://iq.public.com:8070

# Define if fail open mode should be enabled (Default value is disabled).
# When IQ server is not reachable, new components can be downloaded without evaluation.
# firewall.iq.fail.open.mode.enabled=true

# Define repositories with a 'firewall.repo.' prefix.
# Possible options are 'quarantine', 'audit', 'policyCompliantComponentSelection', 'proprietary' and 'disabled'.
# 'policyCompliantComponentSelection' implies 'quarantine'.
# 'proprietary' can only be set on repositories of type 'local'.
#
# If quarantine is enabled and later disabled, all quarantined components will be made available
# in the repository; those components cannot be re-quarantined.
#
# Note that commenting out a repository configuration will not disable it,
# instead if you want to disable a repository configuration including
# 'quarantine', 'audit', or 'policyCompliantComponentSelection'
# then you must explicitly set it to be 'disabled'
# firewall.repo.<example-repository-name>=quarantine
# firewall.repo.<other-example-repository-name>=audit
# firewall.repo.<another-example-repository-name>=disabled
# firewall.repo.<example-local-repository-name>=proprietary

# Define http proxy settings if applicable
# firewall.iq.proxy.hostname=
# firewall.iq.proxy.port=
# firewall.iq.proxy.username=
# firewall.iq.proxy.password=
# firewall.iq.proxy.ntlm.domain=
# firewall.iq.proxy.ntlm.workstation=

This plugin supports the 'remote' repository type.
The 'virtual' repository type is indirectly supported.
Firewall may be configured to a virtual repository when they include a remote repository with Firewall enabled.
'local' repositories can be configured as 'proprietary' to prevent Namespace Confusion Attacks.

Considerations

Removing the firewall.properties with the plugin installed will cause all download requests to be denied until the firewall.properties file is restored and JFrog Artifactory is restarted.
If quarantine is enabled and later disabled, all currently quarantined components will be made available in the repository. Those components cannot be re-quarantined.
Commenting out a repository configuration will not disable it, instead if you want to disable a repository configuration including 'quarantine', 'audit', or 'policyCompliantComponentSelection' then you must explicitly set it to disabled.
Nexus Firewall for Artifactory will not work when the "store artifacts locally" advanced setting is disabled.

Using an HTTP Proxy for Outbound Traffic

Use the following configuration options if your JFrog Artifactory instance needs to reach IQ Server via an HTTP proxy server.

# The host running the proxy server.
firewall.iq.proxy.hostname=company-proxy.example.com

# The port which the proxy server listens on.
firewall.iq.proxy.port=8080

# The username used to access the proxy server (if necessary).
firewall.iq.proxy.username=proxyusername

# The password used to access the proxy server (if necessary).
# firewall.iq.proxy.password=proxypassword

NTLM

Configure the domain and workstation if your proxy server uses NT LAN Manager (NTLM) authentication.

# The Windows domain used for authentication
firewall.iq.proxy.ntlm.domain=companydomain
 
# The name of the local computer running JFrog Artifactory
firewall.iq.proxy.ntlm.workstation=localworkstation

High Availability Cache Strategy

Firewall for JFrog Artifactory HA requires a different internal cache strategy and can be configured with the following:

For versions 2.2 and 2.4.2 only. This configuration setting was removed in 2.4.3.

# Disable local memory cache (default: MEMORY_THEN_STORAGE )
firewall.cache.quarantine.strategy=STORAGE_ONLY

It is safe to switch between different cache strategies. Restart JFrog Artifactory for the changes to take effect.

NEW IN 2.4.8 Configuration REST API Endpoints

In the following examples, the calls are made to your JFrog Artifactory server by substituting in an admin username and password as well as your JFrog Artifactory URL.

Sensitive configuration properties will have their values obfuscated in returned API requests.

Get Configuration Properties

The getFirewallProperties endpoint returns all configuration properties.

curl -u yourusername:yourpassword "https://artifactory.example.com/api/plugins/execute/getFirewallProperties"

Specific configuration properties may be requested using the same endpoint; both keys and values.

curl -u yourusername:yourpassword "https://artifactory.example.com/api/plugins/execute/getFirewallProperties?params=keys=k1,k2"

Add or Update Configuration Properties

This sets key k1 to value v1 and key k2 to value v2.

curl -u yourusername:yourpassword -X PUT "https://artifactory.example.com/api/plugins/execute/addOrUpdateFirewallProperties?params=k1=v1%7Ck2=v2"

Remove a Configuration Property

This API endpoint removes the k1 and k2 configuration properties.

curl -u yourusername:yourpassword -X DELETE "https://artifactory.example.com/api/plugins/execute/removeFirewallProperties?params=keys=k1,k2"

Set the Configuration File Content

This endpoint sets the entire configuration file content to that of the given firewall.properties file. Note the following before using this endpoint:

This endpoint requires the submitted file encoding to be ISO 8859-1.
All configuration file properties will be overridden using this endpoint.

curl -u yourusername:yourpassword -X PUT --data-binary @firewall.properties "https://artifactory.example.com/api/plugins/execute/setFirewallProperties"

Reload

This endpoint will reload the plugin.

curl -u yourusername:yourpassword -X POST "https://artifactory.example.com/api/plugins/execute/reload"

There are two other ways for the plugin to be reloaded:

Automatically when changes to the firewall.properties file are detected.
Manually by calling the JFrog reload plugins endpoint, however this only works if the plugin has been modified since the last user plugins reload.

Whereas this reload endpoint can be called at any time.

Check IQ Server Connection

This endpoint will check the IQ Server connection.

When the connection is successful a 200 status code is returned.
A different status code is returned by the IQ Server connection attempt.

The returned body will contain the non-sensitive IQ Server connection properties for review.

curl -u yourusername:yourpassword -X POST "https://artifactory.example.com/api/plugins/execute/checkIQConnection"

Reviewing Results

Every repository with Firewall enabled receives its own Application Composition Report URL. Make the following call to the JFrog Artifactory server to get the URL.

curl -u yourusername:yourpassword "https://artifactory.example.com/api/plugins/execute/firewallEvaluationSummary?params=repo=your-repo-name"

Substitute your username, password, JFrog Artifactory URL, and proxy repository name in the example above.

This returns a JSON with details on the repository:

{
  "moderateComponentCount":0,
  "quarantinedComponentCount":0,
  "reportUrl":"https://myiqserver:8070/ui/links/repository/0396e6d401d143399d53493e57c106e8/result",
  "severeComponentCount":0,
  "criticalComponentCount":0,
  "affectedComponentCount":0
}

The reportUrl can be opened in a browser. This forwards you to the static policy report URL which can be bookmarked for future access.

The property firewall.iqRepositoryUrl links to the same Application Composition report URL and is unique to each repository.

IQ Repository URL property for a repository with Firewall enabled:

About Timestamps

The Firewall for Artifactory plugin will only process new components from when the plugin was enabled. Previously downloaded components will continue to be allowed to prevent existing builds from breaking.

Logging

The Sonatype Repository Firewall for JFrog Artifactory plugin ships with some basic informative logging by default. Additional logs are available for debugging if necessary. Per component blocking is not logged by default to prevent excessive log entries.

JFrog Artifactory uses the Logback library for logging. To understand JFrog Artifactory logging and modify logged information, see the JFrog documentation here: Artifactory Log Files - Configuring Log Verbosity

Add this section to the logback.xml file to increase logging for the plugin:

<logger name="com.sonatype.iq.artifactory">
    <level value="debug"/>
</logger>

Uninstallation

Stop the JFrog Artifactory server

Remove the nexusFirewallForArtifactoryPlugin.groovy file from the plugins directory to disable the Repository Firewall for JFrog Artifactory plugin.

JFrog Artifactory 7.x

JFrog Artifactory 6.x

${ARTIFACTORY_HOME}
   /var
      /etc
         /artifactory
            /plugins
               nexusFirewallForArtifactoryPlugin.groovy
               nexusFirewallForArtifactoryPlugin.groov?~
               firewall.properties
               firewall.propertie?~
               /lib
                  nexus-iq-artifactory-plugin.jar

${ARTIFACTORY_HOME}
   /etc
      /plugins
         nexusFirewallForArtifactoryPlugin.groovy
         nexusFirewallForArtifactoryPlugin.groov?~
         firewall.properties
         firewall.propertie?~
         /lib
             nexus-iq-artifactory-plugin.jar

Clean up files that are no longer used (optional).
1. Remove backup files created by JFrog Artifactory: nexusFirewallForArtifactoryPlugin.groov?~ and firewall.propertie?~ (where ? is a character used to indicate the version of the config file)
2. Remove the lib/nexus-iq-artifactory-plugin.jar
Start the JFrog Artifactory server
Attributes on repository objects created by Nexus Firewall for JFrog Artifactory are safe to delete. All attributes the Firewall for JFrog Artifactory plugin creates use the prefix firewall. The screenshot below shows a typical example of firewall repository attributes in JFrog Artifactory:

Release Notes

Date	Version	Notes
September 14, 2023	2.4.8	Added REST API endpoints to allow admin users to change the configuration, reload the plugin, and to check the IQ Server connection Fixed an issue with incorrect MODE selection Fixed an issue when using cargo sparse indexes Requires Sonatype IQ Server release 168. Firewall Guided Setup can now be used to configure Artifactory repositories.
July 17, 2023	2.4.7	Adding Fail Open Mode to enable users to ALLOW or DENY access to quarantined objects while IQ connection failures
June 1, 2023	2.4.5	Fixed an issue where new component audit/quarantine notifications were not sent
April 6, 2023	2.4.4	Added support for Policy Compliant Component Selection for npm Added support for Namespace Confusion Protection Improved logging during plugin initialization
October 19, 2022	2.4.3	Fixed an issue with the retrieval of version number for JFrog Artifactory Fixed an issue with high availability cache strategy. The firewall.cache.quarantine.strategy configuration settings is deprecated and will now be ignored
August 19, 2022	2.4.2	Fixed issue with API incompatibility with JFrog Artifactory 7.38+
October 8, 2021	2.2	Added High-Availablity sections
February 8, 2021	2.0.20210202-144950.fea7183	Fixed issue with 'Repository Manager' name in the 'Repositories' view in Sonatype IQ Server. See the "1.x to 2.0 Migration" for more information.
October 6, 2020	1.5.20200826-145900.1e80e0e	Ability to re-quarantine a component
May 8, 2019	1.3.20190506-103422.bcec6d6	Fixed CSRF issue with IQ URL
April 1, 2019	1.2.20190401-141713.4839bdb	Audit the entire repository when enabled Improved how to access the IQ policy report URL Improved IQ connection handling More graceful handling if the `firewall.properties` configuration file goes missing Fixed issue when using a web application path
March 18, 2019	1.1.20190318-124352.6da59c5	Added support for proxies Improved IQ summary report URL Allow readers to access the Evaluation Summary
March 1, 2019	1.0.20190228-114947.80c1638	Initial release