• Stars
    star
    1,191
  • Rank 39,271 (Top 0.8 %)
  • Language
    Go
  • License
    Apache License 2.0
  • Created about 7 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Security risk analysis for Kubernetes resources

Kubesec

Testing Workflow Security Analysis Workflow Release Workflow

Go Report Card PkgGoDev

🚨 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

Kubesec is available as a:

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:

Your feedback is always welcome!

More Repositories

1

simulator

Kubernetes Security Training Platform - focusing on security mitigation
Go
659
star
2

kubectl-kubesec

Security risk analysis for Kubernetes resources
Go
493
star
3

netassert

Network security testing for Kubernetes DevSecOps workflows
Go
361
star
4

badrobot

BadRobot - Operator Security Audit Tool
Go
208
star
5

truffleproc

truffleproc — hunt secrets in process memory (TruffleHog & gdb mashup)
Shell
110
star
6

kubesec-webhook

Security risk analysis for Kubernetes resources
Go
74
star
7

theseus

Continuous Zero-Downtime Deployments for Kubernetes & Istio
Shell
28
star
8

threat-modelling-labs

Labs for Threat Modelling training delivered by ControlPlane
Makefile
27
star
9

kubesec-action

Runs Kubesec as GitHub action
Dockerfile
18
star
10

threat-modelling-zero-trust-talk

Go
10
star
11

operator-threat-matrix

Kubernetes Operator Threat Matrix
9
star
12

collie

OSCAL and Kyverno Policy Demo for AWS
Shell
8
star
13

cp-jenkins

ControlPlane's Opinionated Jenkins-as-Code
Python
7
star
14

spire-vault

Example configuration for integrating Spire with Vault.
Makefile
6
star
15

workshop-2018-kc-seattle-secure-kubernetes-deployment-pipelines

KubeCon Seattle - Building Security into Kubernetes Deployment Pipelines
SQLPL
5
star
16

vault-trust-operator

Dockerfile
4
star
17

grafeas-docker

Dockerfiles and compose file for containerised Grafeas
Shell
3
star
18

intro-k8s-workshop-ccau

null
2
star
19

netassertv2-packet-sniffer

This repo houses Netassertv2 TCP/UDP Packet sniffer
Go
2
star
20

threat-modelling-envoy-gateway-talk

Demos and investigation work supporting the Envoy Gateway threat model
Shell
2
star
21

docker-gcloud-sdk

null
Dockerfile
1
star
22

hostile-npm

An example of a hostile pre-install npm hook
Shell
1
star
23

tekton-training

Sample Tekton Pipeline specification for ControlPlane training labs.
Makefile
1
star