Whitesource

Name	Whitesource
Status	Delivered
Link	whitesourcesoftware.com
Topics	Legal, Security, Quality
Languages	Javascript

WhiteSource automatically identifies all the open source components and dependencies in your build by constant and automatic cross-referencing of your open source components against WhiteSource’s definitive database of open source repositories. WhiteSource provides a dedicated instance to validate and enforce security and legal compliance for all Symphony Software Foundation hosted projects.

Below are listed the main WhiteSource features that have been adopted by Foundation projects.

1. Check libraries for outdated versions
2. Check libraries for security vulnerabilities
3. Check libraries for bugs
4. Check libraries for problematic/undefined licenses
5. Check libraries for release activity
6. Integration with CI environments

Glossary

To avoid confusion, below are listed some WhiteSource concepts that differ with the definitions used within the Foundation.

1. A FINOS repository is a Github repository hosted by the Foundation; in WhiteSource terms, this is called a project
2. A FINOS Project is a logical entity that includes a. one or more project leaders b. a project team c. one or more Foundation repositories; if one, project and repository will have the same name. d. In WhiteSource terms, this is called a product and can be accessed directly by the WhiteSource main menu; each WhiteSource Product will list below the projects included.
3. Foundation WhiteSoure dashboard - WhiteSource provides a dedicated instance for the Foundation projects that can be accessed a. by all project leaders, to check and export project metrics b. by Foundation Staff, to configure Foundation WhiteSource policies
4. Foundation WhiteSource policies - A collection of rules and workflows implemented in the WhiteSource dashboard by the Foundation team to enforce security and legal compliance; below are reported the details.
5. Alert - The visual notification that WhiteSource shows in the main dashboard when a policy violation is found

Features

WhiteSource provides the following features to Foundation project leads/committers that have been granted access:

1. Access the WhiteSource dashboard for one or more projects a. Access WhiteSource Due Diligence and Risk reports b. Browse (and drill down) through project libraries c. Browse (and drill down) through licenses found in the project d. Check alerts and warnings triggered by policy violations
2. Configure WhiteSource build plugins to upload project metrics
3. Configure Travis CI (or other CI environments) to continuously a. validate code against Foundation policies enforced by WhiteSource b. fail the build, if any policy violation is found c. upload project metrics to the WhiteSource Foundation dashboard

WhiteSource Policies

Below are the WhiteSource policies that have been configured by the Foundation and are enforced across all integrated projects; all libraries that are scanned in a project are matched against the following policies, in the order reported below, until a policy is matched.

1. [SECURITY] Reject High Security Vulnerability Severity - any library that contains high level CVEs is marked as Rejected,
2. [SECURITY] Reject High Security Vulnerability Score - any library that contains CVEs with score higher than 7 is marked as Rejected,
3. [QUALITY] Reject High Bug Rating - any library high bug rating is marked as Rejected,
4. [LEGAL] Licenses that require review - any library with unknown license is marked as Rejected,
5. [QUALITY] Reassign Low Version Activity - any library with a low amount of versions released is Reassigned to the project lead for validation,
6. [QUALITY] Reassign Stale (5 years) Library - any library without a release for more than 5 years is Reassigned to the project lead for validation,
7. [LEGAL] Reject Problematic (Category X license) libraries - any library using a Category X license, as indicated in our contribution legal requirements, are marked as Rejected.

Note that legal policies are currently disabled due to the large amount of false positive generated by dual-licensed libraries. We are working to improve things.

Integration with GitHub.com

FINOS have rolled out the WhiteSource integration for Github.com, which enables:

1. Automatic (and configurable) scanning of all commits on the default branch (commonly master) and Pull Requests
2. Automatic (and configurable) scanning of all Pull Requests against the default branch (commonly master)
3. Support for most of languages and build tools currently used in FINOS projects
4. Creation of GitHub issues with CVE description and meta; please find the issue details on the WhiteSource docs page

FINOS default configurations

