diff --git a/README.md b/README.md index 5a341355b..eb0abcf43 100644 --- a/README.md +++ b/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.

Starboard Overview

-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 diff --git a/docs/cli/getting-started.md b/docs/cli/getting-started.md index db455c2ce..872445594 100644 --- a/docs/cli/getting-started.md +++ b/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 diff --git a/docs/cli/index.md b/docs/cli/index.md index 0b761f8de..00df10fbf 100644 --- a/docs/cli/index.md +++ b/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 + diff --git a/docs/index.md b/docs/index.md index c123d937e..8b7343871 100644 --- a/docs/index.md +++ b/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 \ No newline at end of file diff --git a/docs/integrations/infra-scanners/index.md b/docs/integrations/infra-scanners/index.md index 71d5a3a0c..643248e05 100644 --- a/docs/integrations/infra-scanners/index.md +++ b/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 ``` -
-Result +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 ``` -
- -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: -
-Result - -``` +```console +$ kubectl get kubehunterreports -o wide NAME SCANNER AGE HIGH MEDIUM LOW cluster kube-hunter 27h 0 0 1 ``` -
\ No newline at end of file + +## 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 \ No newline at end of file diff --git a/docs/operator/getting-started.md b/docs/operator/getting-started.md index 83656e648..b8a33c2d0 100644 --- a/docs/operator/getting-started.md +++ b/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 \ No newline at end of file diff --git a/docs/operator/index.md b/docs/operator/index.md index 1828818c2..f082f2b3e 100644 --- a/docs/operator/index.md +++ b/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