Merge pull request Checkmarx#1906 from Checkmarx/feature/update-docs-…

…release

update docs with releases page and query development help

docs/CONTRIBUTING.md

@@ -62,8 +62,8 @@ Use succinct but descriptive name (prefix with *feature/issue#-descriptive-name>
 Contributions are made to this repo via Issues and Pull Requests (PRs).  A few general guidelines that cover both:
 
 - Search for existing [issues](https://github.com/Checkmarx/kics/issues) and [pull requests](https://github.com/Checkmarx/kics/pulls) before creating your own to avoid duplicates.
-- PRs will only be accepted if associated with an issue (enhancement or bug) that has been submitted and reviewed/labeld as *accepted*.
-- We will work hard to makes sure issues that are raised are handled in a timely manner.
+- PRs will only be accepted if associated with an issue (enhancement or bug) that has been submitted and reviewed/labeled as *accepted*.
+- We will work hard to make sure issues that are raised are handled in a timely manner.
 
 ### Issues
 
@@ -109,4 +109,4 @@ The following templates will be used when [creating a new issue](https://github.
 - [GitHub Help](https://help.github.com)
 
 Join the chat [on Gitter](https://gitter.im/kics-io/community).  
-Or contact KICS core team at [[email protected]](mailto:[email protected])
+Or contact KICS core team at [[email protected]](mailto:[email protected])

docs/about.md

@@ -1,4 +1,4 @@
-<img alt="KICS - Keep Infrastructure as Code Secure" src="../img/logo/kics-logo-donkey.png" width="250">
+<img alt="KICS - Keeping Infrastructure as Code Secure" src="../img/logo/kics-logo-donkey.png" width="250">
 
 ---
 
@@ -49,4 +49,4 @@ IaC security testing tools must be able to consume configuration files and scrip
 
 ---
 
-<img alt="KICS - Keep Infrastructure as Code Secure" src="../img/logo/kics-donkey.png" width="250">  
+<img alt="KICS - Keeping Infrastructure as Code Secure" src="../img/logo/kics-donkey.png" width="250">  

docs/index.md

@@ -1,4 +1,4 @@
-<img alt="KICS - Keep Infrastructure as Code Secure" src="img/logo/kics-logo-donkey.png" width="250">  
+<img alt="KICS - Keeping Infrastructure as Code Secure" src="img/logo/kics-logo-donkey.png" width="250">  
 
 ---
 
@@ -33,13 +33,13 @@ Setting up and using KICS is super-easy.
 
 What makes KICS really powerful and popular is its built-in extensibility. This extensibility is achieved by:
 
-- Fully customizable and adjustable heuristics rules, called [queries](queries.md). These can be easily edited, extended, and added.
+- Fully customizable and adjustable heuristics rules, called [queries](queries.md). These can be easily edited, extended and added.
 - Robust but yet simple [architecture](architecture.md), which allows quick addition of support for new Infrastructure as Code solutions.
 
 
 ## Contribution
 
-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 project from day one and anyone can find his own way to contribute to the project.  
 [Check out how](CONTRIBUTING.md), within just minutes, you can start making a difference, by sharing your expertise with a community of thousands of security experts and software developers.
 
 - [How can I help?!](CONTRIBUTING.md)

docs/queries.md

@@ -35,10 +35,10 @@ the severity, category and its description.
 For example, the JSON code above is the metadata corresponding to the query in the beginning of this document.
 ```json
 {
-  "id": "allUsers_group_gets_read_access",
+  "id": "5738faf3-3fe6-4614-a93d-f0003242d4f9",
   "queryName": "All Users Group Gets Read Access",
   "severity": "HIGH",
-  "category": "IAM",
+  "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"
 }
@@ -73,3 +73,57 @@ Summarizing, the following is the expected file tree for a query:
     |   |   |- 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:
+
+```bash
+go run ./cmd/console/main.go -p "pathToTestData" -d "pathToGenerateJson"
+```
+
+So for example, if we wanted to transform a .tf file in ./code/test we could type:
+```bash
+go run ./cmd/console/main.go -p  "./src/test" -d "src/test/input.json"
+```
+After having the .json that will be our Rego input, we can begin to write queries.
+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
+
+### Testing 
+
+For a query to be considered complete, it must be compliant with at least one positive and one negative test case. To run the unit tests you can run this command:
+
+```bash
+go test -mod=vendor -v -cover ./... -count=1
+```
+Check if the new test was added correctly and if all tests are passing locally. If succeeds, a Pull Request can now be created.
+
+### Guidelines
+
+Filling metadata.json:
+
+- '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:
+  - Identity and Access Management
+  - Network Security
+  - Monitoring
+  - Encryption and Key Management
+  - Logging
+  - Operational
+  - Cloud Assets Management
+  - Vulnerability and Threat Management
+  - Backup and Disaster Recovery
+  - 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
+
+

docs/releases.md

@@ -0,0 +1,19 @@
+## Releases
+
+For our release versions we follow the [SemVer](https://semver.org/) specification, meaning that we structure our versions into a MAJOR.MINOR.PATCH semantic.
+
+Our current release process is structured in the following way:
+
+- PATCH versions for minor backwards compatible bug fixes and new small features. This should have a bi-weekly cadence.
+- MINOR versions will include functionality that is backwards compatible. This should have a monthly cadence.
+- MAJOR versions for major functionality that it's added or changes that are not backwards compatible.
+
+Every release is packed with:
+
+- Source code .zip/tarballs
+- Binaries for Windows and Linux
+- Docker image uploaded to [DockerHub](https://hub.docker.com/r/checkmarx/kics)
+
+If waiting for a new release it's not enough, we also provide nightly builds that include the latest changes.
+
+You can find our releases [here](https://github.com/Checkmarx/kics/releases)

docs/results.md

@@ -9,8 +9,8 @@ KICS results are output in clear and simple JSON format. Example:
 	"queries_failed_to_execute": 0,
 	"queries": [
 		{
-			"query_name": "Container Allow Privileg Escalation Is True",
-			"query_id": "container_allow_privilege_escalation_is_true",
+			"query_name": "Container Allow Privilege Escalation Is True",
+			"query_id": "c878abb4-cca5-4724-92b9-289be68bd47c",
 			"severity": "MEDIUM",
 			"files": [
 				{
@@ -26,4 +26,4 @@ KICS results are output in clear and simple JSON format. Example:
 		}
 	]
 }
-```
+```

mkdocs.yml

@@ -4,7 +4,7 @@ site_url: http://www.kics.io
 site_description: >-
   Open source solution for static code analysis of Infrastructure as Code. Finding security vulnerabilities, compliance issues, and infrastructure misconfigurations during project development cycle.
 copyright:  >-
-  © 2020 Checkmarx Ltd. All Rights Reserved.
+  © 2021 Checkmarx Ltd. All Rights Reserved.
 
 
 # Repo
@@ -26,6 +26,7 @@ nav:
     - Roadmap: roadmap.md
     - Plans: 'https://github.com/Checkmarx/kics/projects'
     - Issues: 'https://github.com/Checkmarx/kics/issues'
+    - Releases: releases.md
   - About: about.md
 
 # Theme
@@ -35,7 +36,7 @@ theme:
   favicon: img/logo/kics-logo-text.png
   include_sidebar: true
   sticky_navigation: true
-  
+
 # Plugins
 plugins:
   - search