Artifactory Plugin - Versions v22.11.2 and Newer

Note: There are major changes from the previous Artifactory plugin version v22.6.1 to version v22.11.2. For documentation on versions v22.6.1 and older, please see here.

This document covers step-by-step instructions on how to install and use the Mend plugin for Artifactory. Starting with v22.11.2, the Artifactory plugin’s SCA option is now split into two execution modes: cron and triggers. These modes share the same properties file. The Supply Chain Defender (SCD) integration also includes new functionality.

Mend Plugin for Artifactory Features

The following features list the enhancements between Artifactory plugin versions v22.6.1 and v22.11.2.

Configuration

• Starting with v22.11.2, only a few parameters apply to both execution modes: wssUrl, apiKey, userKey, and the proxy flags. Other parameters were separated between the two execution modes and renamed. These parameters are defined in the SCA triggers and SCA cron sections below.

• The repoKeys parameter was replaced by two parameters: sca.repoIncludes and sca.repoExcludes. These parameters support regex.

SCA triggers Execution Mode

• The beforeRemoteDownload trigger was changed to sca.triggers.afterRemoteDownload to improve plugin performance.

• As a result of the sca.triggers.afterRemoteDownload scan, the Mend Project acts as a blacklist for all blocked artifacts (approved artifacts are not visible in the Mend Project).
  Unblocking the artifacts is possible by ignoring the specific policy violation alert within the Mend portal.

Supply Chain Defender (SCD) Integration

• Starting with version v22.11.2, the plugin includes reporting to the Mend UI for blocked artifacts, similar to the SCA behavior. Like the SCA, you can now also allow previously blocked artifacts, by ignoring the alerts within the Mend UI. This change affects both triggers and cron flows of the SCD integration.

Support for Virtual Environments

• The plugin now supports virtual environments for the triggers execution mode which was not supported in previous versions of the plugin. The cron execution mode still only supports local repositories.

Mend Plugin for Artifactory Download

The Mend Artifactory plugin can be downloaded from here:

NOTE: The Artifactory Plugin versions will be available and supported for a year after their release. 

Mend Plugin for Artifactory ZIP Folder Components

Downloading and extracting the ZIP folder for the Artifactory plugin includes the following items:

• README.md

• whitesource-artifactory-plugin.groovy

• whitesource-artifactory-plugin.properties

• whitesource-artifactory-plugin-VERSION.jar

Installing the Mend Plugin for Artifactory

To install the Mend plugin for Artifactory, please follow the steps outlined below:

Artifactory Version <= 6.x

1. Download and extract the zip folder.

2. Place the whitesource-artifactory-plugin.properties and whitesource-artifactory-plugin.groovy files under ${ARTIFACTORY_HOME}/etc/plugins

3. Create a new lib folder under: ${ARTIFACTORY_HOME}/etc/plugins.

4. Place the whitesource-artifactory-plugin-VERSION.jar file in the plugins/lib directory.

5. Update the whitesource-artifactory-plugin.properties file with the appropriate parameters. 

6. If you would like to enable the cron execution mode, schedule the cron job in the whitesource-artifactory-plugin.groovy file.

7. Save your changes and restart Artifactory.

Artifactory Version >= 7.x

1. Download and extract the zip folder.

2. Place the whitesource-artifactory-plugin.properties and whitesource-artifactory-plugin.groovy files under ${ARTIFACTORY_HOME}/var/etc/artifactory/plugins.

3. Create a new lib folder under ${ARTIFACTORY_HOME}/var/etc/artifactory/plugins.

4. Place the whitesource-artifactory-plugin-VERSION.jar file in the plugins/lib directory.

5. Update the whitesource-artifactory-plugin.properties file with the appropriate parameters.

6. If you would like to enable the cron execution mode, schedule the cron job in the whitesource-artifactory-plugin.groovy file.

7. Save your changes and restart Artifactory.

SCA - Creating Mend Policies

To create Reject policies for the Mend plugin for Artifactory, please follow the steps outlined below:

NOTE: In this example, we are using an Organization-level policy and creating the policy to reject MIT licenses.

1. Within the Organization, navigate to Policies.

   

2. On the Policies page, click Add Policy.

   

3. On the Add Policy page, add the Name of your policy.
   NOTE: It is recommended that you name the policy so that you will know what it means when viewing the properties in Artifactory.

   

4. Set the Match to By License Group.

   

5. Click Add Licenses.

   

