WhiteSource Advise for WebStorm

 

Overview

WhiteSource Advise is a plug-in for the WebStorm Integrated Development Environment (IDE) that is designed to empower developers with important, valuable information on security vulnerabilities concerning open-source components employed in their development projects.

WhiteSource Advise does the following:

  • It facilitates workflows by making critical component vulnerability information available to the software developer from within the IDE, preventing the need to use a separate application for such purpose.

  • It implements automatic vulnerability checking in the background that allows for immediate feedback to the user as she types. For example, a new component reference that is being typed into a project's package.json file will be automatically analyzed for security vulnerabilities.

  • It offers a transparent UX for developers, by seamlessly integrating with the IDE environment: it highlights project open source components found to have reported security vulnerabilities (CVEs), displays information on such vulnerabilities, and offers recommendations for fixing them.

Support for Languages and Package Managers

WhiteSource Advise supports JavaScript projects using npm (package.json dependency files) that include a package-lock.json file.

NOTE: Yarn projects are not supported.

Prerequisites

Ensure the following:

  • A valid license for WhiteSource for Developers

  • A license key for WhiteSource Advise for IDE, available via one of the following options:

    • If you do not have direct access to the WhiteSource Application, obtain the license key from your WhiteSource Administrator.

    • If you have access to the WhiteSource Application, do as follows (NOTE: This option is only available when using version 20.12.1 or later of WhiteSource Advise):

      1. Go to the WhiteSource Application.

      2. Open the Profile page.

      3. In the WhiteSource Advise - IDE Integration section at the bottom, select your organization.

      4. Copy your personal license key to be used later in Activating WhiteSource Advise.

  • WebStorm is installed and you are familiar with its basic functionality

  • Ensure the NPM package manager is installed. 

  • The plugin supports the following WebStorm versions:

    • 2020.3

    • 2020.2

    • 2020.1

    • 2019.3

    • 2019.2

    • 2019.1

    • 2018.3

    • 2018.2 (from version 2018.2.3)

Installing WhiteSource Advise

To install WhiteSource Advise, do as follows:

  1. Start WebStorm.

  2. From the menu bar, select File > Settings. The Settings screen is displayed.

  3. From the left sidebar, click Plugins.

  4. In the Search box, enter whitesource and then press Enter from your keyboard. The WhiteSource Advise plugin information is displayed.

  5. Click Install and then click Restart IDE.

  6. In the pop-up dialog box, click Restart.

Activating WhiteSource Advise

To activate WhiteSource Advise, do as follows:

  1. Start WebStorm, specifying the preferred project.

  2. From the sidebar on the right, click WhiteSource (if you do not see the sidebar, select View >Tool Windows > WhiteSource). The Welcome screen is displayed.

  3. In Email, enter your organizational email (the email domain must be licensed to use Advise).

  4. In License Key, enter your license key (See here for more information on how to obtain a license key). 

  5. Click Connect.

NOTE: If you check Remember Token, the login credentials will be stored for later use. Once stored, the WhiteSource Advise login credentials will be used for all projects.

Configuring WhiteSource Advise

Changes made to the WhiteSource settings will only apply after running the next scan.

You can configure the WhiteSource settings on a global or a project level. See the following sections.

Global-Level Configuration

To configure WhiteSource Advise on a global level, do as follows:

  1. From the menu bar, select File > Settings. The Settings screen is displayed.

  2. Select Tools > WhiteSource.

  3. In Scan Results Settings, review the options and modify if necessary. See here for a list of all options.

  4. Click OK.

Project-Level Configuration

To configure WhiteSource Advise on a project-level, do as follows:

  1. From the menu bar, select File > Settings. The Settings screen is displayed.

  2. Select Tools > WhiteSource > Project Settings. The Project Settings screen is displayed.

  3. In Scan Results Settings, review the options and modify if necessary. See here for a list of all options.

  4. By default, all settings are inherited from the global-level configuration. To override the specific configuration on project level, clear the Inherit from global settings checkbox.

  5. Click OK.

Options Table

Option

Description

Default Setting

Option

Description

Default Setting

Only show issues for direct dependencies

When enabled, WhiteSource Advise will only return vulnerabilities for direct dependencies defined in your dependency file.

Unselected (not checked)

Minimum vulnerability severity level

Alert only on detected vulnerabilities satisfying a Low/Medium/High minimum severity level.

  • Low - vulnerability alerts for all severities (Low, Medium, High) are displayed.

  • Medium- vulnerability alerts only for Medium or High severities are displayed.

  • High - vulnerability alerts only for High severities are displayed.

Low

Scanning a Project for Security Vulnerabilities

