kubesec

README

kubesec

🚨 v1 API is deprecated, please read the release notes 🚨

Security risk analysis for Kubernetes resources

Live demo

Visit Kubesec.io

This uses ControlPlane's hosted API at v2.kubesec.io/scan

---

• Download Kubesec
  • Command line usage
  • Usage example
  • Docker usage
• Kubesec HTTP Server
  • CLI usage example
  • Docker usage example
• Kubesec-as-a-Service
  • Command line usage
  • Usage example
• Example output
• Contributors
• Contributing
• Getting Help
• Release Notes
  • 2.2.0
  • 2.1.0
  • 2.0.0
  • 1.0.0

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 get -u github.com/controlplaneio/kubesec/cmd/kubesec

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:512c5e0 scan /dev/stdin < kubesec-test.yaml

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:d432be9 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

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!

• Andrew Martin
• Stefan Prodan

Contributing

Kubesecis Apache 2.0 licensed and accepts contributions via GitHub pull requests.

When submitting bug reports please include as much details as possible:

• which Kubesec version
• which Kubernetes version
• what happened (Kubesec logs and expected output)

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!

Release Notes

2.2.0

• added in-toto support

2.1.0

• add rule for allowPrivilegeEscalation: true with a score of -7
• add points field to each recommendation so the values that comprise the total score can be seen
• fix case sensitivity bug in .capabilities.drop | index("ALL")
• rules in critical and advise lists prioritised and returned in same order across runs

2.0.0

• first open source release
• passes same acceptance tests as Kubesec v1
• more stringent analysis: scoring for a rule is multiplied by number of matches (previously the score was only applied once), initContainers are included in score, new securityContext directive support, seccomp and apparmor pod-targeting tighter
• CLI and HTTP server bundled in single binary

1.0.0

• initial release at https://kubesec.io
• closed source