k8s-security-agent 0.2.0

Agentic Kubernetes security scanner powered by an LLM

k8s-security-agent

An agentic Kubernetes security scanner powered by an LLM. Connect it to any cluster and chat with it to find misconfigurations, RBAC issues, exposed secrets, and more.

Prerequisites

• Python 3.11+
• uv
• A running Kubernetes cluster reachable via your kubeconfig (any flavor: EKS, GKE, AKS, kind, k3d, minikube, Docker Desktop, etc.)
• An API key for one of the supported LLM providers

Don't have a cluster handy? See Optional: spin up a local cluster with k3d below.

Supported LLM Providers

Provider	Example Model	Free Tier	Get API Key
Groq	llama-3.3-70b-versatile	Yes	console.groq.com
Mistral	mistral-large-latest	Yes	console.mistral.ai
Gemini	gemini-2.0-flash	Yes	aistudio.google.com
Anthropic	claude-sonnet-4-6	$5 credit	console.anthropic.com

Installation

Install the CLI globally with uv (recommended) or pipx:

uv tool install k8s-security-agent

pipx install k8s-security-agent

This puts a k8s-security-agent command on your PATH.

From source (for development)

git clone https://github.com/JOSHUAJEBARAJ/k8-security-agent
cd k8-security-agent
uv sync

Configure the LLM

The agent reads three required env vars: LLM_PROVIDER, LLM_MODEL, and the API key for the chosen provider. If any are missing the agent will exit with an error telling you what to set.

Export them in your shell:

export LLM_PROVIDER=mistral
export LLM_MODEL=mistral-large-latest
export MISTRAL_API_KEY=your_mistral_api_key_here

Or, if running from source, copy .env.example to .env and fill it in:

cp .env.example .env

# .env
LLM_PROVIDER=mistral
LLM_MODEL=mistral-large-latest
MISTRAL_API_KEY=your_mistral_api_key_here

.env is only loaded when you run from a checkout of this repo. If you installed the package globally, export the vars in your shell (or your shell rc) instead.

Switching providers or models — change LLM_PROVIDER and LLM_MODEL (and the matching API key). No code changes needed.

The agent relies on tool/function calling, so any model you pick must support it. Most "instruct" or "chat" flagship models do; small/older models often don't.

Optional: spin up a local cluster with k3d

If you don't already have a cluster, k3d is the quickest way to get one running locally (requires Docker).

# Install k3d
brew install k3d

# Create a cluster
k3d cluster create k8s-security-test --agents 2

# Verify it's running
kubectl get nodes

Any other local option works just as well — kind, minikube, or Docker Desktop's built-in Kubernetes. The agent only needs kubectl to be able to reach the cluster.

Running the agent

If you installed via uv tool or pipx:

k8s-security-agent

If you're running from a source checkout:

uv run k8s-security-agent

Usage

Just type naturally — the agent decides which checks to run based on your question.

you> run a full security audit
you> what pods are running in the default namespace?
you> scan the nginx pod for vulnerabilities
you> show me all RBAC issues
you> are there any privileged containers?
you> list all namespaces

Type exit or press Ctrl+C to quit.

Deploying a vulnerable workload for testing

A sample deployment with intentional misconfigurations is included:

kubectl apply -f sample-deployment.yaml

Then ask the agent to scan it:

you> scan the vulnerable-app pod for security issues

To clean up:

kubectl delete -f sample-deployment.yaml

Security checks

Check	What it detects
privileged	Privileged containers, allowPrivilegeEscalation
rbac	cluster-admin bindings, wildcard role grants
secrets	Hardcoded secrets in env vars
network	Namespaces missing NetworkPolicy
resources	Containers with no CPU/memory limits
apparmor	Missing AppArmor profile annotations
automount	Default SA with auto-mounted tokens
capabilities	Missing capability drops, dangerous adds
hostns	hostNetwork, hostPID, hostIPC enabled
image	Unpinned or latest image tags
mounts	Sensitive host path mounts
nonroot	Missing runAsNonRoot
rootfs	readOnlyRootFilesystem not set
seccomp	Missing seccomp profile