docs: review and update docs (aquasecurity#803)

Signed-off-by: Daniel Pacak <pacak.daniel@gmail.com>

README.md

@@ -14,27 +14,30 @@
 # Introduction
 
 Starboard integrates security tools into the Kubernetes environment, so that users can find and view the risks that
-relate to different resources in a Kubernetes-native way. Starboard provides [custom resources definitions][crds]
-and a [Go module][go-module] to work with a range of existing security scanners, as well as a [kubectl]-compatible
-command, the [Octant plugin][octant-plugin], and the [Lens extension][lens-extension] that make security
-reports available through familiar Kubernetes tools.
+relate to different resources in a Kubernetes-native way. Starboard provides [Custom Resource Definitions] and a
+[Go module] to work with a range of existing security scanners, as well as a [kubectl]-compatible command, the
+[Octant Plugin], and the [Lens Extension] that make security reports available through familiar Kubernetes tools.
 
 <p align="center">
 <img src="docs/images/starboard-overview.png" alt="Starboard Overview"/>
 </p>
 
-Starboard can be run in two different modes:
+Starboard provides:
+
+- Automated vulnerability scanning for Kubernetes applications.
+- Automated configuration audits for Kubernetes resources with predefined rules or custom Open Policy Agent (OPA) policies.
+- Automated infrastructures scanning and compliance checks with CIS Benchmarks published by the Center for Internet Security (CIS).
+- Penetrations test results for a Kubernetes cluster.
 
-- As a [command][cli], so you can trigger scans and view the risks in a kubectl-compatible way or as part of your CI/CD pipeline.
-- As an [operator] to automatically update security reports in response to workload and other changes on a Kubernetes
-  cluster - for example, initiating a vulnerability scan when a new pod is started.
+Starboard can be run in two different modes:
 
-> **NOTE** Even though manual scanning through the command-line is useful, the fact that it's not automated makes it
-> less suitable with numerous Kubernetes workloads. Therefore, the [operator] provides a better option
-> for these scenarios, constantly monitoring built-in Kubernetes resources, such as Deployments, and running appropriate
-> scanners against the underlying deployment descriptors.
+- As a [Kubernetes operator] to automatically update security reports in response to workload and other changes on a
+  Kubernetes cluster - for example, initiating a vulnerability scan when a new Pod is started or running CIS Benchmarks
+  when a new Node is added.
+- As a [command][cli], so you can trigger scans and view the risks in a kubectl-compatible way or as part of your CI/CD
+  pipeline.
 
-You can read more about the motivations and use cases in this [blog][aqua-starboard-blog] and join our [discussions][discussions].
+You can read more about the motivations and use cases in this [blog][aqua-starboard-blog] and join our [discussions].
 
 ![](docs/images/starboard-cli-with-octant-demo.gif)
 
@@ -47,7 +50,7 @@ This project is incubating and the APIs are not considered stable.
 The official documentation, which provides detailed installation, configuration, and quick start guides, is available
 at https://aquasecurity.github.io/starboard/.
 
-Try the [getting started guide][cli-getting-started] to install the Starboard command and generate your first
+Try the [Getting Started][cli-getting-started] guide to install the Starboard command and generate your first
 vulnerability report.
 
 # Contributing
@@ -82,12 +85,12 @@ Contact us about any matter by opening a GitHub Discussion [here](https://github
 [aqua-starboard-blog]: https://blog.aquasec.com/starboard-kubernetes-tools
 [discussions]: https://github.com/aquasecurity/starboard/discussions
 
-[crds]: https://aquasecurity.github.io/starboard/latest/crds/
-[go-module]: https://pkg.go.dev/github.com/aquasecurity/starboard/pkg
+[Custom Resource Definitions]: https://aquasecurity.github.io/starboard/latest/crds/
+[Go module]: https://pkg.go.dev/github.com/aquasecurity/starboard/pkg
 [cli]: https://aquasecurity.github.io/starboard/latest/cli
 [cli-getting-started]: https://aquasecurity.github.io/starboard/latest/cli/getting-started/
-[operator]: https://aquasecurity.github.io/starboard/latest/operator
+[Kubernetes operator]: https://aquasecurity.github.io/starboard/latest/operator
 
-[octant-plugin]: https://aquasecurity.github.io/starboard/latest/integrations/octant
-[lens-extension]: https://aquasecurity.github.io/starboard/latest/integrations/lens
+[Octant Plugin]: https://aquasecurity.github.io/starboard/latest/integrations/octant
+[Lens Extension]: https://aquasecurity.github.io/starboard/latest/integrations/lens
 [kubectl]: https://kubernetes.io/docs/reference/kubectl

docs/cli/getting-started.md

@@ -79,7 +79,7 @@ starboard get vulnerabilityreports deployment/nginx --container nginx -o yaml
     replicaset-nginx-6d4cf56db6-nginx   library/nginx   1.16   Trivy     41m   21         50     34       104   0
     ```
 
-    To read more about custom resources and label selectors check [custom resource definitions].
+    To read more about custom resources and label selectors check [Custom Resource Definitions].
 
 Moving forward, let's take the same `nginx` Deployment and audit its Kubernetes configuration. As you remember we've
 created it with the `kubectl create deployment` command which applies the default settings to the deployment descriptors.
@@ -114,15 +114,17 @@ open nginx.deploy.html
 
 ## What's Next?
 
-To learn more about the available Starboard commands and scanners, such as [kube-bench] or [kube-hunter], use
-`starboard help`.
+* Learn more about the available Starboard commands and scanners, such as [kube-bench] or [kube-hunter], by running
+  `starboard help`.
+* Read up on [Infrastructure Scanners] integrated with Starboard.
 
 [Trivy]: ./../integrations/vulnerability-scanners/trivy.md
 [Polaris]: ./../integrations/config-checkers/polaris.md
-[custom resource definitions]: ./../crds/index.md
+[Custom Resource Definitions]: ./../crds/index.md
 [Katacoda]: https://www.katacoda.com/courses/kubernetes/playground/
 [Play with Kubernetes]: http://labs.play-with-k8s.com/
 [minikube]: https://minikube.sigs.k8s.io/docs/
 [kind]: https://kind.sigs.k8s.io/docs/
 [kube-bench]: https://github.com/aquasecurity/kube-bench
 [kube-hunter]: https://github.com/aquasecurity/kube-hunter
+[Infrastructure Scanners]: ./../integrations/infra-scanners/index.md

docs/cli/index.md

@@ -1,13 +1,27 @@
 # Overview
 
 Starboard CLI is a single executable binary which can be used to find risks, such as vulnerabilities or insecure pod
-descriptors, in Kubernetes workloads. By default, the risk assessment reports are stored as [custom resources].
+descriptors, in Kubernetes workloads. By default, the risk assessment reports are stored as instances of
+[Custom Resource Definitions].
+
+!!! note
+    Even though manual scanning through the command-line is useful, the fact that it's not automated makes it less
+    suitable with a large number of Kubernetes resources. Therefore, the [Starboard Operator] provides a better option
+    for these scenarios, constantly monitoring built-in Kubernetes resources, such as Deployments and Nodes, and running
+    appropriate scanners.
 
 To learn more about the available Starboard CLI commands, run `starboard help` or type a command followed by the
-`-h` flag:
+`--help` flag:
 
 ```
-starboard scan kubehunterreports -h
+starboard scan kubehunterreports --help
 ```
 
-[custom resources]: ./../crds/index.md
+## What's Next?
+
+* Install the command and follow the [Getting Started] guide.
+
+[Custom Resource Definitions]: ./../crds/index.md
+[Starboard Operator]: ./../operator/index.md
+[Getting Started]: ./getting-started.md
+

docs/index.md

@@ -1,28 +1,24 @@
 # Welcome to {{ config.site_name }}
 
-Starboard integrates security tools into the Kubernetes environment, so that
-users can find and view the risks that relate to different resources in
-a Kubernetes-native way. Starboard provides [custom resources definitions][crds]
-and a [Go module] to work with a range of existing security scanners,
-as well as a [kubectl]-compatible command, the [Octant plugin][octant-plugin],
-and the [Lens extension][lens-extension] that make security reports available
-through familiar Kubernetes tools.
+Starboard integrates security tools into the Kubernetes environment, so that users can find and view the risks that
+relate to different resources in a Kubernetes-native way. Starboard provides [Custom Resource Definitions] and a
+[Go module] to work with a range of existing security scanners, as well as a [kubectl]-compatible command, the
+[Octant Plugin], and the [Lens Extension] that make security reports available through familiar Kubernetes tools.
 
-Starboard can be run in two different modes:
+Starboard provides:
+
+- Automated vulnerability scanning for Kubernetes applications.
+- Automated configuration audits for Kubernetes resources with predefined rules or custom Open Policy Agent (OPA) policies.
+- Automated infrastructures scanning and compliance checks with CIS Benchmarks published by the Center for Internet Security (CIS).
+- Penetrations test results for a Kubernetes cluster.
 
-- As a [command][cli], so you can trigger scans and view the risks in
-  a kubectl-compatible way or as part of your CI/CD pipeline.
-- As an [operator] to automatically update security reports in response
-  to workload and other changes on a Kubernetes cluster - for example,
-  initiating a vulnerability scan when a new pod is started.
+Starboard can be run in two different modes:
 
-!!! tip
-    Even though manual scanning through the command-line is useful, the
-    fact that it's not automated makes it less suitable with a large number
-    of Kubernetes workloads. Therefore, the [operator] provides a better option
-    for these scenarios, constantly monitoring built-in Kubernetes resources,
-    such as Deployments, and running appropriate scanners against the underlying
-    deployment descriptors.
+- As a [Kubernetes operator] to automatically update security reports in response to workload and other changes on a
+  Kubernetes cluster - for example, initiating a vulnerability scan when a new Pod is started or running CIS Benchmarks
+  when a new Node is added.
+- As a [command][cli], so you can trigger scans and view the risks in a kubectl-compatible way or as part of your CI/CD
+  pipeline.
 
 ## What's Next?
 
@@ -31,13 +27,14 @@ Starboard can be run in two different modes:
 - See a detailed introduction to Starboard with demos at [KubeCon + CloudNativeCon NA 2020][kubecon-video].
 - Join our [discussions] on GitHub.
 
-[crds]: ./crds/index.md
+[Custom Resource Definitions]: ./crds/index.md
 [cli]: cli/index.md
-[operator]: operator/index.md
+[Kubernetes operator]: operator/index.md
 [Go module]: https://pkg.go.dev/github.com/aquasecurity/starboard@{{ var.tag }}
-[octant-plugin]: integrations/octant.md
-[lens-extension]: integrations/lens.md
+[Octant Plugin]: ./integrations/octant.md
+[Lens Extension]: integrations/lens.md
 [kubectl]: https://kubernetes.io/docs/reference/kubectl/
 [use-cases]: https://blog.aquasec.com/starboard-kubernetes-tools
 [discussions]: https://github.com/aquasecurity/starboard/discussions
 [kubecon-video]: https://www.youtube.com/watch?v=cgcwIY1HVI0
+[kube-hunter]: https://github.com/aquasecurity/kube-hunter

docs/integrations/infra-scanners/index.md

@@ -2,73 +2,71 @@
 
 Currently, these are the tools for infrastructure checking in Kubernetes:
 
-* CIS benchmark results per node provided by [kube-bench](https://github.com/aquasecurity/kube-bench)
-* Pen-testing results provided by [kube-hunter](https://github.com/aquasecurity/kube-hunter)
-
+* CIS benchmark for Kubernetes nodes provided by [kube-bench].
+* Penetration test results for a Kubernetes cluster provided by [kube-hunter].
 
 ## Kube-bench
 
-The CIS benchmark for Kubernetes provides prescriptive guidance for system and application administrators, security specialists, auditors, help desk, and platform deployment personnel who are responsible for establishing secure configuration for solutions that incorporate Kubernetes.
-
-Currently, you can obtain the results using starboard operator and starboard client.
+The CIS benchmark for Kubernetes provides prescriptive guidance for system and application administrators, security
+specialists, auditors, help desk, and platform deployment personnel who are responsible for establishing secure
+configuration for solutions that incorporate Kubernetes.
 
-Here the scan results using starboard client (installed by krew).
+To run the CIS Kubernetes benchmark for each node in your cluster use the following Starboard CLI command:
 
-> *scan ciskubebenchreports: Run the CIS Kubernetes Benchmark for each node of your cluster*
 ```
-kubectl starboard scan ciskubebenchreports -v 3
+starboard scan ciskubebenchreports
 ```
 
-Check the ciskubebenchreports generated:
-```
-kubectl get ciskubebenchreports -o wide
+If everything goes fine, list benchmark results with the `kubectl get` command:
+
+```console
+$ kubectl get ciskubebenchreports -o wide
+NAME                 SCANNER      AGE   FAIL   WARN   INFO   PASS
+kind-control-plane   kube-bench   13s   11     43     0      69
+kind-worker          kube-bench   14s   1      29     0      19
+kind-worker2         kube-bench   14s   1      29     0      19
 ```
 
-<details>
-<summary>Result</summary>
+With Starboard CLI it is also possible to generate a CIS Benchmark HTML report and open it in your web browser:
 
 ```
-NAME                   SCANNER      AGE     FAIL   WARN   INFO   PASS
-k8s-local-control-plane   kube-bench   3d14h   1      27     0      26
-k8s-local-worker          kube-bench   3d14h   1      27     0      19
-k8s-local-worker2         kube-bench   3d14h   1      27     0      19
+starboard report nodes/kind-control-plane > kind-control-plane-report.html
 ```
-</details>
-
-Generate the report HTML
 ```
-k starboard get report nodes/k8s-local-worker > node01-report.html
+open kind-control-plane-report.html
 ```
 
-```
-open node01-report.html
-```
+![Aqua Starboard Node Security HTML Report](../../images/node01-report.png)
 
-![HTML Report](../../images/node01-report.png)
 
 ## Kube-hunter
 
-kube-hunter hunts for security weaknesses in Kubernetes clusters. The tool was developed to increase awareness and visibility for security issues in Kubernetes environments.
+Kube-hunter hunts for security weaknesses in Kubernetes clusters. It was developed to increase awareness and visibility
+for security issues in Kubernetes environments.
 
-Currently, you can obtain the results using **only** starboard client.
+!!! tip
+    Kube-hunter is only integrated with Starboard CLI.
 
-Here the scan results.
+To run kube-hunter in your cluster as a Pod use the following command:
 
-> *scan kubehunterreports: Hunt for security weaknesses in your Kubernetes cluster*
 ```
-kubectl starboard scan kubehunterreports -v 3
+starboard scan kubehunterreports
 ```
 
-Check the kubehunterreports generated:
-```
-kubectl get kubehunterreports -o wide
-```
+If everything goes well, you can retrieve the penetration test report with the `kubectl get` command:
 
-<details>
-<summary>Result</summary>
-
-```
+```console
+$ kubectl get kubehunterreports -o wide
 NAME      SCANNER       AGE   HIGH   MEDIUM   LOW
 cluster   kube-hunter   27h   0      0        1
 ```
-</details>
+
+## What's Next?
+
+* See how Starboard Operator can automate [Infrastructure Scanning] with kube-bench.
+* Watch the video where we demonstrated [Automating Kubernetes Compliance Checks with Starboard Operator].
+
+[kube-bench]: https://github.com/aquasecurity/kube-bench/
+[kube-hunter]: https://github.com/aquasecurity/kube-hunter/
+[Infrastructure Scanning]: ./../../operator/getting-started.md#infrastructure-scanning
+[Automating Kubernetes Compliance Checks with Starboard Operator]: https://www.youtube.com/watch?v=hOQyEPL-ULI

docs/operator/getting-started.md

@@ -181,13 +181,15 @@ kube-system      └─Pod/kube-scheduler-kind-control-plane           True
 
 ## What's Next?
 
-- Find out how the operator scans workloads that use container images from [private registries](./../integrations/private-registries.md).
-- By default, the operator uses Trivy as [vulnerability scanner](./../integrations/vulnerability-scanners/index.md)
-  and Polaris as [configuration checker](./../integrations/config-checkers/index.md), but you can choose other tools that
-  are integrated with Starboard or even implement you own plugins.
+- Find out how the operator scans workloads that use container images from [Private Registries].
+- By default, the operator uses Trivy as [Vulnerability Scanner] and Polaris as [Configuration Checker], but you can
+  choose other tools that are integrated with Starboard or even implement you own plugins.
 
 [minikube]: https://minikube.sigs.k8s.io/docs/
 [kind]: https://kind.sigs.k8s.io/docs/
 [Katacoda]: https://www.katacoda.com/courses/kubernetes/playground/
 [Play with Kubernetes]: http://labs.play-with-k8s.com/
 [tree]: https://github.com/ahmetb/kubectl-tree
+[Private Registries]: ./../integrations/private-registries.md
+[Vulnerability Scanner]: ./../integrations/vulnerability-scanners/index.md
+[Configuration Checker]: ./../integrations/config-checkers/index.md

docs/operator/index.md

@@ -44,7 +44,7 @@ with new plugin's configuration.
 
 ## What's Next?
 
-- Install the operator and follow the [getting started](./getting-started.md) guide.
+- Install the operator and follow the [Getting Started](./getting-started.md) guide.
 
 [vulnerabilityreports]: ./../crds/vulnerability-report.md
 [configauditreports]: ./../crds/configaudit-report.md