There are 2 configuration files to define at repository level, in order to enable the WhiteSource integration with GitHub.com: .whitesource file configures the bot and whitesource.config configures the WhiteSource agent.

.whitesource

Specifies whether to use GitHub Issues or not and points to the WhiteSource agent configuration. You can copy this file definition from https://github.com/finos/project-blueprint

.whitesource
{
  "scanSettings": {
    "configMode": "LOCAL"
  },
  "checkRunSettings": {
    "vulnerableCheckRunConclusionLevel": "failure"
  },
  "issueSettings": {
    "minSeverityLevel": "LOW"
  }
}

whitesource.config

Specifies build-time configurations, including language-specific settings, file inclusions/exclusions and more. You can copy the default configuration from FINOS project blueprint. More info can be found on parameters docs page

Enable WhiteSource scanning

1. Read the WhiteSource for Github.com integration documentation, to know what it does and how
2. Email help@finos.org to request the activation of WhiteSource integration on a FINOS hosted project a. When enabled, the app will create a Pull Request to add a .whitesource file in the codebase root
3. Merge the Pull Request raised on point #2

Testing WhiteSource scanning

caution

This integration only scans for new CVEs that are introduced by a code change, therefore the build is triggered only when a build descriptor is updated, ie pom.xml or package.json.

If you'd like to be notified about new and upcoming CVEs, please email help@finos.org and request email notification for new CVEs spotted on a given project.

The easiest and less invasive way to test is to create a new branch, add a dependency with security vulnerabilities and commit the change; few minutes later (time depends on build complexity), the app will have created one GitHub Issue for each CVE found.

If no issues are created, and want to know if the scan was performed, email help@finos.org and FINOS team will help you debugging bot's execution.

Configuring WhiteSource scanning

False positives are expected, when enabling the WhiteSource integration, because of a long list of factors related with the (sometimes low) quality of the downstream library that you're consuming; being able to fine-tune the WhiteSource agent is very important, in particular excluding files and folders that should not be scanned, which is necessary most of the times.

To have the ability to exclude files and folders, please follow instructions on https://docs.mend.io/bundle/integrations/page/global_repo_configuration.html

Please note that there may be additional configurations to apply, based on your build requirements and tools; build-specific configurations can be viewed on WhiteSource Agent docs, and see what applies to your project configuration.

Build integration

As alternative to the GitHub.com integration, WhiteSource also provides an agent (CLI tool) that can be downloaded and executed from any environment; this may be necessary in case the project's build tool or language are not supported by WhiteSource and some custom build logic must be performed to prepare for the scanning.

Many build servers are supported, including Travis CI, the most used tool used by FINOS hosted projects

Glossary To avoid confusion, below are listed some WhiteSource concepts that differ with the definitions used within the Foundation.

A Foundation repository is a Github repository hosted by the Foundation; in WhiteSource terms, this is called a project A Foundation project is a logical entity that includes one or more project leaders a project team one or more Foundation repositories; if one, project and repository will have the same name. In WhiteSource terms, this is called a product and can be accessed directly by the WhiteSource main menu; each WhiteSource product will list below the projects included.

Additionally, a convenience script has been created and saved to https://github.com/finos/contrib-toolbox/blob/main/scripts/wss-maven-scan.sh which can be used for simplifying one-off scanning of projects; it requires a WhiteSource API key that must requested via help@finos.org, and accepts GitHub repo coordinates, a GitHub user/org name and a GitHub repository name.

Below an example to submit metrics for the Open Developer Platform repo.

export WSS_API_KEY="xxx"
curl -L https://raw.githubusercontent.com/finos/contrib-toolbox/master/scripts/wss-maven-scan.sh | bash -s -- finos software-project-blueprint

Request access

You can request access to the FINOS WhiteSource dashboard if you're part of a FINOS project team; please send an email to help@finos.org that specifies:

1. the email address you'd like to use to login
2. the Foundation project you would like to scan with WhiteSource