NOTE: This is a controlled WhiteSource Integration Release. If you have a dedicated ThreadFix or Fortify Agent installation with a version earlier than v18.20.x, migrate to the latest AVM Agent. To obtain access to the latest release, please contact support@whitesourcesoftware.com.

Overview

This page describes how to integrate WhiteSource’s open-source management platform with AVM platforms. These integrations enable you to view information about the security vulnerabilities of open source components and synchronize auditing informational decisions. A dashboard is provided that displays a summary view of the vulnerability assessment for the relevant deployment.

The following steps describe how the WhiteSource Agent integrates WhiteSource's open-source management platform with an AVM platform: 

  1. The WhiteSource Agent retrieves the WhiteSource vulnerability alerts reports for the user's WhiteSource products and projects and sends these reports to the AVM platform. Only descriptive information regarding the projects or products is sent.

  2. Once configured, updates are performed on the AVM platform according to a predefined schedule. WhiteSource products and projects reports are displayed as application reports in the AVM dashboard.

  3. Based on the customer's preferences, the audit information is updated in WhiteSource or the AVM platform to reflect the most recent status of the alerts.
    For example, WhiteSource alerts could become false positive or suspended alerts in AVM, and vice versa.

After the integration has completed, all WhiteSource vulnerability alerts reports of open-source software in an organization will be continuously and automatically synchronized with WhiteSource and the relevant AVM platform. The selected WhiteSource products and projects will be updated to the relevant applications on the AVM platforms. 

Details about the configuration of specific AVM platforms are described in the following pages:

Mapping WhiteSource Entities to an AVM Application

During integration, the AVM Agent searches for the WhiteSource projects and products that were mapped to the specific AVM platform's applications. The WhiteSource Agent takes the mapping and synchronizes the vulnerability alerts between WhiteSource and the AVM platform. If any vulnerability alerts were generated for the mapped WhiteSource products and projects, the corresponding applications from the AVM platform will be updated.  

You can create a mapping between WhiteSource entities and the AVM application as follows:

Creating a Mapping Using Tags

In order to map WhiteSource products and projects to the AVM platform applications, you can manually add specifically-defined (Avm.) products/project tags, as follows:

  1. For each product that you want to synchronize with the AVM application, add the following product tags (for details, see Adding Product Tags):

    1. Key: AVM.application.name
      Value: Name of AVM application to sync, or "*" to reuse the same name as the WhiteSource product

    2. Key: AVM.application.version
      Value: Name of AVM application version to sync. If no version tag is presented, the default version 1.0 will be used.

  2. For each project that you want to synchronize with the application, add the following project tags (for details, see Adding Project Tags):

    1. Key: AVM.application.name
      Value: Name of AVM application to sync, or "*" to reuse "WS Product name\WS Project name" as the name of the application 

    2. Key: AVM.application.version 
      Value: Name of AVM application version to sync. If no version tag is presented, the default version 1.0 will be used. 

For example:

To map a specific WhiteSource project to an AVM application: 

NOTES:

Using APIs to Map Multiple WhiteSource Products or Projects to AVM Applications

The mapping process enables AVM users to automate the setting of AVM-related tags to multiple projects and products in WhiteSource, by using APIs.

Setting Project Tags

Send a POST request with the following parameters:

{
"requestType" : "saveProjectTag",
"projectToken" : "${projectToken}",
"userKey": "${userKey}",
"tagKey":"${tagName}",
"tagValue":"${tagValue}"
}

where:

The following cURL example sends a request to the WhiteSource SAAS server to synchronize the AVM application to a WhiteSource project:

curl --request POST \
  --url https://saas.whitesourcesoftware.com/api/v1.1 \
  --header 'content-type: application/json' \
  --data '{ "requestType" : "saveProjectTag", "projectToken" : "${projectToken}",  "userKey": "${userKey}", "tagKey":"AVM.application.name", "tagValue":"TestValue"}'

The response should be:

{
"projectTagsInfo":{"name":"${NameOfProject}","token":"${projectToken}","tags":{"AVM.application.name":"TestValue"}}
}

where NameOfProject is the name of the WhiteSource project that was updated.

Setting Product Tags

Send a POST request with the following parameters:

{
"requestType" : "saveProductTag",
"productToken" : "${productToken}",
"userKey": "${userKey}",
"tagKey":"${tagName}",
"tagValue":"${tagValue}"
}

where:

The following Python example sends a request to the WhiteSource SAAS server to synchronize the AVM application to a WhiteSource product:

import http.client
conn = http.client.HTTPSConnection("saas.whitesourcesoftware.com")
payload = "{\n    \"requestType\" : \"saveProductTag\",\n    \"productToken\" : \"${productToken}\",\n    \"userKey\": \"${userKey}\",\n    \"tagKey\":\"${tagName}\",\n    \"tagValue\":\"${tagValue}\"\n}"
headers = {
    'content-type': "application/json",
    }
