/
WhiteSource for GitHub.com

WhiteSource for GitHub.com

Jun 22, 2020

Warning

This page is now hosted on https://odp.finos.org/docs/development-infrastructure/code-validation/whitesource

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:

  1. At build time, using the WhiteSource unified agent

  2. 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:

  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

 

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

  1. Read the  WhiteSource for Github.com integration, to know what it does and how

  2. 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

  3. 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:

  1. Copy the FINOS blueprint .whitesource into your GitHub repository

  2. Copy the FINOS blueprint whitesource.config into your GitHub repository

  3. Configure your project excludes in whitesource.config

  4. 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.

  1. A Foundation repository is a Github repository hosted by the Foundation; in WhiteSource terms, this is called a project

  2. 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.