| Table of Contents |
|---|
Overview
Mend Advise is a plug-in for the PyCharm 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.
Mend 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 requirements.txt, Pipfile, or pyproject.toml 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 Package Managers
Mend Advise supports projects using the following package managers:
Pip (requirements.txt dependency files only)
Pipenv (Pipfile dependency files)
Poetry (project.toml dependency files).
Prerequisites
Ensure the following:
A valid license for Mend for Developers
A license key for Mend Advise for IDE, available via one of the following options:
If you do not have direct access to the Mend Application, obtain the license key from your Mend Administrator.
If you have access to the Mend Application, do as follows (NOTE: This option is only available when using version 20.12.1 or later of Mend Advise):
Go to the Mend Application.
Open the Profile page.
In the Mend Advise - IDE Integration section at the bottom, select your organization.
Copy your personal license key to be used later in Activating Mend Advise.
PyCharm is installed and you are familiar with its basic functionality
Ensure the relevant package manager (Poetry/Pip/Pipenv) is installed depending on the project type.
Ensure the pipdeptree package version 0.12.0 or later is installed in your Python environment.
In case this package is missing, Mend Advise will automatically try to install it before a triggered scan occurs and remove it after a triggered scan completes (thereby slowing down the scanning process).
If you have configured a proxy, you must allow access to the PyPi public repository. Alternatively, if you are using a private registry, you must add to it this package so that it can be successfully installed.
If you are using the Requirements or Toml plugin for PyCharm, ensure you perform one of the following before installing Mend Advise:
Uninstall the plugin(s) from PyCharm.
From the Project sidebar, right-click your project dependency file (requirements.txt, Pipfile, or pyproject.toml) and click Mark as Plain Text.
Supported Versions
The plugin supports PyCharm 2019.1 and above (both Community and Ultimate versions). The last tested version is 2022.1.
Installing Mend Advise
To install Mend Advise, do as follows:
Start PyCharm.
From the menu bar, select File > Settings. The Settings screen is displayed.
From the left sidebar, click Plugins.
In the Search box, enter Mend and then press Enter from your keyboard. The Mend Advise plugin information is displayed.
Click Install and then click Restart IDE.
In the pop-up dialog box, click Restart.
Activating Mend Advise
To activate Mend Advise, do as follows:
Start PyCharm, specifying the preferred project.
From the sidebar on the right, click Mend (if you do not see the sidebar, select View >Tool Windows > Mend). The Welcome screen is displayed.
In Email, enter your organizational email (the email domain must be licensed to use Advise).
In License Key, enter your license key (See here for more information on how to obtain a license key).
Click Connect.
NOTE: If you check Remember Token, the login credentials will be stored for later use. Once stored, the Mend Advise login credentials will be used for all projects.
Configuring Mend Advise
| Info |
|---|
Changes made to the Mend settings will only apply after running the next scan. |
You can configure the Mend settings on a global or a project level. See the following sections.
Global-Level Configuration
To configure Mend Advise on a global level, do as follows:
From the menu bar, select File > Settings. The Settings screen is displayed.
Select Tools > Mend.
In Scan Results Settings, review the options and modify if necessary. See here for a list of all options.
Click OK.
Project-Level Configuration
To configure Mend Advise on a project-level, do as follows:
From the menu bar, select File > Settings. The Settings screen is displayed.
Select Tools > Mend > Project Settings. The Project Settings screen is displayed.
In Scan Results Settings, review the options and modify if necessary. See here for a list of all options.
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.
Click OK.
Options Table
...
Option
...
Description
...
Default Setting
...
Only show issues for direct dependencies
...
When enabled, Mend 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
...
Include dev dependencies
...
Whether to alert on vulnerabilities detected in dev dependencies.
...
Unselected (not checked)
...
Diff operation to be performed on a base branch
...
Enables developer focus mode functionality.
The dropdown will include all locally available git branches for this project.
It will allow to choose the base branch which will be the base for comparing security alerts from feature branches.
...
Unselected (not checked)
Scanning a Project for Security Vulnerabilities
To scan a project, do one of the following:
From the menu bar, select Tools > Mend Advise
From the top toolbar, click the Mend icon
Do as follows:
From the sidebar on the right, click Mend.
From the top, click Advise.
Click Run Mend Advise.
Developer Focus Mode
The developer Focus Mode allows developers to see only vulnerability alerts that are new in their feature branches compared to a predefined base branch. This promotes the security shift left approach and empowers developers to fix newly introduced vulnerabilities immediately, as part of their feature development efforts and prior to merging vulnerable code into production branches.
To enable Focus Mode, do as follows:
In the Mend Advise project-level configuration enable the Diff operation to be performed on a base branch checkbox.
Choose the base branch to which all other branch scans will be compared.
Make sure your base branch is checked out and trigger a Mend Advise scan either manually or by building your project.
In case there was no scan on the predefined base branch after its initial configuration, all branches will show all the scan results, not just the newly created security alerts.
| Info |
|---|
Every time the base branch configuration changes, a Mend Advise scan must be triggered on that branch prior to seeing new security results. |
Vulnerable Commit Alert
An alert can be enabled to notify about newly added vulnerabilities when committing the code inside the PyCharm. This alert will appear only if the committed feature branches have new vulnerabilities compared to a preconfigured base branch.
To enable a Vulnerable Commit Alert, do as follows:
Enable the Focus Mode (enable the Diff operation, choose the base branch, and trigger a Mend Advise scan).
Go to Setting > Version Control > Commit > Before Commit and make sure that Notify on new OS vulnerabilities is enabled.
In case the feature branch contains new vulnerabilities (that were not presented in the base branch), a pop up will suggest reviewing the found vulnerabilities or commit anyway.
Reviewing Scan Results
To review scan results, open one of the following windows:
Inspection Results Window
Click the Inspection Results tab at the bottom (alternatively, select View > Tool Windows > Inspection Results). The Inspection Results window is displayed.
Ensure that you are in the Mend 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 either a requirements.txt, Pipfile, or pyproject.toml item. Note the following functionality:
Next to each requirements.txt, Pipfile, or pyproject.toml item, a total number of errors and warnings are displayed in this format, for example, <requirements.txt 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 requirements.txt, Pipfile, or pyproject.toml 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 requirements.txt, Pipfile, or pyproject.toml 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.
Click the Problems tab at the bottom (alternatively, select View > Tool Windows > Problems). The Problems window is displayed.
Note that this tab features information on vulnerability issues found inside the current project. For every component, the relevant vulnerabilities are displayed via either a requirements.txt, Pipfile, or pyproject.toml item. The following functionality is included:
Each component within the requirements.txt, Pipfile, or pyproject.toml 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 requirements.txt, Pipfile, or pyproject.toml 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 Mend Advise can be used to display security vulnerability details for a project, via PyCharm's main code view.
Open the Mend security check tab and do as follows:
To quickly locate the component referenced by a reported vulnerability in the project’s requirements.txt, Pipfile, or pyproject.toml view, double-click the component in the Mend security check tab. The referenced component description in the requirements.txt, Pipfile, or pyproject.toml file will be displayed and highlighted in the main code view.
To quickly locate vulnerability analysis results for a component in the requirements.txt, Pipfile, or pyproject.toml view, click the Mend Advise severity icon displayed to the left of that component reference in the pom.xml. 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 Mend Vulnerability Database, providing more information on the specific vulnerability.
To quickly display an analysis summary for a component in the requirements.txt, Pipfile, or pyproject.toml 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 Mend Advise, do as follows:
From the sidebar on the right, click Mend (if you do not see the sidebar, select View >Tool Windows > Mend). 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.
Generating Debug Logs for Mend Support
To generate debug logs, do as follows:
From the menubar, click Help. A menu is displayed.
Select Diagnostic Tools > Debug Log Settings. The Custom Debug Log Configuration dialog box is displayed.
Enter this text: #org.whitesource.intellij.plugin
Click OK.
Debug logs will now be generated for the integration.
Upgrading Mend Advise
To upgrade the Mend Advise plugin, do as follows:
From the menu bar, select File > Settings > Plugins. Ensure that you are in the Installed tab. A list of installed plugins is displayed.
In the Downloaded section, search for Mend 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.Select Mend Advise.
If you are prompted to restart, do so.
Uninstalling Mend Advise
To uninstall the plugin, do as follows:
...
From the menu bar, select File > Settings > Plugins. Ensure that you are in the Installed tab. A list of installed plugins is displayed.
...
In the Downloaded section, search for Mend Advise and click it. The Mend Advise plugin page is displayed.
...
On the right-hand side, click the drop-down box, and then click Uninstall. The Plugin Uninstall dialog box is displayed.
...
Click Yes to confirm.
...
This page is available at: https://docs.mend.io/bundle/integrations/page/mend_advise_for_pycharm.html