Overview

This topic describes how the JFrog Artifactory plugin integrates with WhiteSource. The plugin adds additional information to the Artifactory artifacts and updates WhiteSource.  Once invoked, all the artifacts' metadata on the Artifactory will be uploaded to the WhiteSource inventory.

• Artifactory instance is mapped to WhiteSource product. 

• Artifactory repositories will be mapped to WhiteSource 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 WhiteSource 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 WhiteSource.

• 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 WhiteSource: The plugin updates WhiteSource 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 WhiteSource 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, WhiteSource 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 WhiteSource 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

// whitesource-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 whitesource account.
//userKey="<your WSS user key>"

// Product Name - represents Artifactory instance, Artifactory repository represents project
// In order to map repository to a product in WhiteSource 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 whitesource-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.

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>