Skip to content

Commit 16e4b60

Browse files
Hazem-GamallHazem-Gamall
authored
Update README.md
1 parent 88aa13b commit 16e4b60

1 file changed

Lines changed: 33 additions & 128 deletions

File tree

‎README.md‎

Lines changed: 33 additions & 128 deletions
Original file line numberDiff line numberDiff line change
@@ -1,114 +1,52 @@
11
# CogniCrypt<sub>SAST</sub>
22

3-
This repository contains CogniCrypt<sub>SAST</sub>, the static analysis component for [CogniCrypt](https://www.cognicrypt.org).
4-
The static analysis CogniCrypt<sub>SAST</sub> takes rules written in the specification language CrySL as input,
3+
This repository contains **CogniCrypt<sub>SAST</sub>**, the static analysis component for [CogniCrypt](https://www.cognicrypt.org).
4+
The static analysis **CogniCrypt<sub>SAST</sub>** takes rules written in the specification language CrySL as input,
55
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
66
libaries (e.g., the [JCA](https://docs.oracle.com/en/java/javase/14/security/java-cryptography-architecture-jca-reference-guide.html) in particular). More information on CrySL and the static analysis may be found in [this paper](http://drops.dagstuhl.de/opus/volltexte/2018/9215/).
77

8-
## Running CognitCrypt<sub>SAST</sub>
9-
10-
Let's assume we have the following program with some violations:
11-
12-
```java
13-
import java.security.GeneralSecurityException;
14-
import javax.crypto.KeyGenerator;
15-
import javax.crypto.SecretKey;
16-
import javax.crypto.spec.SecretKeySpec;
17-
import javax.crypto.Cipher;
18-
19-
public class Example {
20-
21-
public static void main(String[] args) throws GeneralSecurityException {
22-
// Constraint Error: "DES" is not allowed
23-
KeyGenerator generator = KeyGenerator.getInstance("DES"); // r0
8+
Refer to the [documentation](https://crossingtud.github.io/CryptoAnalysis/latest/) for more technical details.
249

25-
// Constraint Error: Key size of 64 is not allowed
26-
generator.init(64);
27-
28-
// KeyGenerator is not correctly initialized
29-
// RequiredPredicateEror: Generated key is not secure
30-
SecretKey key = generator.generateKey(); // r1
10+
## Running CognitCrypt<sub>SAST</sub>
3111

32-
// Constraint Error: "DES" is not allowed
33-
Cipher cipher = Cipher.getInstance("DES"); // r2
12+
**CogniCrypt<sub>SAST</sub>** analyzes Java and Android apps to detect cryptographic misuses based on [CrySL rules](https://github.com/CROSSINGTUD/Crypto-API-Rules).
3413

35-
// RequiredPredicateError: "key" is not securely generated
36-
cipher.init(Cipher.ENCRYPT_MODE, key);
14+
### 1. Prepare Your Inputs
3715

38-
// IncompleteOperationError: Cipher object is not used
39-
}
40-
}
41-
```
16+
- Compile your application to a `.jar` or `.class` output
17+
- Download CrySL rules (e.g. [JCA rules](https://github.com/CROSSINGTUD/Crypto-API-Rules))
4218

43-
Using the [JCA rules](https://github.com/CROSSINGTUD/Crypto-API-Rules/tree/master/JavaCryptographicArchitecture/src), we execute the following command on a compiled version of this program:
19+
### 2. Run the Analysis
4420

4521
```bash
46-
java -jar HeadlessJavaScanner-x.y.z-jar-with-dependencies.jar --appPath ./Examples.jar --rulesDir ./JCA-CrySL-rules.zip --reportFormat CMD --reportPath ./output/ --visualization
22+
java -jar HeadlessJavaScanner-x.y.z-jar-with-dependencies.jar \
23+
--appPath ./YourApp.jar \
24+
--rulesDir ./CrySL-Rules/ \
25+
--reportFormat CMD \
26+
--reportPath ./output/ \
27+
--visualization
4728
```
4829

49-
CogniCrypt<sub>SAST</sub> runs the analysis and prints a report to the command line. In total, it reports 3 `ConstraintErrors`, 2 `RequiredPredicateErrors` and 1 `IncompleteOperationError`, and their positions in the original programs. Additionally, since we use `--visualization`, it creates the following image `visualization.png` in the directory `./output/`:
50-
51-
![visualization.png](misc/visualization.png)
52-
53-
You can see that two `ConstraintErrors` on the object `r0` (KeyGenerator) cause a `RequiredPredicateError` on the object `r1` (SecretKey) which in turn causes a `RequiredPredicateError` on the object `r2` (Cipher). Additionally, there is another `ConstraintError` and `IncompleteOperationError` on the Cipher object. Note that the variables and statements correspond to the intermediate representation Jimple. You can match the variables to the command line output that lists all analyzed objects.
54-
55-
56-
## Structure
57-
We provide the implementation of the static analysis of CogniCrypt in:
58-
* `CryptoAnalysis` contains the components for the actual analysis
59-
* `CryptoAnalysisTargets` contains various example applications that are also used to test the correctness of CryptoAnalyis
60-
61-
We further provide two SAST tools that allow the analysis of Java and Android applications:
62-
63-
* `HeadlessJavaScanner` contains the SAST tool that analyzes Java applications (see below)
64-
* `HeadlessAndroidScanner` contains the SAST tool that analyzes Android applications (see below)
65-
66-
## Releases
67-
68-
You can checkout a pre-compiled version of CogniCrypt<sub>SAST</sub> [here](https://github.com/CROSSINGTUD/CryptoAnalysis/releases). We recommend using the latest version. You can find CogniCrypt<sub>SAST</sub> also on [Maven Central](https://central.sonatype.com/artifact/de.fraunhofer.iem/CryptoAnalysis).
69-
70-
## Checkout and Build
71-
72-
CogniCrypt<sub>SAST</sub> uses Maven as build tool. You can compile and build this project via
30+
### 3. Output
7331

74-
```mvn clean package -DskipTests```.
75-
76-
The packaged `jar` artifacts including all dependencies can be found in `/apps`. Building requires at least Java 17.
77-
78-
## CogniCrypt<sub>SAST</sub> for Java Applications
79-
80-
CogniCrypt<sub>SAST</sub> can be started in headless mode as CLI tool via the file `HeadlessJavaScanner-x.y.z-jar-with-dependencies.jar`. It requires two arguments:
81-
* 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](https://github.com/CROSSINGTUD/Crypto-API-Rules).
82-
* The path of the application to be analyzed (.jar file or the root compilation output folder which contains the .class files in subdirectories)
32+
- Reports are written to `--reportPath` and/or printed to the console
33+
- Misuse types include: `ConstraintError`, `TypestateError`, see [Error Types](https://crossingtud.github.io/CryptoAnalysis/latest/error-types/) for more.
34+
- `visualization.png` shows misuse dependencies
8335

84-
```
85-
java -jar HeadlessJavaScanner-x.y.z-jar-with-dependencies.jar
86-
--rulesDir <path-to-crysl-source-code-format-rules>
87-
--appPath <application-path>
88-
```
36+
> ⚠️ Note: You may need to allocate more memory for large analyses:
37+
> `-Xmx8g -Xss60m`
8938
90-
For an easy start we prepared a .jar containing classes with crypto misuses. The source code for these misuses is found [here](https://github.com/CROSSINGTUD/CryptoAnalysis/tree/develop/CryptoAnalysisTargets/CogniCryptDemoExample/src/main/java/example).
39+
For advanced options, Android support, and more, visit the [full documentation](https://crossingtud.github.io/CryptoAnalysis/latest/).
9140

92-
Other additional arguments that can be used are as follows:
41+
## Android Support
9342

94-
```
95-
--cg <selection_of_call_graph_for_analysis> (possible values are CHA, SPARK, SPARKLIB)
96-
--sootPath <absolute_path_of_whole_project>
97-
--identifier <identifier_for_labeling_output_files>
98-
--reportPath <directory_location_for_cryptoanalysis_report>
99-
--reportFormat <format of cryptoanalysis_report> (possible values are CMD, TXT, SARIF, CSV, CSV_SUMMARY)
100-
--visualization (Create a visualization of all errors (requires --reportPath option to be set))
101-
--dstats (disables the output of the analysis statistics in the reports)
102-
--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)
103-
--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))
104-
--help (show more information for the CLI arguments)
105-
```
43+
**CogniCrypt<sub>SAST</sub>** also supports analysis of Android applications via `HeadlessAndroidScanner`. You'll need an `.apk` file and the Android SDK platform directory.
10644

107-
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).
45+
See the [Android analysis guide](https://crossingtud.github.io/CryptoAnalysis/latest/android-scanner/) for full instructions and setup.
10846

109-
### Use as a GitHub Action
47+
## Use as a GitHub Action
11048

111-
CogniCrypt<sub>SAST</sub> can be used as a GitHub action.
49+
**CogniCrypt<sub>SAST</sub>** can be used as a GitHub action.
11250

11351
```yaml
11452
- name: Run CogniCrypt
@@ -127,52 +65,19 @@ See [`action.yml`](action.yml) for all input options.
12765

12866
An example of how to use the GitHub action can be found in the [CryptoAnalysis-demo repository](https://github.com/CROSSINGTUD/CryptoAnalysis-demo/actions).
12967

130-
## Report and Error Types
131-
132-
CogniCrypt<sub>SAST</sub> reports misuses when the code is not compliant with the CrySL rules. For each misuse, CogniCrypt<sub>SAST</sub> reports the class and the method the misuse is contained in. There are multiple misuse types:
133-
134-
* **ConstraintError**: A constraint of a CrySL rule is violated, e.g., a key is generated with the wrong key size.
135-
* **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](https://github.com/CROSSINGTUD/Crypto-API-Rules/blob/master/src/de/darmstadt/tu/crossing/KeyStore.cryptsl)).
136-
* **ForbiddenMethodError**: A method that is forbidden (CrySL block FORBIDDEN) to be called under some circumstances was found.
137-
* **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.
138-
* **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)`.
139-
140-
* **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.
141-
* **IncompleteOperationError**: The usage of an object may be incomplete: For example a `Cipher`object 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).
142-
* **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.
143-
144-
CogniCrypt<sub>SAST</sub> supports different report formats, which can be set by using `--reportformat` option. The supported formats are:
145-
- `CMD`: The report is printed to the command line. The content is equivalent to the format from the `TXT` option.
146-
- `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.
147-
- `SARIF`: The report is written to the JSON file `CryptoAnalysis-Report.json`. The content is formatted in the SARIF format.
148-
- `CSV`: The report is written to the CSV file `CryptoAnalysis-Report.csv`. The content is formatted in the CSV format.
149-
- `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.
150-
- `GITHUB_ANNOTATION`: Works like `CMD` but also outputs all violations as annotations when running inside as a GitHub Action.
68+
## Releases
15169

152-
If the `--reportformat` option is not specified, CogniCrypt<sub>SAST</sub> 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 (and the visualization) are created in the specified directory.
70+
You can checkout a pre-compiled version of **CogniCrypt<sub>SAST</sub>** [here](https://github.com/CROSSINGTUD/CryptoAnalysis/releases). We recommend using the latest version. You can find **CogniCrypt<sub>SAST</sub>** also on [Maven Central](https://central.sonatype.com/artifact/de.fraunhofer.iem/CryptoAnalysis).
15371

15472

155-
## CogniCrypt<sub>SAST</sub> for Android Applications
73+
## Checkout and Build
15674

157-
CogniCrypt<sub>SAST</sub> 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 CogniCrypt<sub>SAST</sub>'s. It requires three arguments:
158-
* `--apkFile`: The absolute path to the .apk file
159-
* `--platformDirectory`: The absolute path to the android SDK platforms. The platforms are obtainable via [Android Studio](https://developer.android.com/studio/releases/platforms). Under the Android SDK location you find a folder `platforms`. Supply CogniCrypt<sub>SAST</sub> with the path to this folder.
160-
* `--rulesDir`: The absolute path to the directory of the CrySL rules.
75+
**CogniCrypt<sub>SAST</sub>** uses Maven as build tool. You can compile and build this project via
16176

162-
```
163-
java -jar HeadlessAndroidScanner-x.y.z-jar-with-dependencies.jar
164-
--rulesDir <path-to-crysl-source-code-format-rules>
165-
--platformDirectory <path-to-android-platform>
166-
--appPath <application-path>
167-
```
77+
```mvn clean package -DskipTests```.
16878

169-
Optional arguments are:
170-
* `--cg`: The call graph algorithm to use. Possible values are {CHA, RTA, VTA, SPARK}
171-
* `--reportPath`: Path to a directory to store the reports
172-
* `--reportFormat`: Report format(s)
173-
The arguments `--reportPath` and `--reportFormat` have the same functionality as the `HeadlessJavaScanner-x.y.z-jar-with-dependencies.jar` (see above).
79+
The packaged `jar` artifacts including all dependencies can be found in `/apps`. Building requires at least Java 17.
17480

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

17782
## How can I contribute?
17883
We hare happy for every contribution from the community!

0 commit comments

Comments
 (0)