Kube-hunter Penetration Testing: Complete Implementation Guide

What Is Kube-hunter?

Kube-hunter is an open-source security tool designed to hunt for weaknesses and misconfigurations in Kubernetes clusters. Created and maintained by Aqua Security, it takes the perspective of an attacker attempting to compromise a cluster, actively probing for known vulnerabilities and common configuration errors. The tool is containerised and can be run from outside the cluster (as a remote attacker would) or from inside a pod (simulating a compromised container).

Kube-hunter operates by executing a series of active hunters – modular tests that check for specific risks such as exposed sensitive ports, insecure RBAC configurations, unauthenticated access to the Kubelet API, anonymous access to etcd, privileged containers, and many more. Each hunter produces a finding classified as a vulnerability or an advisory, along with a severity level and a detailed explanation of the risk.

The tool can be used in several modes:

Remote scanning – simulating an external attacker targeting the Kubernetes API server and exposed services.
Internal scanning – running inside a pod to discover what an attacker could do after gaining initial access.
CIDR-based scanning – scanning a whole IP range to locate live Kubernetes nodes and test them.
Active and passive modes – active mode performs intrusive tests; passive mode only performs information gathering without exploiting anything.

Kube-hunter outputs a detailed JSON report that can be integrated into CI/CD pipelines, security dashboards, or used as a standalone assessment tool. It also provides an interactive HTML report for immediate visual triage.

Why Kube-hunter Matters

🚀 Deploy your AI agent in 10 minutes

Managed Hermes hosting. Zero DevOps. 100M tokens/mo included.

Try it free →

Kubernetes security is a complex, multi-layered challenge. Default configurations, overly permissive RBAC rules, exposed management interfaces, and container escape vectors can all lead to full cluster compromise. Kube-hunter matters because it gives teams a practical, attacker’s-eye view of their cluster, revealing blind spots that static analysis or compliance checklists often miss.

Key reasons to adopt Kube-hunter include:

Realistic threat modelling – The tool uses the same techniques an attacker would, including port scanning, API enumeration, token extraction, and exploitation of well-known CVEs.
Immediate actionable results – Each finding comes with a clear description, severity, and recommended fix, shortening the time from discovery to remediation.
Low overhead and easy integration – As a containerised tool, it can be run ad-hoc or scheduled as a CronJob within the cluster itself, providing continuous security validation.
Comprehensive coverage – Kube-hunter checks nodes, the API server, etcd, Kubelet, the dashboard, and workloads, covering the entire Kubernetes attack surface.
Compliance support – Many of the checks map directly to CIS Kubernetes Benchmarks and other regulatory frameworks, helping teams meet audit requirements.

By regularly running Kube-hunter, organisations can catch misconfigurations before they become incidents, validate that security hardening measures are effective, and foster a proactive security culture around their Kubernetes infrastructure.

Installation and Setup

Kube-hunter is distributed as a Docker image and can be run anywhere Docker is available. The recommended approach is to pull the official image and execute it with the appropriate options. You can also install it as a Python package (for advanced usage) or deploy it as a Kubernetes Job or CronJob for continuous scanning.

Prerequisites

Docker installed on the machine that will run the scan (or a Kubernetes cluster with ability to run pods).
Network connectivity to the target cluster – for remote scans, the machine must be able to reach the Kubernetes API server and node IPs.
Appropriate permissions – for internal scanning, you need a service account token and at least read-only access to pods and nodes (the default service account is often sufficient).
Python 3.7+ if you plan to install from source or use the pip package.

Using the Docker Image

Pull the latest image:

docker pull aquasec/kube-hunter:latest

Verify the image is available:

docker images | grep kube-hunter

For a quick test, you can run kube-hunter in passive remote mode against a known Kubernetes API endpoint:

docker run --rm aquasec/kube-hunter:latest --kube-hunter-mode remote --passive --kubeconfig  \
  --remote :

However, the container does not have your kubeconfig file by default. To use a local kubeconfig, mount it as a volume:

docker run --rm -v $HOME/.kube/config:/root/.kube/config aquasec/kube-hunter:latest --kube-hunter-mode remote --passive

Installing as a Python Package

For environments without Docker or for integration into existing Python toolchains, install via pip:

pip install kube-hunter

After installation, the kube-hunter command is available directly. This method is useful when you need to embed kube-hunter in automated scripts or combine it with other Python-based security tools.

Deploying Inside Kubernetes (Internal Scan)

To run an internal scan from within the cluster, you can create a simple pod or Job. Below is an example Job manifest that runs kube-hunter in internal mode and writes the report to a persistent volume (adjust storage as needed):

