| Table of Contents |
|---|
Overview
The WhiteSource platform enables security and compliance professionals to enforce policies automatically throughout their Software Development Life Cycle.
...
NOTE: You can set up customized Workflow Rules for all or a selected list of WhiteSource products or projects which will generate fix Pull Requests based on vulnerability severity or CVSS score. For details, see here.
How Do Policies Work?
When a new inventory request is uploaded to the WhiteSource server, the policies mechanism is triggered. The open-source library code is automatically scanned to see exactly which licenses, libraries and security vulnerabilities are in the code. Security or compliance professionals can decide whether any new library that does not match an In-House or Whitelist rule should be permitted or not.
...
A policy check summary report of the results is generated in HTML and JSON formats (located in the whitesource folder created in the directory from where the Agent was run) and can also be presented within the build server console via API.
Matching a Policy to a Library
Libraries are matched with the defined policies. A match type defines which criteria of the library should be checked in order to determine if the action should be applied to it.
...
Match Type | Description |
|---|---|
License Group NOTE: In the API, use "LICENSE". | The library license is matched against specific licenses in a selected group or a specific license group, and the policy is enforced per the rules. |
GLOB Pattern on Resource Name NOTE: In the API, use "RESOURCE_NAME_REGEX". | The library name is matched against a given GLOB Pattern. |
GLOB Pattern on GAV Custom Attributes NOTE: In the API, use "GAV REGEX". | The library's GAV (Group Artifact Version) strings are matched against the provided GLOB pattern. You can define only 1 or 2 of the 3 parameters (Group Id, Artifact Id and Version). For example, Apache (Group Id) and Commons (Artifact Id). |
Security Vulnerability Severity NOTE: In the API, use "VULNERABILITY_SEVERITY". | The library is matched against the security vulnerability severity. There are three levels of severity (as defined by the NVD): High, Medium and Low. The policy will perform the action on libraries that have a least one security vulnerability, per severity, with the selected severity. For example, a component with 1 High severity vulnerability and 2 Low severity vulnerabilities will be considered as High and the relevant policy will be enforced on it. If Prioritize is enabled, you have the option to apply this match only to libraries with Effective Vulnerability (i.e. at least one reported vulnerability was detected as a "red shield") by selecting the Only Libraries with Effective Vulnerabilities check box. |
Security Vulnerability Score (CVSS 3) NOTE: In the API, use "VULNERABILITY_SCORE". | The library is matched against the security vulnerability CVSS 3 score. The score can be any number between 0-10. NOTE: As of version 20.1.3, bug rating and version activity match types were removed. Existing organizations will no longer be able to add these match types when creating a new policy. They will remain, however, for organizations that already have this policy so they will still be editable. |
Library Age NOTE: In the API, use "LIBRARY_STALENESS". | The library is matched against the library age, which can be defined in months (1-240 months). The policy will perform the action on libraries that were released during the specified number of months. |
Primary Attribute Value NOTE: In the API, use "PRIMARY_ATTRIBUTE_VALUE". | If a component is marked with this attribute value, the library is matched against its attribute value. |
Library Request History NOTE: In the API, use "LIBRARY_REQUEST_HISTORY". | The policy performs the action on libraries according to previous actions which were performed on them. |
Exists in Product’s Inventory NOTE: In the API, use "PRODUCT". | The policy performs the action on libraries that were previously approved and available in the selected product inventory. |
Vulnerability Effectiveness (prioritize shields) NOTE: In the API, use "EFFECTIVENESS". | The policy performs the action on libraries that have at least one security vulnerability with the selected shield type: red, yellow, green, or grey. Selecting None for Vulnerability Effectiveness indicates a policy for libraries that do not have shields. NOTE: For customers with Vulnerability-Based Alerting enabled, grey shields are not displayed. |
Applying Actions to a Library
The Action is the operation the policy runs on a matched library.
NOTE: A library or request can be matched to only one type and execute only one action.
You can apply one of the following actions on a matched library:
Action | Description |
|---|---|
Approve | Automatically approves the library. The request will be automatically closed. |
Reject | Automatically rejects the library:
|
Reassign | Workflow - reassigns the request to a designated user or group in the system which is not the default approver. NOTE: For a Reassign action to take effect, the Open pending tasks for new libraries check box (Integrate tab > Advanced Settings) must be selected. |
Conditions | Workflow - automatically assigns conditions and open tasks on libraries. NOTE: For a Conditions action to take effect, the Open pending tasks for new libraries check box (Integrate tab > Advanced Settings) must be selected. A request is opened for the default approver and sub-tasks are opened as “conditions” for the different assignees according to the policy definition. Conditions will be automatically sent to assignees when libraries are matched. Conditions can be assigned to a single user/group or to different members of a group/organization. The Conditions are added to the Pending Tasks panel and the Request Details page where assignees can view the original library request and update the status of the conditions after handling their assigned conditions. By clicking one of the following check boxes, you can choose to set conditions to trigger the automatic approval or rejection of the original request based on the resolution of the relevant assignees:
The assignee can mark the condition as Satisfied or Rejected. The assignee can also suggest to the approver another user to review the condition, by clicking Propose Reassignment. Only the approver is allowed to change assignees. The Default Approver can perform the following actions on conditions: Edit, Reassign, Override and Approve, or Override and Reject. |
Issue | Workflow: Issue tracker integration. WhiteSource policies can integrate with Ticket Management Systems (such as, JIRA or Work Items), enabling the automatic creation of tickets for tracking issues. When scanning the open source code, if vulnerabilities are found that need fixing, a ticket is automatically created in the issue tracker with all relevant information, addressed to the specific developers that need to fix the issue. After resolving the issue, the Security officer must check that the risk was mitigated. NOTE: For an Issue action to take effect, the Open pending tasks for new libraries check box (Integrate tab > Advanced Settings) must be selected. When creating an ‘Issue’ policy you can select the Jira Project to open the issue for the Issue Type (such as, bug), Priority and Assignee. The JIRA describes the level and match type of the policy, including the organization, product and project to which the library belongs. Additional information is also displayed that can help to identify why this library matched the policy (for example, if the policy match type is high severity vulnerability, the vulnerability severity and link will appear). When working with JIRA, if the issue type in the project requires mandatory fields, those fields are displayed and must be filled in. NOTES:
|
Scope and Prioritization of Policies
WhiteSource enables you to define a hierarchy for the policies in your organization according to the severity of rules in different projects and products.
...
In cases where different policies are required for different stages of the software development lifecycle (SDLC), it is common practice to allow certain types of libraries into the artifacts repository but block them from the build or from the product environment. The way to achieve policy enforcement is to create a different product for each phase of the SDLC.
For an example of how to do this, see Use Case 3: Managing Policies for Different Stages in the SDLC.
Roles and Permissions
All users are allowed to view the policies in the scopes to which they have access permissions.
...
NOTE: A Product Admin has higher permissions than an ORG Admin, as project and product policies are the first policies that WhiteSource will look at for a match.
Managing Policies
Organizational policies are managed via the Policies menu item from the main menu.
In the Policies page, you can view, add, edit, change the priority of, enable/disable, and remove policies.
Product-level policies are available for products that want to set their own policies which override the organizational ones. Product policies are managed from the product page, under the Policies button.
...
Creating a New Policy
To create a new WhiteSource policy, do as follows:
In the Policies page, click the Add Policy button. The Add Policy page is displayed.
Match your policy to a library. From the Match drop-down list, select the library type to which you want to match the policy.
Specify the action to be performed on the matched library. In the Action section, click the action you want to apply to the library.
Click the Add button to revert to the Policies page showing the newly-created policy.
If required, you can reorder the policy according to priority by selecting it and clicking the Raise Priority/Lower Priority buttons.
...
You can apply newly created policies to pending requests by clicking Apply to Pending Requests. This action will apply them only to pending requests, and not to approved inventory items.
If there are new libraries that do not match a policy and the Open pending tasks for new libraries check box (Integrate tab > Advanced Settings) is selected, a new task will be created for the Default Approver.
By clicking Apply to Existing Inventory, you can apply newly created policies that have been assigned the Approve, Reject or Issue actions, to the existing inventory.
Updating a Policy
To update a policy, do as follows:
In the Policies page, select the policy you want to update and click the edit link.
Edit your policy by library match, action, and priority, as required. For details, see Creating a New Policy.
Enabling/Disabling a Policy
If you have a policy that you do not want to match with any library but you don’t want to delete it in case you need it at a future date, you can temporarily disable the policy.
To disable a policy, select the relevant policy in the Policies page, and click the disable link.
To enable a policy, select it and click the enable link.
Deleting a Policy
To delete a policy, do as follows:
In the Policies page, select the relevant policy and click the remove link. A confirmation dialog box opens.
Click OK to confirm the deletion.
Policy Use Case Examples
The following use case examples illustrate how you can use WhiteSource policies to test the security of your open source code after scanning it.
Use Case 1: Library Approval/Rejection Workflow
This use case will show how not to apply a policy that refers to a specific license if the library has a double license which includes the specific license. For example, how to reject libraries with GPL only but allowing those with GPL and Apache.
...
Libraries that include GPL with multiple other licenses will not be rejected. These libraries will be automatically combined with the security tests of the user’s one source code.
Use Case 2: Ticket Creation Workflow
WhiteSource policies can integrate with Ticket Management Systems (such as JIRA or Work Items), enabling the automatic creation of tickets for tracking issues externally to WhiteSource. When vulnerabilities are found in the user’s code that development needs to fix, a ticket is automatically created in the issue tracker with all related information. All relevant developers will automatically receive a task in JIRA to resolve the issue.
...
After resolving the issue, the Security officer can check that the risk was mitigated.
Use Case 3: Managing Policies for Different Stages in the SDLC
In cases where different policies are required for different stages of the software development lifecycle, it is common to allow certain types of libraries into the artifact repository but block them from the build or from the production environment.
...
The following steps are required to do this:
Creating the Products
First, create a product for each environment: ERP-1.0_Repo, ERP-1.0_Build and ERP-1.0_Prod. This is what it should look like in the portal:
Mapping the Products to the SDLC Stages
Once the products are created, you can integrate each of them with the relevant step of the SDLC. In our example:
...
All of these connections can (and should) be done with WhiteSource native plugins.
Setting Up the Policies
The next step is to create distinct sets of policies for each product. These policies will then be automatically enforced in the corresponding tools during the different steps of the SDLC. In our example:
...
ERP-1.0_Prod will not accept any vulnerable components and will double-check that no GPL licensed libraries snuck in somehow:
...
Enforcing the Policies
The way these policies are enforced is also different in each step of the SDLC. In the artifact repository, artifacts that do not comply with the policy will not be allowed to enter the repository and will not be accessible to the developers that use it. In the CI/Build tool, there are two ways to enforce the policies: either fail the build or launch a workflow around it and notify the relevant individuals.
Best Practices
This section covers some basic best practices for automated policies.
...
As a general rule, WhiteSource promotes the shift-left strategy which preempts the introduction of problematic dependencies long before they reach the build stage, using Advise for Chrome/Edge, IDE integrations: Intellij, Eclipse, Visual Studio, and GitHub/GitLab integrations. However, policies are an equally powerful last defense against introducing recently discovered vulnerabilities into your code.
Policies
The following policies best practices are listed in order of importance:
Reject libraries with vulnerabilities.
Any vulnerability can be exploited, so we cannot recommend a “minimum level.” You will need to decide for yourself how to set this, but you can always start with High Severity vulnerabilities and create policies down the line for less severe vulnerabilities.
Consult with a legal expert and reject any licenses that are too restrictive.
Again, while we cannot provide legal advice, Risk Scores are available for a subset of licenses - determined by legal experts that specialize in open source compliance, so that is a good place to start!
Enable pending tasks to ensure that any new libraries which are introduced are subject to manual review, if they are not resolved by the existing policies. And then…
Create a group(s) of users as necessary that should review the pending tasks and assign the these users to the relevant Products (via Product>
>Product Default Approvers) . These groups should be restricted to personnel with the authority to make decisions, such as security experts, managers or team leaders. The more you delegate to reviewers, the more visibility you will have, resulting in fewer neglected pending tasks. Groups are more easily administered and as such, they are more highly recommended than individual user assignments.Consult with a legal expert and approve any licenses that are deemed permissible. This will help to resolve any pending tasks for new libraries.
Ensure that the order of your policies correctly reflect the Priority you require. The higher the policy on the list, the higher the priority. A library will be subject to the first policy it matches.
Establish organization-level policies and only use product and project-level policies where there are exceptions, to limit complexity.
“Issue” policies at the product or project-level that create JIRA or Work Item tickets can be assigned to the relevant team in your organization. This allows you to seamlessly integrate remediation tasks into your development process.
Unified Agent
The Unified Agent is a Java command-line tool that scans directories' open source components for vulnerable libraries and source files, as well as license compliance, and uploads the results to the WhiteSource web application.
...