examples/exceptions/README.md
Kubescape Exceptions allow you to exclude specific resources from affecting your security risk score. This is useful when certain resources intentionally deviate from security best practices and you want to acknowledge this without impacting your overall compliance metrics.
kube-system resources that are expected to have elevated privilegesAn exception file is a JSON array containing one or more exception objects:
[
{
"name": "exception-name",
"policyType": "postureExceptionPolicy",
"actions": ["alertOnly"],
"resources": [...],
"posturePolicies": [...]
}
]
| Field | Description |
|---|---|
name | Unique name for this exception |
policyType | Must be "postureExceptionPolicy" |
actions | List of actions. Currently only "alertOnly" is supported |
resources | List of resources to apply this exception to |
posturePolicies | List of policies/controls to exclude |
Resources are defined using attribute-based selectors. Supported attributes:
| Attribute | Description | Regex Support |
|---|---|---|
name | Kubernetes resource name | ✅ Yes |
kind | Kubernetes resource kind (e.g., Deployment, Pod) | ✅ Yes |
namespace | Kubernetes namespace | ✅ Yes |
cluster | Cluster name (usually the current-context) | ✅ Yes |
<label-key> | Any resource label (e.g., app, environment) | ❌ No |
Policies can be specified by:
| Attribute | Description | Regex Support |
|---|---|---|
frameworkName | Framework name (e.g., NSA, MITRE) | ✅ Yes |
controlName | Control name (e.g., HostPath mount) | ✅ Yes |
controlID | Control ID (e.g., C-0048) | ✅ Yes |
Find framework names in the frameworks directory and control information in the controls directory.
kubescape scan --exceptions /path/to/exceptions.json
Resources matching exceptions will be marked as excluded rather than failed in the results.
⚠️ Important: You must declare at least one resource AND one policy in each exception.
Multiple items in the resources list are evaluated with OR logic:
"resources": [
{ "attributes": { "namespace": "dev" } },
{ "attributes": { "namespace": "test" } }
]
This matches resources in the dev namespace OR the test namespace.
Multiple attributes in a single object are evaluated with AND logic:
"resources": [
{ "attributes": { "namespace": "production", "kind": "Deployment" } }
]
This matches only Deployment resources AND in the production namespace.
Exclude control C-0048 (HostPath mount) for all resources:
[
{
"name": "exclude-hostpath-control",
"policyType": "postureExceptionPolicy",
"actions": ["alertOnly"],
"resources": [
{
"designatorType": "Attributes",
"attributes": {
"kind": ".*"
}
}
],
"posturePolicies": [
{
"controlID": "C-0048"
}
]
}
]
Exclude all resources in the kube-system namespace from all frameworks:
[
{
"name": "exclude-kube-system",
"policyType": "postureExceptionPolicy",
"actions": ["alertOnly"],
"resources": [
{
"designatorType": "Attributes",
"attributes": {
"namespace": "kube-system"
}
}
],
"posturePolicies": [
{
"frameworkName": ".*"
}
]
}
]
[
{
"name": "exclude-deployments-in-default",
"policyType": "postureExceptionPolicy",
"actions": ["alertOnly"],
"resources": [
{
"designatorType": "Attributes",
"attributes": {
"namespace": "default",
"kind": "Deployment"
}
}
],
"posturePolicies": [
{
"controlName": "HostPath mount"
}
]
}
]
Exclude resources with label environment=dev from NSA and MITRE frameworks:
[
{
"name": "exclude-dev-environment",
"policyType": "postureExceptionPolicy",
"actions": ["alertOnly"],
"resources": [
{
"designatorType": "Attributes",
"attributes": {
"environment": "dev"
}
}
],
"posturePolicies": [
{
"frameworkName": "NSA"
},
{
"frameworkName": "MITRE"
}
]
}
]
Exclude nginx resources in a minikube cluster:
[
{
"name": "exclude-nginx-minikube",
"policyType": "postureExceptionPolicy",
"actions": ["alertOnly"],
"resources": [
{
"designatorType": "Attributes",
"attributes": {
"cluster": "minikube",
"app": "nginx"
}
}
],
"posturePolicies": [
{
"frameworkName": ".*"
}
]
}
]
You can combine multiple exceptions in a single file:
[
{
"name": "exclude-kube-namespaces",
"policyType": "postureExceptionPolicy",
"actions": ["alertOnly"],
"resources": [
{
"designatorType": "Attributes",
"attributes": {
"namespace": "kube-system"
}
},
{
"designatorType": "Attributes",
"attributes": {
"namespace": "kube-public"
}
}
],
"posturePolicies": [
{
"frameworkName": ".*"
}
]
},
{
"name": "exclude-privileged-control-for-monitoring",
"policyType": "postureExceptionPolicy",
"actions": ["alertOnly"],
"resources": [
{
"designatorType": "Attributes",
"attributes": {
"namespace": "monitoring"
}
}
],
"posturePolicies": [
{
"controlID": "C-0057"
}
]
}
]