apiVersion: batch/v1
kind: Job
metadata:
  name: kube-hunter-internal-scan
spec:
  template:
    spec:
      containers:
      - name: kube-hunter
        image: aquasec/kube-hunter:latest
        args: ["--kube-hunter-mode", "internal", "--report", "json", "--output", "/reports/kube-hunter-report.json"]
        volumeMounts:
        - name: reports
          mountPath: /reports
      volumes:
      - name: reports
        persistentVolumeClaim:
          claimName: kube-hunter-pvc
      restartPolicy: Never
  backoffLimit: 1

Apply it with kubectl apply -f job.yaml and check the logs and report file. You can also schedule it as a CronJob for periodic scanning.

Running Kube-hunter: Modes and Options

Kube-hunter’s behaviour is primarily controlled by the --kube-hunter-mode flag and a set of complementary options. Understanding these modes is essential to tailor the scan to your threat model.

Remote Scanning

This mode simulates an attacker outside the cluster. It requires the Kubernetes API server address (and optionally node IPs). It enumerates open ports, probes the API server for anonymous access, checks the Kubelet for unauthorised access, and tests etcd if reachable.

Basic remote scan using an explicit API server IP:

docker run --rm aquasec/kube-hunter:latest --kube-hunter-mode remote --remote 192.168.1.100:6443

You can also scan a whole CIDR range. Kube-hunter will discover live nodes and target their Kubelet ports automatically:

docker run --rm aquasec/kube-hunter:latest --kube-hunter-mode remote --cidr 10.0.1.0/24

In remote mode, kube-hunter first performs network discovery, then launches hunters against discovered services. Adding --passive will limit it to information gathering without attempting any exploitation (e.g., no token extraction).

Internal Scanning

Internal mode assumes the scanner is running inside a pod. It reads the pod’s service account token and uses the Kubernetes environment variables to locate the API server. It then checks what actions the pod’s identity can perform, inspects node configurations via the Kubelet (if reachable), and enumerates cluster‑wide weaknesses from the inside.

Run internal mode via Docker by providing a service account token and API server address manually (simulating a compromised container):

docker run --rm -e KUBERNETES_SERVICE_HOST=10.0.0.1 -e KUBERNETES_SERVICE_PORT=443 \
  -v /var/run/secrets/kubernetes.io/serviceaccount/token:/var/run/secrets/kubernetes.io/serviceaccount/token \
  aquasec/kube-hunter:latest --kube-hunter-mode internal

In a real pod, you simply invoke kube-hunter without needing to mount tokens — the pod’s environment provides everything. The example Job above demonstrates the typical deployment.

Active vs Passive

By default, kube-hunter runs in active mode, meaning it will try to exploit findings to confirm vulnerabilities (e.g., attempt to use discovered tokens, run commands via the Kubelet, etc.). To run a completely safe, non‑intrusive scan, add --passive:

docker run --rm aquasec/kube-hunter:latest --kube-hunter-mode remote --remote 10.0.0.1:6443 --passive

Passive mode is recommended for production environments where any modification or exploitation attempt could impact stability. It still detects exposed endpoints and configuration weaknesses without taking any active steps.

Report Formats

Kube-hunter can output results in several formats. The default is a human‑readable table printed to stdout. For automation, use --report json to get a structured JSON report that can be parsed by scripts or dashboards.

Generate a JSON report and save it to a file:

docker run --rm -v $(pwd)/reports:/reports aquasec/kube-hunter:latest --kube-hunter-mode remote \
  --remote 192.168.1.100:6443 --report json --output /reports/scan-result.json

You can also use --report plain for a text summary. For a quick visual overview, run kube-hunter with the --html flag to produce an interactive HTML report (requires a browser to open).

Filtering and Customisation

Kube-hunter supports selecting specific hunters via --active-hunters or --matching-hunters patterns, and excluding tests with --exclude-hunters. This is useful when you want to focus on a particular area, such as only Kubelet checks, or when certain hunters are irrelevant to your environment.

Example: run only hunters related to RBAC and the dashboard:

docker run --rm aquasec/kube-hunter:latest --kube-hunter-mode internal --matching-hunters "RBAC\|Dashboard"

To see all available hunters and their descriptions, run with --list-hunters:

docker run --rm aquasec/kube-hunter:latest --list-hunters

Interpreting Results and Remediation

Each finding from kube-hunter includes:

Severity – typically high, medium, low, or info.
Category – such as Information Disclosure, Unauthenticated Access, Privilege Escalation.
Description – what was found and why it is dangerous.
Remediation – specific steps to fix the issue.
Evidence – details like open ports, response snippets, or extracted tokens.

