diff --git a/README.md b/README.md index 932b52a20..8a6c75457 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Codyze is a static code analyzer that focuses on verifying security compliance i Documentation: https://www.codyze.io -## Build & run Codyze +## Build & Run Codyze Java 11 (OpenJDK) is a prerequisite. @@ -22,50 +22,28 @@ To build an executable version of Codyze, use the `installDist` task: $ ./gradlew installDist ``` -This will provide you with an executable Codyze installation under `build/install/codyze`. Change to that directory and run Codyze: +This will provide you with an executable Codyze installation under `build/install/codyze`. +To start Codyze, change to the directory and run Codyze. + +Codyze has three execution modes: +* commando line interface mode (`-c`) +* language server protocol mode (`-l`) +* interactive console mode (`-t`). + +One of these modes has to be specified as command line option when running Codyze. + +An exemplary call to start the commando line interface mode would be ```shell $ cd build/install/codyze -$ ./bin/codyze +$ ./bin/codyze -c -m ./mark -s ``` +where `` denotes the path to the source directory or file which should be analyzed. -Without further command line arguments, Codyze will print its command line help: +Codyze can be further configured with more command line arguments or a YAML configuration file. +For more information about the usage and configurations, please refer to https://www.codyze.io and the corresponding [wiki page](https://github.com/Fraunhofer-AISEC/codyze/wiki/Usage). -``` -Usage: codyze (-c | -l | -t) [[--typestate=]] [[--analyze-includes] - [--includes=[:|;...]] [--includes=[:|; - ...]]...] [-hV] [--no-good-findings] [-m=] [-o=] - [-s=] [--timeout=] -Codyze finds security flaws in source code - -s, --source= Source file or folder to analyze. - -m, --mark= Load MARK policy files from folder - -o, --output= Write results to file. Use -- for stdout. - --timeout= Terminate analysis after timeout - Default: 120 - --no-good-findings Disable output of "positive" findings which indicate correct - implementations - -h, --help Show this help message and exit. - -V, --version Print version information and exit. -Execution mode - -c Start in command line mode. - -l Start in language server protocol (LSP) mode. - -t Start interactive console (Text-based User Interface). -Analysis settings - --typestate= - Typestate analysis mode - NFA: Non-deterministic finite automaton (faster, intraprocedural) - WPDS: Weighted pushdown system (slower, interprocedural) -Translation settings - --analyze-includes Enables parsing of include files. By default, if --includes are given, - the parser will resolve symbols/templates from these include, but not - load their parse tree. - --includes=[:|;...] - Path(s) containing include files. Path must be separated by : - (Mac/Linux) or ; (Windows) -``` -Please refer to https://www.codyze.io for further usage instructions. - ## Research & Student Work If you are looking for an exciting thesis project or student job in the field of static analysis, we are happy to discuss possible topics. Please contact us at _codyze [at] aisec.fraunhofer.de_. diff --git a/schema/codyze-config-schema.json b/schema/codyze-config-schema.json new file mode 100644 index 000000000..2b3eca148 --- /dev/null +++ b/schema/codyze-config-schema.json @@ -0,0 +1,191 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Codyze Configuration File Schema", + "description": "A schema for writing yaml configuration files for codyze", + "type": "object", + "properties": { + "source": { + "description": "Path to the to be analyzed directory or file", + "type": "string" + }, + "output": { + "description": "Path to output file in which results are written. Use “-” to print to stdout", + "default": "findings.sarif", + "type": "string" + }, + "timeout": { + "description": "Terminates analysis after given minutes", + "default": "120", + "type": "integer", + "exclusiveMinimum": 0 + }, + "sarif": { + "description": "Enables the SARIF output", + "type": "boolean", + "default": "false" + }, + "codyze": { + "description": "Configurations for codyze", + "type": "object", + "properties": { + "mark": { + "description": "Paths to Mark rule files", + "type": "array", + "items": { + "type": "string" + }, + "uniqueItems": true, + "default": ["./"] + }, + "no-good-findings": { + "description": "Disables output of \"positive\" findings", + "type": "boolean", + "default": "false" + }, + "disabled-mark-rules": { + "description": "The specified mark rules will be excluded from being parsed and processed.", + "type": "array", + "items": { + "description": "Has to be specified as .", + "type": "string", + "pattern": "\\.." + } + }, + "pedantic": { + "description": "Activates pedantic analysis mode. In this mode, Codyze analyzes all MARK rules and report all findings. This option overrides \"disabledMarkRules\" and \"noGoodFinding\" and ignores any Codyze source code comments.", + "type": "boolean", + "default" : "false" + }, + "analysis": { + "description": "Analysis configurations", + "type": "object", + "properties": { + "typestate": { + "description": "Specify typestate analysis mode.\nDFA: Deterministic finite automaton (faster, intraprocedural)\nWPDS: Weighted pushdown system (slower, interprocedural)", + "default": "DFA", + "type": "string", + "enum": [ + "DFA", + "WPDS" + ] + } + } + } + } + }, + "cpg": { + "description": "Configurations for cpg", + "type": "object", + "properties": { + "additional-languages": { + "description": "Specify programming languages of to be analyzed files (full names)", + "type": "array", + "items": { + "type": "string", + "enum": [ + "python", + "go" + ] + }, + "uniqueItems": true + }, + "unity": { + "description": "Only relevant for C++. A unity build refers to a build that consolidates all translation units into a single one, which has the advantage that header files are only processed once, adding far less duplicate nodes to the graph", + "type": "boolean", + "default": "false" + }, + "type-system-in-frontend" : { + "description": "If false, type listener system is only activated after the frontends are done building the initial AST structure.", + "type": "boolean", + "default": "true" + }, + "default-passes": { + "description": "Controls the usage of default passes for cpg.", + "type": "boolean", + "default": "true" + }, + "passes": { + "description": "CPG passes in the order in which they should be executed, fully qualified name of the classes only. If default-passes is specified, the default passes are executed first.", + "type": "array", + "items": { + "type": "string", + "pattern": ".\\.." + } + }, + "debug-parser": { + "description": "Controls debug output generation for the cpg parser", + "type": "boolean", + "default": "false" + }, + "disable-cleanup": { + "description": "Switch off cleaning up TypeManager memory after the analysis. Set to true only for testing", + "type": "boolean", + "default": "false" + }, + "code-in-nodes": { + "description": "Controls showing the code of a node as parameter in the node", + "type": "boolean", + "default": "true" + }, + "annotations": { + "description": "Enables processing annotations or annotation-like elements", + "type": "boolean", + "default": "false" + }, + "fail-on-error": { + "description": "Should the parser/translation fail on errors (true) or try to continue in a best-effort manner (false)", + "type": "boolean", + "default": "false" + }, + "symbols": { + "description": "Definition of additional symbols", + "type": "object", + "properties": { + "description": "symbol: description", + "type": "string" + } + }, + "parallel-frontends": { + "description": "Enables parsing the ASTs for the source files in parallel, but the passes afterwards will still run in a single thread", + "type": "boolean", + "default": "false" + }, + "translation": { + "description": "Translation configurations", + "type": "object", + "properties": { + "analyze-includes": { + "description": "Enables parsing of include files. If includePaths are given, the parser will resolve symbols/templates from these in include but not load their parse tree", + "type": "boolean", + "default": "false" + }, + "includes": { + "description": "Paths containing include files", + "type": "array", + "items": { + "type": "string" + }, + "uniqueItems": true + }, + "enabled-includes": { + "description": "If includes is not empty, only the specified files will be parsed and processed in the cpg, unless it is a part of the disabled list, in which it will be ignored.", + "type": "array", + "items": { + "type": "string" + }, + "uniqueItems": true + }, + "disabled-includes": { + "description": "If includes is not empty, the specified files will be excluded from being parsed and processed in the cpg. The disabled list entries always take priority over the enabled list entries.", + "type": "array", + "items": { + "type": "string" + }, + "uniqueItems": true + } + } + } + } + } + } +} \ No newline at end of file diff --git a/src/main/java/de/fraunhofer/aisec/codyze/config/CpgConfiguration.kt b/src/main/java/de/fraunhofer/aisec/codyze/config/CpgConfiguration.kt index eaf3226b0..374df3740 100644 --- a/src/main/java/de/fraunhofer/aisec/codyze/config/CpgConfiguration.kt +++ b/src/main/java/de/fraunhofer/aisec/codyze/config/CpgConfiguration.kt @@ -91,6 +91,7 @@ class CpgConfiguration { ) var codeInNodes = true + @JsonProperty("annotations") @Option( names = ["--annotations"], description = ["Enables processing annotations or annotation-like elements"], @@ -115,6 +116,7 @@ class CpgConfiguration { ) var symbols: Map = HashMap() + @JsonProperty("parallel-frontends") @Option( names = ["--parallel-frontends"], description =