CryptoAnalysis

Cognicrypt _Sast

このリポジトリには、CognicRyptの静的分析コンポーネントであるCognicrypt _SASTが含まれています。静的分析Cognicrypt _SASTは、仕様言語CrySLに入力として記述されたルールを取得し、ルールの仕様に基づいて静的分析を実行します。 CRYSLは、暗号化する責任者（特にJCAなど）の使用仕様をエンコードするように設計されたドメイン固有の言語（DSL）です。 CRYSLと静的分析の詳細については、この論文に記載されています。

CognitCryptを実行してい_ます

いくつかの違反を伴う次のプログラムがあると仮定しましょう。

 import java . security . GeneralSecurityException ;
import javax . crypto . KeyGenerator ;
import javax . crypto . SecretKey ;
import javax . crypto . spec . SecretKeySpec ;
import javax . crypto . Cipher ;

public class Example {

    public static void main ( String [] args ) throws GeneralSecurityException {
        // Constraint Error: "DES" is not allowed
        KeyGenerator generator = KeyGenerator . getInstance ( "DES" ); // r0

        // Constraint Error: Key size of 64 is not allowed
        generator . init ( 64 );

        // KeyGenerator is not correctly initialized
        // RequiredPredicateEror: Generated key is not secure
        SecretKey key = generator . generateKey (); // r1

        // Constraint Error: "DES" is not allowed
        Cipher cipher = Cipher . getInstance ( "DES" ); // r2

        // RequiredPredicateError: "key" is not securely generated
        cipher . init ( Cipher . ENCRYPT_MODE , key );

        // IncompleteOperationError: Cipher object is not used
    }
}

JCAルールを使用して、このプログラムのコンパイルされたバージョンで次のコマンドを実行します。

java -jar HeadlessJavaScanner-x.y.z-jar-with-dependencies.jar --appPath ./Examples.jar --rulesDir ./JCA-CrySL-rules.zip --reportFormat CMD --reportPath ./output/ --visualization

CognicRypt _SASTは分析を実行し、コマンドラインへのレポートを印刷します。合計で、3つのConstraintErrors 、2つのRequiredPredicateErrors 、1つのIncompleteOperationError 、および元のプログラムにおけるその位置を報告します。さらに、 --visualizationを使用しているため、Directory ./output/で次の画像visualization.pngを作成します。

オブジェクトr0 （keygenerator）上の2つのConstraintErrorsがオブジェクトr1 （SecretKey）にRequiredPredicateErrorエラーを引き起こし、オブジェクトr2 （CIPHER）にRequiredPredicateErrorエラーを引き起こすことがわかります。さらに、暗号オブジェクトには別のConstraintErrorとIncompleteOperationErrorがあります。変数とステートメントは、中間表現Jimpleに対応することに注意してください。変数を、すべての分析されたオブジェクトをリストするコマンドライン出力に一致させることができます。

構造

cognicryptの静的分析の実装を次のように提供します。

• CryptoAnalysisには、実際の分析のコンポーネントが含まれています
• CryptoAnalysisTargets 、暗号分析の正しさをテストするためにも使用されるさまざまな例アプリケーションが含まれています

さらに、JavaおよびAndroidアプリケーションの分析を可能にする2つのSASTツールを提供します。

• HeadlessJavaScannerには、Javaアプリケーションを分析するSASTツールが含まれています（以下を参照）
• HeadlessAndroidScannerには、Androidアプリケーションを分析するSASTツールが含まれています（以下を参照）

リリース

ここでは、事前にコンパイルされたcognicrypt _sastのバージョンをチェックアウトできます。最新バージョンを使用することをお勧めします。 Maven CentralでもCognicrypt _Sastを見つけることができます。

チェックアウトとビルド

Cognicrypt _Sastは、Mavenをビルドツールとして使用します。このプロジェクトをコンパイルして構築できます

mvn clean package -DskipTests 。

すべての依存関係を含むパッケージ化されたjarアーティファクトは、 /appsにあります。建物には少なくともJava 17が必要です。

Javaアプリケーション用のCognicRypt _SAST

Cognicrypt _SASTは、ファイルHeadlessJavaScanner-xyz-jar-with-dependencies.jarを介してCLIツールとしてヘッドレスモードで開始できます。 2つの引数が必要です。

• CRYSL（ソースコード形式）ルールファイルのディレクトリへのパス。 JCAの仕様を含むルールのソースコードはここにあります。
• 分析するアプリケーションのパス（.jarファイルまたはサブディレクトリの.classファイルを含むルートコンパイル出力フォルダー）

 java -jar HeadlessJavaScanner-x.y.z-jar-with-dependencies.jar 
      --rulesDir <path-to-crysl-source-code-format-rules> 
      --appPath <application-path>

簡単にスタートするために、暗号化の誤用を伴う.jarを含むクラスを準備しました。これらの誤用のソースコードはここにあります。

