Scanning Java apps with the CLI

This tutorial will walk you through the steps needed to setup and use Eclipse Steady to scan a Java application that is not built with tools such as Maven or Gradle.

Terminology: 'Goals'

For consistency with the terminology used in Maven, the different "commands" available in Eclipse Steady are referred to as "goals".

Prerequisites

  1. JDK 7 or later
  2. URLs of the backend service and apps Web frontend
  3. 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-3.1.14.zip from Releases and extract it into a newly created folder. This folder will contain the following items:

./app/

Put the application code (java, class or JAR files) and all application dependencies (JAR 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-3.1.14-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.

./instr/lang-java-3.1.14-jar-with-dependencies.jar

This is used to instrument the Java runtime when performing dynamic analysis.

./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.
  2. Set the option vulas.core.space.token so that it is assigned your own workspace token.
  3. Put the application code (java, class or JAR files) and all application dependencies (JAR files) into this folder.
  4. Specify how Eclipse Steady can distinguish the code of your application from its dependencies, which is necessary for the call graph construction during the reachability analyses (goals a2c and t2c).

You can do so in two different ways: you can use either vulas.core.app.appPrefixes or vulas.core.app.appJarNames.

# Package prefix(es) of application code (multiple values to be separated by comma), only relevant for CLI
vulas.core.app.appPrefixes =

# Regex that identifies JARs with application code (multiple values to be separated by comma), only relevant for CLI
vulas.core.app.appJarNames =

Warning

In order for the static reachability analysis to be performed correctly, all application methods must be used as entry points for the call graph construction. Therefore, if the criterion to distinguish application code and dependencies is not specified correctly, the potential execution of vulnerable open-source methods may be missed.

To check whether the specification is correct, you may want to inspect the application frontend and see whether there are any items in the Dependencies tab that are created by you or your organization (there should be none, only 3rd party libraries should be there), and whether there are open-source packages at all in the table on the Dependencies tab (there should be none, only packages from your own project).

IMPORTANT REMARKS

You should also keep the following into account:

  1. Single java and class files are always considered as application code (regardless of the package prefix configured with vulas.core.app.appPrefixes).
  2. JARs are always considered application dependencies unless they only contain methods starting with the configured package prefix.
  3. Nested JARs must be manually extracted (but no need to do so for WARs).

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.