Skip to content

Java Tracer reference manual

Installation

Before you can use the Java Tracer, see installation instructions.

Configuration

The Java Tracer can be configured with JVM properties (using the -D parameter in the command line).

For example, to choose the directory where the tracer will write traces, use the cryptosense.agent.out parameter the following way:

Text Only

Text Only
java \
    -Dcryptosense.agent.out=/path/to/trace-directory \
    -javaagent:/path/to/cs-java-tracer.jar \
    -jar /path/to/application.jar

If you don’t launch your application directly with the java command, you can usually specify those properties in the same place where you added the javaagent:/path/to/cs-java-tracer.jar parameter (see examples below).

Parameters

Here is a list of supported properties:

  • cryptosense.agent.out: path to a directory where traces will be written to. (default is cs-tracer). Make sure the application under test has the right to create a file in this directory.
  • cryptosense.agent.compress: gzip-compress output JSON files on-the-fly (default is true). Note that traces can be uploaded to the analyzer in compressed or uncompressed form.
  • cryptosense.agent.unlimitedTraceSize: remove trace size limit (default is false). Traces are limited to 4GB uncompressed by default. This parameter is deprecated: use cryptosense.agent.maxTraceSize instead.
  • cryptosense.agent.maxTraceSize: set a maximum uncompressed trace size. The value specified should be a whole number of MB. The default is 4096, i.e. 4GB. Setting a value of 0 means there is no limit.
  • cryptosense.agent.prefix: optional custom file name prefix for traces (default is cs-trace). The file name will consist of this prefix followed by an underscore, followed by a timestamp, with extension .cst or .cst.gz depending on whether compression is turned on. For example, if the prefix is set to testprefix, the file name would look like testprefix_2018-12-13-08-42-33-428_11435.cst (depending on the date and time the trace was run).
  • cryptosense.agent.trace: whether the report should include stack traces for each call (default is true ). Setting to false significantly reduces the size of the resulting trace files, but the report will lack important information.
  • cryptosense.agent.ignoreUpdate: whether the calls to various update() functions (like MessageDigest.update) should be discarded (default is false ). Setting to true significantly reduces the size of the resulting trace files, but the report will lack important information.
  • cryptosense.agent.excludeBuiltins: whether the calls to certain internal crypto functions in the JRE are included in the trace or not (default is false ). The excluded calls include hash function calls to verify JAR files on startup, and internal hash calls for certain internal PBKDFs that use a large number of iterations and can quickly fill up a trace. Note that this doesn’t affect the results, since the calls are accounted for by Analyzer.
  • cryptosense.agent.tags: list of comma separated tags to include in the trace header. To include space in the tag, uses single quotes like cryptosense.agent.tags='spaced tag 1','spaced tag 2'. The tags are written in the trace header as a list of strings (default is an empty list).

Here are some examples with different parameters:

Limiting the trace size:

Text Only

Text Only
java \
    -Dcryptosense.agent.out=/path/to/trace-directory \
    -Dcryptosense.agent.maxTraceSize=200 \
    -javaagent:/path/to/cs-java-tracer.jar \
    -jar /path/to/application.jar

Adding a prefix to the trace name:

Text Only

Text Only
java \
    -Dcryptosense.agent.out=/path/to/trace-directory \
    -Dcryptosense.agent.prefix=prefix \
    -javaagent:/path/to/cs-java-tracer.jar \
    -jar /path/to/application.jar

Excluding stacktraces from calls:

Text Only

Text Only
java \
    -Dcryptosense.agent.out=/path/to/trace-directory \
    -Dcryptosense.agent.trace=false \
    -javaagent:/path/to/cs-java-tracer.jar \
    -jar /path/to/application.jar

Using the Tracer with Build Systems

Gradle

Gradle 5.6.3 or higher is required.

Gradle can pass arguments to the JVM that runs the test suite. You can add the following line to your build.gradle to trace your tests:

Text Only

Text Only
if (project.hasProperty('with-cryptosense')) {
    test.jvmArgs = ['-javaagent:/path/to/cs-java-tracer.jar']
}

