IQ Server and Firewall for Artifactory


Overview

The Nexus Firewall for Artifactory plugin uses audit and quarantine features to help 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.

https://www.sonatype.com/nexus-firewall

https://guides.sonatype.com/iqserver/quick-start-guides/firewall/

Prerequisities

Requirements to use Nexus Firewall for Artifactory:

Installation

  1. Download the latest version of the plugin from here
  2. Extract the contents of the plugin zip file into ${ARTIFACTORY_HOME}/etc/plugins. The zip file includes an example configuration file for the plugin, and all necessary files for the operation of the plugin. The final folder structure should resemble:

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


  3. Rename firewall.properties.example to firewall.properties to use as a base for your configuration.
  4. Configure which repositories you would like to enable in the firewall.properties file.

Upgrade

To upgrade to the latest version of the plugin, simply 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 so there is no danger of overwriting your configuration.

Configuration

All plugin configuration is done through the firewall.properties. When changes are made to this file they can be applied by restarting Artifactory.

# 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

# 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 username defined here must exist in IQ and have the "Component Evaluator" role. See Role Management for further information.

The plugin only supports the 'remote' repository type, usually configured as a remote proxy of Maven Central at https://repo1.maven.org/maven2. The 'virtual' repository type is indirectly supported in that if your virtual repository includes a remote repository that has Firewall enabled, then components can be quarantined or audited.

Removing the firewall.properties with the plugin installed will cause all download requests to be denied until the firewall.properties file is restored and Artifactory is restarted.

If quarantine is enabled and later disabled, all quarantined components will be made available in the repository; those components cannot be re-quarantined.

Using an HTTP Proxy for Outbound Traffic

If your Artifactory instance needs to reach IQ Server via an HTTP proxy server, use the following configuration options.

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

# The port at 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 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 Artifactory
firewall.iq.proxy.ntlm.workstation=localworkstation

Usage

When the plugin is configured and Artifactory is restarted, the following events will take place

  1. When Artifactory is started, the configuration file will be read and any configured repositories will be enabled in IQ. The enabled repositories can be viewed in IQ in the 'Repositories' view under 'Organization and Policies'.
  2. The Firewall quarantine feature only applies to new components that are added after quarantine is enabled. When a new component violates policy, Firewall prevents it from being served from the remote repository.
  3. When repositories are enabled in audit mode, new components added to remote repositories are evaluated against IQ policy. This information is then included in the repository results.

Reviewing Results

Every repository that has Firewall enabled will receive its own Application Composition report URL. To obtain this URL, make the following call to the Artifactory server:

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

In the above example you will need to substiute your appropriate username, password, Artifactory URL, and virtual repository name.

The result is a JSON response 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 is a copy-paste url that can be opened in a browser You will be forwarded to the static policy report URL which can be bookmarked for future access.

In addition, each repository enabled for Firewall has a property, firewall.iqRepositoryUrl that is a copy-paste url to the same Application Composition report URL.

IQ Repository URL property for a repository with Firewall enabled:

About Timestamps

The plugin will only process components which are new to the repository since Firewall was enabled on it. Components that have been served by Artifactory prior to this will always be allowed regardless of their policy status. This is to prevent any existing builds from breaking.

Logging

The Nexus Firewall for Artifactory plugin ships with some basic informative logging by default, and additional logs are available for debugging if necessary. Specifically per component blocking is not logged by default as this can result in an excessive amount of log entries.

Artifactory uses the Logback library for logging. To understand Artifactory logging and how to change what is logged, see the JFrog documentation here: Artifactory Log Files - Configuring Log Verbosity

In order to increase logging for the Firewall plugin, add this section to the logback.xml file:

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

Release notes

DateVersionNotes
2019-05-081.3.20190506-103422.bcec6d6
  • Fixed CSRF issue with IQ url
2019-04-011.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-181.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

Known Limitations

  • The plugin is currently untested on highly available (HA) environments