Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(README): Add project description #1

Merged
merged 3 commits into from
Apr 17, 2020
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
.idea/
1 change: 1 addition & 0 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@

Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
Expand Down
4 changes: 4 additions & 0 deletions NOTICE
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
starboard
Copyright 2019-2020 Aqua Security Software Ltd.

This product includes software developed by Aqua Security (https://aquasec.com).
102 changes: 100 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,2 +1,100 @@
# starboard
Kubernetes-native security
![Starboard](./docs/images/starboard-logo.png)

[![License][license-img]][license]

# Starboard

Starboard is a Kubernetes-native security tool kit for finding risks, such as vulnerable container images
or insecure Pod specs, in Kubernetes workloads. It provides [custom security resources definitions][k8s-security-crds]
danielpacak marked this conversation as resolved.
Show resolved Hide resolved
and the [Go module][starboard-go-module] which allow for the following use cases:
danielpacak marked this conversation as resolved.
Show resolved Hide resolved

- Develop Kubernetes-native security applications such as:
- admission webhook servers (like [Anchore Image Validator][anchore-image-validator])
- container security operators (like [Container Security Operator][container-security-operator])
- vulnerability adapters and exporters (like [KubeTrivyExporter][kube-trivy-exporter])
- Kubernetes audit tools (like [kubeaudit][kubeaudit])
- 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)
- 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
danielpacak marked this conversation as resolved.
Show resolved Hide resolved
- 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 binary executable to find container image
vulnerabilities or invoke a Go function to check SecurityContext of a given Pod. More ambitious evaluate some
Rego rules against Pod spec.
danielpacak marked this conversation as resolved.
Show resolved Hide resolved
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.

From the integration stand point the existing Kubernetes security tools are not something easy to deal with.
danielpacak marked this conversation as resolved.
Show resolved Hide resolved
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*.
This would allow security vendors to focus on what they do best, whereas others could consume the data in the
homogeneous format.
danielpacak marked this conversation as resolved.
Show resolved Hide resolved

## Getting started

For those who're familiar with `kubectl`, the easiest way to get started is to use the starboard plugin, which allows you to
scan any Kubernetes workload deployed in the cluster. For, example you can find vulnerabilities in the
Deployment named `booking-svc` in the `dev` namespace with the following command:

```
$ kubectl starboard find vulnerabilities -n dev deployments.apps/booking-svc
```

With the that you can pull the vulnerabilities report(s) using kubectl get command and label selectors:

```
$ kubectl get vulnerabilities -n dev -o yaml \
-l starboard.workload.kind=Deployment \
-l starboard.workload.name=booking-svc
```

Additionally, you could check for other risks with:

```
$ kubectl starboard find risks -n dev deployments.apps/booking-svc
```

And get the corresponding report(s):

```
$ kubectl get risks -n dev -o yaml \
-l starboard.workload.kind=Deployment \
-l starboard.workload.name=booking-svc
```

## Contributing

We'd love to see contributions such as security companies especially when it comes to standardizing custom security resources.

## License

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
[k8s-security-crds]: https://github.com/aquasecurity/k8s-security-crds
[starboard-go-module]: https://github.com/aquasecurity/kubectl-starboard/tree/master/pkg
[kubectl-starboard]: https://github.com/aquasecurity/kubectl-starboard/tree/master/cmd/kubectl-starboard
[starboard-octant-plugin]: https://github.com/aquasecurity/starboard-octant-plugin
[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
[kubectl-plugins]: https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins/
[kubeaudit]: https://github.com/Shopify/kubeaudit
[openshift-console]: https://github.com/openshift/console
[popeye]: https://github.com/derailed/popeye
Binary file added docs/images/starboard-logo.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.