Ensure your project is built (a package-lock.json file is generated) before you scan it with WhiteSource Advise.

To scan a project, do one of the following:

  • From the menu bar, select Tools > WhiteSource Advise

  • From the top toolbar, click the WhiteSource icon

  • Do as follows:

    1. From the sidebar on the right, click WhiteSource.

    2. From the top, click Advise.

    3. Click Run WhiteSource Advise.

Reviewing Scan Results

To review scan results, open one of the following windows:

Inspection Results Window

  1. Click the Inspection Results tab at the bottom (alternatively, select View > Tool Windows > Inspection Results). The Inspection Results window is displayed.

  2. Ensure that you are in the WhiteSource Security Check tab (it is part of the Inspection Results area). This tab features information on vulnerability issues found inside the current project. For every component, the relevant vulnerabilities are displayed via a package.json item. Note the following functionality:

    • Next to each package.json item, a total number of errors and warnings are displayed in this format, for example, <package.json 20 errors 32 warnings>. High severity security vulnerabilities are represented as errors, and medium/low-security vulnerabilities are represented as warnings

    • Each component within the package.json item list consists of the following metadata:

      • Component name

      • Component version

      • Vulnerability unique identifier

      • Indication of transitive or direct dependency

    • Double-clicking a component will open up the package.json file in which it was referenced. It will point to the direct dependency you declared.

Problems Window

NOTE: The Problems window is available only from version 2020.2. of the IDE.

  1. Click the Problems tab at the bottom (alternatively, select View > Tool Windows > Problems). The Problems window is displayed.

  2. Note that this tab features information on vulnerability issues found inside the current project. For every component, the relevant vulnerabilities are displayed via a package.json item. The following functionality is included:

    • Each component within the package.json item list consists of the following metadata:

      • Component name

      • Component version

      • Vulnerability unique identifier

      • Indication of transitive or direct dependency

    • Double-clicking a component will open up the package.json file in which it was referenced. It will point to the direct dependency you declared.

Displaying Vulnerability Information for a Scanned Component

This section describes how WhiteSource Advise can be used to display security vulnerability details for a project, via WebStorm's main code view.

Open the WhiteSource security check tab and do as follows:

  • To quickly locate the component referenced by a reported vulnerability in the project’s package.json view, double-click the component in the WhiteSource security check tab. The referenced component description in the package.json file will be displayed and highlighted in the main code view.

  • To quickly locate vulnerability analysis results for a component in the package.json view, click the WhiteSource Advise severity icon displayed to the left of that component reference in the package.json file. Note that the icon denotes the severity of the vulnerability (yellow: low severity; orange: medium severity; red: high severity). A tooltip featuring relevant analysis details including a dependency path from the proprietary code to the open-source component will be displayed. Vulnerability details are also displayed as part of the tooltip and include the vulnerability identifier (e.g., CVE), severity, and a fix suggestion if available. A Details link is displayed which leads to the WhiteSource Vulnerability Database, providing more information on the specific vulnerability.

  • To quickly display an analysis summary for a component in the package.json view, hover the mouse pointer over the code for the component in that view; a tooltip will be displayed, featuring a list of all vulnerabilities found within the particular component.

Viewing General Plugin Information 

To view version information about WhiteSource Advise, do as follows:

  • From the sidebar on the right, click WhiteSource (if you do not see the sidebar, select View >Tool Windows > WhiteSource). The Welcome screen is displayed.

  • From the Welcome screen, click About. 

The About screen displays information about the Advise plugin's version, general information on your IDE, along with links for Privacy policy and Terms and Conditions.

Upgrading WhiteSource Advise 

To upgrade the WhiteSource Advise plugin, do as follows:

  1. From the menu bar, select File > Settings > Plugins. Ensure that you are in the Installed tab. A list of installed plugins is displayed.

  2. In the Downloaded section, search for WhiteSource Advise, and on the right-hand side, click Update.
    NOTE: If there is no new version, the Update button will not appear, and there is no need to continue this procedure. 

  3. Select WhiteSource Advise.

  4. If you are prompted to restart, do so.

Uninstalling WhiteSource Advise

To uninstall the plugin, do as follows: 

  1. From the menu bar, select File > Settings > Plugins. Ensure that you are in the Installed tab. A list of installed plugins is displayed. 

  2. In the Downloaded section, search for WhiteSource Advise and click it. The WhiteSource Advise plugin page is displayed.

  3. On the right-hand side, click the drop-down box, and then click Uninstall. The Plugin Uninstall dialog box is displayed. 

  4. Click Yes to confirm.

  5. If you are prompted to restart, do so.