Skip to content
develop
Go to file
Code

Latest commit

Bumps [org.eclipse.xtext.xbase](https://github.com/eclipse/xtext-extras) from 2.23.0 to 2.24.0.
- [Release notes](https://github.com/eclipse/xtext-extras/releases)
- [Commits](eclipse/xtext-extras@v2.23.0...v2.24.0)

Signed-off-by: dependabot-preview[bot] <support@dependabot.com>

Co-authored-by: dependabot-preview[bot] <27856297+dependabot-preview[bot]@users.noreply.github.com>
24569e7

Git stats

Files

Permalink
Failed to load latest commit information.

README.md

Build Status

CogniCryptSAST

This repository contains CogniCryptSAST, the static analysis component for CogniCrypt. The static analysis CogniCryptSAST 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 libaries (e.g., the JCA in particular). More information on CrySL and the static analysis may be found in this paper.

Releases

You can checkout a pre-compiled version of CogniCryptSAST here.

Download the two files:

  • CryptoAnalysis-x.y.z-jar-with-dependencies.jar
  • JCA-CrySL-rules.zip

Checkout and Build

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

mvn package -DskipTests=true.

A packaged jar artifact including all dependency is found in CryptoAnalysis/build/CryptoAnalysis-x.y.z-jar-with-dependencies.jar

Usage

CogniCryptSAST can be started in headless mode (i.e., detached from Eclipse) via the class crypto.HeadlessCryptoScanner. It requires two arguments:

  • The absolute path to the directory of the CrySL (source code format) rule files. The source code for the rules which contains spesification for the JCA is found here.
  • The absolute path of the application to be analyzed (.jar file or the root compilation output folder which contains the .class files in subdirectories)
java -cp <path-to-analysis-jar> crypto.HeadlessCryptoScanner --rulesDir=<absolute-path-to-crysl-source-code-format-rules> \
      --applicationCp=<absolute-application-path>

For an easy start we prepared a .jar containing classes with crypto misuses. The source code for these misuses is found here. To run CogniCryptSAST on these classes, simply execute the following command (on a linux based system).

java -cp CryptoAnalysis/build/CryptoAnalysis-2.6-jar-with-dependencies.jar crypto.HeadlessCryptoScanner \
  --rulesDir=$(pwd)/CryptoAnalysis/src/main/resources/JavaCryptographicArchitecture \
  --applicationCp=$(pwd)/CryptoAnalysisTargets/CogniCryptDemoExample/Examples.jar

Note, depending on the analyzed application, the analysis may require a lot of memory and a large stack size. Remember to set the necessary heap size (e.g. -Xmx8g) and stack size (e.g. -Xss60m).

Report and Error Types

In the standard option, CogniCryptSAST outputs a report to the console. CogniCryptSAST reporst misuses when the code is not compliant with the CrySL rules. For each misuse CogniCryptSAST reports the class and the method the misuse is contained in. There are multiple misuse types:

  • ConstraintError: A constraint of a CrySL rule is violated, e.g., a key is generated with the wrong key size.

  • NeverTypeOfError: Reported when a value was found to be of a certain reference type: For example, a character array containing a password should never be converted from a String. (see KeyStore rule here).

  • ForbiddenMethodError: A method that is forbidden (CrySL block FORBIDDEN) to be called under some circumstances was found.

  • ImpreciseValueExtractionError: The static analysis was not able to extract all information required within the CrySL CONSTRAINT block. For example the key size could be supplied as a value listed in a configuration file. The static analysis does not model the file's content and may not constraint on the value.

  • TypestateError: The ORDER block of CrySL is violated, i.e., the expected method sequence call to be made is incorrect. For example, a Signature object expects a call to initSign(key) prior to update(data).

  • RequiredPredicateError: An object A expects an object B to have been used correctly (CrySL blocks REQUIRES and ENSURES). For example a Cipher object requires a SecretKey object to be correctly and securely generated.

  • IncompleteOperationError: The usage of an object may be incomplete: For example a Cipherobject may be initialized but never used for en- or decryption, this may render the code dead. This error heavily depends on the computed call graph (CHA by default).

When the option --reportDir=<folder> is chosen, CogniCryptSAST writes the report to the file CogniCrypt-Report.txt and additionally outputs the .jimple files of the classes where misuses where found in. Jimple is an intermediate representation close to the syntax of Java.

Updating CrySL Rules

The tool takes CrySL rules in their source code formats (crysl). You can adapt the rules in any text editor. Additionaly, the Eclipse plugin CogniCrypt ships with a CrySL editor to modify the rules with IDE support (e.g., content assist, auto completion, etc.). A step-by-step-explanation on how edit CrySL rules is avialable at the tool's website cognicrypt.org.

CogniCryptSAST for Android Applications

CogniCryptSAST can also be run on Android Applications using the Android version for CogniCryptSAST in CryptoAnalysis-Android. Its usage does not deviate much from regular CogniCryptSAST's. CogniCrypt_SAST for Android can be started via the class de.fraunhofer.iem.crypto.CogniCryptAndroid. It requires three arguments in this order:

  • The absolute path to the .apk file
  • The absolute path to the android SDK platforms. The platforms are obtainable via Android Studio. Under the Android SDK location you find a folder platforms. Supply CogniCryptSAST with the path to this folder.
  • The absolute path to the directory of the CrySL rules.
java -cp <path-to-analysis-jar> -Xmx8g -Xss60m de.fraunhofer.iem.crypto.CogniCryptAndroid \
      <path-to-apk> <path-to-android-platforms> <path-to-crysl-rules>

As an optional fourth parameter one can specify an output folder:

java -cp <path-to-analysis-jar> -Xmx8g -Xss60m de.fraunhofer.iem.crypto.CogniCryptAndroid \
      <path-to-apk> <path-to-android-platforms> <path-to-crysl-rules> <output-dir>

If specified, the analysis generates a report file CogniCrypt-Report.txt along with the .jimple output of the classes the analysis found misuses in. The format of the report file follows that described above.

Note, depending on the analyzed application, the analysis may require a lot of memory and a large stack size. Remember to set the necessary heap size (e.g. -Xmx8g) and stack size (e.g. -Xss60m).