Artifactory Plugin

Overview

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

This topic describes how the JFrog Artifactory plugin integrates with Mend. The plugin adds additional information to the Artifactory artifacts and updates Mend.  Once invoked, all the artifacts' metadata on the Artifactory will be uploaded to the Mend inventory. The Artifactory plugin supports two use cases, our SCA and Supply Chain Defender (SCD).

  • Artifactory instance is mapped to Mend product. 

  • Artifactory repositories will be mapped to Mend projects.

  • Policies will be enforced and policy details will be added to the artifacts property tab: WSS-Action (Approve/Reject) and WSS-Policy-Details.

  • Additional data for each artifact will be added to the property tab: WSS-Licenses, WSS-Description, WSS-Homepage and WSS-Vulnerabilities.

The plugin is licensed under the Apache 2.0 license.

NOTES

  • The Mend inventory will be updated only when using a cron-based job, if the updateWss property is set to true.

  • Artifactory editions not supported by the Groovy-based User Plugins are not supported by Mend.

  • Scanning of Docker repositories is not supported.

  • Scanning of virtual repositories is not supported.

  • The recommended integration method for the JFrog Artifactory is using the Unified Agent.

  • Updates in Artifactory: The plugin updates Artifactory repositories with no more than 10,000 artifacts.

  • Updates in Mend: The plugin updates Mend with repositories with no more than 2,000 artifacts.

How the Artifactory Plugin Works

The Artifactory plugin works in the following modes:

  1. Cron-based job: When invoked, repository artifacts will be updated in Mend and additional data will be added to the property tab of each artifact.

  2. After create: In this mode, when a new artifact is uploaded to Artifactory, Mend policies are triggered and additional data is added to the property tab of the artifact. This mode is controlled by the triggerAfterCreate property.

  3. Before download: In this mode, only Mend policy-approved artifacts will be downloaded from remote or local repositories. This mode is controlled by the triggerBeforeDownload (for downloading from local repositories) and triggerBeforeRemoteDownload (for downloading from remote repositories) properties.

Downloading the Plugin

Latest Plugin Version

File

Features

Release Date

MD5

Latest Plugin Version

File

Features

Release Date

MD5

22.6.1

whitesource-artifactory-plugin-22.6.1.zip

Release Notes 22.6.1

2022-06-27

358EDE072FA8A49C3EDD7627B7615E36

Previous Plugin Versions

Version

File

Features

Release Date

MD5

Version

File

Features

Release Date

MD5

22.3.1.1

whitesource-artifactory-plugin-22.3.1.1.zip

security vulnerability fixes

2022-03-31

E70AFF03202285872BDBF4F07E97A986

22.3.1

whitesource-artifactory-plugin-22.3.1.zip

Release Notes 22.03.1

2022-03-20

5BDDC4AE889385788F44A58E32641A0B

21.12.1

whitesource-artifactory-plugin-21.12.1.zip

Release Notes 21.12.1

2021-12-26

FD435A4B3C7D2EAC3D07DC5FA6774789

21.7.2

whitesource-artifactory-plugin-21.7.2.zip

Temp folders deletion fix & upgrade dependencies versions

2021-08-15

1B4B6DE62613AD5F52B8B162F6A7993D

20.9.1

whitesource-artifactory-plugin-20.9.1.zip

Fix typo

2020-10-04

3A238385348051D7AD24EE166F26F935

20.7.3

whitesource-artifactory-plugin-20.7.3.zip

Support Artifactory 7.x 

2020-08-16

0A26F0B1CA1A7C2C5FA012D9AED3ED4C

20.6.2

whitesource-artifactory-plugin-20.6.2.zip

Bug fixed - Block artifact in before download in case of policy violation.

2020-07-07

A766DE35D4D39C7C5761E1F7F49501E7

20.5.1

whitesource-artifactory-plugin-20.5.1.zip

Bug fixes

2020-05-24

0F7A360476D0B870229CF54C500A5AC4

Installing the Plugin

NOTE: For details on how to migrate from a previous version of the Artifactory Plugin earlier than 21.12.1, see https://whitesource.atlassian.net/wiki/spaces/WD/pages/2445705254.

Artifactory Version <= 6.x

  1. Download the zip file and extract it.

  2. Replace 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 new whitesource-artifactory-plugin-VERSION.jar file in the plugins/lib directory.

  5. Update the whitesource-artifactory-plugin.properties file with the appropriate parameters (see Cron Scheduling Example and General Parameters).

  6. Schedule the cron job in the whitesource-artifactory-plugin.groovy file (see Cron Scheduling Example).

  7. Restart Artifactory.

