Revised documentation files (Checkmarx#2109)

README.md

@@ -30,8 +30,12 @@ Support of other solutions and additional cloud providers are on the [roadmap](d
 Setting up and using KICS is super-easy.
 
 -   First, see how to [install and get KICS running](docs/getting-started.md).
--   Next, check how you can easily [integrate it into your CI](docs/integrations.md) for any project.
--   Eventually, [explore the output results format](docs/results.md) and quickly fix the issues detected.
+-   Then explore KICS [output results format](docs/results.md) and quickly fix the issues detected.
+
+Interested in more advanced stuff?
+-   Deep dive into KICS [queries](docs/queries.md).
+-   Understand how to [integrate](docs/integrations.md) KICS in your favourit CI/CD pipelines.
+
 
 ## How it Works
 
@@ -43,7 +47,7 @@ What makes KICS really powerful and popular is its built-in extensibility. This
 ## Release process
 
 KICS release process is quite simple. We have nightly builds that will pack and pre-release all changes merged into master.
-The nightly release will have a "nightly" prefix with the last commit hash code. We have binaries available for both Windows and Linux, as well a Docker image in [DockerHub](https://hub.docker.com/r/checkmarx/kics)
+The nightly release will have a "nightly" prefix with the last commit hash code. We have binaries available for both Windows and Linux, as well a Docker image in <a href="https://hub.docker.com/r/checkmarx/kics" target="_blank">DockerHub</a>
 
 ## Contribution
 
@@ -55,7 +59,7 @@ KICS is a true community project. It's built as an open source from day one, and
 <a href="https://www.kics.io" title="www.kics.io"><img src="docs/img/button_www-kics-io.png" align="right"></a>
 
 [KICS public documentation](https://docs.kics.io/) has all the project aspects covered.  
-Join the chat [on Gitter](https://gitter.im/kics-io/community).  
+Join the chat <a href="https://gitter.im/kics-io/community" target="_blank">on Gitter</a>.  
 Or contact KICS core team at [[email protected]](mailto:[email protected])
 
 **Keeping Infrastructure as Code Secure!**

docs/CONTRIBUTING.md

@@ -6,7 +6,7 @@ KICS is a true community project. It's built as an open source from day one, and
 
 Within just minutes, you can start making a difference, by sharing your expertise with a community of thousands of security experts and software developers.
 
-### Contribution Options
+#### Contribution Options
 
 Good news! You don't have to contribute code. There are plenty of ways you can contribute to KICS project:
 
@@ -15,10 +15,11 @@ Good news! You don't have to contribute code. There are plenty of ways you can c
 - Improving and translating the documentation 
 - Volunteering to maintain the project
 
-### Code of Conduct
+#### Code of Conduct
 
 By participating and contributing to the project, you agree to uphold our [Code of Conduct](code-of-conduct.md).
 
+---
 
 ## Get Started!
 
@@ -57,6 +58,8 @@ Use succinct but descriptive name (prefix with *feature/issue#-descriptive-name>
    ```
 1. Submit a pull request on GitHub website.
 
+---
+
 ## How to Contribute
 
 Contributions are made to this repo via Issues and Pull Requests (PRs).  A few general guidelines that cover both:
@@ -65,14 +68,14 @@ Contributions are made to this repo via Issues and Pull Requests (PRs).  A few g
 - 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
+#### Issues
 
 Issues should be used to report problems with the solution / source code, request a new feature, or to discuss potential changes before a PR is created. When you create a new Issue, a template will be loaded that will guide you through collecting and providing the information we need to investigate.
 
 If you find an Issue that addresses the problem you're having, please add your own reproduction information to the existing issue rather than creating a new one. Adding a [reaction](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/) can also help by indicating to our maintainers that a particular problem is affecting more than just the reporter.
 
 
-### Pull Requests
+#### Pull Requests
 
 Pull Requests (PRs) are always welcome and can be a quick way to get your fix or improvement slated for the next release. In general, PRs should:
 
@@ -85,15 +88,15 @@ Pull Requests (PRs) are always welcome and can be a quick way to get your fix or
 
 For changes that address core functionality or would require breaking changes (e.g. a major release), please open an Issue to discuss your proposal first. 
 
-### Pull Request Guidelines
+#### Pull Request Guidelines
 
 Before you submit a pull request, please reassure that it meets these guidelines:
 
 1. All validations and tests passed locally.
 1. The pull request includes tests.
 1. The relevant docs are updated, whether you're pushing new functionality or updating a query.
 
-### Templates
+#### Templates
 
 The following templates will be used when [creating a new issue](https://github.com/Checkmarx/kics/issues/new/choose):  
 
@@ -102,6 +105,8 @@ The following templates will be used when [creating a new issue](https://github.
 - Query Template
 - Bug Report Template
 
+---
+
 ## Resources
 
 - [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
@@ -110,3 +115,50 @@ The following templates will be used when [creating a new issue](https://github.
 
 Join the chat [on Gitter](https://gitter.im/kics-io/community).  
 Or contact KICS core team at [[email protected]](mailto:[email protected])
+
+And become one of our top contributors!
+
+---
+
+## Top Contributors
+
+Special thanks to  **[Lior Kaplan](https://github.com/kaplanlior)** from **_Kaplan Open Source Consulting_** for his assistance in creating KICS. 
+
+The people listed below had made a huge contribution to KICS. 
+
+- [Ruben Silva](https://github.com/Ruben-Silva) 
+- [Rafaela Soares](https://github.com/rafaela-soares)
+- [João Martins](https://github.com/joaomartinscx)
+- [Joel Carvalho](https://github.com/joelcarvalhocheckmarx)
+- [Pedro Mimoso](https://github.com/pedro-mimoso)
+- [Nuno Araújo](https://github.com/NunoAraujoCX)
+- [Fábio Gonçalves](https://github.com/fabioGoncalvesCx)
+- [Mariana Carvalho](https://github.com/mcarvalhox)
+- [Jorge Cruz](https://github.com/jorge-cruz)
+- [João Oliveira](https://github.com/JoaoO1998)
+- [Diogo Lemos](https://github.com/diogo-lemos)
+- [Alex Roichman](https://github.com/Alexaro1cx)
+- [Adar Weidman](https://github.com/AdarWeidman)
+- [Eli Trop](https://github.com/elit-cx)
+- [Joel Sousa](https://github.com/joelsou5a)
+- [Sónia Antão](https://github.com/soniantao)
+- [Catarina Araújo](https://github.com/cataraujo190)
+- [Pedro Pereira](https://github.com/pedropereiraaa)
+- [Samuel Ferreira](https://github.com/samuel-ferreira)
+
+#### Core Team
+
+- [Rui Gomes](https://github.com/ruigomescx)
+- [Rogério Peixoto](https://github.com/rogeriopeixotocx)
+- [João Reigota](https://github.com/joaoReigota1)
+- [Felipe Avelar](https://github.com/felipe-avelar)
+- [Nuno Oliveira](https://github.com/nunoocx)
+- [Mark Mishaev](https://github.com/markmishaevcx)
+- [Igor Markov](https://github.com/IgorMarkov)
+- [Ori Bendet](https://github.com/oribendetcx)
+- [Erez Yalon](https://github.com/erezyalon)
+
+
+**Thank you all!**
+
+

docs/about.md

@@ -12,7 +12,7 @@ Contact KICS core team at [[email protected]](mailto:[email protected]) or joi
 
 ---
 
-## What is Infrastructure as Code
+## Infrastructure as Code
 
 Infrastructure as Code (IaC) is the creation, provisioning and configuration of software-defined compute (SDC), network and storage infrastructure through machine-readable definition files, rather than physical hardware configuration or interactive configuration tools.
 
@@ -41,12 +41,8 @@ Main Benefits of Infrastructure as Code:
 
 ---
 
-## What is Infrastructure as Code Testing
+## Infrastructure as Code Testing
 
 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.
-
----
-
-<img alt="KICS - Keeping Infrastructure as Code Secure" src="https://raw.githubusercontent.com/Checkmarx/kics/master/docs/img/logo/kics-logo-donkey.png" width="250">  
+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/architecture.md

@@ -1,11 +1,13 @@
 ## Overview
 
-KICS is 100% open source is written in Golang using Open Policy Agent ([OPA](https://www.openpolicyagent.org/)).
+KICS is 100% open source is written in Golang using Open Policy Agent (<a href="https://www.openpolicyagent.org/" target="_blank">OPA</a>).
 
-Golang speed, simplicity and reliability made it the perfect choice for writing KICS, while [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/) as a query language, was a native choice to implement security queries. 
+Golang speed, simplicity and reliability made it the perfect choice for writing KICS, while <a href="https://www.openpolicyagent.org/docs/latest/policy-language/" target="_blank">Rego</a> as a query language, was a native choice to implement security queries. 
 
 So far have written 1000+ ready-to-use queries that cover a wide range of vulnerabilities checks for AWS, GCP, Azure and other cloud providers. 
 
+---
+
 ## High Level Architecture
 
 KICS has a pluggable architecture with extensible pipeline of parsing IaC languages, which allows an easy integration of new IaC languages and queries.
@@ -21,9 +23,11 @@ At a high very level, KICS is composed of the following main components: a comma
 
 <img src="https://raw.githubusercontent.com/Checkmarx/kics/master/docs/img/arch/high-level-arch.png" align="left">  
 
+<br/>
 
 ## Execution Flow
 
 The sequence diagram below depicts interaction of the main KICS components:  
+<br/>
 <img src="https://raw.githubusercontent.com/Checkmarx/kics/master/docs/img/arch/exec-flow-1.png" align="left">  
 <img src="https://raw.githubusercontent.com/Checkmarx/kics/master/docs/img/arch/exec-flow-2.png" align="left">

docs/configuration-file.md

@@ -1,38 +1,38 @@
 ## Configuration File
 
-Configuration file example:
+KICS allow you to provide all configurations either as command line arguments or as code.
+
+Here is a Configuration file example:
 
 ```JSON
 {
-  "path": "assets/queries",
+  "path": "assets/iac_samples",
   "verbose": true,
   "log-file": true,
   "queries-path": "assets/queries",
   "output-path": "results.json"
 }
 ```
 
-## Supported extensions
+---
 
-    -JSON
-    -TOML
-    -YAML
-    -HCL
+## Supported Formats
+KICS supports the following formats for the configuration files.
 
-## How to Add and Run a Configuration File
+- JSON
+- TOML
+- YAML
+- HCL
 
-1. Start by creating a file called 'config' using your preferred extension.
-2. From the templates section, look for the extension you used and copy its content to your 'config' file changing the content as needed.
-3. To use KICS with your configuration file, run the command:
-```
-go run ./cmd/console/main.go scan --config <path-of-configuration-file>
-```
+Notice that format is about the content and not the file extension.
+
+KICS is able to infer the format without the need of file extension.
 
-(CLI flags will have priority over the configuration file properties)
+---
 
-# Templates
+## Templates
 
-## JSON Format
+#### JSON Format
 
 ```JSON
 {
@@ -48,7 +48,7 @@ go run ./cmd/console/main.go scan --config <path-of-configuration-file>
 }
 ```
 
-## YAML Format
+#### YAML Format
 
 ```YAML
 path: "path to file or directory to scan"
@@ -62,7 +62,7 @@ type: "type of queries to use in the scan"
 payload-path: "file path to store source internal representation in JSON format"
 ```
 
-## TOML Format
+#### TOML Format
 
 ```TOML
 path = "path to file or directory to scan"
@@ -76,7 +76,7 @@ type = "type of queries to use in the scan"
 payload-path = "file path to store source internal representation in JSON format"
 ```
 
-## HCL Format
+#### HCL Format
 
 ```hcl
 "exclude-paths" = "exclude paths or files from scan"
@@ -89,3 +89,29 @@ payload-path = "file path to store source internal representation in JSON format
 "type" = "type of queries to use in the scan"
 "verbose" = true
 ```
+
+---
+
+
+## How to Use 
+You can enclose all your configurations in a file and use it in two different ways.
+
+#### Command Argument File
+
+1. Create a file with any name/any extension. For the sake of example, let's call it `kics-config.json`
+2. Add the necessary configurations as shown in the templates section in any of the supported formats.
+3. Pass the configuration file as argument:
+```
+kics scan --config kics-config.json
+```
+
+#### Configuration as Code
+
+1. Create a file named `kics.config` and place it in the root of your project repository.
+2. Add the necessary configurations as shown in the templates section in any of the supported formats.
+3. Invoke KICS without arguments (KICS will search for the specific file in the root)
+```
+kics scan
+```
+
+**Note**: CLI flags will have priority over the configuration file properties!