| Warning | ||
|---|---|---|
| ||
This page is now hosted on https://odp.finos.org/docs/development-infrastructure/code-validation/whitesource |
| Info | ||
|---|---|---|
| ||
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:
|
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 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; please find the issue details on the WhiteSource docs page
| Note | ||
|---|---|---|
| ||
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
configurationBelow is the default configuration suggested by FINOS, which is the same provided by default; more parameters and configurations can be found on WhiteSource integration docs page.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
| Code Block | ||||
|---|---|---|---|---|
| ||||
{
"scanSettings": {
"configMode": "AUTO",
"configExternalURL": "",
"projectToken" : "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
- When enabled, the app will create a Puill Request to add a
.whitesourcefile in the codebase root
- When enabled, the app will create a Puill Request to add a
- 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
.whitesourceinto your GitHub repository - Copy the FINOS blueprint
whitesource.configinto your GitHub repository - Configure your project
excludesin 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.