JFrog Artifactory Setup

Important: The Firewall for 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 requires version 2.2 of the Firewall for Artifactory plugin

Overview

The Nexus Firewall for Artifactory plugin uses the Audit and Quarantine features to protect your development environment from risky or undesirable components. These features use IQ Server policy management 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

Multi-node Clusters require the Firewall for JFrog Artifactory Plugin 2.2 or later


Requirements:

Installation

  1. Download the latest version of the plugin
  2. 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.
  3. Rename  firewall.properties.example to firewall.properties to use it as the base for your configuration.

    The final folder structure should resemble:

    JFrog Artifactory 7.xJFrog 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
  4. Configure and enable your repositories in the firewall.properties file.

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 nexus FirewallForArtifactoryPlugin.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. firewall.properties.example will not overwrite your configuration. 

1.x to 2.0 Migration

Nexus Firewall for 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.

  1. Install Nexus IQ Server 119 or higher
  2. Install Nexus Firewall for Artifactory Plugin version 2.2 or higher
  3. 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.
Restart JFrog Artifactory to apply configuration changes. 

# 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 property identifies this JFrog Artifactory instance in the IQ 'Repositories' view
firewall.repository.manager.id=acme-artifactory

# The URL that users will use to connect to the IQ Server.
# This URL will be preprended to the Application Composition report URI.
# For example,
#   http://iq.public.com:8070/ui/links/repository/0396e6d401d143399d53493e57c106e8/result
firewall.iq.public.url=http://iq.public.com:8070

# Define http proxy settings if applicable
# firewall.iq.proxy.hostname=company-proxy.example.com
# firewall.iq.proxy.port=8080
# firewall.iq.proxy.username=proxyusername
# firewall.iq.proxy.password=proxypassword
# firewall.iq.proxy.ntlm.domain=companydomain
# firewall.iq.proxy.ntlm.workstation=localworkstation

# Define repositories with a 'firewall.repo.' prefix. Possible options are 'quarantine', 'audit',
# and 'disabled'.
#
# 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

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.  Usually this is a remote proxy of Maven Central at https://repo1.maven.org/maven2. 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. 

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 Artifactory HA requires a different internal cache strategy and can be configured with the following:

Since version: 2.2

# 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:

  1. JFrog Artifactory reads the configuration file and enables configured repositories in IQ. View these repositories in 'Repositories' under 'Organization and Policies' in IQ Server. 
  2. 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.
  3. In Audit mode, new components added to remote repositories are evaluated against IQ policy. This information is availble in the repository results. 

Reviewing Results

Every repository with Firewall enabled receives its own Application Composition Report URL. Make the follwing 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 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

  1. Remove the nexusFirewallForArtifactoryPlugin.groovy file from the plugins directory to disable the Nexus Firewall for Artifactory plugin. Depending on your JFrog Artifactory license or version you might have to restart the JFrog Artifactory server for this change to take effect.

    JFrog Artifactory 7.xJFrog 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


  2. Confirmed that the plugin is no longer active (see logging above).
  3.  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
  4. Attributes on repository objects created by Nexus Firewall for Artifactory are safe to delete. All attributes the Firewall for Artifactory plugin creates use the prefix firewall. The screenshot below shows a typical example of firewall repository attributes in JFrog Artifactory:

Release notes

DateVersion

Notes

2021-10-082.2
  • Added High-Availablity sections

2021-02-08

2.0.20210202-144950.fea7183

  • Fixed issue with 'Repository Manager' name in the 'Repositories' view in IQ. See the "1.x to 2.0 Migration" for more information.

2020-10-06

1.5.20200826-145900.1e80e0e

  • Ability to re-quarantine a component

2019-05-08

1.3.20190506-103422.bcec6d6

  • Fixed CSRF issue with IQ url

2019-04-01

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

2019-03-18

1.1.20190318-124352.6da59c5

  • Added support for proxies

  • Improved IQ summary report URL

  • Allow readers to access the Evaluation Summary

2019-03-01

1.0.20190228-114947.80c1638

  • Initial release