Skip to content

Commit

Permalink
Remove contents that are in blog (aquasecurity#34)
Browse files Browse the repository at this point in the history 
* Remove contents that are in blog

TODO: add blog link
TODO: remove unnecessary references

* docs: update blog link

Also remove unused references, and add references to Trivy and Polaris in the getting started guide

* docs: typo
  • Loading branch information
@lizrice
lizrice authored Jun 1, 2020
1 parent 04bea13 commit fec324e
Showing 1 changed file with 21 additions and 135 deletions.
156 changes: 21 additions & 135 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,10 @@

## Table of Contents

- [Abstract](#abstract)
- [Rationale](#rationale)
- [Use Cases](#use-cases)
- [Starboard for DevOps](#starboard-for-devops)
- [Starboard for Enterprises](#starboard-for-enterprises)
- [Starboard for Security Vendors](#starboard-for-security-vendors)
- [Installing](#installing)
- [Introduction](#introduction)
- [Installation](#installation)
- [From the Binary Releases](#from-the-binary-releases)
- [From Krew](#from-krew)
- [As a kubectl plugin](#kubectl-plugin)
- [From Source (Linux, macOS)](#from-source-linux-macos)
- [Getting Started](#getting-started)
- [Next Steps](#next-steps)
Expand All @@ -26,117 +21,17 @@
- [Contributing](#contributing)
- [License](#license)

## Abstract

Starboard is a Kubernetes-native security tool kit for finding risks in your Kubernetes workloads and environments.
It provides [custom security resources definitions][starboard-crds] and the [Go module][starboard-go-module] to work
alongside a range of existing security tools, allowing for use cases such as these:

- Develop Kubernetes-native security applications such as:
- admission webhook servers (like [Anchore Image Validator][anchore-image-validator]
and [Starboard Admission Webhook][starboard-admission-webhook])
- container security operators (like [Container Security Operator][container-security-operator]
and [Starboard Security Operator][starboard-security-operator])
- vulnerability adapters and exporters (like [KubeTrivyExporter][kube-trivy-exporter])
- Kubernetes audit tools (like [kubeaudit][kubeaudit] and [Polaris][polaris])
- Kubernetes resources sanitizers and linters (like [Popeye][popeye])
- [kubectl plugins][kubectl-plugins] to scan workloads early on in the development stage
(like [kubectl starboard][kubectl-starboard] plugin)
- webhook servers for integrating with enterprise cloud native artifacts registries
(like [Starboard Harbor Webhook][starboard-harbor-webhook])
- webhook servers for integrating with commercial cloud native security platforms
(like [Starboard Aqua CSP Webhook][starboard-aqua-csp-webhook])
- Extend existing Kubernetes dashboards, such as [Octant][octant] or [OpenShift Console][openshift-console], with
vulnerability assessment reports
- Implement scoring, health check, and metrics systems for the whole Kubernetes cluster or a single namespace,
aggregating results from different tools to simplify overall security assessments
- Implement custom security dashboards from scratch

## Rationale

By looking at existing Kubernetes security tools you can quickly realize two things. On one hand they differ in many
ways, i.e. have different capabilities, data models, output sinks, license, maturity level and credibility.
On the other hand, they usually have the same or very similar modus operandi, i.e.:

1. Discover Kubernetes workloads via Kubernetes API or by parsing descriptor YAML files
2. Invoke some type of scanner which finds risks, e.g. execute a [Trivy][trivy] binary executable to find container
image vulnerabilities, invoke a Go function to check SecurityContext of a given Pod, or evaluate a Pod spec against
some [Rego][opa-rego] rules.
3. Save risk assessment report somewhere, typically to the standard output or a file. JSON/YAML with a free-style schema
seems to be an "industry" standard.

It's not easy to deal with the results from these different, standalone Kubernetes security tools.
With all these heterogeneous data models it's very hard to take advantage of all the features provided by a given tool.
Especially when you want to use a few or all of them.

What if all the Kubernetes security tools spoke the same language that everyone knows and understands?
Similarly to the standardized and well known Pod spec, we could come up with the schema for a *vulnerability*,
a *risk assessment check*, a *black-* or *white-listed vulnerability*, or maybe even a *scanner config*. What if you
could combine the results from different tools to give an easy-to-understand overview of current security status?
This would allow security vendors to focus on what they do best, whereas others could consume the data in the
homogeneous format.

Project Starboard illustrates how the outputs from different security tools can be stored and combined using native
Kubernetes approaches:

* Storing results in Kubernetes CRDs that can be queried using the Kubernetes API
* Using Kubernetes Operators to efficiently manage security assessments of different resources within the cluster
* Using Kubernetes Operators to aggregate results, using flexible policies, into Kubernetes-native CRDs

## Use Cases

### Starboard for DevOps
## Introduction

![](docs/images/starboard-cli-with-octant-demo.gif)

One idea behind Starboard is to help development and DevOps teams deliver secure and compliant applications from the
get-go. As shown in the figure below, Dave Loper is using [`kubectl`][kubectl] to deploy and test his applications.
Without learning the whole new tool, he can now use a familiar [`kubectl starboard`][kubectl-starboard] plugin interface
to scan container images, which comprise his applications, for potentially dangerous and exploitable vulnerabilities. He
can also look for configuration issues that might affect stability, reliability, and scalability of his deployment. This
makes Dave Loper a new security guard of his organization. What's more, by doing that his organization effectively
implemented the shift left security principle in SDLC.

Sometimes, to better understand the complexity of his applications, Dave is using [Octant][octant], a Kubernetes
introspective and object management platform. With [Starboard Octant plugin][starboard-octant-plugin] we extended the
Octant's capabilities to present vulnerability and configuration audits in user-friendly manner.

![](docs/images/use-cases/starboard-for-devops.png)

### Starboard for Enterprises

Manual scanning through the [`kubectl starboard`][kubectl-starboard] plugin is useful, but it has its limitations: it
doesn't scale well with a huge number of Kubernetes workloads and / or multi-tenant clusters as is the case for
enterprises.

In such cases a more suitable option is to deploy the [Starboard Security Operator][starboard-security-operator], which
constantly monitors Kubernetes-native resources, such as Deployments, and runs appropriate scanners against the
underlying deployment descriptors. The scan reports can be saved as custom resources in the same instance of
[etcd][etcd] used by the Kubernetes cluster running the workloads, or an etcd instance external to the cluster.

Because they are accessible over the Kubernetes API, the vulnerability reports or any other security audits can be used
to build or integrate with dashboards tailored for SRE and Security teams.

The same data can be used by the [Starboard Admission Webhook][starboard-admission-webhook] to accept or reject new
deployments based on security policies put in place, e.g. number of critical vulnerabilities found in a container
image.

Another interesting scenario would be to take advantage of [Starboard Harbor Webhook][starboard-harbor-webhook] or
[Starboard Aqua CSP Webhook][starboard-aqua-csp-webhook] components to import existing vulnerability reports generated
by Harbor or Aqua CSP respectively via Webhook integrations.
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 security resources definitions][starboard-crds] and a [Go module][starboard-go-module] to work with a range of existing security tools, as well as a `kubectl`-compatible command-line tool and an Octant plug-in that make security reports available through familiar Kubernetes tools.

![](docs/images/use-cases/starboard-for-enterprises.png)
You can read more about the motivations and use cases [here][aqua-starboard-blog].

### Starboard for Security Vendors

Starboard provides a framework for security tool developers and vendors, making it easy to integrate their tooling into
Kubernetes in a way that's familiar for users. As a tool developer you can re-use one of the existing CR definitions,
or create a new one. The Starboard code generator saves time and effort on creating the tools to integrate with
Kubernetes tooling, for example creating webhooks and plugins for Starboard.
![](docs/images/starboard-cli-with-octant-demo.gif)

## Installing
## Installation

This guide shows how to install the [Starboard CLI][starboard-cli]. Starboard CLI can be installed either from source,
This guide shows how to install the [Starboard CLI][starboard-cli] from source,
or from pre-built binary releases.

### From the Binary Releases
Expand All @@ -151,14 +46,14 @@ binary versions can be manually downloaded and installed.

From there, you should be able to run Starboard CLI commands: `starboard help`

### From Krew
#### kubectl plugin

The Starboard CLI is compatible with [kubectl][kubectl] and is intended as [kubectl plugin][kubectl-plugins],
but it's perfectly fine to run it as a stand-alone executable. If you rename the `starboard` executable to
`kubectl-starboard` and if it's in your path, you can invoke it using `kubectl starboard`.

Once we resolve [#8][issue-8] our intention is to submit Starboard to [krew-index][krew-index] so that if accepted,
you'll be able to install starboard with [Krew][krew] plugins manager:
you'll be able to install starboard with the [Krew][krew] plugins manager:

```
$ kubectl krew install starboard
Expand Down Expand Up @@ -204,7 +99,7 @@ kubehunterreports kubehunter aquasecurity.github.io fa
vulnerabilities vulns,vuln aquasecurity.github.io true Vulnerability
```

> There's the `starboard cleanup` subcommand, which can be used to remove all resources created by Starboard.
> There's also a `starboard cleanup` subcommand, which can be used to remove all resources created by Starboard.
As an example let's run an old version of `nginx` that we know has vulnerabilities. Create an `nginx` Deployment in the
`dev` namespace:
Expand All @@ -219,7 +114,7 @@ Run the scanner to find the vulnerabilities:
$ starboard find vulnerabilities deployment/nginx --namespace dev
```

Finally, retrieve the latest vulnerability reports:
Behind the scenes, this uses [Trivy][trivy] 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 vulnerabilities deployment/nginx \
Expand All @@ -228,7 +123,7 @@ $ starboard get vulnerabilities deployment/nginx \
```

Starboard relies on labels and label selectors to associate vulnerability reports with the specified Deployment.
For a Deployment with *N* containers Starboard creates *N* instances of `vulnerabilities.aquasecurity.github.io`
For a Deployment with *N* container images Starboard creates *N* instances of `vulnerabilities.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:
Expand All @@ -245,22 +140,21 @@ In this example, the `nginx` deployment has a single container called `nginx`, h

To read more about custom resources and label selectors check [Custom Security Resources Specification][starboard-crds-spec].

For those for whom the CLI interface is not enough, we've implemented the
[Starboard Octant plugin][starboard-octant-plugin] to display the same vulnerability reports in the Octant's interface.
The [Starboard Octant plugin][starboard-octant-plugin] displays the same vulnerability reports in Octant's UI.

<p align="center">
<img src="docs/images/getting-started/deployment_vulnerabilities.png">
</p>

Check the plugin's repository for the installation instructions.
Check the plugin's repository for installation instructions.

## Next Steps

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:
Run the scanner to audit the configuration using [Polaris][polaris]:

```
$ starboard polaris
Expand Down Expand Up @@ -383,6 +277,7 @@ This repository is available under the [Apache License 2.0][license].
[license-img]: https://img.shields.io/github/license/aquasecurity/starboard.svg
[license]: https://github.com/aquasecurity/starboard/blob/master/LICENSE

[aqua-starboard-blog]: https://blog.aquasec.com/starboard-kubernetes-tools
[starboard-crds]: #custom-security-resources-definitions
[starboard-crds-spec]: ./SECURITY_CRDS_SPEC.md
[vulnerabilities-crd]: ./kube/crd/vulnerabilities-crd.yaml
Expand All @@ -399,23 +294,14 @@ This repository is available under the [Apache License 2.0][license].
[starboard-harbor-webhook]: https://github.com/aquasecurity/starboard-harbor-webhook
[aqua-kube-bench]: https://github.com/aquasecurity/kube-bench
[aqua-kube-hunter]: https://github.com/aquasecurity/kube-hunter
[octant]: https://github.com/vmware-tanzu/octant
[polaris]: https://github.com/FairwindsOps/polaris
[trivy]: https://github.com/aquasecurity/trivy

[k8s-code-generator]: https://github.com/kubernetes/code-generator

[kubectl]: https://kubernetes.io/docs/reference/kubectl
[kubectl-plugins]: https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins

[octant]: https://github.com/vmware-tanzu/octant
[anchore-image-validator]: https://github.com/banzaicloud/anchore-image-validator
[kube-trivy-exporter]: https://github.com/kaidotdev/kube-trivy-exporter
[container-security-operator]: https://github.com/quay/container-security-operator
[kubeaudit]: https://github.com/Shopify/kubeaudit
[openshift-console]: https://github.com/openshift/console
[popeye]: https://github.com/derailed/popeye
[polaris]: https://github.com/FairwindsOps/polaris
[etcd]: https://etcd.io
[trivy]: https://github.com/aquasecurity/trivy
[opa-rego]: https://www.openpolicyagent.org/docs/latest/policy-language/
[krew]: https://github.com/kubernetes-sigs/krew
[krew-index]: https://github.com/kubernetes-sigs/krew-index

Expand Down

0 comments on commit fec324e

Please sign in to comment.