If you use subprojects, you will need to apply this configuration to each of those you want to get traces. A simple way of achieving this for all subprojects is to enclose the above snippet in a subprojects { ... } block. The Gradle documentation has more information about the test task.

Then, you can get a trace by running the following command:

Text Only

Text Only
gradle cleanTest test -Pwith-cryptosense

You can also use our Gradle plugin. See more details here.

Maven

Maven 3.3.9 or higher is required.

Maven integration is provided by our Maven plugin. Further details and installation instructions.

Using the Tracer in Application Frameworks

Java applications are often launched from within application servers. In this case, you will need to add the necessary parameters to a config file:

Tomcat

The file bin/setenv.sh should be created or edited to contain:

Text Only

Text Only
CATALINA_OPTS="$CATALINA_OPTS -javaagent:/path/to/cs-java-tracer.jar -Dcryptosense.agent.<PARAM>=<VALUE>"

JBoss

For JBoss it is necessary to whitelist the cryptosense package in standalone.conf :

Text Only

Text Only
JBOSS_MODULES_SYSTEM_PKGS="${JBOSS_MODULES_SYSTEM_PKGS:+$JBOSS_MODULES_SYSTEM_PKGS,}cryptosense"

You can then add:

Text Only

Text Only
JAVA_OPTS="$JAVA_OPTS -javaagent:/path/to/cs-java-tracer.jar -Dcryptosense.agent.<PARAM>=<VALUE>"

WebLogic

The file startWebLogic.sh should be edited to contain (before Java is called):

Text Only

Text Only
export JAVA_OPTIONS="$JAVA_OPTIONS -javaagent:/path/to/cs-java-tracer.jar -Dcryptosense.agent.<PARAM>=<VALUE>"

Other frameworks

Our Java tracer works with several other frameworks including WebSphere and Firefly. Contact us if you need help.

Trace Streaming

The Java tracer supports streaming results directly to the Sandbox Control Center instead of first creating a local file. Currently, this is only available for the SaaS version of SandboxAQ Security Suite. In order to stream traces, the following options should be set :

  • cryptosense.agent.domain: should be set to proxy.cryptosense.com.
  • cryptosense.agent.tls: should be set to true.
  • cryptosense.agent.port: should be set to 443.
  • cryptosense.agent.projectId: should be set to the ID of the project to which the trace should be added. This ID is an integer and can be gathered from the URL of the projects root page (of the format https://analyzer.cryptosense.com/project/<project id>/dashboard). The ID used for this option is not the same ID as the one returned by the GraphQL API.
  • cryptosense.agent.apiKey: should be set to the API key linked to a user that has sufficient privileges to write to the given project.

Renaming the tracer Jar file

It is not recommended to rename the Jar file. The reason is that the boot class path in the Jar manifest must match the file name exactly.

If you absolutely must rename the Jar file, you must also modify the manifest to match, otherwise you will encounter java.lang.NoClassDefFoundError while your application is running. Your application may or may not crash, but the tracer will certainly not operate correctly.

Suppose you want to change the name of the Jar file to new-name.jar. You will need to extract the file META-INF/MANIFEST.MF from the Jar, and edit it, changing the boot class path line to:

Text Only

Text Only
Boot-Class-Path: new-name.jar

You will then need to update the Jar file, replacing the old META-INF/MANIFEST.MF with the new modified version.

Supported operations

The Java tracer covers methods from the following classes:

  • java.security.KeyPairGenerator
  • java.security.KeyStore
  • java.security.MessageDigest
  • java.security.Signature
  • javax.crypto.Cipher
  • javax.crypto.KeyAgreement
  • javax.crypto.KeyGenerator
  • javax.crypto.Mac
  • javax.crypto.SecretKeyFactory
  • javax.net.ssl.SSLServerSocket
  • com.amazonaws.services.kms.AWSKMSClient
  • com.azure.security.keyvault.keys.cryptography.CryptographyClient