From 2515156348e500fdc832f0d88d09935f8b492fd1 Mon Sep 17 00:00:00 2001 From: Felipe Avelar Date: Wed, 10 Feb 2021 15:45:09 +0000 Subject: [PATCH] Updated docs to incorporate new features (#2035) --- docs/about.md | 2 +- docs/getting-started.md | 7 +++++ docs/queries.md | 64 ++++++++++++++++++++++++++++++++--------- docs/results.md | 21 +++++++++++--- 4 files changed, 76 insertions(+), 18 deletions(-) diff --git a/docs/about.md b/docs/about.md index 82895714e5d..81c439926f1 100644 --- a/docs/about.md +++ b/docs/about.md @@ -6,7 +6,7 @@ [Checkmarx](https://www.checkmarx.com/) is the global leader in software security solutions for modern enterprise software development. Checkmarx delivers the industry’s most comprehensive Software Security Platform that unifies with DevOps and provides static and interactive application security testing, software composition analysis and developer AppSec awareness and training programs to reduce and remediate risk from software vulnerabilities. Checkmarx is trusted by more than 40 percent of the Fortune 100 and half of the Fortune 50, including leading organizations such as SAP, Samsung and Salesforce.com. -Checkmarx +Checkmarx Contact KICS core team at [kics@checkmarx.com](mailto:kics@checkmarx.com) or join the chat [on Gitter](https://gitter.im/kics-io/community). diff --git a/docs/getting-started.md b/docs/getting-started.md index 75767faaade..41fed30e99e 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -60,11 +60,18 @@ version Displays the current version ### Scan Command Options ```txt + --config string path to configuration file +-e, --exclude-paths exclude paths or files from scan + The arg should be quoted and uses comma as separator + example: './shouldNotScan/*,somefile.txt' -h, --help help +-l, --log-file log to file info.log + --no-progress hides scan's progress bar -o, --output-path string file path to store result in json format -p, --path string path to file or directory to scan -d, --payload-path string file path to store source internal representation in JSON format -q, --queries-path string path to directory with queries (default "./assets/queries") +-t, --type type of queries to use in the scan -v, --verbose verbose scan ``` diff --git a/docs/queries.md b/docs/queries.md index ce221613600..68abfacf2d9 100644 --- a/docs/queries.md +++ b/docs/queries.md @@ -40,7 +40,8 @@ For example, the JSON code above is the metadata corresponding to the query in t "severity": "HIGH", "category": "Identity and Access Management", "descriptionText": "It's not recommended to allow read access for all user groups.", - "descriptionUrl": "https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket#acl" + "descriptionUrl": "https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket#acl", + "platform": "Terraform" } ``` @@ -53,11 +54,11 @@ Per each query created, it is mandatory the creation of **test cases** with, at with data about the expected results, as shown below: ```json [ - { - "queryName": "All Users Group Gets Read Access", - "severity": "HIGH", - "line": 3 - } + { + "queryName": "All Users Group Gets Read Access", + "severity": "HIGH", + "line": 3 + } ] ``` @@ -73,6 +74,42 @@ Summarizing, the following is the expected file tree for a query: | | |- metadata.json | | |- query.rego ``` + +Also, a query can contains multiples positive and negative files, but all cases files names must start with negative or positive and +each positive file must be referencered on `positive_expected_result.json`, as shown below: + +```json +[ + { + "queryName": "ELB Sensitive Port Is Exposed To Entire Network", + "severity": "HIGH", + "line": 37, + "fileName": "positive1.yaml" + }, + { + "queryName": "ELB Sensitive Port Is Exposed To Entire Network", + "severity": "HIGH", + "line": 22, + "fileName": "positive2.yaml" + } +] +``` +And the file tree should be as follows: + +```none +- + |- + | |- + | | |- test + | | | |- positive1<.ext> + | | | |- positive2<.ext> + | | | |- negative1<.ext> + | | | |- negative2<.ext> + | | | |- positive_expected_result.json + | | |- metadata.json + | | |- query.rego +``` + ## Development of a Query The queries are written in Rego and our internal parser transforms every IaC file that supports into a universal JSON format. This way anyone can start working on a query by picking up a small sample of the vulnerability that the query should target, and convert this sample, that can be a .tf or .yaml file, to our JSON structure JSON. To convert the sample you can run the following command: @@ -89,7 +126,7 @@ After having the .json that will be our Rego input, we can begin to write querie To test and debug there are two ways: - [Using Rego playground](https://play.openpolicyagent.org/) -- Install Open Policy Agent extension in VS Code and create a simple folder with a .rego file for the query and a input.json for the sample to test against +- [Install Open Policy Agent extension](https://marketplace.visualstudio.com/items?itemName=tsandall.opa) in VS Code and create a simple folder with a .rego file for the query and a input.json for the sample to test against ### Testing @@ -104,13 +141,13 @@ Check if the new test was added correctly and if all tests are passing locally. Filling metadata.json: -- 'id' should be filled with a UUID. You can use the built-in command to generate this: +- `id` should be filled with a UUID. You can use the built-in command to generate this: ```bash go run ./cmd/console/main.go generate-id ``` -- 'queryName' describes the name of the vulnerability -- 'severity' can be filled with 'HIGH', 'MEDIUM','LOW' or 'INFO' -- 'category' pick one of the following: +- `queryName` describes the name of the vulnerability +- `severity` can be filled with `HIGH`, `MEDIUM`,`LOW` or `INFO` +- `category` pick one of the following: - Identity and Access Management - Network Security - Monitoring @@ -123,6 +160,7 @@ go run ./cmd/console/main.go generate-id - Domain Name System (DNS) - Management - Network Ports Security -- 'descriptionText' should explain with detail the vulnerability and if possible provide a way to remediate -- 'descriptionUrl' points to the official documentation about the resource being targeted +- `descriptionText` should explain with detail the vulnerability and if possible provide a way to remediate +- `descriptionUrl` points to the official documentation about the resource being targeted +- `platform` refers to querys target platform diff --git a/docs/results.md b/docs/results.md index 48fed459f48..0ead20e44d8 100644 --- a/docs/results.md +++ b/docs/results.md @@ -3,27 +3,40 @@ KICS results are output in clear and simple JSON format. Example: ```json { - "files_scanned": 4, - "files_failed_to_scan": 1, - "queries_total": 227, + "files_scanned": 2, + "files_parsed": 2, + "files_failed_to_scan": 0, + "queries_total": 253, "queries_failed_to_execute": 0, + "queries_failed_to_compute_similarity_id": 0, "queries": [ { "query_name": "Container Allow Privilege Escalation Is True", "query_id": "c878abb4-cca5-4724-92b9-289be68bd47c", "severity": "MEDIUM", + "platform": "Terraform", "files": [ { "file_name": "assets/queries/terraform/kubernetes_pod/container_allow_privilege_escalation_is_true/test/positive.tf", + "similarity_id": "063ed2389809f5f01ff420b63634700a9545c5e5130a6506568f925cdb0f8e13", "line": 11, "issue_type": "IncorrectValue", "search_key": "kubernetes_pod[test3].spec.container.allow_privilege_escalation", + "search_value": "", "expected_value": "Attribute 'allow_privilege_escalation' is undefined or false", "actual_value": "Attribute 'allow_privilege_escalation' is true", "value": null } ] } - ] + ], + "scan_id": "console", + "severity_counters": { + "HIGH": 0, + "INFO": 0, + "LOW": 0, + "MEDIUM": 1 + }, + "total_counter": 1 } ```