Scanning Java apps built with Maven

Prerequisites

  1. JDK 7 or later
  2. Apache Maven 3.x with settings.xml configured to download from the Maven repository hosting the Eclipse Steady plugin for Maven
  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.

Setup

The plugin for Maven can be used with or without adding a Eclipse Steady profile to the pom.xml of your application. This tutorial guides you through the setup with Eclipse Steady profile.

Cannot add the Eclipse Steady profile?

If possible we recommend to use the Eclipse Steady profile as the execution of goals using the command-line is more concise (readable). If you cannot paste the Eclipse Steady profile in the pom.xml of your application you can still use the Eclipse Steady plugin for Maven. Check out the Manual Java (Maven)

Add the following to the <profiles> section of the pom.xml of your application project and make sure that <vulas.shared.backend.serviceUrl> points to the URL of the backend service and that <vulas.core.space.token> specifies the token of your individual workspace (see highlighted lines).

    <profile>
        <id>steady</id>
        <activation>
            <property>
                <name>steady</name>
            </property>
        </activation>
        <properties>
            <vulas.version>3.2.5</vulas.version>
            <vulas.shared.backend.serviceUrl>http://localhost:8033/backend/</vulas.shared.backend.serviceUrl>
            <vulas.core.space.token>WORKSPACE_TOKEN</vulas.core.space.token>
            <vulas.core.appContext.group>${project.groupId}</vulas.core.appContext.group>
            <vulas.core.appContext.artifact>${project.artifactId}</vulas.core.appContext.artifact>
            <vulas.core.appContext.version>${project.version}</vulas.core.appContext.version>
        </properties>
        <build>
            <plugins>
                <plugin>
                    <groupId>org.eclipse.steady</groupId>
                    <artifactId>plugin-maven</artifactId>
                    <version>${vulas.version}</version>
                    <configuration>
                        <layeredConfiguration>
                            <vulas.shared.backend.serviceUrl>${vulas.shared.backend.serviceUrl}</vulas.shared.backend.serviceUrl>
                            <vulas.core.space.token>${vulas.core.space.token}</vulas.core.space.token>

                            <vulas.core.appContext.group>${vulas.core.appContext.group}</vulas.core.appContext.group>
                            <vulas.core.appContext.artifact>${vulas.core.appContext.artifact}</vulas.core.appContext.artifact>
                            <vulas.core.appContext.version>${vulas.core.appContext.version}</vulas.core.appContext.version>

                            <vulas.shared.tmpDir>${project.build.directory}/vulas/tmp</vulas.shared.tmpDir>
                            <vulas.core.uploadDir>${project.build.directory}/vulas/upload</vulas.core.uploadDir>
                            <vulas.core.app.sourceDir>${project.build.directory}/classes,${project.basedir}/src/main/java,${project.basedir}/src/main/python</vulas.core.app.sourceDir>

                            <!-- steady:instr : Instruments JAR/WAR files found in source dir,
                                and writes to target dir. Files in include dir are put into /WEB-INF/lib
                                of output WARs. Files in lib dir are part of the class path when instrumenting. -->
                            <vulas.core.instr.sourceDir>${project.build.directory}</vulas.core.instr.sourceDir>
                            <vulas.core.instr.targetDir>${project.build.directory}/vulas/target</vulas.core.instr.targetDir>
                            <vulas.core.instr.includeDir>${project.build.directory}/vulas/include</vulas.core.instr.includeDir>
                            <vulas.core.instr.libDir>${project.build.directory}/vulas/lib</vulas.core.instr.libDir>
                            <vulas.core.instr.writeCode>false</vulas.core.instr.writeCode>
                            <vulas.core.instr.instrumentorsChoosen>org.eclipse.steady.java.monitor.trace.SingleTraceInstrumentor</vulas.core.instr.instrumentorsChoosen>
                            <vulas.core.instr.searchRecursive>false</vulas.core.instr.searchRecursive>
                            <vulas.core.monitor.periodicUpload.enabled>false</vulas.core.monitor.periodicUpload.enabled>
                            <vulas.core.instr.maxStacktraces>10</vulas.core.instr.maxStacktraces>

                            <!-- steady:a2c/t2c : Performs static call graph analysis -->
                            <vulas.reach.wala.callgraph.reflection>NO_FLOW_TO_CASTS_NO_METHOD_INVOKE</vulas.reach.wala.callgraph.reflection>
                            <vulas.reach.timeout>60</vulas.reach.timeout>

                            <!-- steady:report -->
                            <vulas.report.reportDir>${project.build.directory}/vulas/report</vulas.report.reportDir>
                        </layeredConfiguration>
                    </configuration>
                </plugin>
            </plugins>
        </build>
    </profile>

In case of aggregated, multi-module Maven projects with modules inheriting from their parent, it is sufficient to include the profile in the top-level (parent) pom.xml. If a module does not inherit from the parent, the profile has to be added to its POM file.

Goal execution

See here for a description of all analysis goals.

app

  1. mvn -Dsteady compile steady: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.

In case your application does not follow the standard structure of Maven applications, please refer to the Manual Java (Maven) to learn how to configure the Eclipse Steady plugin accordingly.

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. mvn -Dsteady steady:report

  2. A summary report is written to disk (in HTML, XML and JSON format), by default into folder target/vulas/report. By default a build exception is thrown if the application includes a library subject to known vulnerabilities.

Warning

The goal report must be executed separately from the other analysis goal. Otherwise, in case of multi-module Maven projects, it may throw a build exception before all modules have been analyzed.

clean

  1. mvn -Dsteady steady: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.