Skip to content

Documentation

Overview

The Kubernetes Security Scanning Tool (kube-scan) helps you identify security vulnerabilities in Kubernetes clusters. This tool supports external scanning and provides a detailed HTML report for further analysis.

Installation

To use the tool, first pull the Docker image from the private repository:

docker pull braundo30/kube-scan:latest

Private Repo Access

Please note that this is a private repo, and unless you've been explicitly granted access, you will be unable to pull this image.


Usage

To run the tool, use the following docker run command format:

docker run --rm -p 8000:8000 braundo30/kube-scan:latest --target <API_SERVER_IP> --mode <MODE>

Arguments:

  • --target (required): Specify the IP or hostname of the Kubernetes API server to target.
  • --mode (required): Choose the scanning mode:
    • external: Simulates attacks from outside the cluster.
    • internal: Simulates attacks from within the cluster (under active development).
  • -p 8000:8000: Maps the internal HTTP server to your local machine's port 8000.

Feature Development

Launching scans via the user interface is under active development and not included in the latest release.


Accessing the Report

Once the scan completes, the tool automatically generates an HTML report and serves it via a simple HTTP server.

  • Open your browser and navigate to the following URL to view the report at http://localhost:8000/report.html.

  • To stop the server, press CTRL+C in the terminal running the tool.

Example Commands

Example 1: External Scan of a Kubernetes Cluster

Run an external scan targeting the API server at 10.254.18.39:

docker run --rm -p 8000:8000 braundo30/kube-scan:latest --target 10.254.18.39 --mode external

After the scan is complete:

Example 2: Specifying a Custom Port for the Report Server

By default, the report server runs on port 8000. If port 8000 is already in use, you can specify a custom port with the --port argument:

docker run --rm -p 8080:8000 braundo30/kube-scan:latest --target 10.254.18.39 --mode external --port 8080
After the scan is complete:


Tips and Best Practices

Ensure Access to the Target API Server
  • The --target argument must specify an API server endpoint accessible from the machine running the Docker container.
Output Directory
  • By default, the report is served directly via the internal web server. You don't need to manage any files manually.
Keeping the Tool Updated
  • Periodically pull the latest version of the Docker image to ensure you have the most recent security checks: 
    docker pull braundo30/kube-scan:latest
Customizing Docker Commands
  • Use volume mounts (-v) if you want to persist logs or files generated by future updates of the tool.


Troubleshooting

Error: python: can't open file '/app/main.py': [Errno 2] No such file or directory
  • Ensure you are using the correct docker run command and targeting the appropriate API server.
Can't Access the Report in Browser
  • Verify that the port mapping (-p) in the docker run command matches the URL you are using to access the report.
  • Confirm that the Docker container is running and has not been stopped.
Scanner taking a long time to complete.
  • Some tests (e.g., DNS spoofing) may take longer depending on the target's configuration. Be patient, and allow the tool to complete all tests.


Feedback and Support

If you encounter any issues or have feature requests, please contact me at [email protected].

Enjoy using the Kubernetes Security Scanning Tool to secure your clusters!