From 9b9940f708e99f91f2701298ce122e2963d94abb Mon Sep 17 00:00:00 2001 From: dwertent Date: Sun, 14 Nov 2021 14:31:53 +0200 Subject: [PATCH 1/2] adding exceptions docs --- README.md | 6 +- examples/exceptions/README.md | 179 ++++++++++++++++++ .../exclude-allowed-hostPath-control.json | 22 +++ .../exclude-deployments-in-ns-default.json | 23 +++ .../exclude-kube-namespaces.json} | 6 + .../exceptions/exclude-nginx-in-minikube.json | 26 +++ 6 files changed, 261 insertions(+), 1 deletion(-) create mode 100644 examples/exceptions/README.md create mode 100644 examples/exceptions/exclude-allowed-hostPath-control.json create mode 100644 examples/exceptions/exclude-deployments-in-ns-default.json rename examples/{exceptions.json => exceptions/exclude-kube-namespaces.json} (85%) create mode 100644 examples/exceptions/exclude-nginx-in-minikube.json diff --git a/README.md b/README.md index 0e12d043..e5075326 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,7 @@ Want to contribute? Want to discuss something? Have an issue? * [Overview](https://youtu.be/wdBkt_0Qhbg) * [Scanning Kubernetes YAML files](https://youtu.be/Ox6DaR7_4ZI) +* [Scan Kubescape on an air-gapped environment (offline support)](https://youtu.be/IGXL9s37smM) * [Managing exceptions in the Kubescape SaaS version](https://youtu.be/OzpvxGmCR80) ## Install on Windows @@ -158,8 +159,9 @@ kubescape scan framework nsa --format prometheus ``` #### Scan with exceptions, objects with exceptions will be presented as `exclude` and not `fail` +[Full documentation](examples/exceptions/README.md) ``` -kubescape scan framework nsa --exceptions examples/exceptions.json +kubescape scan framework nsa --exceptions examples/exceptions/exclude-kube-namespaces.json ``` #### Scan Helm charts - Render the helm chart using [`helm template`](https://helm.sh/docs/helm/helm_template/) and pass to stdout @@ -175,6 +177,8 @@ helm template bitnami/mysql --generate-name --dry-run | kubescape scan framework ### Offline Support +[Video tutorial](https://youtu.be/IGXL9s37smM) + It is possible to run Kubescape offline! First download the framework and then scan with `--use-from` flag diff --git a/examples/exceptions/README.md b/examples/exceptions/README.md new file mode 100644 index 00000000..75f23e89 --- /dev/null +++ b/examples/exceptions/README.md @@ -0,0 +1,179 @@ +# Kubescape Exceptions + +Kubescape Exceptions is the proper way of excluding failed resources from effecting the risk score. + +e.g. When a `kube-system` resource fails and it is ok, simply add the resource to the exceptions configurations. + +## Definitions + + +* `name`- Exception name - unique name representing the exception +* `policyType`- Do not change +* `actions`- List of available actions. Currently alertOnly is supported +* `resources`- List of resources to apply this exception on + * `designatorType: Attributes`- An attribute-based declaration {key: value} + Supported keys: + * `name`: k8s resource name (case-sensitive, regex supported) + * `kind`: k8s resource kind (case-sensitive, regex supported) + * `namespace`: k8s resource namespace (case-sensitive, regex supported) + * `cluster`: k8s cluster name (usually it is the `current-context`) (case-sensitive, regex supported) + * resource labels as key value (case-sensitive, regex NOT supported) +* `posturePolicies`- An attribute-based declaration {key: value} + * `frameworkName` - Framework names can be find [here](https://github.com/armosec/regolibrary/tree/master/frameworks) + * `controlName` - Control names can be find [here](https://github.com/armosec/regolibrary/tree/master/controls) + * `controlID` - Not yet supported + * `ruleName` - Rule names can be find [here](https://github.com/armosec/regolibrary/tree/master/rules) + + +## Usage + +The `resources` list and `posturePolicies` list are design to be a combination of the resources sand policies to exclude +> You must declare at least one resource and one policy + +e.g. If you wish to exclude all namespaces with the label "environment": "dev", the resource list should look as following: +``` +"resources": [ + { + "designatorType": "Attributes", + "attributes": { + "namespace": ".*", + "environment": "dev" + } + } +] +``` + +But if you wish to exclude all namespaces **OR** any resource with the label "environment": "dev", the resource list should look as following: +``` +"resources": [ + { + "designatorType": "Attributes", + "attributes": { + "namespace": ".*" + } + }, + { + "designatorType": "Attributes", + "attributes": { + "environment": "dev" + } + } +] +``` + +Same works with the `posturePolicies` list -> + +e.g. If you wish to exclude the resources decleared in the `resources` list that faild when scanning the `NSA` framework **AND** failed the `Allowed hostPath` control, the `posturePolicies` list should look as following: +``` +"posturePolicies": [ + { + "frameworkName": "NSA" + "controlName": "Allowed hostPath" + } +] +``` + +But if you wish to exclude the resources decleared in the `resources` list that faild when scanning the `NSA` framework **OR** failed the `Allowed hostPath` control, the `posturePolicies` list should look as following: +``` +"posturePolicies": [ + { + "frameworkName": "NSA" + }, + { + "controlName": "Allowed hostPath" + } +] +``` + +## Examples + +Here are some examples demonstrating the different ways the exceptions file can be configured + + +### Exclude control + +Exclude the ["Allowed hostPath" control](https://github.com/armosec/regolibrary/blob/master/controls/allowedhostpath.json#L2) by declaring the control in the `"posturePolicies"` section. + +The resources + +``` +[ + { + "name": "exclude-allowed-hostPath-control", + "policyType": "postureExceptionPolicy", + "actions": [ + "alertOnly" + ], + "resources": [ + { + "designatorType": "Attributes", + "attributes": { + "kind": ".*" + } + } + ], + "posturePolicies": [ + { + "controlName": "Allowed hostPath" + } + ] + } +] +``` + +### Exclude deployments in the default namespace that failed the "Allowed hostPath" control +``` +[ + { + "name": "exclude-deployments-in-ns-default", + "policyType": "postureExceptionPolicy", + "actions": [ + "alertOnly" + ], + "resources": [ + { + "designatorType": "Attributes", + "attributes": { + "namespace": "default", + "kind": "Deployment" + } + } + ], + "posturePolicies": [ + { + "controlName": "Allowed hostPath" + } + ] + } +] +``` + +### Exclude resources with label "app=nginx" running in a minikube cluster that failed the "NSA" or "MITRE" framework +``` +[ + { + "name": "exclude-nginx-minikube", + "policyType": "postureExceptionPolicy", + "actions": [ + "alertOnly" + ], + "resources": [ + { + "designatorType": "Attributes", + "attributes": { + "cluster": "minikube", + "app": "nginx" + } + } + ], + "posturePolicies": [ + { + "frameworkName": "NSA" + }, + { + "frameworkName": "MITRE" + } + ] + } +] +``` \ No newline at end of file diff --git a/examples/exceptions/exclude-allowed-hostPath-control.json b/examples/exceptions/exclude-allowed-hostPath-control.json new file mode 100644 index 00000000..106dfaa6 --- /dev/null +++ b/examples/exceptions/exclude-allowed-hostPath-control.json @@ -0,0 +1,22 @@ +[ + { + "name": "exclude-allowed-hostPath-control", + "policyType": "postureExceptionPolicy", + "actions": [ + "alertOnly" + ], + "resources": [ + { + "designatorType": "Attributes", + "attributes": { + "kind": ".*" + } + } + ], + "posturePolicies": [ + { + "controlName": "Allowed hostPath" + } + ] + } +] \ No newline at end of file diff --git a/examples/exceptions/exclude-deployments-in-ns-default.json b/examples/exceptions/exclude-deployments-in-ns-default.json new file mode 100644 index 00000000..dceb4010 --- /dev/null +++ b/examples/exceptions/exclude-deployments-in-ns-default.json @@ -0,0 +1,23 @@ +[ + { + "name": "exclude-deployments-in-ns-default", + "policyType": "postureExceptionPolicy", + "actions": [ + "alertOnly" + ], + "resources": [ + { + "designatorType": "Attributes", + "attributes": { + "namespace": "default", + "kind": "Deployment" + } + } + ], + "posturePolicies": [ + { + "controlName": "Allowed hostPath" + } + ] + } +] \ No newline at end of file diff --git a/examples/exceptions.json b/examples/exceptions/exclude-kube-namespaces.json similarity index 85% rename from examples/exceptions.json rename to examples/exceptions/exclude-kube-namespaces.json index 7f67a52b..a8aecd4a 100644 --- a/examples/exceptions.json +++ b/examples/exceptions/exclude-kube-namespaces.json @@ -28,6 +28,12 @@ "posturePolicies": [ { "frameworkName": "NSA" + }, + { + "frameworkName": "MITRE" + }, + { + "frameworkName": "ArmoBest" } ] } diff --git a/examples/exceptions/exclude-nginx-in-minikube.json b/examples/exceptions/exclude-nginx-in-minikube.json new file mode 100644 index 00000000..c0e3cdfe --- /dev/null +++ b/examples/exceptions/exclude-nginx-in-minikube.json @@ -0,0 +1,26 @@ +[ + { + "name": "exclude-nginx-in-minikube", + "policyType": "postureExceptionPolicy", + "actions": [ + "alertOnly" + ], + "resources": [ + { + "designatorType": "Attributes", + "attributes": { + "cluster": "minikube", + "app": "nginx" + } + } + ], + "posturePolicies": [ + { + "frameworkName": "NSA" + }, + { + "frameworkName": "MITRE" + } + ] + } +] \ No newline at end of file From fea84c9652a7cfabfe8afae756662cdf65c1ed28 Mon Sep 17 00:00:00 2001 From: dwertent Date: Sun, 14 Nov 2021 14:42:10 +0200 Subject: [PATCH 2/2] update opa-utils pkg version --- go.mod | 4 ++-- go.sum | 9 ++++----- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/go.mod b/go.mod index 6567897a..ac553962 100644 --- a/go.mod +++ b/go.mod @@ -3,9 +3,9 @@ module github.com/armosec/kubescape go 1.17 require ( - github.com/armosec/armoapi-go v0.0.8 + github.com/armosec/armoapi-go v0.0.23 github.com/armosec/k8s-interface v0.0.8 - github.com/armosec/opa-utils v0.0.39 + github.com/armosec/opa-utils v0.0.42 github.com/armosec/rbac-utils v0.0.1 github.com/armosec/utils-go v0.0.3 github.com/briandowns/spinner v1.16.0 diff --git a/go.sum b/go.sum index c5a8c3df..d298636d 100644 --- a/go.sum +++ b/go.sum @@ -84,13 +84,12 @@ github.com/armon/consul-api v0.0.0-20180202201655-eb2c6b5be1b6/go.mod h1:grANhF5 github.com/armon/go-metrics v0.0.0-20180917152333-f0300d1749da/go.mod h1:Q73ZrmVTwzkszR9V5SSuryQ31EELlFMUz1kKyl939pY= github.com/armon/go-radix v0.0.0-20180808171621-7fddfc383310/go.mod h1:ufUuZ+zHj4x4TnLV4JWEpy2hxWSpsRywHrMgIH9cCH8= github.com/armosec/armoapi-go v0.0.2/go.mod h1:vIK17yoKbJRQyZXWWLe3AqfqCRITxW8qmSkApyq5xFs= -github.com/armosec/armoapi-go v0.0.7/go.mod h1:iaVVGyc23QGGzAdv4n+szGQg3Rbpixn9yQTU3qWRpaw= -github.com/armosec/armoapi-go v0.0.8 h1:JPa9rZynuE2RucamDh6dsy/sjCScmWDsyt1zagJFCDo= -github.com/armosec/armoapi-go v0.0.8/go.mod h1:iaVVGyc23QGGzAdv4n+szGQg3Rbpixn9yQTU3qWRpaw= +github.com/armosec/armoapi-go v0.0.23 h1:jqoLIWM5CR7DCD9fpFgN0ePqtHvOCoZv/XzCwsUluJU= +github.com/armosec/armoapi-go v0.0.23/go.mod h1:iaVVGyc23QGGzAdv4n+szGQg3Rbpixn9yQTU3qWRpaw= github.com/armosec/k8s-interface v0.0.8 h1:Eo3Qen4yFXxzVem49FNeij2ckyzHSAJ0w6PZMaSEIm8= github.com/armosec/k8s-interface v0.0.8/go.mod h1:xxS+V5QT3gVQTwZyAMMDrYLWGrfKOpiJ7Jfhfa0w9sM= -github.com/armosec/opa-utils v0.0.39 h1:YOPMmwZaseqZT2/io918YycrMoJYu+ggbINnZJR9ZUA= -github.com/armosec/opa-utils v0.0.39/go.mod h1:JaE2a0kB2O22JZCqBBfOS9Pvh9rXs9xXXb9lVo01rTs= +github.com/armosec/opa-utils v0.0.42 h1:7YzQJNVBmM0+1nWOAiUgDt+mvlVEwApg80FjMh4oxXo= +github.com/armosec/opa-utils v0.0.42/go.mod h1:OqewZoSqKD5udtQ4lGFixb8yyFNqLq9zqinlAL6KSjM= github.com/armosec/rbac-utils v0.0.1 h1:N2MI98F/0zbDjmRZ29CNElU1AXkFLk5csd/qAHOBdXY= github.com/armosec/rbac-utils v0.0.1/go.mod h1:pQ8CBiij8kSKV7aeZm9FMvtZN28VgA7LZcYyTWimq40= github.com/armosec/utils-go v0.0.2/go.mod h1:itWmRLzRdsnwjpEOomL0mBWGnVNNIxSjDAdyc+b0iUo=