CogniCrypt_SAST

This repository contains CogniCrypt_SAST, the static analysis component for CogniCrypt. The static analysis CogniCrypt_SAST takes rules written in the specification language CrySL as input and performs a static analysis based on the specification of the rules. CrySL is a domain-specific language (DSL) designed to encode usage specifications for cryptographic libraries (e.g. the JCA in particular). More information on CrySL and the static analysis may be found in this paper.

Features

CogniCrypt_SAST consists of the following features:

• A context-sensitive, field-sensitive and flow-sensitive typestate and pointer analysis
• A CLI to analyze Java and Android applications
• Support for the static analysis frameworks Soot, SootUp and Opal

We provide a complete documentation for all technical details and options.

Releases

You can check out a pre-compiled version of CogniCrypt_SAST here. We recommend using the latest version. You can find CogniCrypt_SAST also on Maven Central.

Checkout and Build

CogniCrypt_SAST uses Maven as build tool. You can compile and build this project via

mvn clean package -DskipTests

The packaged jar artifacts including all dependencies can be found in /apps. Building requires at least Java 17.

Running CogniCrypt_SAST

CogniCrypt_SAST analyzes Java and Android apps to detect cryptographic misuses based on CrySL rules.

1. Prepare Your Inputs

• Compile your application to a .jar or .apk file
• Download the HeadlessJavaScanner-x.y.z-jar-with-dependencies.jar for analyzing Java applications or the HeadlessAndroidScanner-x.y.z-jar-with-dependencies.jar for analyzing Android applications from the GitHub releases or build them yourself
• Download CrySL rules (e.g. JCA rules)

2. Run the Analysis

• CogniCrypt_SAST for Java applications

java -jar HeadlessJavaScanner-x.y.z-jar-with-dependencies.jar \
  --appPath <YourApp.jar> \
  --rulesDir ./CrySL-Rules/ \
  --reportFormat CMD,SARIF \
  --reportPath ./output/

• CogniCrypt_SAST for Android applications

java -jar HeadlessAndroidScanner-x.y.z-jar-with-dependencies.jar \
--apkFile <YourApp.apk> \
--platformDirectory <path_to_platforms_directory>
--rulesDir ./CrySL-Rules/ \
--reportFormat CMD,SARIF \
--reportPath ./output/

3. Output

• Reports are written to --reportPath and/or printed to the console
• Misuse types include: ConstraintError, TypestateError, see Error Types for all error types

⚠️ Note: You may need to allocate more memory for large analyses: -Xmx8g -Xss60m

For advanced options, visit the full documentation.

Use as a GitHub Action

CogniCrypt_SAST can be used as a GitHub action.

- name: Run CogniCrypt
  uses: CROSSINGTUD/CryptoAnalysis@version
  with:
    appPath: "CryptoAnalysisTargets/HelloWorld/HelloWorld.jar"
    basePath: "CryptoAnalysisTargets/HelloWorld"

The appPath needs to be configured to point to a compiled version of your application.

The basePath is used to relate paths in the analyzed jar and the source tree. Class com.example is searched for at basePath/com/example.

See action.yml for all input options.

An example of how to use the GitHub action can be found in the CryptoAnalysis-demo repository.