Kubesec
🚨 v1 API is deprecated, please read the release notes 🚨
Security risk analysis for Kubernetes resources
Live demo
This uses ControlPlane's hosted API at v2.kubesec.io/scan
- Download Kubesec
- Kubesec HTTP Server
- Kubesec-as-a-Service
- Example output
- Contributors
- Getting Help
- Contributing
- Changelog
Download Kubesec
Kubesec is available as a:
- Docker container image at
docker.io/kubesec/kubesec:v2
- Linux/MacOS/Win binary (get the latest release)
- Kubernetes Admission Controller
- Kubectl plugin
Or install the latest commit from GitHub with:
Go 1.16+
$ go install github.com/controlplaneio/kubesec/v2@latest
Go version < 1.16
$ GO111MODULE="on" go get github.com/controlplaneio/kubesec/v2
Command line usage:
$ kubesec scan k8s-deployment.yaml
Usage example:
$ cat <<EOF > kubesec-test.yaml
apiVersion: v1
kind: Pod
metadata:
name: kubesec-demo
spec:
containers:
- name: kubesec-demo
image: gcr.io/google-samples/node-hello:1.0
securityContext:
readOnlyRootFilesystem: true
EOF
$ kubesec scan kubesec-test.yaml
Docker usage:
Run the same command in Docker:
$ docker run -i kubesec/kubesec:v2 scan /dev/stdin < kubesec-test.yaml
Specify custom schema
Kubesec leverages kubeconform (thanks @yannh) to validate the manifests to scan. This implies that specifying different schema locations follows the rules as described in the kubeconform README.
Here is a quick overview on how this work for scanning a pod manifest:
- I want to use the latest available schema from upstream.
kubesec [scan|http]
Schema will be fetched from: https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master/master-standalone-strict/pod-v1.json
- I want to use a specific schema version from upstream.
kubesec [scan|http] --kubernetes-version 1.25.3
Schema will be fetched from: https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master/v1.25.3-standalone-strict/pod-v1.json
- I want to use a specific schema version in an airgap environment over HTTP.
kubesec [scan|http] --kubernetes-version 1.25.3 --schema-location https://host.server
Schema will be fetched from: https://host.server/v1.25.3-standalone-strict/pod-v1.json
- I want to use a specific schema version in an airgap environment with local files:
kubesec [scan|http] --kubernetes-version 1.25.3 --schema-location /opt/schemas
Schema will be fetched from: /opt/schemas/v1.25.3-standalone-strict/pod-v1.json
Note: in order to limit external network calls and allow usage in airgap
environments, the kubesec
image embeds schemas. If you are looking to change
the schema location, you'll need to change the K8S_SCHEMA_VER
and SCHEMA_LOCATION
environment variables at runtime.
Print the scanning rules with their associated scores
All the scanning rules can be printed in in different formats (json (default), yaml and table). This is useful to easily get the point associated with each rule:
kubesec print-rules
which produces the following output:
[
{
"id": "AllowPrivilegeEscalation",
"selector": "containers[] .securityContext .allowPrivilegeEscalation == true",
"reason": "Ensure a non-root process can not gain more privileges",
"kinds": [
"Pod",
"Deployment",
"StatefulSet",
"DaemonSet"
],
"points": -7,
"advise": 0
},
...
]
Kubesec HTTP Server
Kubesec includes a bundled HTTP server
CLI usage example:
Start the HTTP server in the background
$ kubesec http 8080 &
[1] 12345
{"severity":"info","timestamp":"2019-05-12T11:58:34.662+0100","caller":"server/server.go:69","message":"Starting HTTP server on port 8080"}
Use curl to POST a file to the server
$ curl -sSX POST --data-binary @test/asset/score-0-cap-sys-admin.yml http://localhost:8080/scan
[
{
"object": "Pod/security-context-demo.default",
"valid": true,
"message": "Failed with a score of -30 points",
"score": -30,
"scoring": {
"critical": [
{
"selector": "containers[] .securityContext .capabilities .add == SYS_ADMIN",
"reason": "CAP_SYS_ADMIN is the most privileged capability and should always be avoided",
"points": -30
},
{
"selector": "containers[] .securityContext .runAsNonRoot == true",
"reason": "Force the running image to run as a non-root user to ensure least privilege",
"points": 1
},
// ...
Finally, stop the Kubesec server by killing the background process
$ kill %
Docker usage example:
Start the HTTP server using Docker
$ docker run -d -p 8080:8080 kubesec/kubesec:v2 http 8080
Use curl to POST a file to the server
$ curl -sSX POST --data-binary @test/asset/score-0-cap-sys-admin.yml http://localhost:8080/scan
...
Don't forget to stop the server.
Kubesec-as-a-Service
Kubesec is also available via HTTPS at v2.kubesec.io/scan
Please do not submit sensitive YAML to this service.
The service is ran on a good faith best effort basis.
Command line usage:
$ curl -sSX POST --data-binary @"k8s-deployment.yaml" https://v2.kubesec.io/scan
Usage example:
Define a BASH function
$ kubesec ()
{
local FILE="${1:-}";
[[ ! -e "${FILE}" ]] && {
echo "kubesec: ${FILE}: No such file" >&2;
return 1
};
curl --silent \
--compressed \
--connect-timeout 5 \
-sSX POST \
--data-binary=@"${FILE}" \
https://v2.kubesec.io/scan
}
POST a Kubernetes resource to v2.kubesec.io/scan
$ kubesec ./deployment.yml
Return non-zero status code is the score is not greater than 10
$ kubesec ./score-9-deployment.yml | jq --exit-status '.score > 10' >/dev/null
# status code 1
Example output
Kubesec returns a returns a JSON array, and can scan multiple YAML documents in a single input file.
[
{
"object": "Pod/security-context-demo.default",
"valid": true,
"message": "Failed with a score of -30 points",
"score": -30,
"scoring": {
"critical": [
{
"selector": "containers[] .securityContext .capabilities .add == SYS_ADMIN",
"reason": "CAP_SYS_ADMIN is the most privileged capability and should always be avoided",
"points": -30
}
],
"advise": [
{
"selector": "containers[] .securityContext .runAsNonRoot == true",
"reason": "Force the running image to run as a non-root user to ensure least privilege",
"points": 1
},
{
// ...
}
]
}
}
]
Contributors
Thanks to our awesome contributors!
Getting Help
If you have any questions about Kubesec and Kubernetes security:
- Read the Kubesec docs
- Reach out on Twitter to @sublimino or @controlplaneio
- File an issue
Your feedback is always welcome!