6. In the Select Licenses window, filter by MIT as follows:

   1. Set By to License and Value to MIT.

   2. Click Filter.

      

7. Click the box next to License to select all the results.

   

8. Click OK.

9. For Action type, select Reject.

   

10. Click Add at the bottom-right corner of the page.

11. You will be reverted to your Organizational Policies page. Click Save to save your newly-created policy.

    

Configuring the Artifactory Plugin

Proxy settings are relevant for requests for Mend servers only. Proxy for remote repository requests is not supported.

Shared Parameters

The following parameters are shared by both the cron and triggers execution modes of the plugin within the properties file:

SCA triggers

SCA cron

Enabling and disabling the cron execution mode is handled within the plugin’s whitesource-artifactory-plugin.groovy file, in scanrepositoriesCron.

The cron execution mode is disabled by default. Cron scheduling examples can be found in the README.md file included in the ZIP folder.

The behavior of the cron execution mode remains the same as for versions prior to 22.11.2, except that the repoKeys parameter were replaced by two parameters: sca.cron.repoIncludes and sca.cron.repoExcludes.

Note: The extraction depth of the Artifactory Plugin for archived files is currently set to the first level. The Unified Agent has an extraction depth of up to seven levels.

SCA triggers Execution Mode Results

sca.triggers.beforeDownload Behavior

Artifacts can still be downloaded to Artifactory’s remote-cache. The Mend plugin blocks the user from downloading it to their local machine.

With our org-level policy created earlier and sca.triggers.beforeDownload set to true, when a user tries to install the “q” library from Artifactory, they receive a 403 Error:

Within the Artifactory plugin logs, you will see the following lines when an artifact is blocked from being downloaded by a user (using our “q” NPM library example):

1 Check WhiteSource policies for artifact 'npm-demo-remote-cache/q/-/q-1.5.1.tgz'
2 Artifact q/-/q-1.5.1.tgz did not confirm with WhiteSource policy "Reject MIT Licenses"
3 Finished ‘beforeDownload’ event scan for 'npm-demo-remote-cache/q/-/q-1.5.1.tgz'
4 Download request has been canceled: Artifact q/-/q-1.5.1.tgz did not confirm with        5 WhiteSource policy "Reject MIT Licenses""

You can still see the “q” library downloaded in your Artifactory remote-cache:

sca.triggers.afterRemoteDownload Behavior

The Mend Project acts as a “blacklist”. It will only display artifacts within the Mend Project inventory that were blocked due to policy violations. Artifacts will be deleted within the Artifactory’s remote-cache. Using the same “q” library and org-level policy example, and with sca.triggers.afterRemoteDownload set to true, when a user tries to install the “q” library from Artifactory, they receive a 403 Error:

Within the Artifactory plugin logs, you will see the following lines when an artifact is blocked from being downloaded by a user (using our “q” NPM library example):

1 npm-demo-remote downloading https://registry.npmjs.org/q/-/q-1.5.1.tgz 35.95 KB
2 npm-demo-remote downloaded https://registry.npmjs.org/q/-/q-1.5.1.tgz 35.95 KB
3 Start ‘afterRemoteDownload’ event scan for ‘npm-demo-remote/q/-/q-1.5.1.tgz’
4 Check WhiteSource policies for artifact 'npm-demo-remote-cache/q/-/q-1.5.1.tgz'
5 WhiteSourceService - CheckPolicyCompliance - START
6 WhiteSourceService - CheckPolicyCompliance - END - request token: <>
7 WhiteSourceService - getDependencyData - START
8 WhiteSourceService - getDependencyData - END
9 Artifact q/-/q-1.5.1.tgz did not conform with WhiteSource policy “Reject MIT Licenses”
10 WhiteSourceService - update - START
11 Inventory update results for <MendOrgName>
12 Newly created project:
13 <MendProjectName>
14 Project name: <MendProjectName>, project URL: <MendProjectURL>
15 WhiteSourceService - update - END
16 delete - START - delete artifact: npm-demo-remote-cache:q/-/q-1.5.1.tgz reason:        17 Blocked by Policy
18 delete - END - Success deleting artifact npm-demo-remote-cache:q/-/q-1.5.1.tgz
19 Finished ‘afterRemoteDownload’ event scan for ‘npm-demo-remote/q/-/q-1.5.1.tgz’
20 Download request has been canceled: Artifact q/-/q-1.5.1.tgz did not confirm with        21 WhiteSource policy "Reject MIT Licenses"

