kubescape/docs/getting-started.md

Getting started with Kubescape

Kubescape can run as a command line tool on a client, as an operator inside a cluster, as part of your CI/CD process, or more.

The best way to get started with Kubescape is to download it to the machine you use to manage your Kubernetes cluster.

Install Kubescape

curl -s https://raw.githubusercontent.com/kubescape/kubescape/master/install.sh | /bin/bash

(We're a security product; please read the file before you run it!)

You can also

• Install on windows
• Install on macOS
• Install on NixOS or Linux/macOS via nix

Run your first scan

kubescape scan --enable-host-scan --verbose

You will see output like this:

Usage

Some documentation on using Kubescape is yet to move here from the ARMO Platform docs.

Examples

• Scan a running Kubernetes cluster:

  kubescape scan --enable-host-scan  --verbose
  

  Note

  
  Read more about host scanning.

• Scan a running Kubernetes cluster with the NSA framework:

  kubescape scan framework nsa
  

• Scan a running Kubernetes cluster with the MITRE ATT&CK® framework:

  kubescape scan framework mitre
  

• Scan for a specific control, using the control name or control ID. See the list of controls.

  kubescape scan control "Privileged container"
  

• Use an alternative kubeconfig file:

  kubescape scan --kubeconfig cluster.conf
  

• Scan specific namespaces:

  kubescape scan --include-namespaces development,staging,production
  

• Exclude certain namespaces:

  kubescape scan --exclude-namespaces kube-system,kube-public
  

• Scan local YAML/JSON files before deploying:

  kubescape scan *.yaml
  

  Take a look at the demonstration](https://youtu.be/Ox6DaR7_4ZI).

• Scan Kubernetes manifest files from a Git repository:

  kubescape scan https://github.com/kubescape/kubescape
  

• Scan with exceptions

  kubescape scan --exceptions examples/exceptions/exclude-kube-namespaces.json
  

  Objects with exceptions will be presented as exclude and not fail.

  See more examples about exceptions.

• Scan Helm charts

  kubescape scan </path/to/directory>
  

  Note

  
  Kubescape will load the default VALUES file.

• Scan a Kustomize directory

  kubescape scan </path/to/directory>
  

  Note

  
  Kubescape will generate Kubernetes YAML objects using a kustomize file and scan them for security.

Output formats

• JSON:

  kubescape scan --format json --format-version v2 --output results.json
  

  Note

  
  Add the --format-version v2 flag for maximum compatibility.

• junit XML:

  kubescape scan --format junit --output results.xml
  

• PDF:

  kubescape scan --format pdf --output results.pdf
  

  Contributed by @alegrey91

• Prometheus metrics:

  kubescape scan --format prometheus
  

  Contributed by @Joibel

• HTML

  kubescape scan --format html --output results.html
  

• Display all scanned resources (including the resources which passed):

  kubescape scan --verbose
  

Offline/air-gapped environment support

It is possible to run Kubescape offline! Check out our video tutorial.

Download all artifacts

1. Download the controls and save them in the local directory. If no path is specified, they will be saved in ~/.kubescape.

   kubescape download artifacts --output path/to/local/dir
   

2. Copy the downloaded artifacts to the offline system.

3. Scan using the downloaded artifacts:

   kubescape scan --use-artifacts-from path/to/local/dir
   

Download a single artifact

You can also download a single artifact, and scan with the --use-from flag:

1. Download and save in a file. If no file name is specified, the artifact will be saved as ~/.kubescape/<framework name>.json.

   kubescape download framework nsa --output /path/nsa.json
   

2. Copy the downloaded artifacts to the offline system.

3. Scan using the downloaded framework:

   kubescape scan framework nsa --use-from /path/nsa.json
   

Other ways to use Kubescape

Scan periodically using Helm

We publish a Helm chart for our in-cluster components. Please follow the instructions here

VS Code Extension

Scan your YAML files while writing them using our VS Code extension.

Lens Extension

View Kubescape scan results directly in the Lens IDE using the Kubescape Lens extension.

Playground

Experiment with Kubescape in the Kubescape playground: this scenario will install a K3s cluster and Kubescape. You can start with any of the kubescape scan commands in the examples.

Tutorial videos

• Kubescape overview
• How to secure Kubernetes clusters with Kubescape
• Scan Kubernetes YAML files
• Scan container image registry
• Scan Kubescape on an air-gapped environment (offline support)
• Managing exceptions in ARMO Platform
• Configure and run customized frameworks
• Customize control configurations:
  • Kubescape CLI
  • ARMO Platform

Other installation methods

The curl install method will work on all platforms, but you may wish to use a native method to install Kubescape.

Install on Windows

You must have PowerShell v5.0 or higher installed.

iwr -useb https://raw.githubusercontent.com/kubescape/kubescape/master/install.ps1 | iex

If you get an error, you may need to change the execution policy:

Set-ExecutionPolicy RemoteSigned -scope CurrentUser

Install on macOS

You can install Kubescape via Homebrew:

brew tap kubescape/tap
brew install kubescape-cli

Install on NixOS or with nix

This method is community-supported. If you are having trouble, please reach out to NixOS support

You can use nix on Linux or macOS.

Try it out in an ephemeral shell: nix-shell -p kubescape

NixOS:

  # your other config ...
  environment.systemPackages = with pkgs; [
    # your other packages ...
    kubescape
  ];

home-manager:

  # your other config ...
  home.packages = with pkgs; [
    # your other packages ...
    kubescape
  ];

Or, to your profile (not preferred): nix-env --install -A nixpkgs.kubescape