Java Static Scanner Reference Manual

Installation

Running the scanner

The scanner is a Java application. Execute it using its runner script, either

On Linux: /path/to/java-static-scanner-VERSION/bin/java-static-scanner
On Windows: /path/to/java-static-scanner-VERSION/bin/java-static-scanner.bat

The example below is for Linux.

./java-static-scanner-VERSION/bin/java-static-scanner \
    --search-path /path/to/classes/and/jars \
    --trace /path/to/trace/or/directory \
    --exclude java,javax,sun,org.bouncycastle,org.jboss \
    --show-calls all \
    --find-strings \
    --add-call-sites \
    --num-passes 1 \
    --continue-on-parsing-error

Arguments

The arguments have the following meanings:

--search-path (required): Path to the directory containing .class, .jar and .war files to be scanned. This tool only analyzes Java bytecode, not source code.

--trace (optional): Path to a Cryptosense trace (.cst or .cst.gz file) or a directory containing several traces that you want to use to measure coverage of crypto calls in the bytecode. This is only useful in conjunction with one (or both) of --add-call-sites and --find-strings.

--exclude (optional, defaults to com.sun,java,javax,org.bouncycastle,sun): Comma-separated list of package prefixes that must not be taken into account. For instance, if your application bundles some library com.example with crypto calls you don't want to consider, you can use com.example as a prefix to exclude classes like com.example.SomeClass and com.example.sub.OtherClass from the scan.

--show-calls {all, missed, none} (optional, defaults to all): Determine what calls to show for each package:

all : Show all crypto call sites found in the scan.
missed : Show only those call sites found in the scan but not in the trace. (Only relevant if --trace is also specified.)
none : Don't show any individual calls, only package names and overall stats.

--json (optional): Produce a JSON format report rather than the default plain text.

--find-strings (optional): Only relevant if --trace is also specified. Find all string literals in the bytecode and write them (together with their locations) into the trace. If the original trace was in foo.cst.gz, the augmented trace will be in foo-with-scan.cst.gz. For text output, this option just adds a summary line saying how many strings were found; for JSON output, it will include the list. The augmented trace file can be uploaded to the Cryptosense Analyzer SaaS platform to allow detection of hard-coded cryptographic values (keys, IVs, salts etc).

--add-call-sites (optional): Only relevant if --trace is also specified. Add all crypto call sites to the trace. If the original trace was in foo.cst.gz, the augmented trace will be in foo-with-scan.cst.gz.

--num-passes (optional, defaults to 1): Set the maximum number of passes the scanner will make over the code looking for call sites. The first pass finds the locations of calls to the Java crypto API. The second pass finds where the calls from the first pass were called from, and so on. Setting a value of 0 means the scanner will keep going until it stops finding anything new, i.e. when it has explored the entire application all the way up to the entry point.

Note that for large applications, the number of indirect call sites found has the potential to grow quite fast with the number of scanner passes, so we recommend using this option with some caution. The main usefulness of this option is if your application uses some sort of wrapper layer around the standard cryptographic API, and you want to know where in the application proper that layer gets called. For such a scenario, setting --num-passes to 2 or 3 should usually be sufficient.

--continue-on-parsing-error (optional): If the scanner encounters a class that the bytecode parser cannot handle, log a warning and continue, rather than exiting. This will become the default in a future release.

Using the static scanner to enhance a host scan

The host scanner can use the static scanner to look inside Jar files found during a host scan and extract any hard-coded keys or certificates found in the bytecode. For instructions, see the host scanner manual.