Merge pull request #7245 from Checkmarx/update_docs_getting_started

docs(update): update getting started documentation with installation guidance

docs/documentation.md

@@ -6,7 +6,7 @@ There are multiple ways to get KICS up and running:
 
 KICS is available as a <a href="https://hub.docker.com/r/checkmarx/kics" target="_blank">Docker image</a> and can be used as follows:
 
-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)
+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)
 
 ```shell
 docker pull checkmarx/kics:latest
@@ -17,7 +17,7 @@ You can see the list of available tags in [dockerhub](https://hub.docker.com/r/c
 
 ℹ️ **UBI Based Images**
 
-When using [UBI8](https://catalog.redhat.com) based image, the KICS process will run under the `kics` user and `kics` group with default UID=1000 and GID=1000, when using bind mount to share host files with the container, the UID and GID can be overriden to match current user with the `-u` flag that overrides the username:group or UID:GID. e.g:
+When using [UBI8](https://catalog.redhat.com) based image, the KICS process will run under the `kics` user and `kics` group with default UID=1000 and GID=1000. When using bind mount to share host files with the container, the UID and GID can be overriden to match current user with the `-u` flag that overrides the username:group or UID:GID. e.g:
 
 ```sh
 docker run -it -u $UID:$GID -v $PWD:/path checkmarx/kics:ubi8 scan -p /path/assets/queries/dockerfile -o /path -v