Within Artifactory, looking into the remote-cache, the folder is empty:

In the Mend portal, you will see the blocked artifacts within the Mend Project.
In the screenshot below, you can see your “q” library example in the Inventory and that there are two policy violations on the npm-demo-remote-cache Project dashboard:

Clicking on the policy violations within the dashboard will bring you to the Licensing & Compliance Alerts report. Here, the details of the policy violation are provided:

SCA - Allowing Previously Blocked Artifacts

Let’s say you want to allow the blocked “q-1.5.1.tgz” library to be downloaded by users. To do so, within the Licensing & Compliance Alerts report in the Mend portal, select the “q” library > Actions > Ignore Alerts:

A pop-up window will appear confirming that you would like to ignore this alert and also allow you to add any comments. Click OK once you are finished.

When you set the Status filter of the report to Any Status and click Apply, you will see the ignored alert for the “q-1.5.1.tgz’:

NOTE: In this example, we are only ignoring in Mend/”allowing” in Artifactory version 1.5.1 of the “q” library. If a user tries to download a different version that contains an MIT license (from our policy example), let’s say q-1.5.0, they will receive a 403 Forbidden error and the “q” library with the different version will be added to the “blacklist” Mend Project.

Now, when a user tries to download the q-1.5.1 version again after the alert for it was ignored in the Mend UI, it will be allowed.

The Artifactory remote-cache will also contain the library.

Supply Chain Defender (SCD) Integration

Mend’s Artifactory SCD integration supports only NPM and Ruby repositories. Unsupported repositories will not be affected by the SCD.

Properties File SCD Parameters

Please use the same whitesource-artifactory-plugin.properties file as your SCA settings and add the following additional parameters in order to use the SCD integration.

SCD Feature Summary

Single Query

A single query is triggered by any request to install a package (i.e., npm install) via your package manager that is associated with an Artifactory repository. Any remote request made by the Artifactory server to a supported registry is verified against the SCD database. The request is permitted if the requested package is not flagged by the SCD; otherwise, it is blocked.

Related parameters:scd.repoKeys, scd.strict, scd.aliases.npmjs, scd.aliases.rubygems

Note the following:

• If the packages exist in the local npm cache on your machine, Artifactory will not be called by npm.

• If the packages exist in the Artifactory cache (previously downloaded), the triggerBeforeRemoteDownload will not be triggered.

• Setting scd.beforeRemoteDownload=true is mandatory to trigger the security check for new installations.

Batch Query

A batch query is triggered by a cron job. Every existing artifact within the repositories defined in the scd.repoKeys parameter is scanned and checked against the SCD database. Each blocked artifact will be handled according to the scd.cron.quarantine flag.

Reporting

Starting with version v22.11.2, the plugin includes the ability to report on blocked artifacts within the Mend UI with a “blacklist” project, similar to the SCA behavior. Like the SCA mode, you can now allow previously blocked artifacts by ignoring the alerts within the Mend UI.

SCD - Creating Mend Policies

You will need to add a single policy to your Mend product that blocks everything. To do this, please follow the steps below:

1. Within the Mend UI, navigate to your product > Policies.

   

2. On the Policies page, click Add Policy.
   

   

3. On the Add Policy page, add the Name of your policy. It is recommended that you name the policy so that you will know what it means when viewing the properties in Artifactory.

   

4. Set the Match type to By Glob Pattern on Resource Name, and add two asterisks (**) to the value.

   

5. For the Action type, select Reject.

   

6. Click Add at the bottom-right corner of the page.

7. You will be reverted to your Product Policies page. Click Save to save your newly-created policy.

   

SCD Integration Flow

For each new remote download, the Mend for Artifactory plugin will call the SCD integration.

1. If the package is “clean”, the plugin will allow the download.

2. Otherwise, the plugin will behave as follows: 

   1. Call checkPolicies parameter.

   2. If scd.checkPolicies=true, all packages are blocked due to the new policy created in the "SCD - creating Mend policies" section, which in turn, blocks the download.

   3. After the first time a package is blocked, it will then be visible in the UI as a policy violation alert.

Within the Mend UI, you may choose to ignore the alert to allow the blocked package to be downloaded via the Licensing & Compliance Alerts > Ignore Alerts option. For example:

If the Mend user ignored the alert in the Mend UI, then in the next run, the package will be allowed to download.

