Near Real Time scanning

WhiteSource runs project scanning in near-real-time: every time a new CVE gets spotted on a library that is used by the project, the vulnerability is notified. Scanning can also happen:

At build time, using the WhiteSource unified agent
On code change, using the WhiteSource integration for GitHub.com

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 vulnerabilities (CVEs) across all FINOS hosted projects, making use of the WhiteSource for Github.com integration, providing:

Automatic (and configurable) scanning of all commits on the default branch (commonly master) and Pull Requests
Automatic (and configurable) scanning of all Pull Requests against the default branch (commonly master)
Support for most of languages and build tools currently used in FINOS projects
Creation of GitHub issues with CVE description and meta

Responsible disclosure

Since GitHub Issues for public repositories are all public (and permissions cannot be altered), all CVE reporting would be publicly available, posing a security risk for deployed installations of FINOS projects. We are working with WhiteSource to figure out a way to enable email notifications, disable GitHub issues and keep the rest of the workflow as it is.

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 FINOS configuration from https://github.com/finos/project-blueprint . More info can be found on https://whitesource.atlassian.net/wiki/spaces/WD/pages/489160834/Unified+Agent+Configuration+File+Parameters

Enable WhiteSource scanning

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

Testing WhiteSource scanning

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, you must:

Copy the FINOS blueprint .whitesource into your GitHub repository
Copy the FINOS blueprint whitesource.config into your GitHub repository
Configure your project excludes in whitesource.config
Send a Pull Request to your project and see the WhiteSource scanning in action

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.

WhiteSource for GitHub.com