feat(cli): parametrizing query execution timeout - closes #3047

Signed-off-by: Rogério Peixoto <[email protected]>

docs/CONTRIBUTING.md

@@ -1,8 +1,8 @@
 ## Contribution
 
-We would like to THANK YOU for considering contributing to KICS!  
+We would like to THANK YOU for considering contributing to KICS!
 
-KICS is a true community project. It's built as an open source from day one, and anyone can find his own way to contribute to the project.  
+KICS is a true community project. It's built as an open source from day one, and anyone can find his own way to contribute to the project.
 
 Within just minutes, you can start making a difference, by sharing your expertise with a community of thousands of security experts and software developers.
 
@@ -12,7 +12,7 @@ Good news! You don't have to contribute code. There are plenty of ways you can c
 
 - Reporting new [bugs or issues](https://github.com/Checkmarx/kics/issues)
 - Help triaging issues
-- Improving and translating the documentation 
+- Improving and translating the documentation
 - Volunteering to maintain the project
 
 #### Code of Conduct
@@ -26,34 +26,35 @@ By participating and contributing to the project, you agree to uphold our [Code
 Follow the instructions below to setup local KICS development environment and push your changes.
 
 1. Fork the `kics` repo on GitHub.
-1. Clone your fork locally:  
-   ```
+1. Clone your fork locally:
+   ```shell
    git clone https://github.com/Checkmarx/kics.git
    ```
-1. Create a branch for local development.  
-Use succinct but descriptive name (prefix with *feature/issue#-descriptive-name>* or *hotfix/issue#-descriptive-name*):  
-   ```
+1. Create a branch for local development.
+Use succinct but descriptive name (prefix with *feature/issue#-descriptive-name>* or *hotfix/issue#-descriptive-name*):
+   ```shell
    git checkout -b <name-of-your-issue>
    ```
 1. Make your changes locally.
-1. Validate your changes to reassure they meet project quality and contribution standards:  
-   ```
+1. Validate your changes to reassure they meet project quality and contribution standards:
+   ```shell
    golint .
-   ```  
    ```
+   ```shell
    go mod vendor
-   ```  
    ```
+   ```shell
    go test -mod=vendor -v ./...
    ```
-1. Commit your changes and push your branch to GitHub:  
-   ```
+1. Commit your changes and push your branch to GitHub:
+   ```shell
    git add .
-   ```  
    ```
-   git commit
-   ```  
+   We recommend following [conventional commits messages](https://www.conventionalcommits.org/en/v1.0.0-beta.2/)
+   ```shell
+   git commit -m "feat(CLI): add new flag --blabla"
    ```
+   ```shell
    git push --set-upstream origin <name-of-your-issue>
    ```
 1. Submit a pull request on GitHub website.

docs/about.md

@@ -1,4 +1,4 @@
-<img alt="KICS - Keeping Infrastructure as Code Secure" src="../img/logo/kics-black.png" width="250">  
+<img alt="KICS - Keeping Infrastructure as Code Secure" src="../img/logo/kics-black.png" width="250">
 
 ---
 
@@ -45,4 +45,4 @@ Main Benefits of Infrastructure as Code:
 
 Infrastructure as Code testing examines configuration definitions and scripts used to instantiate infrastructure to ensure the resulting resources are secure.
 
-IaC security testing tools must be able to consume configuration files and scripts in relevant formats, apply tests to ensure conformance with common configuration hardening standards (i.e., Center for Internet Security Benchmarks and many others), identify security issues associated with specific operational environments, identify embedded secrets, and perform other tests supporting organization-specific standards and compliance requirements. Optionally, tools can automatically remediate errors (e.g., changing read/write permissions on storage resources). This capability specifically examines IaC testing in the context of the development process, however tools may also support examination of deployed production instances and responding to issues identified in those systems.
+IaC security testing tools must be able to consume configuration files and scripts in relevant formats, apply tests to ensure conformance with common configuration hardening standards (i.e., Center for Internet Security Benchmarks and many others), identify security issues associated with specific operational environments, identify embedded secrets, and perform other tests supporting organization-specific standards and compliance requirements. Optionally, tools can automatically remediate errors (e.g., changing read/write permissions on storage resources). This capability specifically examines IaC testing in the context of the development process, however tools may also support examination of deployed production instances and responding to issues identified in those systems.

docs/configuration-file.md

@@ -70,6 +70,7 @@ KICS is able to infer the format without the need of file extension.
   "queries-path": "path to directory with queries (default ./assets/queries) (default './assets/queries')",
   "report-formats": "formats in which the results will be exported (json, sarif, html)",
   "type": "type of queries to use in the scan",
+  "timeout": "number of seconds the query has to execute before being canceled",
   "verbose": true,
   "profiling": "enables performance profiler that prints resource consumption metrics in the logs during the execution (CPU, MEM)"
 }
@@ -97,6 +98,7 @@ queries-path: "path to directory with queries (default ./assets/queries) (defaul
 report-formats: "formats in which the results will be exported (json, sarif, html)"
 silent: false
 type: "type of queries to use in the scan"
+timeout: "number of seconds the query has to execute before being canceled"
 verbose: true
 ```
 
@@ -122,6 +124,7 @@ queries-path = "path to directory with queries (default ./assets/queries) (defau
 report-formats = "formats in which the results will be exported (json, sarif, html)"
 silent = false
 type = "type of queries to use in the scan"
+timeout = "number of seconds the query has to execute before being canceled"
 verbose = true
 ```
 
@@ -147,6 +150,7 @@ verbose = true
 "report-formats" = "formats in which the results will be exported (json, sarif, html)"
 "silent" = false
 "type" = "type of queries to use in the scan"
+"timeout" = "number of seconds the query has to execute before being canceled"
 "verbose" = true
 ```
 

docs/getting-started.md

@@ -8,7 +8,7 @@ KICS is available as a <a href="https://hub.docker.com/r/checkmarx/kics" target=
 
 To scan a directory/file on your host you have to mount it as a volume to the container and specify the path on the container filesystem with the -p KICS parameter (see Scan Command Options section below)
 
-```txt
+```shell
 docker pull checkmarx/kics:latest
 docker run -v {​​​​path_to_host_folder_to_scan}​​​​:/path checkmarx/kics:latest scan -p "/path" -o "/path/results.json"
 ```
@@ -23,14 +23,14 @@ You can provide your own path to the queries directory with `-q` CLI option (see
 
 Run the following command to download and install kics. It will detect your current OS and download the appropriate binary package, defaults installation to `./bin` the queries will be placed alongside the binary in `./bin/assets/queries`:
 
-```sh
-curl -sfL https://raw.githubusercontent.com/Checkmarx/kics/master/install.sh | bash
+```shell
+curl -sfL 'https://raw.githubusercontent.com/Checkmarx/kics/master/install.sh' | bash
 ```
 
 If you want to place it somewhere else like `/usr/local/bin`:
 
-```sh
-sudo curl -sfL https://raw.githubusercontent.com/Checkmarx/kics/master/install.sh | bash -s -- -b /usr/local/bin
+```shell
+sudo curl -sfL 'https://raw.githubusercontent.com/Checkmarx/kics/master/install.sh' | bash -s -- -b /usr/local/bin
 ```
 
 #### Binary
@@ -45,23 +45,23 @@ So all you need is:
 1. Download KICS binaries based on your OS
 1. Extract files
 1. Run kics executable with the cli options as described below (note that kics binary should be located in the same directory as queries directory)
-   ```
-   ./kics scan -p <path-of-your-project-to-scan> -o <output-results.json>
+   ```shell
+   ./kics scan -p '<path-of-your-project-to-scan>' -o '<output-results.json>'
    ```
 
 #### Build from Sources
 
 1. Download and install Go from <a href="https://golang.org/dl/" target="_blank">https://golang.org/dl/</a>
 1. Clone the repository:
-   ```
+   ```shell
    git clone https://github.com/Checkmarx/kics.git
    ```
-   ```
+   ```shell
    cd kics
    ```
 1. Kick a scan!
-   ```
-   go run ./cmd/console/main.go scan -p <path-of-your-project-to-scan> -o <output-results.json>
+   ```shell
+   go run ./cmd/console/main.go scan -p '<path-of-your-project-to-scan>' -o '<output-results.json>'
    ```
 
 ---

docs/queries.md

@@ -2,7 +2,7 @@
 
 KICS queries are written in OPA (Rego).
 
-```Opa
+```rego
 CxPolicy [ result ] {
    resource := input.document[i].resource.aws_s3_bucket[name]
    role = "public-read"

docs/usage/commands.md

@@ -51,13 +51,13 @@ Flags:
   -x, --exclude-results strings      exclude results by providing the similarity ID of a result
                                      can be provided multiple times or as a comma separated string
                                      example: 'fec62a97d569662093dbb9739360942f...,31263s5696620s93dbb973d9360942fc2a...'
-      --fail-on                      which kind of results should return an exit code different from 0
+      --fail-on strings              which kind of results should return an exit code different from 0
                                      accetps: high, medium, low and info
-                                     example: "high,low"
-      --ignoreOnExitFlag             defines which kind of non-zero exits code should be ignored
-                                     accepts: all, results, errors, none
-                                     example: if 'results' is set, only engine errors will make KICS exit code different from 0
+                                     example: "high,low" (default [high,medium,low,info])
   -h, --help                         help for scan
+      --ignore-on-exit string        defines which kind of non-zero exits code should be ignored
+                                     accepts: all, results, errors, none
+                                     example: if 'results' is set, only engine errors will make KICS exit code different from 0 (default "none")
       --minimal-ui                   simplified version of CLI output
       --no-progress                  hides the progress bar
   -o, --output-path string           directory path to store reports
@@ -67,6 +67,7 @@ Flags:
       --preview-lines int            number of lines to be display in CLI results (min: 1, max: 30) (default 3)
   -q, --queries-path string          path to directory with queries (default "./assets/queries")
       --report-formats strings       formats in which the results will be exported (json, sarif, html)
+      --timeout int                  number of seconds the query has to execute before being canceled (default 60)
   -t, --type strings                 case insensitive list of platform types to scan
                                      (Ansible, CloudFormation, Dockerfile, Kubernetes, OpenAPI, Terraform)
 
@@ -79,6 +80,7 @@ Global Flags:
       --profiling string    enables performance profiler that prints resource consumption metrics in the logs during the execution (CPU, MEM)
   -s, --silent              silence stdout messages (mutually exclusive with verbose and ci)
   -v, --verbose             write logs to stdout too (mutually exclusive with silent)
+
 ```
 
 The other commands have no further options.

internal/console/scan.go

@@ -57,6 +57,7 @@ var (
 	queryPath         string
 	reportFormats     []string
 	types             []string
+	queryExecTimeout  int
 )
 
 const (
@@ -84,6 +85,7 @@ const (
 	scanCommandStr          = "scan"
 	typeFlag                = "type"
 	typeShorthand           = "t"
+	queryExecTimeoutFlag    = "timeout"
 )
 
 // NewScanCmd creates a new instance of the scan Command
@@ -223,19 +225,15 @@ func setBoundFlags(flagName string, val interface{}, cmd *cobra.Command) {
 
 func initScanFlags(scanCmd *cobra.Command) {
 	scanCmd.Flags().StringSliceVarP(&path,
-		pathFlag,
-		pathFlagShorthand,
+		pathFlag, pathFlagShorthand,
 		[]string{},
 		"paths or directories to scan\nexample: \"./somepath,somefile.txt\"")
 	scanCmd.Flags().StringVarP(&cfgFile,
 		configFlag,
-		"",
-		"",
+		"", "",
 		"path to configuration file")
-	scanCmd.Flags().StringVarP(
-		&queryPath,
-		queriesPathCmdName,
-		queriesPathShorthand,
+	scanCmd.Flags().StringVarP(&queryPath,
+		queriesPathCmdName, queriesPathShorthand,
 		"./assets/queries",
 		"path to directory with queries",
 	)
@@ -256,36 +254,30 @@ func initScanFlags(scanCmd *cobra.Command) {
 		3,
 		"number of lines to be display in CLI results (min: 1, max: 30)")
 	scanCmd.Flags().StringVarP(&payloadPath,
-		payloadPathFlag,
-		payloadPathShorthand,
+		payloadPathFlag, payloadPathShorthand,
 		"",
 		"path to store internal representation JSON file")
 	scanCmd.Flags().StringSliceVarP(&excludePath,
-		excludePathsFlag,
-		excludePathsShorthand,
+		excludePathsFlag, excludePathsShorthand,
 		[]string{},
 		"exclude paths from scan\nsupports glob and can be provided multiple times or as a quoted comma separated string"+
 			"\nexample: './shouldNotScan/*,somefile.txt'",
 	)
 	scanCmd.Flags().BoolVarP(&min,
-		minimalUIFlag,
-		"",
+		minimalUIFlag, "",
 		false,
 		"simplified version of CLI output")
 	scanCmd.Flags().StringSliceVarP(&types,
-		typeFlag,
-		typeShorthand,
+		typeFlag, typeShorthand,
 		[]string{""},
 		"case insensitive list of platform types to scan\n"+
 			fmt.Sprintf("(%s)", strings.Join(source.ListSupportedPlatforms(), ", ")))
 	scanCmd.Flags().BoolVarP(&noProgress,
-		noProgressFlag,
-		"",
+		noProgressFlag, "",
 		false,
 		"hides the progress bar")
 	scanCmd.Flags().StringSliceVarP(&excludeIDs,
-		excludeQueriesFlag,
-		"",
+		excludeQueriesFlag, "",
 		[]string{},
 		"exclude queries by providing the query ID\n"+
 			"can be provided multiple times or as a comma separated string\n"+
@@ -300,28 +292,29 @@ func initScanFlags(scanCmd *cobra.Command) {
 			"example: 'fec62a97d569662093dbb9739360942f...,31263s5696620s93dbb973d9360942fc2a...'",
 	)
 	scanCmd.Flags().StringSliceVarP(&excludeCategories,
-		excludeCategoriesFlag,
-		"",
+		excludeCategoriesFlag, "",
 		[]string{},
 		"exclude categories by providing its name\n"+
 			"can be provided multiple times or as a comma separated string\n"+
 			"example: 'Access control,Best practices'",
 	)
 	scanCmd.Flags().StringSliceVarP(&failOn,
-		failOnFlag,
-		"",
+		failOnFlag, "",
 		[]string{"high", "medium", "low", "info"},
 		"which kind of results should return an exit code different from 0\n"+
 			"accetps: high, medium, low and info\n"+
 			"example: \"high,low\"",
 	)
 	scanCmd.Flags().StringVarP(&ignoreOnExit,
-		ignoreOnExitFlag,
-		"",
+		ignoreOnExitFlag, "",
 		"none",
 		"defines which kind of non-zero exits code should be ignored\n"+"accepts: all, results, errors, none\n"+
 			"example: if 'results' is set, only engine errors will make KICS exit code different from 0",
 	)
+	scanCmd.Flags().IntVarP(&queryExecTimeout,
+		queryExecTimeoutFlag, "",
+		60,
+		"number of seconds the query has to execute before being canceled")
 }
 
 func initScanCmd(scanCmd *cobra.Command) {
@@ -374,7 +367,9 @@ func createInspector(t engine.Tracker, querySource source.QueriesSource) (*engin
 		ByCategories: excludeCategories,
 	}
 
-	inspector, err := engine.NewInspector(ctx, querySource, engine.DefaultVulnerabilityBuilder, t, excludeQueries, excludeResultsMap)
+	inspector, err := engine.NewInspector(ctx,
+		querySource, engine.DefaultVulnerabilityBuilder,
+		t, excludeQueries, excludeResultsMap, queryExecTimeout)
 	if err != nil {
 		return nil, err
 	}