Note: Artifactory will persist in trying to download blocked packages if users continue to request them.

SCD Example - NPM

Defining a remote repository

1. Within JFrog, navigate to the Administration tab > Repositories → Add Repository → Remote Repository.

   

2. Select the required repository package type.

   

3. In the newly-opened window, enter the required repository key.

4. Click Create Remote Repository.

Setting up the associated package manager

1. Now, from the Application tab, navigate to Artifactory → Artifacts → select your newly-created repository.

2. At the upper-right corner, click Set Me Up and follow the provided instructions.

   

NPM Package Manager

1. Run the following command in your terminal:

   CODE

   npm config set registry http://your-artifactory-url:port/artifactory/api/npm/repo-name/

2. Using the credentials set when creating the Artifactory repository, run the following command:

   CODE

   npm login

A configuration message should appear when successful.

Attempting to download:

When a user attempts to download a malicious NPM package, for example, ua-parser-js@0.7.29, they will receive the following error:

SCD Logs

Log Location

The Artifactory service log file can be found under - $JFROG_HOME\artifactory\var\log\artifactory-service.log. It can also be viewed in JFrog from the Administration tab under Monitoring → System Logs → Select Log File → artifactory-service.log:

Log Examples

triggerBeforeRemoteDownload

The following log message will be displayed when trying to install a “bad” package via a package manager:

[WARN] beforeRemoteDownload - Rejected package even-more-externals:3.0.0 request - Diffend status: LibraryQueryResponse{status='blocked'}

For both NPM and Ruby, you will receive a 403 http status code as the requested package is being blocked.

NPM

Ruby

Cron-based Job

The following messages will be displayed when a “blocked” package is detected during a cron scan:

[INFO] - DiffendAgent - START - Cron artifacts scan
[WARN] - checkArtifacts - Bad Package - Action needed for PackageInfo{npm:even-more-externals:3.0.0}
[INFO] - move - START - move artifact npm-demo-remote-cache:even-more-externals/-/even-more-externals-3.0.0.tgz into quarantine-repo
[INFO] - move - END - Success moving artifact npm-demo-remote-cache:even-more-externals/-/even-more-externals-3.0.0.tgz into quarantine-repo
[INFO] - DiffendAgent - End - Cron artifacts scan

(SCD) Non-supported repository

The following log message will be printed when running the SCD integration on a non-supported repository (SCD only supports NPM and Ruby):

[DEBUG] - isDiffendSupported - Unsupported diffend registry type: maven: repository: maven-remote

Appending SCD Logs

You can edit the logback.xml file located at $JFROG_HOME/artifactory/var/etc/artifactory/logback.xml to include the SCD logs. The new log file, wss-plugin.log, will be available at $JFROG_HOME\artifactory\var\log.

To include the SCD logs, add the following inside the configuration element (between the <configuration> and </configuration> tags):

<appender name="WSS-PLUGIN-APPENDER" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <File>${log.dir}/wss-plugin.log</File>
    <rollingPolicy class="org.jfrog.common.logging.logback.rolling.FixedWindowWithDateRollingPolicy">
        <FileNamePattern>${log.dir.archived}/wss-plugin.%i.log.gz</FileNamePattern>
    </rollingPolicy>
    <triggeringPolicy class="org.jfrog.common.logging.logback.triggering.SizeAndIntervalTriggeringPolicy">
        <MaxFileSize>25MB</MaxFileSize>
    </triggeringPolicy>
    <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
        <layout class="org.jfrog.common.logging.logback.layout.BackTracePatternLayout">
            <pattern>%date{yyyy-MM-dd'T'HH:mm:ss.SSS, UTC}Z [jfrt ] [%-5p] [%-16X{uber-trace-id}] [%-30.30(%c{3}:%L)] [%-20.20thread] - %m%n</pattern>
        </layout>
    </encoder>
</appender>

<logger name="whitesource-artifactory-plugin" level="info">
	<appender-ref ref="WSS-PLUGIN-APPENDER"/>
</logger>

SCD Integration Log Levels

The default log level for the plugin is "info". After verifying that the plugin is working as expected, it is recommended to change the log level to "warn" (to reduce noise). In the case of troubleshooting, it is recommended to set the log level to "debug".

To change the plugin log level, add the following to ${ARTIFACTORY_HOME}/etc/logback.xml:

<logger name="whitesource-artifactory-plugin">
    <level value="info"/>
</logger>