使用できる他の追加の引数は次のとおりです。

 --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 (Create a visualization of all errors (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)

注意して、分析されたアプリケーションに応じて、分析には多くのメモリと大きなスタックサイズが必要になる場合があります。必要なヒープサイズ（-XMX8Gなど）とスタックサイズ（例えば-XSS60M）を設定することを忘れないでください。

GitHubアクションとして使用します

Cognicrypt _SASTは、GitHubアクションとして使用できます。

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

appPath 、アプリケーションのコンパイルされたバージョンを指すように構成する必要があります。

basePath 、分析された瓶とソースツリーのパスを関連付けるために使用されます。クラスcom.exampleはbasePath/com/exampleで検索されます。

すべての入力オプションについては、 action.yml参照してください。

GitHubアクションの使用方法の例は、暗号分析DEMOリポジトリにあります。

レポートとエラータイプ

CognicRyptは、CRYSLルールにコードが準拠していない場合、 _{SAST SASTの}報告を報告しています。誤用ごとに、Cognicrypt_はクラスと誤用が含まれている方法を報告します。複数の誤用タイプがあります。

• Constrainterror ：CRYSLルールの制約に違反されます。たとえば、キーが間違ったキーサイズで生成されます。

• nevetypeoferror ：値が特定の参照タイプであることが判明した場合に報告されています。たとえば、パスワードを含む文字配列は、 Stringから決して変換してはなりません。 （ここでKeyStoreルールを参照）。

• ForbiddenMethoderror ：一部の状況下で呼び出される禁止された方法（Cryslブロックが禁止されている）が見つかりました。

• RecreciseValueExtractionError ：静的分析では、CRYSL制約ブロック内で必要なすべての情報を抽出できませんでした。たとえば、キーサイズは、構成ファイルにリストされた値として提供できます。静的分析はファイルのコンテンツをモデル化せず、値を制約しない場合があります。

• TypeStateError ：CRYSLの注文ブロックに違反します。つまり、予想されるメソッドシーケンス呼び出しが行われることは間違っています。たとえば、 Signatureオブジェクトは、 update(data)の前にinitSign(key)への呼び出しを期待します。

• requiredpredicateerror ：オブジェクトAは、オブジェクトBが正しく使用されていると予想しています（Cryslブロックが必要とし、保証します）。たとえば、 Cipherオブジェクトには、 SecretKeyオブジェクトを正しく安全に生成する必要があります。

• 不完全なOperationError ：オブジェクトの使用は不完全な場合があります。たとえば、 Cipherオブジェクトは初期化される場合がありますが、en-または復号化に使用されることはありません。これにより、コードが死亡する可能性があります。このエラーは、計算されたコールグラフ（デフォルトでCHA）に大きく依存します。

• UncaughtexceptionError ：メソッドは例外をスローする場合がありますが、例外はプログラムに巻き込まれていません。たとえば、メソッド呼び出しはトライ/キャッチブロックに囲まれていません。

CognicRypt _SASTは、 --reportformatオプションを使用して設定できるさまざまなレポート形式をサポートしています。サポートされている形式は次のとおりです。

• CMD ：レポートはコマンドラインに印刷されています。コンテンツは、 TXTオプションの形式に相当します。
• TXT ：レポートは、テキストファイルCryptoAnalysis-Report.txtに書き込まれます。コンテンツは、 CMDオプションの形式に相当します。さらに、誤用が見つかったクラスのjimpleファイルは出力です。 Jimpleは、Javaの構文に近い中間表現です。
• SARIF ：このレポートは、JSONファイルCryptoAnalysis-Report.jsonに書かれています。コンテンツはSARIF形式でフォーマットされています。
• CSV ：レポートは、CSVファイルCryptoAnalysis-Report.csvに書き込まれます。コンテンツはCSV形式でフォーマットされています。
• CSV_SUMMARY ：レポートはファイルCryptoAnalysis-Report-Summary.csvに書き込まれ、分析結果の要約が含まれています。 CSV形式と比較して、この形式はエラーに関する具体的な情報を提供するのではなく、各誤用型の量のみをリストします。このオプションは以前にCSVオプションによって実装されていました。これは、CSV形式のエラーに関するより詳細な情報を提供するために変更されました。
• GITHUB_ANNOTATION ： CMDのように機能するだけでなく、すべての違反をGitHubアクションとして内部で実行するときに注釈として出力します。

--reportformatオプションが指定されていない場合、CognIcryptはCMDオプションにデフォルトで_sastです。また、同じ分析に複数の異なる形式を使用することもできます（例： --reportformat CMD,TXT,CSVコマンドラインに印刷され、テキストとCSVファイルに書き込まれるレポートを作成します）。オプション--reportPath <directory_location_for_cryptoanalysis_report>が設定されている場合、レポート（および視覚化）が指定されたディレクトリに作成されます。

Androidアプリケーション用のCognicRypt _SAST

Cognicrypt _SASTは、AndroidスキャナーHeadlessAndroidScanner-xyz-jar-with-dependencies.jarを使用してAndroidアプリケーションで実行することもできます。その使用法は、通常のCognicrypt _Sastからあまり逸脱していません。 3つの引数が必要です。

• --apkFile ：.apkファイルへの絶対パス
• --platformDirectory ：Android SDKプラットフォームへの絶対パス。プラットフォームは、Android Studio経由で入手可能です。 Android SDKの場所には、フォルダーplatformsがあります。このフォルダーへのパスで_Cognicryptを供給します。
• --rulesDir ：CRYSLルールのディレクトリへの絶対的なパス。

 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>

オプションのパラメーターは、 --reportPathおよび--reportFormatです。それらはHeadlessJavaScanner-xyz-jar-with-dependencies.jarと同じ機能を持っています（上記参照）。

指定されている場合、分析では、レポートファイルCogniCrypt-Report.txtとクラスの.jimple出力とともに生成されます。分析では、誤用が見つかりました。レポートファイルの形式は上記のものです。

繰り返しますが、分析されたアプリケーションに応じて、分析には多くのメモリと大きなスタックサイズが必要になる場合があります。必要なヒープサイズ（-XMX8Gなど）とスタックサイズ（例えば-XSS60M）を設定することを忘れないでください。

どうすれば貢献できますか？

コミュニティからのあらゆる貢献に満足しています！

• 問題の詳細とマージリクエストのために貢献します。
• このプロジェクトのコーディングガイド。