Skip to content

Commit

Permalink
docs(cli): update getting started guide (aquasecurity#800)
Browse files Browse the repository at this point in the history 
Signed-off-by: Daniel Pacak <pacak.daniel@gmail.com>
  • Loading branch information
@danielpacak
danielpacak authored Nov 10, 2021
1 parent ec82095 commit 8fceb1e
Showing 1 changed file with 37 additions and 42 deletions.
79 changes: 37 additions & 42 deletions docs/cli/getting-started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,15 +24,18 @@ starboard install
```

The `install` subcommand creates the `starboard` namespace, in which Starboard executes Kubernetes jobs to perform
scans. It also sends custom security resources definitions to the Kubernetes API:
scans. It also sends custom security resources definitions to the Kubernetes API and creates default configuration
objects:

```console
$ kubectl api-resources --api-group aquasecurity.github.io
NAME SHORTNAMES APIGROUP NAMESPACED KIND
ciskubebenchreports kubebench aquasecurity.github.io false CISKubeBenchReport
configauditreports configaudit aquasecurity.github.io true ConfigAuditReport
kubehunterreports kubehunter aquasecurity.github.io false KubeHunterReport
vulnerabilityreports vulns,vuln aquasecurity.github.io true VulnerabilityReport
NAME SHORTNAMES APIVERSION NAMESPACED KIND
ciskubebenchreports kubebench aquasecurity.github.io/v1alpha1 false CISKubeBenchReport
clusterconfigauditreports clusterconfigaudit aquasecurity.github.io/v1alpha1 false ClusterConfigAuditReport
clustervulnerabilityreports clustervuln,clustervulns aquasecurity.github.io/v1alpha1 false ClusterVulnerabilityReport
configauditreports configaudit aquasecurity.github.io/v1alpha1 true ConfigAuditReport
kubehunterreports kubehunter aquasecurity.github.io/v1alpha1 false KubeHunterReport
vulnerabilityreports vuln,vulns aquasecurity.github.io/v1alpha1 true VulnerabilityReport
```

!!! tip
Expand All @@ -50,42 +53,39 @@ Run the vulnerability scanner to generate vulnerability reports:
starboard scan vulnerabilityreports deployment/nginx
```

Behind the scenes, by default this uses [Trivy][trivy] in Standalone mode to identify vulnerabilities in the container
images associated with the specified deployment. Once this has been done, you can retrieve the latest vulnerability
Behind the scenes, by default this uses [Trivy] in Standalone mode to identify vulnerabilities in the container
images associated with the specified Deployment. Once this has been done, you can retrieve the latest vulnerability
reports for this workload:

```
starboard get vulnerabilityreports deployment/nginx -o yaml
```

For a Deployment with *N* containers Starboard will create *N* instances of `vulnerabilityreports.aquasecurity.github.io`
resources. To retrieve a vulnerability report for the specified container use the `--container` flag:

```
starboard get vulnerabilityreports deployment/nginx --container nginx -o yaml
```

!!! tip
Starboard relies on labels and label selectors to associate vulnerability reports with the specified Deployment.
For a Deployment with *N* container images Starboard creates *N* instances of `vulnerabilityreports.aquasecurity.github.io`
resources. In addition, each instance has the `starboard.container.name` label to associate it with a particular
container's image. This means that the same data retrieved by the `starboard get vulnerabilities` subcommand can be
fetched with the standard `kubectl get` command:
It is possible to retrieve vulnerability reports with the `kubectl get` command, but it requires knowledge of
Starboard implementation details. In particular, naming convention and labels and label selectors used to associate
vulnerability reports with Kubernetes workloads.

```console
$ kubectl get vulnerabilityreports -o wide \
-l starboard.resource.kind=Deployment,starboard.resource.name=nginx
NAME REPOSITORY TAG SCANNER AGE CRITICAL HIGH MEDIUM LOW UNKNOWN
deployment-nginx-nginx library/nginx 1.16 Trivy 2m6s 3 40 24 90 0
$ kubectl get vulnerabilityreports -o wide
NAME REPOSITORY TAG SCANNER AGE CRITICAL HIGH MEDIUM LOW UNKNOWN
replicaset-nginx-6d4cf56db6-nginx library/nginx 1.16 Trivy 41m 21 50 34 104 0
```

In this example, the `nginx` deployment has a single container called `nginx`, hence only one instance of the
`vulnerabilityreports.aquasecurity.github.io` resource is created with the label `starboard.container.name=nginx`.

To read more about custom resources and label selectors check [custom resource definitions].

[trivy]: ./../integrations/vulnerability-scanners/trivy.md
[custom resource definitions]: ./../crds/index.md
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.
However, we also know that in Kubernetes the defaults are usually the least secure.

Run the scanner to audit the configuration using [Polaris](./../integrations/config-checkers/polaris.md), which is the
default configuration checker:
Run the scanner to audit the configuration using [Polaris], which is the default configuration checker:

```
starboard scan configauditreports deployment/nginx
Expand All @@ -97,19 +97,10 @@ Retrieve the configuration audit report:
starboard get configauditreports deployment/nginx -o yaml
```

or

```console
$ kubectl get configauditreport -o wide \
-l starboard.resource.kind=Deployment,starboard.resource.name=nginx
NAME SCANNER AGE DANGER WARNING PASS
deployment-nginx Polaris 5s 0 8 9
```

## Generating HTML Reports

Once you scanned the `nginx` Deployment for vulnerabilities and checked its configuration you can generate an HTML
report of identified risks:
report of identified risks and open it in your web browser:

```
starboard report deployment/nginx > nginx.deploy.html
Expand All @@ -119,15 +110,19 @@ starboard report deployment/nginx > nginx.deploy.html
open nginx.deploy.html
```

![HTML Report](../images/html-report.png)
![Aqua Starboard Workload Security HTML Report](../images/html-report.png)

## What's Next?

To learn more about the available Starboard commands and scanners, such as [kube-bench][aqua-kube-bench] or
[kube-hunter][aqua-kube-hunter], use `starboard help`.
To learn more about the available Starboard commands and scanners, such as [kube-bench] or [kube-hunter], use
`starboard help`.

[Trivy]: ./../integrations/vulnerability-scanners/trivy.md
[Polaris]: ./../integrations/config-checkers/polaris.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/
[polaris]: https://github.com/FairwindsOps/polaris
[aqua-kube-bench]: https://github.com/aquasecurity/kube-bench
[aqua-kube-hunter]: https://github.com/aquasecurity/kube-hunter
[kube-bench]: https://github.com/aquasecurity/kube-bench
[kube-hunter]: https://github.com/aquasecurity/kube-hunter

0 comments on commit 8fceb1e

Please sign in to comment.