Artifactory Version >= 7.x

  1. Download the zip file and extract it.

  2. Replace 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 new whitesource-artifactory-plugin-VERSION.jar file in the plugins/lib directory.

  5. Update the whitesource-artifactory-plugin.properties file with the appropriate parameters (see Cron Scheduling Example and General Parameters).

  6. Schedule the cron job in the whitesource-artifactory-plugin.groovy file (see Cron Scheduling Example).

  7. Restart Artifactory.

Configuring the Plugin

Properties File Example

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 // Mend-artifactory-plugin properties file wssUrl="" // wssUrl="http://localhost:8080/agent" // Organization Token: apiKey="<your WSS api key>" // UserKey Token: Unique identifier of user, can be generated from the profile page in your Mend account. //userKey="<your WSS user key>" // Product Name - represents Artifactory instance, Artifactory repository represents project // In order to map repository to a product in Mend mark this field as comment productName="<your Artifactory representing name>" // Check Policices. will check only delta between WSS and current files checkPolicies=false // check all files all the time. if true that checkpolicies must also be true forceCheckAllDependencies=false // update WSS updateWss=false // update WSS regardless of the check policies result forceUpdate=false // Names of the repositories in the Artifactory to scan repoKeys=["repo1","repo2","repo3"] // Proxy Settings useProxy=false //proxyHost="127.0.0.1" //proxyPort=3128 //proxyUser="" //proxyPass="" // The type of files that will be extracted and their content will be checked archiveIncludes = ["war", "ear", "zip"] // archiveExtractionDepth=2 // Once the archive was extracted, which files within it should be checked includesRepositoryContent=["m", "mm", "js", "php", "jar", "zip"] // Whether to run beforeDownload/beforeRemoteDownload/afterCreate methods (defaults to true) //triggerBeforeDownload=false //triggerBeforeRemoteDownload=false //triggerAfterCreate=false

General Parameters

Attribute

Type

Description

Required

Additional Information

Attribute

Type

Description

Required

Additional Information

wssUrl

String

URL for sending the request.

Use the ‘Mend Server URL' which can be retrieved from your Profile page on the 'Server URLs' panel. Then, add the '/agent’ path to it. For example: "https://saas.whitesourcesoftware.com/agent".

No.
Defaults to https://saas.whitesourcesoftware.com/agent



apiKey

String

Unique identifier of the organization. This can be retrieved from the Integration page in your Mend account.

Yes



userKey

String

Unique identifier of the user. This can be generated from the Profile page in your Mend account.

Yes

Supported since version 18.5.1

productName

String

Represents the Artifactory instance and product in Mend.

Comment this field to map the repository to the product in Mend (project will also represent the repository).

No



checkPolicies

Boolean

Whether or not to send the check policies request to Mend.

No



forceCheckAllDependencies





Boolean

Used only if checkPolicies is set to true.

  • Setting forceCheckAllDependencies to true will force check all policies for all dependencies introduced to the Mend projects.

  • Setting forceCheckAllDependencies to false or not using it at all will check only the new dependencies introduced to the Mend projects.

No

Supported since version 1.0.3

updateWss

Boolean

Whether or not to send an update to Mend.

Yes

Supported since version 1.0.6

forceUpdate

Boolean

Whether or not to update the organization inventory regardless of policy violations.

No. The default value is false.

Supported since version 1.0.3

repoKeys

Array

The list of the repositories to scan.

Yes



useProxy

boolean

Whether or not to use proxy settings.

Yes



proxyHost

String

Proxy host URL.

No



proxyPort

Integer

Proxy port.

No 



proxyUser

String

Proxy user name if it exists.

No 



proxyPass

String

Proxy password if it exists.

No 



archiveIncludes

String

Comma separated list specifying the types of files that will be extracted.

No.
The default list includes the following:
jar, war, ear, egg, zip, whl, sca, sda, gem, tar.gz, tar, tgz, tar.bz2, rpm, rar.

Supported since version 1.0.3

archiveExtractionDepth

String

Drill down hierarchy level in archive files.
Max value is 7.

No, the default value is 2.

Supported since version 19.4.2

includesRepositoryContent

String

Comma separated list specifying which files to include in the scan once the archive is extracted according to the parameters in:

1 archiveIncludes

No

Required since version 1.0.3

triggerBeforeDownload

Boolean

Whether or not to enforce a Mend policy check on downloaded artifacts from local repositories. When enabled, only Mend policy-approved artifacts will be downloaded.

No, the default value is true.

Supported since version 18.10.3

triggerBeforeRemoteDownload

Boolean

Whether or not to enforce a Mend policy check on downloaded artifacts from remote repositories. When enabled, only Mend policy-approved artifacts will be downloaded.

