CryptoAnalysis
4.1.0
该存储库包含Cognitrypt Sast ，这是Cognicrypt的静态分析成分。静态分析Cognitrypt Sast将规范语言CRYSL编写的规则作为输入，并基于规则规范执行静态分析。 Crysl是一种特定领域的语言（DSL），旨在编码密码诽谤的用法规范（例如，尤其是JCA）。有关CRYSL和静态分析的更多信息，请参见本文。
假设我们有以下程序有一些违规：
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 ，它会在./output/中创建以下图像visualization.png 。
您可以看到对象r0 （keygenerator）上的两个ConstraintErrors在对象r1 （secretkey）上引起RequiredPredicateError ，又导致对象r2 （cipher）上的RequiredPredicateError 。此外，密码对象上还有另一个ConstraintError和IncompleteOperationError 。请注意，变量和语句对应于中间表示jimple。您可以将变量匹配到列出所有分析对象的命令行输出。
我们提供了认知静态分析的实施：
CryptoAnalysis包含用于实际分析的组成部分CryptoAnalysisTargets包含各种示例应用程序，这些应用程序也用于测试CryptoAnalyis的正确性我们进一步提供了两个SAST工具，可以分析Java和Android应用程序：
HeadlessJavaScanner包含分析Java应用程序的SAST工具（见下文）HeadlessAndroidScanner包含分析Android应用的SAST工具（见下文） 您可以在此处查看cognitrypt的预编译版本。我们建议使用最新版本。您可以在Maven Central上找到Cognitrypt Sast 。
Cognicrypt Sast使用Maven作为构建工具。您可以通过
mvn clean package -DskipTests 。
包装的jar工件在内，包括所有依赖关系，都可以在/apps中找到。建筑物至少需要Java 17。
Cognicrypt Sast可以通过文件HeadlessJavaScanner-xyz-jar-with-dependencies.jar以CLI工具的形式启动。它需要两个论点：
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）。
Cognicrypt Sast可以用作GitHub动作。
- name : Run CogniCrypt
uses : CROSSINGTUD/CryptoAnalysis@version
with :
appPath : " CryptoAnalysisTargets/HelloWorld/HelloWorld.jar "
basePath : " CryptoAnalysisTargets/HelloWorld "需要配置该appPath以指向应用程序的编译版本。
basePath用于将分析的jar和源树中的路径联系起来。在basePath/com/example中搜索com.example类。
有关所有输入选项，请参见action.yml 。
可以在加密分析寄存器库中找到如何使用github动作的一个示例。
当代码不符合CRYSL规则时，Cognicrypt报告了SAST报告的滥用。对于每种滥用，Cognicrypt sast报告了类和滥用所包含的方法。有多种滥用类型：
约束：违反了Crysl规则的约束，例如，键的密钥大小是错误的。
Nevertypeoferror ：报告何时发现一个值为某种参考类型：例如，绝对不应从String转换包含密码的字符数组。 （请参阅此处的KeyStore规则）。
Filbidendmethoderror ：在某些情况下发现了一种禁止的方法（禁止Crysl块）。
ImbreciseValueExtractionError ：静态分析无法提取CRYSL约束块中所需的所有信息。例如，密钥大小可以作为配置文件中列出的值提供。静态分析不会对文件的内容进行建模，并且可能不会限制该值。
passestateError ：违反了Crysl的订单块，即要进行的预期方法序列呼叫是不正确的。例如， Signature对象期望在更新之前对initSign(key)进行调用update(data) 。
必要的PREDICEWICEERROR ：一个对象A期望对象B正确使用（Crysl块需要并确保）。例如， Cipher对象需要正确并安全地生成一个SecretKey对象。
不完整的呼气：对象的用法可能不完整：例如，可以初始化Cipher对象，但从未用于启动或解密，这可能会使代码死亡。此错误在很大程度上取决于计算的呼叫图（默认情况下为CHA）。
UnneaughtexceptionError ：一种方法可能会引发例外，但是该程序并未捕获该例外。例如，方法调用不会被尝试/捕获块包围。
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选项已更改以提供有关CSV格式中错误的更详细信息。GITHUB_ANNOTATION ：工作类似于CMD ，但在作为GitHub动作内部运行时，所有违规行为都作为注释。如果未指定--reportformat选项，则Cognicrypt将SAST默认为CMD选项。它还允许使用多种不同格式进行相同的分析（例如--reportformat CMD,TXT,CSV创建一个报告，该报告打印到命令行并将其写入文本和CSV文件）。如果设置了选项--reportPath <directory_location_for_cryptoanalysis_report> ，则在指定的目录中创建了报告（和可视化）。
Cognitrypt SAST也可以使用Android Scanner HeadlessAndroidScanner-xyz-jar-with-dependencies.jar在Android应用程序上运行。它的用法与常规Cognitrypt Sast的使用并不多。它需要三个论点：
--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）。
我们为社区的每一项贡献感到高兴！
