Getting started with the Java Static Scanner
On this page we will show you
- how to use the Cryptosense Java Static Scanner to scan application bytecode;
- how to use this together with the Java Tracer and the Analyzer to determine coverage; and
- how to use this together with the Java Tracer and the Analyzer to find hard-coded cryptographic values.
Before you start, make sure you have followed the installation instructions.
You will also need the bytecode (
.class files) for the application you
want to scan.
Scanning the bytecode
Run the scanner using the scripts in the
- On Linux:
- On Windows:
A typical minimal usage would be
/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:
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.AppMainand the method is
- The method signature, in standard Java notation. In this case
()V, which means that this method takes no arguments and returns
- 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.javaat 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)[Bmeans that this method takes a byte array as input and returns a byte array.
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 the Analyzer to compute coverage of cryptographic call sites in a trace.
Run the application with the Java Tracer attached, to produce a trace file. See these instructions
Rather than uploading the trace immediately, we use the static scanner to scan the bytecode and produce an augmented trace:
/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.gzin the same directory as the original trace.
Upload the augmented trace and 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
/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
--add-call-sites options are not exclusive: they can
be used together in the same run.
For full information about all the command-line options and arguments for the static scanner, see the Reference Manual.