Scanning Python apps with the CLI

Using Eclipse Steady for Python applications not built with SetupTools

Prerequisites

  1. JDK 7 or later
  2. pip is installed and "knows" all application dependencies (check with pip list)
  3. URLs of the backend service and apps Web frontend
  4. The token of a Eclipse Steady workspace

Workspace creation

If you do not have a workspace yet, you can easily create one by going on the application frontend and clicking on the third button in the lower left corner:

Setup workspace button

For a detailed description of workspaces and of the inputs you have to provide in the form that is displayed when you click that button, please see this section of the manual.

Download

Please download the latest ZIP archive vulas-cli-<VERSION>.zip from Releases and extract it into a newly created folder. This folder will contain the following items:

./app/

Put the application code (python files) into this folder. It will be searched recursively, thus, it is possible to just copy the entire installation directory of an application into the folder.

./vulas-cli-<version>-jar-with-dependencies.jar

An executable JAR, which is the actual command-line version of the Eclipse Steady client. This is what you will use later to execute Eclipse Steady scans.

./vulas-custom.properties.sample

This is a template for the configuration file required by Eclipse Steady. You will change it in order to specify an identifier for your application (see below).

Setup

  1. Rename the file vulas-custom.properties.sample to vulas-custom.properties and edit it to specify <GROUP>, <ARTIFACT> and <VERSION> of the application to be analyzed. Those settings will be used to uniquely identify the application in the backend. For Python applications, feel free to use the same value for both <GROUP> and <ARTIFACT>.
  2. Set the option vulas.core.space.token so that it is assigned your own workspace token.
  3. Put the application code (python files) into the folder ./app/.
  4. Specify the setting vulas.core.bom.python.pip such that it points to a pip binary (not only the path in which the binary is located, but the binary itself, e.g., /foor/bar/pip). pip will be used to determine the dependencies of your Python application. You can either use the global pip or one installed in a virtual environment (virtualenv, Anaconda, etc.).
# Full path to PIP binary (e.g., global installation, virtual environment or Anaconda)
#vulas.core.bom.python.pip = <PATH-TO-PIP-BINARY>/pip

Additional notes:

  • Java resources contained in folder ./app/ will also be added as application code or dependencies.

  • For the above reason, make sure that the Eclipse Steady CLI is not contained in ./app/ or other folders specified by setting vulas.core.app.sourceDir, if any.

Goal execution

See here for a description of all analysis goals.

app

  1. java -jar vulas-cli-3.1.14-jar-with-dependencies.jar -goal app

  2. Connect to the apps Web frontend, then select your workspace and application. The table in tab Dependencies is populated. Dependencies with known vulnerabilities are shown in tab Vulnerabilities.

Assess and mitigate

Once app has been run, the assessment of findings can already start: Each finding shown on the Vulnerabilities tab corresponds to a dependency of an application on a component with a known security vulnerability. See here for more information on how to assess and mitigate findings. Other analysis goals can be used to collect further evidence concerning the reachability of vulnerable code.

report

  1. java -jar vulas-cli-3.1.14-jar-with-dependencies.jar -goal report

  2. Check the console to see where the HTML, JSON and XML reports have been written to.

clean

  1. java -jar vulas-cli-3.1.14-jar-with-dependencies.jar -goal clean

  2. All application-specific data in the Eclipse Steady backend are deleted.

Run clean whenever the application changes

If you already scanned your project in the past, you should run the clean goal prior to new analyses in order to delete the old analysis results in the backend. Otherwise, old analysis results will be shown together with new results. For example, if you updated a dependency from a vulnerable to a non-vulnerable version, both versions will be shown in the apps Web frontend.