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"
}
]
}
]
Industrial Control System / Operational Technology (ICS/OT) workloads frequently require deviations from standard Kubernetes hardening, for example hostNetwork: true for Modbus/DNP3 protocol bridges that need direct reachability to PLC subnets. See docs/ics-ot-workloads.md for the full guidance on scanning OT workloads with Kubescape.
The example below scopes the exception narrowly: it suppresses only C-0041 (hostNetwork) for resources carrying the label sector: ics-ot, leaving every other control in the failed state so genuinely new misconfigurations still surface. Pair every exception with a compensating control (typically a NetworkPolicy that default-denies ingress to the OT namespace) and document the risk acceptance in your change-management system.
[
{
"name": "exclude-ot-sector-host-network",
"policyType": "postureExceptionPolicy",
"actions": ["alertOnly"],
"resources": [
{
"designatorType": "Attributes",
"attributes": {
"sector": "ics-ot"
}
}
],
"posturePolicies": [
{
"controlID": "C-0041"
}
]
}
]