🚨 v1 API is deprecated, please read the release notes 🚨
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
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 install github.com/controlplaneio/kubesec/v2@latest
$ GO111MODULE="on" go get github.com/controlplaneio/kubesec/v2
$ kubesec scan k8s-deployment.yaml
$ 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
Run the same command in Docker:
$ docker run -i kubesec/kubesec:v2 scan /dev/stdin < kubesec-test.yaml
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. (Formatted x.y.z with no v prefix)
kubesec [scan|http] --kubernetes-version <version>
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 <version> --schema-location https://host.server
Schema will be fetched from: https://host.server/v<version>-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 <version> --schema-location /opt/schemas
Schema will be read from: /opt/schemas/v<version>-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.
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 includes a bundled HTTP server
The listen address for the HTTP server can be configured by setting
KUBESEC_ADDR
environment variable. The value can be a single port
such as 8080
or an address in the form of ip:port
or [ipv6]:port
.
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 %
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 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.
$ curl -sSX POST --data-binary @"k8s-deployment.yaml" https://v2.kubesec.io/scan
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
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
},
{
// ...
}
]
}
}
]
Thanks to our awesome contributors!
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!