@@ -27,7 +27,7 @@ Another option is [rebuilding the dockerfile](https://github.com/Checkmarx/kics/
 
 #### Build from Sources
 
-1. Download and install Go 1.16 or higher from <a href="https://golang.org/dl/" target="_blank">https://golang.org/dl/</a>.
+1. Download and install Go 1.16 or higher (1.22 recommended) from <a href="https://golang.org/dl/" target="_blank">https://golang.org/dl/</a>.
 2. Clone the repository:
     ```sh
     git clone https://github.com/Checkmarx/kics.git
@@ -60,6 +60,8 @@ KICS is available on Checkmarx [homebrew-tap](https://github.com/Checkmarx/homeb
 brew install Checkmarx/tap/kics
 ```
 
+#### Default Queries
+
 To use KICS default queries add the KICS_QUERIES_PATH environmental variable to your shell profile, e.g:
 
 ```

docs/getting-started.md

@@ -1,12 +1,78 @@
-## Scan a directory
+## Installation
+
+There are multiple ways to get KICS up and running:
+
+#### Docker
+
+KICS is available as a <a href="https://hub.docker.com/r/checkmarx/kics" target="_blank">Docker image</a> and can be used as follows:
+
+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)
+
+```shell
+docker pull checkmarx/kics:latest
+docker run -t -v "{path_to_host_folder_to_scan}":/path checkmarx/kics scan -p /path -o "/path/"
+```
+
+You can see the list of available tags in [dockerhub](https://hub.docker.com/r/checkmarx/kics/tags?page=1&ordering=-name)
+
+ℹ️ **UBI Based Images**
+
+When using [UBI8](https://catalog.redhat.com) based image, the KICS process will run under the `kics` user and `kics` group with default UID=1000 and GID=1000, when using bind mount to share host files with the container, the UID and GID can be overriden to match current user with the `-u` flag that overrides the username:group or UID:GID. e.g:
+
+```sh
+docker run -it -u $UID:$GID -v $PWD:/path checkmarx/kics:ubi8 scan -p /path/assets/queries/dockerfile -o /path -v
+```
+
+Another option is [rebuilding the dockerfile](https://github.com/Checkmarx/kics/blob/master/docker/Dockerfile.ubi8) providing build arguments e.g: `--build-arg UID=999 --build-arg GID=999 --build-arg KUSER=myuser --build-arg KUSER=mygroup`
+
+#### Build from Sources
+
+1. Download and install Go 1.16 (1.22 recommended) or higher from <a href="https://golang.org/dl/" target="_blank">https://golang.org/dl/</a>.
+2. Clone the repository:
+    ```sh
+    git clone https://github.com/Checkmarx/kics.git
+    ```
+3. Build the binaries:
+    ```sh
+    cd kics
+    go mod vendor
+    make build
+    ```
+
+    or 
+
+    ```sh
+    cd kics
+    go mod vendor
+    LINUX/MAC: go build -o ./bin/kics cmd/console/main.go
+    WINDOWS: go build -o ./bin/kics.exe cmd/console/main.go (make sure to create the bin folder)
+    ```
+4. Kick a scan!
+    ```sh
+    ./bin/kics scan -p '<path-of-your-project-to-scan>' --report-formats json -o ./results
+    ```
+
+## Scan Examples
+
+#### Scan a directory
 ```
 docker run -t -v {path_to_host_folder_to_scan}:/path checkmarx/kics:latest scan -p /path -o "/path/"
 ```
 
-## Scan a single file
+#### Scan a single file
 ```
 docker run -t -v {path_to_host_folder}:/path checkmarx/kics:latest scan -p /path/{filename}.{extension} -o "/path/"
 ```
 
-## Scan Example
+#### Scan Example
 [![](https://raw.githubusercontent.com/Checkmarx/kics/23c62655308523e1bf6aa8ae5852848deb263651/docs/img/faster.gif)](https://raw.githubusercontent.com/Checkmarx/kics/23c62655308523e1bf6aa8ae5852848deb263651/docs/img/faster.gif)
+
+## Next Steps
+
+-   [Understand how to configure KICS](configuration-file.md) so you can have a better KICS experience.
+-   [Explore KICS commands](commands.md) to see what you can do with KICS.
+-   [Explore supported platforms](platforms.md) to see which files you can scan with KICS.
+-   [Explore the queries internals](queries.md) for better understanding how KICS works.
+-   [Create a new query](creating-queries.md) to learn how to create your own custom queries.
+-   [Explore the output results format](results.md) and quickly fix the issues detected.
+-   [Contribute](CONTRIBUTING.md) if you want to go the extra mile.

docs/queries.md

@@ -51,7 +51,7 @@ The **result** defines the specific data used to present the *vulnerability* in
 #### Metadata
 
 Each query has a metadata.json companion file with all the relevant information about the *vulnerability*, including
-the severity, category and its description.
+the severity, category and its description. Additional fields can be found on queries metadata file, such as descriptionID, cloudProvider or cwe.
 
 For example, the JSON code above is the metadata corresponding to the query in the beginning of this document.
 ```json
@@ -66,10 +66,9 @@ For example, the JSON code above is the metadata corresponding to the query in t
 }
 ```
 
-
 #### Organization
-Filesystem-wise, KICS queries are organized per IaC technology or tool (e.g., terraform, k8s, dockerfile, etc.) and grouped
-under provider (e.g., aws, gcp, azure, etc.) when applicable.
+
+Filesystem-wise, KICS queries are organized per IaC technology or tool/platform (e.g., terraform, k8s, dockerfile, etc.) and grouped under provider (e.g., aws, gcp, azure, etc.) when applicable.
 
 Per each query created, it is mandatory the creation of **test cases** with, at least, one negative and positive case and a JSON file
 with data about the expected results, as shown below:
@@ -135,3 +134,25 @@ And the file tree should be as follows:
 #### Query Dependencies
 
 If you want to use the functions defined in your own library, you should use the flag `-b` to indicate the directory where the libraries are placed. The functions need to be grouped by platform and the library name should follow the following format: `<platform>.rego`. It doesn't matter your directory structure. In other words, for example, if you want to indicate a directory that contains a library for your terraform queries, you should group your functions (used in your terraform queries) in a file named `terraform.rego` wherever you want.
+
+#### Default Queries
+
+To use KICS default queries add the KICS_QUERIES_PATH environmental variable to your shell profile, e.g:
+
+```
+echo 'export KICS_QUERIES_PATH=/usr/local/opt/kics/share/kics/assets/queries' >> ~/.zshrc
+```
+
+#### Custom Queries
+
+You can provide your own path to the queries directory with `-q` CLI option (see CLI Options section below), otherwise the default directory will be used. The default _./assets/queries_ is built-in in the image. You can use this to provide a path to your own custom queries. Check [create a new query guide](creating-queries.md) to learn how to define your own queries.
+
+#### Password and Secrets
+
+Since the Password and Secrets mechanism uses generic regexes, we advise you to tweak the rules of the secret to your context. Please, see the [Password and Secrets documentation](https://github.com/Checkmarx/kics/blob/master/docs/secrets.md#new-rules-addition) to know how you can use your own rules.
+
+---
+
+**Note**: KICS does not execute scan by default as of [version 1.3.0](https://github.com/Checkmarx/kics/releases/tag/v1.3.0).
+
+**Note**: KICS deprecated the availability of binaries in the GitHub releases assets as of [version 1.5.2](https://github.com/Checkmarx/kics/releases/tag/v1.5.2), it is advised to update all systems (pipelines, integrations, etc.) to use the [KICS Docker Images](https://hub.docker.com/r/checkmarx/kics).