conn.request("POST", "/api/v1.1", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

The response should be:

{ "productTagsInfo": { "name": "${NameOfProduct}", "token": "${productToken}", "tags": { "${tagName}": "${tagValue}" } } }

where NameOfProduct is the name of the WhiteSource product that was updated.

Get All Products

Send a getAllProducts POST request with the following parameters:

cURL example:

curl -X POST \
  https://saas.whitesourcesoftware.com/api/v1.1 \
  -H 'content-type: application/json' \
  -d '{
    "requestType" : "getAllProducts",
    "orgToken" : "${orgToken}",
    "userKey": "${userKey}"
}

where orgToken is the unique API key of the organization.

A successful response with all products should be:

{
    "products": [
        {
            "productId" : "product_a_id",
            "productName": "Product A",
            "productToken": "product_a_token"
        },
        {
            "productId" : "product_b_id",
            "productName": "Product B",
            "productToken": "product_b_token"
        }
    ],
    "message": "Success"
}

Get All Projects of a Product

Send a getAllProjects POST request with the following parameters:

cURL example:

curl -X POST \
  https://saas.whitesourcesoftware.com/api/v1.1 \
  -H 'content-type: application/json' \
  -d '{
    "requestType" : "getAllProjects",
    "productToken" : "${productToken}",
    "userKey":"${userKey}"
}'

A successful response with all projects will be:

{
    "projects": [
        {
            "projectId" : "project_a_id",
            "projectName": "Project A",
            "projectToken": "project_a_token"
        },
        {
            "projectId" : "project_b_id",
            "projectName": "Project B",
            "projectToken": "project_b_token"
        }
    ],
    "message": "Success"
}

Configuring the AVM Agent

The configuration of the AVM Agent can be done by:

-Or-

To configure the AVM Agent, do the following:

  1. Download the Jar file.

  2. Create a text file with the name whitesource-avm-agent.config or download it and place it in the same directory as the Jar file.

  3. Edit the file or run the Agent with the minimal set of parameters to allow end-to-end integration.

  4. Alternatively, run the Agent while setting the minimal mandatory set of parameters in the command line.   

Following are the minimal parameters that must be set in the command line: 

Parameter

Description

