JFrog Artifactory Setup
Important: The Firewall for JFrog Artifactory 2.0 plugin fixes an issue with the 'Repository Name' attribute when viewed from IQ. Please see the "1.x to 2.0 Migration" section below for further details.
Multinode clusters require version 2.2 of the Firewall for JFrog Artifactory plugin
Overview
The Nexus Firewall for JFrog Artifactory plugin uses the Firewall features to protect your development environment from risky or undesirable components. These features use IQ Server policies to identify, and if desired, prevent proxy repositories from serving unwanted components.
To get Nexus Firewall visit the Firewall home page.
Check out the Firewall Quick Start Guide for detailed installation information.
Prerequisites
Additional requirements for Multi-node Clusters:
- Firewall for JFrog Artifactory Plugin version 2.2 or later
- JFrog Artifactory version 7.49.3, 7.49.5, 7.49.8 and 7.55.2 are not supported because of a cluster synchronization bug
Requirements:
- Nexus IQ Server version 119 or higher and a "Nexus Firewall for JFrog Artifactory" license
- Next-Gen Firewall features require a new license issued after June 1, 2021
- A version of JFrog Artifactory which has not reached the "Artifactory End of Life" date
Installation
- Stop the JFrog Artifactory server
- Download the latest version of the plugin
- Extract zip file into JFrog Artifactory's
/plugins
directory (see table below). The zip file includes an example configuration file for the plugin and all necessary files for use. - Rename
firewall.properties.example
tofirewall.properties
to use it as the base for your configuration.The final folder structure should resemble:
JFrog Artifactory 7.x JFrog Artifactory 6.x ${ARTIFACTORY_HOME} /var /etc /artifactory /plugins nexusFirewallForArtifactoryPlugin.groovy firewall.properties /lib nexus-iq-artifactory-plugin.jar
${ARTIFACTORY_HOME} /etc /plugins nexusFirewallForArtifactoryPlugin.groovy firewall.properties /lib nexus-iq-artifactory-plugin.jar
Configure and enable your repositories in the
firewall.properties
file.- Start the JFrog Artifactory server
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. Also update the plugin configuration for JFrog Artifactory HA as documented here.
Upgrade
To upgrade to the latest version of the plugin, repeat the installation steps above and overwrite the nexusFirewallForArtifactoryPlugin.groovy
file and the lib/nexus-iq-artifactory-plugin.jar
file. The sample configuration file firewall.properties.example
can be extracted as well, but is not required. Your actual configuration file will be named firewall.properties
. The firewall.properties.example
file will not overwrite your firewall.properties
configuration file.
1.x to 2.0 Migration
Nexus 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 Manager name.
1.x plugin
2.0 plugin
Do the following to complete the migration and display the repository manager identifier:
Backup your IQ database before updating. See Backing up the IQ Server.
- Install Nexus IQ Server 119 or higher
- Install Nexus Firewall for JFrog Artifactory Plugin version 2.2 or higher
- Update the
firewall.properties
file and configure thefirewall.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 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. # 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=
The defined username must match an IQ user with the "Component Evaluator" role. See Role Management for further information.
This plugin only supports the 'remote' repository type. The 'virtual' repository type is indirectly supported. Firewall can audit and quarantine components in a virtual repository if it includes a remote repository with Firewall enabled. 'local' repositories can be configured as 'proprietary' to prevent Namespace Confusion Attacks.
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.
Using an HTTP Proxy for Outbound Traffic
If your JFrog Artifactory instance needs to reach IQ Server via an HTTP proxy server, use the following configuration options.
# 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
If your proxy server uses NT LAN Manager (NTLM) authentication, additionally configure the domain and workstation
# 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.
Usage
When JFrog Artifactory is restarted with the configured plugin:
- JFrog Artifactory reads the configuration file and enables configured repositories in IQ. View these repositories in 'Repositories' under 'Organization and Policies' in IQ Server.
- Only components downloaded after enabling Firewall's quarantine feature will be blocked. Existing components can still be downloaded from the proxy repository. Firewall prevents new components that violate policy from being served from the remote repository.
- In Audit mode, new components added to remote repositories are evaluated against IQ policy. This information is available in the repository results.
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-virtual-repo-name"
Substitute your username, password, JFrog Artifactory URL, and virtual 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 plugin only processes components new to the repository beginning when Firewall was enabled. Components previously served by JFrog Artifactory will always be allowed regardless of their policy status. This prevents any existing builds from breaking.
Logging
The Nexus 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 Firewall 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 Nexus 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).
- 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)
- 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 |
---|---|---|
2023-04-06 | 2.4.4 |
|
2022-10-19 | 2.4.3 |
|
2022-08-19 | 2.4.2 |
|
2021-10-08 | 2.2 |
|
2021-02-08 | 2.0.20210202-144950.fea7183 |
|
2020-10-06 | 1.5.20200826-145900.1e80e0e |
|
2019-05-08 | 1.3.20190506-103422.bcec6d6 |
|
2019-04-01 | 1.2.20190401-141713.4839bdb |
|
2019-03-18 | 1.1.20190318-124352.6da59c5 |
|
2019-03-01 | 1.0.20190228-114947.80c1638 |
|