Skip to content

Commit

Permalink
feat: update README
Browse files Browse the repository at this point in the history 
Signed-off-by: Michael Fornaro <[email protected]>
  • Loading branch information
@xunholy
xunholy committed Apr 11, 2023
1 parent 9bf080e commit 39e822e
Showing 1 changed file with 76 additions and 46 deletions.
122 changes: 76 additions & 46 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,48 +1,73 @@
<h1 align="center">
<p align="center">Kubernetes Security Policies</p>
<a href="https://raspbernetes.github.io/docs/"><img src="https://raspbernetes.github.io/img/logo.svg" alt="Raspbernetes"></a>
</h1>
<div align="center">

![build](https://github.com/raspbernetes/k8s-security-policies/workflows/build/badge.svg)
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fraspbernetes%2Fk8s-security-policies.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fraspbernetes%2Fk8s-security-policies?ref=badge_shield)
# Kubernetes Security Policies

A Comprehensive Library for Fortifying Cluster Configurations.

</div>

## Introduction
This repository provides a security policies library that is used for securing Kubernetes clusters configurations. The security policies are created based on [CIS Kubernetes benchmark](https://cloud.google.com/kubernetes-engine/docs/concepts/cis-benchmarks) and rules defined in [Kubesec.io](https://kubesec.io/).
The policies are written in Rego, a high-level declarative language, its purpose-built for expressing policies over complex hierarchical data structures. For detailed information on Rego see the [Policy Language](https://www.openpolicyagent.org/docs/latest/policy-language/) documentation.

## Structure of the repo
The policies directory contains a list of folders, which corresponds to the list of policies. The folder is named with the benchmark standard and a number to differentiate with each other. For example, the 1.2.1 Ensure that the --anonymous-auth argument is set to false that in CIS benchmark is checked by the REGO files in directory CIS1.2.1. Check more on each policy in [Policy Inventory](policies/POLICIES.md)
This repository offers a comprehensive library of security policies designed to fortify Kubernetes cluster configurations. These security policies are derived from the [CIS Kubernetes benchmark]((https://cloud.google.com/kubernetes-engine/docs/concepts/cis-benchmarks)) and rules specified by [Kubesec.io](https://kubesec.io/). The policies are crafted in REGO, a high-level declarative language tailored for defining policies over intricate hierarchical data structures. For an in-depth understanding of REGO, refer to the [Policy Language](https://www.openpolicyagent.org/docs/latest/policy-language/) documentation.

Each of these folders contains a rego file and unit test rego file. There is another `lib` folder which has two rego files that contain general functions that can be imported into other rego. `kubernetes.rego` contains functions and rules that will be used in security control rego files, `test.rego` contains functions that can be imported in the unit test files.
## Why use Kubernetes Security Policies?

## How does this work?
Kubernetes Security Policies are crucial for:

### Violations
Each of the rego policies checks against the manifests of resources that can be deployed in the K8s cluster, the `violation` block in each policy rego files will normally contain these statements that will do:
- Check what resource object the policy is checking against and return the object
- Check if the object violates that controls defined in the benchmark
- Display the error message if there is a violation
Here is a quick example of a violation:
```
1. **Enhancing Security**: They protect clusters against threats, misconfigurations, and vulnerabilities by applying predefined rules and best practices.

2. **Ensuring Consistency**: Policies enforce standardized configurations across clusters, simplifying management and reducing configuration drift.

3. **Maintaining Compliance**: By implementing established benchmarks like CIS Kubernetes, policies help adhere to industry-specific regulatory requirements.

4. **Automating Enforcement**: Policies automate the enforcement of security best practices, reducing human error and streamlining deployments.

5. **Simplifying Auditing**: They provide a clear approach to defining and enforcing configurations, enabling easier auditing and monitoring of clusters.

Kubernetes Security Policies are essential for a robust security strategy and promoting a proactive security culture within organizations.

## Repository Structure

The `policies` directory houses numerous folders, each representing a distinct policy. Folders are named according to the benchmark standard, followed by a number to ensure differentiation. For instance, the `1.2.1 Ensure that the --anonymous-auth argument is set to false` policy from the CIS benchmark is verified by REGO files located in the `CIS1.2.1` directory. To explore each policy further, consult the [Policy Inventory](policies/POLICIES.md).

Within each folder, you will find a `.rego` file and a unit test `.rego` file. Additionally, there is a separate `lib` folder containing two .rego files that feature general functions importable into other `.rego` files. The `kubernetes.rego` file encompasses functions and rules employed in security control `.rego` files, while the `test.rego` file houses functions that can be imported into unit test files.

## Policy Implementation Process

### Identifying Violations

Each REGO policy examines the manifests of resources deployable in a Kubernetes cluster. The `violation` block in each policy file typically includes:

* Identifying the resource object being examined and returning it.
* Verifying if the object breaches the controls defined in the benchmark.
* Displaying an error message if a violation is detected.

Here's a simplified example of a violation:

```rego
violation[msg] {
kubernetes.pods[pod]
not kubernetes.contains_element(params.allowedDeploymentsOrPods, kubernetes.name)
is_automount_serviceaccount_token_enabled(pod)
msg := kubernetes.format(sprintf("%v: %v - Automount Service account token must be set to false", [kubernetes.kind, kubernetes.name]))
}
```
The `kubernetes.` indicates it is calling a function from `kubernetes.rego`, which put general functions. The logic that specific to this control will be written in the same rego files.

### Parameters
For each of the security policies, there will be parameters going to be used for checking against the resources. The parameters can be from external, for example, if these policies are going to be checked in gatekeeper engine, the parameters can be defined in the gatekeeper `constraints`, or we can directly have default parameters in the file itself, for standardizing the parameters, that we will union these parameters
```
params = object.union(default_parameters, kubernetes.parameters)
The `kubernetes.` prefix indicates a function call from `kubernetes.rego`, which contains general functions. Control-specific logic is written in the corresponding REGO file.

### Configuring Parameters

Security policies use parameters to evaluate resources. These parameters can be external (e.g., defined in Gatekeeper `constraints`) or embedded as default values within the file. Parameters are standardized by combining them:

```rego
params = object.union(default_parameters, kubernetes.parameters)
```
### Unit tests
To verify the correctness of the policies, we use `OPA` testing [framework](https://www.openpolicyagent.org/docs/v0.12.2/how-do-i-test-policies/) to write the unit tests.
Each unit tests will have test functions that need to start with the `test` in the function name, so they can be picked by the `op test` the positive case start with the name of `test_no_violation` and negative starts with `test_violation` and tests with a policy_input that will be in the same structure of the manifests.
```

### Testing Policies

To validate policy accuracy, the `OPA` testing [framework](https://www.openpolicyagent.org/docs/v0.12.2/how-do-i-test-policies/) is used. Each unit test includes functions prefixed with `test` in the name, enabling `opa test` to recognize them. Positive cases start with `test_no_violation` and negative cases with `test_violation`. Tests use `policy_input` formatted like the manifests:

```rego
test_violation {
test.violations(violation) with input as policy_input(true)
}
Expand All @@ -51,12 +76,13 @@ test_no_violation {
test.no_violations(violation) with input as policy_input(false)
}
```
The unit tests files need to have the same package as the rego policy itself. e.g.
`package cis_5_2_5` will the package name for `CIS.5.2.5.rego` and `CIS.5.2.5_test.rego`, so that the unit test will check the policy input against that violation block under the same package.

The `opa test` output indicates that all of the tests passed or not.
```
$opa test policies -v
Unit test files share the same package as the REGO policy, ensuring the test verifies policy input against the violation block within the same package.

The `opa test` output displays whether all tests passed:

```rego
$ opa test policies -v
data.spec_volumes_hostpath_path_var_run_docker_sock.test_no_violation: PASS (318.786µs)
data.containers_image_tag.test_violation_1: PASS (512.689µs)
data.containers_image_tag.test_violation_2: PASS (515.964µs)
Expand All @@ -67,25 +93,29 @@ data.containers_securitycontext_allowprivilegedeescalation_true.test_no_violatio
PASS: 5/5
```

## How this can be used?
The policy library is written in a standard way that can be used by various tools, such as Conftest and Gatekeeper.
## Integration with Policy Enforcement Tools

This policy library is designed to be compatible with various tools, such as Conftest and Gatekeeper.

### Gatekeeper
The rego policies can be used as a schema in the gatekeeper `ConstraintTemplate` and `constraints` can be deployed based on the template onto the Kubernetes clusters for checking the `CREATE` and `UPDATE` operations against API server, and gatekeeper also provides `AUDIT` functions for checking the existing resources against the `constraints`. Check [Gatekeeper](https://github.com/open-policy-agent/gatekeeper) to understand more how the `constraints` can be created.

Rego policies can serve as a schema in Gatekeeper `ConstraintTemplate`. Based on the template, `constraints` can be deployed onto Kubernetes clusters to monitor `CREATE` and `UPDATE` operations against the API server. Gatekeeper also offers `AUDIT` functionality to evaluate existing resources against the `constraints`. To learn more about creating `constraints`, visit the [Gatekeeper](https://github.com/open-policy-agent/gatekeeper) repository.


### Conftest
Using conftest to check the structured yaml manifests files that will be deployed to your clusters.
Make srue you have installed `Conftest`([Conftest](https://github.com/open-policy-agent/conftest)) and run `conftest test` a yaml file agaist the policy library
```
conftest test deployment.yaml -p policies/. --all-namespaces
```
and the output will indicate if tests passed. An example:

Conftest enables the evaluation of structured YAML manifest files intended for deployment to your clusters. To use Conftest, first install [Conftest](https://github.com/open-policy-agent/conftest) and then run `conftest test` on a YAML file against the policy library:


```shell
$ conftest test deployment.yaml -p policies/. --all-namespaces
```

The output indicates whether the tests have passed. Here's an example:

```log
FAIL - deployment.yaml - Containers must not run as root
FAIL - deployment.yaml - Deployments are not allowed
2 tests, 0 passed, 0 warnings, 2 failure
```


## License
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fraspbernetes%2Fk8s-security-policies.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fraspbernetes%2Fk8s-security-policies?ref=badge_large)

0 comments on commit 39e822e

Please sign in to comment.