Kubescape Exceptions
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.
Table of Contents
Use Cases
- Exclude
kube-systemresources that are expected to have elevated privileges - Ignore development/test namespaces from production compliance reports
- Accept known risks for specific workloads after security review
- Temporarily exclude resources while fixes are being implemented
Exception Structure
An exception file is a JSON array containing one or more exception objects:
[
{
"name": "exception-name",
"policyType": "postureExceptionPolicy",
"actions": ["alertOnly"],
"resources": [...],
"posturePolicies": [...]
}
]
Fields
| 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 |
Resource Attributes
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 |
Policy Attributes
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.
Usage
Running a Scan with Exceptions
kubescape scan --exceptions /path/to/exceptions.json
Resources matching exceptions will be marked as excluded rather than failed in the results.
Logic Rules
⚠️ Important: You must declare at least one resource AND one policy in each exception.
Within a list: OR logic
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.
Within an object: AND logic
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.
Examples
Exclude a Specific Control Everywhere
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 kube-system Resources
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": ".*"
}
]
}
]
Exclude Deployments in Default Namespace for a Specific Control
[
{
"name": "exclude-deployments-in-default",
"policyType": "postureExceptionPolicy",
"actions": ["alertOnly"],
"resources": [
{
"designatorType": "Attributes",
"attributes": {
"namespace": "default",
"kind": "Deployment"
}
}
],
"posturePolicies": [
{
"controlName": "HostPath mount"
}
]
}
]
Exclude Resources by Label
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 Specific Workload in Specific Cluster
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": ".*"
}
]
}
]
Multiple Exceptions in One File
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"
}
]
}
]