Support – Static Scanner HOWTO

Measure Crypto Use in an Application

The Cryptosense Static Crypto Scanner can:

  • Identify all the crypto calls in a JAR file or set of class files
  • Check coverage of these calls by Cryptosense traces obtained from our tracing agent

How to use the static scanner

1. Install the Static Crypto Scanner

Extract the downloaded archive by typing

unzip static-crypto-scanner-VERSION.zip

2. Scan the bytecode files of the application

./static-crypto-scanner/bin/static-crypto-scanner \
    --search-path path/to/bytecode/classes/and/jars

The arguments have the following meanings:

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

--trace (optional): Path of 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.

--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 risk assessment.

--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. (Makes no sense without --trace.)
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): Find all hard-coded strings in the bytecode. If a trace has been supplied, write these (together with their locations) into the trace, inside the api_specific element in the header (replacing any such list already there from a previous run). If the original trace was in foo.cst[.gz], the rewritten 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 rewritten 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): If a trace has been supplied with --trace, add all call sites to the trace, inside the api_specific element in the header (replacing any such list already there from a previous run). If the original trace was in foo.cst[.gz], the rewritten trace will be in foo-with-scan.cst[.gz].

3. Understand the results

A typical output looks something like this:

Cryptosense Static Crypto Scanner 1.2.0
Command-line arguments:
  --search-path showcase/ --show-calls none
Scanning bytecode: showcase/
No traces to process.
Crypto call sites:
  cryptosense.showcase: 314 call sites
  TOTAL: 314 call sites
Summary of crypto call sites:
  Asymmetric key generation: 20
  Encryption / Decryption: 31
  Hashing: 6
  Key exchange: 0
  Key derivation: 12
  Key store access: 6
  Key store loading / storage: 6
  Key wrapping / unwrapping: 0
  MAC generation / verification: 2
  Signature generation / verification: 4
  Symmetric key generation: 23

Cryptosense Analyzer rules that apply to call sites in the code: 32
Get definitive application crypto security analysis using Cryptosense Analyzer
Already a user? Login at https://analyzer.cryptosense.com

In this example, you can see that 314 crypto call sites exist in the code, and a summary of what kind of operations they call.

To see more details of the individual crypto calls, use the --show-calls all option.