Skip to content

Latest commit

 

History

History
139 lines (99 loc) · 10.8 KB

README.md

File metadata and controls

139 lines (99 loc) · 10.8 KB
Raw

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.

Structure

We provide the implementation of the static analysis of CogniCrypt in:

  • CryptoAnalysis contains the components for the actual analysis
  • CryptoAnalysisTargets contains various example applications that are also used to test the correctness of CryptoAnalyis

We further provide two SAST tools that allow the analysis of Java and Android applications:

  • HeadlessJavaScanner contains the SAST tool that analyzes Java applications (see below)
  • HeadlessAndroidScanner contains the SAST tool that analyzes Android applications (see below)

Releases

You can checkout a pre-compiled version of CogniCryptSAST here. We recommend using the latest version.

Download the two files:

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

You can find CogniCryptSAST also on Maven Central.

Checkout and Build

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

mvn clean package -DskipTests=true.

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

CogniCryptSAST for Java Applications

CogniCryptSAST can be started in headless mode (i.e., detached from Eclipse) via the file HeadlessJavaScanner-x.y.z-jar-with-dependencies.jar. It requires two arguments:

  • The path to the directory of the CrySL (source code format) rule files. The source code for the rules which contain specification for the JCA is found here.
  • The path of the application to be analyzed (.jar file or the root compilation output folder which contains the .class files in subdirectories)
java -jar HeadlessJavaScanner-x.y.z-jar-with-dependencies.jar 
      --rulesDir <path-to-crysl-source-code-format-rules> 
      --appPath <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.

java -jar HeadlessJavaScanner-x.y.z-jar-with-dependencies.jar
  --rulesDir $(pwd)/CryptoAnalysis-Core/src/main/resources/JavaCryptographicArchitecture
  --appPath $(pwd)/CryptoAnalysisTargets/CogniCryptDemoExample/Examples.jar

Other additional arguments that can be used are as follows:

--cg <selection_of_call_graph_for_analysis> (possible values are CHA, SPARK, SPARKLIB)
--sootPath <absolute_path_of_whole_project>
--identifier <identifier_for_labeling_output_files>
--reportPath <directory_location_for_cryptoanalysis_report>
--reportFormat <format of cryptoanalysis_report> (possible values are CMD, TXT, SARIF, CSV, CSV_SUMMARY)
--visualization (enables the visualization, but also requires --reportPath option to be set)
--dstats (disables the output of the analysis statistics in the reports)
--ignoreSections (Text file with packages (e.g. `de.example.*`), classes (e.g. `de.example.exmapleClass`) or methods (e.g. `de.example.exampleClass.exampleMethod`), one per line. Those packages, classes and methods are ignored during the analysis)
--timeout <timeout in milliseconds> (Timeout for seeds in milliseconds. If a seed exceeds this value, CryptoAnalysis aborts the typestate and extract parameter analysis and continues with the results computed so far. (default: 10000))
--help (show more information for the CLI arguments)

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).

Use as a GitHub Action

CogniCryptSAST 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.

Report and Error Types

CogniCryptSAST reports 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).

  • UncaughtExceptionError: A method may throw an exception, but the exception is not caught in the program. For example, the method call is not surrounded by a try/catch block.

CogniCryptSAST supports different report formats, which can be set by using --reportformat option. The supported formats are:

  • CMD: The report is printed to the command line. The content is equivalent to the format from the TXT option.
  • TXT: The report is written to the text file CryptoAnalysis-Report.txt. The content is equivalent to the format from the CMD option. Additionally, the .jimple files of the classes, where misuses were found in, are output. Jimple is an intermediate representation close to the syntax of Java.
  • SARIF: The report is written to the JSON file CryptoAnalysis-Report.json. The content is formatted in the SARIF format.
  • CSV: The report is written to the CSV file CryptoAnalysis-Report.csv. The content is formatted in the CSV format.
  • CSV_SUMMARY: The report is written to the file CryptoAnalysis-Report-Summary.csv and contains a summary of the analysis results. Compared to the CSV format, this format does not provide concrete information about the errors, it only lists the amount of each misuse type. This option was previously implemented by the CSV option, which has been changed to provide more detailed information about the errors in the CSV format.
  • GITHUB_ANNOTATION: Works like CMD but also outputs all violations as annotations when running inside as a GitHub Action.

If the --reportformat option is not specified, CogniCryptSAST defaults to the CMD option. It also allows the usage of multiple different formats for the same analysis (e.g. --reportformat CMD,TXT,CSV creates a report, which is printed to the command line and is written to a text and CSV file). If the option --reportPath <directory_location_for_cryptoanalysis_report> is set, the reports are created in the specified directory.

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 scanner HeadlessAndroidScanner-x.y.z-jar-with-dependencies.jar. Its usage does not deviate much from regular CogniCryptSAST's. It requires three arguments:

  • --apkFile: The absolute path to the .apk file
  • --platformDirectory: 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.
  • --rulesDir: The absolute path to the directory of the CrySL rules.
java -jar HeadlessAndroidScanner-x.y.z-jar-with-dependencies.jar
      --rulesDir <path-to-crysl-source-code-format-rules>
	  --platformDirectory <path-to-android-platform>
      --appPath <application-path>

Optional parameters are --reportPath and --reportFormat. They have the same functionality as the HeadlessJavaScanner-x.y.z-jar-with-dependencies.jar (see above).

Again, 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).