Below is an example JSON snippet from a real scan (abbreviated for clarity):

{
  "node": "192.168.1.101",
  "service": "Kubelet",
  "category": "Unauthenticated Access",
  "vulnerability": "Kubelet anonymous authentication enabled",
  "severity": "high",
  "description": "The Kubelet is allowing anonymous access, which allows an attacker to control pods and nodes.",
  "remediation": "Disable anonymous authentication by setting --anonymous-auth=false on the Kubelet.",
  "evidence": "HTTP/1.1 200 OK ... pods list returned"
}

Common findings and their immediate fixes:

Anonymous access to API server – Ensure RBAC is enabled and that --anonymous-auth=false is set on the API server.
Kubelet anonymous authentication – Start the Kubelet with --anonymous-auth=false and enforce authentication via --authorization-mode=Webhook.
Exposed etcd without authentication – Enable client certificate authentication and place etcd behind a firewall, never exposing it externally.
Privileged containers running – Audit pod security policies or Pod Security Admission to forbid privileged containers unless strictly necessary.
Service account token mounted unnecessarily – Use automountServiceAccountToken: false in pod specs when no API access is needed.
Dashboard exposed with skip-login – Never expose the dashboard to the internet; use an authentication proxy and disable --enable-skip-login.

After fixing issues, always run a follow-up scan to confirm that vulnerabilities have been resolved. Iterate until the report shows only accepted risks or informational items.

Best Practices for Production Environments

Integrating Kube-hunter into your development and operations workflow requires a careful approach to avoid disruption and ensure actionable results. Follow these best practices:

Run passive scans in production – Always use --passive when scanning production clusters. Active exploitation tests could inadvertently cause denial of service or break fragile workloads.
Schedule regular internal scans – Deploy kube-hunter as a CronJob inside the cluster (with appropriate RBAC permissions) to continuously detect drift. A weekly scan is a good starting point.
Combine remote and internal perspectives – Run remote scans from a dedicated CI stage that simulates an external attacker, and internal scans from within the cluster. Each reveals different weaknesses.
Integrate reports into SIEM or dashboards – Parse the JSON output and feed findings into Elasticsearch, Grafana, or your security information and event management system. Track high‑severity findings over time to measure improvement.
Define an exception process – Not all findings are critical. Some may be accepted risks (e.g., a test environment with deliberately open Kubelet for debugging). Document exceptions and filter them using --exclude-hunters or post‑processing scripts.
Test in staging first – Before running any active scan in production, validate the impact in a staging cluster that mirrors production. This helps avoid surprises.
Keep Kube-hunter updated – The tool evolves as new Kubernetes vulnerabilities are discovered. Use the latest image and watch for new hunters in release notes.
Combine with other tools – Kube-hunter is excellent for live misconfiguration testing, but complement it with static analysis (e.g., kube-bench for CIS benchmarks) and admission controllers (OPA, Kyverno) for prevention.

Automation Example: CI/CD Integration

A powerful pattern is to run a remote passive scan against a freshly deployed staging cluster in your CI pipeline. Below is a simplified GitLab CI snippet that executes kube-hunter and fails the pipeline if high‑severity vulnerabilities are found:

kube-hunter-scan:
  image: aquasec/kube-hunter:latest
  stage: security-testing
  script:
    - kube-hunter --kube-hunter-mode remote --remote ${STAGING_API_IP}:6443 --passive --report json --output scan.json
    - |
      HIGH_COUNT=$(jq '[.[] | select(.severity == "high")] | length' scan.json)
      if [ "$HIGH_COUNT" -gt 0 ]; then
        echo "Found $HIGH_COUNT high-severity vulnerabilities. Pipeline halted."
        exit 1
      fi
      echo "No high-severity findings. Scan passed."
  artifacts:
    paths:
      - scan.json

This approach ensures that any high-risk configuration is caught before production rollout, shifting security left.

Conclusion

Kube-hunter is an essential tool in any Kubernetes security toolbox. By simulating realistic attack paths, it uncovers dangerous misconfigurations that static checks alone cannot find. Its flexibility — supporting remote, internal, passive, and active modes — allows teams to tailor assessments precisely to their environment and risk tolerance. Combined with regular scheduling, CI integration, and a disciplined remediation process, Kube-hunter helps maintain a strong security posture as your clusters grow and evolve. Start with a passive remote scan today, fix the findings, and then embed continuous scanning into your workflow to make Kubernetes hardening a routine, not a crisis.