Java Static Scanner getting started

On this page we will show you

How to use Sandbox Java Static Scanner to scan application bytecode.
How to use this together with the Java Tracer and Sandbox Control Center to determine coverage.
How to use this together with the Java Tracer and Sandbox Control Center to find hard-coded cryptographic values.

Prerequisites

Before you start, make sure you have followed the installation instructions.

You will also need the bytecode (.jar, .war or .class files) for the application you want to scan.

Scanning the bytecode

Run the scanner using the scripts in the java-static-scanner-VERSION/bin directory:

On Linux: java-static-scanner-<VERSION>/bin/java-static-scanner
On Windows: java-static-scanner-<VERSION>/bin/java-static-scanner.bat

A typical minimal usage would be

Text Only

/path/to/java-static-scanner-<VERSION>/bin/java-static-scanner \
    --search-path /path/to/application/class/and/jars

This will write a plain-text report to the terminal, listing all the cryptographic call sites in the scanned bytecode. The call sites are grouped into packages. Each line of output shows a single call site. For example:

Text Only

cryptosense.showcase.AppMain.multiPurposeKey()V (AppMain.java:323) (javax.crypto.Cipher.doFinal([B)[B)

From left to right, this shows:

The class and method in which the call site is located. Here the class is cryptosense.showcase.AppMain and the method is multiPurposeKey.
The method signature, in standard Java notation. In this case ()V, which means that this method takes no arguments and returns Void.
The filename and line number where this call site can be found in the source. In this case the call site is in the file AppMain.java at line 323. (Note that this information is not always present in the bytecode; it depends on the options used when the code was compiled.)
The cryptographic method called. In this case the method is javax.crypto.Cipher.doFinal. The signature ([B)[B means that this method takes a byte array as input and returns a byte array.

Computing coverage

The plain text report in the previous section has limited usefulness. The main use case for the static scanner is to work together with the Java Tracer and Sandbox Control Center to compute coverage of cryptographic call sites in a trace.

Run the application with the Java Tracer attached, to produce a trace file. See Tracing the Application in Java Tracer getting started.
Rather than uploading the trace immediately, we use the static scanner to scan the bytecode and produce an augmented trace:
Bash
```
/path/to/java-static-scanner-<VERSION>/bin/java-static-scanner \
    --search-path /path/to/application/class/and/jars \
    --trace /path/to/trace.cst.gz \
    --add-call-sites
```
This will save the augmented trace file trace-with-scan.cst.gz in the same directory as the original trace.
The augmented trace is now ready to upload. Refer to the API Client manual for instructions for uploading a trace.
Generate a report as usual. This will have a new “Coverage” line in the summary at the top of the inventory page. The Call Sites tab will separate call sites into three types:
- Sites found in both the scan and the trace: This means all is well.
- Sites found in the scan but not in the trace: These call sites exist in the application, but they were never executed during trace generation. If the trace was generated by running the application test suite, then this could mean your test coverage is inadequate and misses some of your application’s cryptography.
- Sites found in the trace but not in the scan: This means your static scan did not scan all the bytecode that makes cryptographic calls. These calls probably come from an external library. You can see these listed in the Call Sites tab and decide what to do next. One possibility would be to include that library’s Jar file in your next scan.

Finding hard-coded cryptographic values

As in the previous section, start with an application and a trace file generated by the Java Tracer, and run the Static Scanner on the application, but this time add the --find-strings option.

Bash

/path/to/java-static-scanner-<VERSION>/bin/java-static-scanner \
    --search-path /path/to/application/class/and/jars \
    --trace /path/to/trace.cst.gz \
    --find-strings

This will add all string literals found in the bytecode to the trace file.

Upload the augmented trace file trace-with-scan.cst.gz and generate a report. Any cryptographic keys, passwords, IVs or salts found hard-coded in the bytecode and used by the application will now be reported in the vulnerabilities list as violations of Rule 55: Hard-coded Cryptographic Value.

Note that the --find-strings and --add-call-sites options are not exclusive: they can be used together in the same run.

Reference manual

For full information about all the command-line options and arguments for the static scanner, see the Java Static Scanner reference manual.