wss.url

  1. The wss.url parameter must point to the WhiteSource HTTP API URL. 

  2. Retrieve the 'WhiteSource Server URL' which you can copy from the Integrate page on the Server URLs panel.

  3. Then, add the /api path to the URL. (e.g., url=https://<domain>.whitesourcesoftware.com/api).
    For example: https://saas.whitesourcesoftware.com/api/v1.3. For more information, refer to HTTP API v1.3 .

wss.apiKey

Unique identifier of the organization. It can be retrieved from the Admin page in your WhiteSource account GUI.

wss.userKey

Unique user identifier. It can be generated from the Profile page in your WhiteSource account GUI.

avm.name

Name of the AVM application.

AVM platform connectivity parameters:

avm.url

URL for your Application Vulnerability Management Server.

avm.apikey or
avm.user & avm.pass

api key as defined in the AVM application’s account OR username and password for your Application Vulnerability Management Server.

Command Line Parameters

Parameter

Type

Description

Required

Default

-c (only CLI) 

String

Configuration file name (including file path)

No

whitesource-avm-agent.config

wss.apiKey

String

Unique identifier of the organization. It can be retrieved from the Admin page in your WhiteSource account GUI.

Old name: apiKey

Yes

No default value

wss.url 

String

WhiteSource HTTP API entry point. 

Old name: url

No

No default value

wss.userKey

String

Unique user identifier. It can be generated from the Profile page in your WhiteSource account GUI.

Old name: userKey

No, unless the WhiteSource administrator enabled the Enforce user-level access option.

No default value

generateOfflineReport

Boolean

Whether to perform the scan in offline mode and generate a zip file for each product/project in your WhiteSource organization.

No


false

force_sync

Boolean

Whether to synchronize all products/projects or only updated products/projects.
When the value is false, synchronize only data in these cases:

  • A new Unified Agent scan on the project/product.

  • A new alert was found on a dependency that exists in the project/product.

  • A new major version was found on a dependency that exists in the project/product.

  • The alert status was changed manually in the application.

 No

true

wss.proxy

String

A proxy that should be used  to connect HTTP platform, overwrites proxy parameter below.

No

No default value

fromDate

String

Fetch vulnerability alerts from WhiteSource from the specified date.

No

No default value

toDate

String

Fetch vulnerability alerts from WhiteSource until the specified date.

No

No default value

wss.connectionTimeout

Integer

WhiteSource connection timeout is measured in milliseconds.

Old name: connectionTimeout

No

Default value is 120,000 milliseconds.

-requestFiles (only CLI) 

String

Provide comma-separated list of absolute paths to generated by offline requests.
This action uploads the offline request file(s) to AVM platform. 

No

No default value

whiteSourceFolderPath

String

Path to the whitesource folder. This folder is created when retrieving the vulnerability alerts report in offline mode. The path can either be absolute or relative.

Only CLI for now

No

Default value is the folder from which the agent is running

synchronizeFrom

String

The direction of alerts status synchronization. 
If the value is set to WS:

  • Alerts (WS) → False Positive Alerts

  • Alerts (WS) → Suppressed Alerts 

If the value is set to AVM:

  • False Positive Alerts → Alerts (WS) 

  • Suppressed Alerts → Alerts (WS)

No

AVM

avm.application.sync

Boolean

If enabled, the specified applications are created in AVM. Includes all the products/projects in WhiteSource that have the tag "AVM.application.name". This will also create the application versions according to the "AVM.application.version" in WhiteSource.

If disabled, no applications will be created on AVM.

No

true

avm.name

String

The AVM application name.

Yes

Fortify

avm.url

String

API base URL for your application vulnerability management server.

For example: "https://threadfix.example.com:8080/threadfix".

No

No default value

avm.apikey

String

api key as defined in the AVM application’s account.

No, if avm.user and avm.pass are set.

No default value.

See https://denimgroup.atlassian.net/wiki/spaces/TDOC/pages/22619214/API+Keys

avm.user

String

Username for your application vulnerability management server

No if avm.apiKey is defined

No default value

avm.pass

String

User's password for your application vulnerability management server

No, if avm.apiKey is defined

No default value

threadfix.team.name

String

Name of team to add applications (ThreadFix only)

No

No default value. If left empty, WS organization name will be  used to create a new team.

avm.proxy

String

A proxy that should be used to connect the AVM platform; overwrites the proxy parameter below. 

No

Format  protocol://<user>:<password>@host\:port/

avm.connectionTimeout

Integer

AVM connection timeout measured in milliseconds.

No

50,000 milliseconds.

avm.pluginName


Engine name at your application vulnerability management server.

No

No

include_avm_applications

String

Enables including AVM applications to be synchronized.

  • Value format should be a comma-delimited regular expression.
    For example:
    include_avm_applications = *Dev.* includes all AVM application names that contains this sub string.
    For example: projectDev, Dev1, …..

  • If the parameter isn’t set or has an empty value, it will include all AVM applications.

No

No default value

exclude_avm_applications

String

Enables excluding AVM applications to be synchronized.

  • Value format should be a comma-delimited regular expression.
    For example:
    exclude_avm_applications = *Dev.* excludes all AVM application names that contains this sub string.
    For example: projectDev, Dev1, …..

  • If the parameter isn’t set or has an empty value, it will not exclude any AVM applications.

  • When both include_avm_applications & exclude_avm_applications are populated, the system will first apply the include REGEX and then the exclude REGEX.

No

No default value

-deleteAlerts (only CLI) 

String

Deletes the Artifact History from AVM for the specified applications.
Enter a comma-separated list of applications as they are displayed in the WhiteSource GUI (case-sensitive).
Entering "*" removes all Artifact History and AVM Issues from AVM for all WhiteSource generated applications.

No

No default value

-deleteApplications (only CLI) 

String

Deletes all specified applications from AVM. Enter a comma-separated list of applications as they appear in WhiteSource (case-sensitive). Entering "*" removes all WhiteSource generated applications from AVM.
Note: Before deleting an AVM application, make sure that all of its issues are deleted.

No

No default value

proxy

String

HTTP Proxy to use by Agent. Could be overwritten by avm.proxy and/or wss.proxy

No

Format  protocol://<user>:<password>@host\:port/

-h  (CLI only) 
or
-help

String

Provides an explanation of all parameters.

No


logLevel

String

Define the debug level for logs. Options are INFO and DEBUG. 

Example: -logLevel DEBUG

Optional values: ALL, DEBUG, INFO, WARN, ERROR, OFF

No

INFO

Note: Almost all command line parameters match configuration file parameters (the exclusions are explicitly listed in the table above). Use "-" + parameter

Configuration File & Parameters

The WhiteSource Agent’s configuration file and its supported parameters can be downloaded from here: whitesource-avm-agent.config.

Running the AVM Agent

Best Practices

The following best practices are recommended:

Use Case Examples

Following are some use cases showing syntax examples for running the WhiteSource->AVM platform integration:

Example of a crontab entry for running daily at 2:15pm:
15 14 * * * /path/to/cron/cronjob.sh </dev/null > /path/to/logs/output.txt 2>&1

Synchronizing Alerts Statuses between WhiteSource and the AVM Platform

The status of alerts is defined in the WhiteHouse Alerts report (see The Alerts Report). Alerts can have the status of active, ignored, or restored.

Starting from Version 19.11.1, AVM can synchronize the Alerts' status with the corresponding status of alerts in AVM platforms in a bi-directional manner.

To initialize the synchronization process of alerts' statuses, set the synchronizeFrom parameter in the whitesource-avm-agent.config file (see Configuration File & Parameters), and indicate the direction of synchronization. The default direction is from AVM to WhiteSource (#synchronizeFrom=WS).

NOTE: If you anticipate a large number of alerts that must be synchronized, enlarge the volume of memory directed to the Java process using the -Xmx flag, according to the following measurements:

For example:
-Xmx2G indicates that when the maximum heap size is set to 2GB, 11,000 alerts can be processed.