Overview

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

Previous Plugin Versions

Installing the Plugin

NOTE: For details on how to migrate from a previous version of the Artifactory Plugin earlier than 21.12.1, see Migrating the Artifactory Plugin.

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

// 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

archiveIncludes

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.

/**
 * 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:

<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

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:

   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:

   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:

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

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