No, the default value is true.

Supported since version 21.12.1

triggerAfterCreate

Boolean

Whether or not to trigger the afterCreate method.

When a new artifact is uploaded to Artifactory, Mend policies are triggered and additional data is added to the property tab of the artifact.

No, the default value is true.

Supported since version 18.10.3

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.

Cron Scheduling Example

This example demonstrates how to configure a schedule for scanning the Artifactory repositories.

  1. Open the Mend-artifactory-plugin.groovy file in a txt editor.

  2. To configure the interval at which the Artifactory repositories are scanned, modify the def scanRepositoriesCron = "0 0 0 * * ?" string in the plugin groovy file.

1 2 3 4 5 6 7 8 9 10 11 12 /** * scanRepositoriesCron (java.lang.String) - A valid cron expression used to schedule job runs. * Modify this parameter to configure the desired schedule to scan your artifactory repositories. * See README.md for examples. */ def scanRepositoriesCron = "0 0 0 * * ?" jobs { scanRepositories(cron: scanRepositoriesCron) { pluginAgent.runRepositoriesScan() } }

scanRepositoriesCron parameters (from left to right):

1 - seconds, 2 - Minutes, 3 - Hours, 4 - Day-of-Month, 5 - Month, 6 - Day-of-Week, 7 - Year (optional field).

Examples:

  • "0 42 10 * * ?" - Build a trigger that will fire daily at 10:42 am.

  • "0 0/2 8-17 * * ?" - Build a trigger that will fire every other minute, between 8am and 5pm, every day. 

For more details, see Cron expression.

SCA Plugin Log Levels

The default log level for the plugin is "warn". To change the plugin log level, add the following to ${ARTIFACTORY_HOME}/etc/logback.xml:

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

Supply Chain Defender (SCD) Integration

Our Artifactory SCD integration supports only NPM and Ruby repositories. Unsupported repositories will not be affected by our SCD.

Properties File SCD Parameters

Please use the same properties file as mentioned prior in this article and add the following additional parameters in order to use the SCD integration.

Attribute

Description

Required

Default Value

Attribute

Description

Required

Default Value

scd.auth.email=””

The email corresponding to the userKey.

Yes

None

scd.repoKeys=["repo-name"]

The list of Artifactory repositories to be scanned by Supply Chain Defender.

This applies to both cron-job and beforeRemoteDownload.

Yes

None

scd.beforeRemoteDownload=

Enables single package query.

No, however, we recommend setting this parameter to true.

false

scd.beforeRemoteDownload.strictness=""

Applies to triggerBeforeRemoteDownload only.

This flag controls the level of allowed/rejected packages by Mend Supply Chain Defender.
Available values:

  • "blocked" - Reject only confirmed malicious package releases

  • "flagged" - Reject malicious package releases plus any which have been flagged and pending manual inspection by Mend

  • "unscanned" - Reject any package release which is confirmed malicious, flagged for review or awaiting scan

e.g. If set to "flagged", then both "flagged" and "blocked" packages will be rejected

No

"flagged"

scd.cron.quarantine="target-repo-name"

Applies to the cron-job mode only.

The cron-job deletes bad packages from the repositories. If scd.cron.quarantine is set and the repository exists, "bad" packages will be moved to this repo, instead of being deleted.

Note: Useful for auditing bad packages.

No

None

scd.cron.dryrun=

Used for testing, prints messages without the actual action.

  • Action: cron-job: delete/move packages

No

false

scd.aliases.npmjs=[““]

URLs of remote repositories to be treated the same as the official “npmjs” registry.

e.g. scd.aliases.npmjs=["https://registry.yarnpkg.com"]

No

None

scd.aliases.rubygems=[““]

URLs of remote repositories to be treated the same as the official “rubygems” registry.

No

None

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 our SCD, otherwise, it is blocked.

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

A few items to note:

  • 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 that are defined in the scd.repoKeys parameter are scanned and checked against the SCD database. Each blocked artifact will be handled according to scd.cron.quarantine flag.

SCD Example - NPM

Defining a remote repository:

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

  2. Choose the desired repository package type:

  3. In the newly opened window, enter the desired repository key

  4. Press “Create Remote Repository”

Set-up the associated package manager:

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

  2. On the upper-right corner, press “Set Me Up” and follow the provided instructions

NPM Package Manager:

  1. Run the following command in your terminal:

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

    1 npm login

A configuration message should appear when successful.

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:

1 [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:

1 2 3 4 5 [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):

1 [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):

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 <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 the plugin is working as expected, we recommend changing the log level to "warn" (to reduce noise). In the case of troubleshooting, we recommend setting the log level to "debug".

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

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