The Complete Production SOP: How to Deploy and Run KubeLinter Kubernetes YAML & Helm Security Checks in Autonomous AI Agents
Step-by-step SOP to install and run KubeLinter Kubernetes YAML & Helm Security Checks in Codex, Claude Code, and Cursor. Includes verified prompts and fixes.
Technical Overview & Architectural Context
Autonomous coding agents frequently generate Kubernetes manifests that lack production-grade hardening. When prompted to generate Deployments, StatefulSets, or Helm templates, LLMs commonly omit container resource limits, permit privileged execution contexts, allow root filesystem mutation, and retain default ServiceAccount token automounting. These oversights introduce severe vulnerabilities, including container escape vectors, unconstrained node-level memory exhaustion, and lateral cluster privilege escalation. The 'kube-linter-k8s-manifest-audit' skill injects deterministic procedural rules and explicit security guardrails into autonomous agents such as Codex, Claude Code, Cursor, and Windsurf. By constraining the agent to enforce static KubeLinter checks before finalizing changes, this skill ensures that security policies—such as readOnlyRootFilesystem enforcement, emptyDir volume creation for temporary state, and automountServiceAccountToken disabling—are applied systematically rather than left to probabilistic LLM generation.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Skill Mounting & Runtime Directory Registration
Create the local skill manifest directory and inject verified procedural rules into your agent's configuration root.
Autonomous runtimes read SKILL.md manifests from system or project-level agent directories. Mount the skill file directly into the designated discovery path for Claude Code or Codex. The agent parses the frontmatter metadata—including triggers, file system constraints, and sandboxing flags—to register deterministic triggers like 'run kubelinter on manifests' and 'audit helm chart kubelinter'.
mkdir -p ~/.agents/skills/kube-linter-k8s-manifest-audit && cat << 'EOF' > ~/.agents/skills/kube-linter-k8s-manifest-audit/SKILL.md
---
name: "kube-linter-k8s-manifest-audit"
description: "Enforce production readiness and security guardrails on Kubernetes YAML and Helm charts."
metadata:
author: "StackRox / Red Hat"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "run kubelinter on manifests"
- "fix kubernetes pod security kubelinter"
- "audit helm chart kubelinter"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---
# KubeLinter Kubernetes YAML & Helm Security Checks
Scans Kubernetes resources with KubeLinter: detecting privileged containers, missing resource limits, writable root filesystems, sensitive volume mounts, and default service account abuse.
## When to Invoke
Invoke this skill whenever you need to:
- run kubelinter on manifests
- fix kubernetes pod security kubelinter
- audit helm chart kubelinter
## Execution SOP & Rules
1. Execute kube-linter lint manifests/ or kube-linter lint ./helm-chart in CI pipelines.
2. Ensure all containers specify cpu and memory limits to prevent cluster resource starvation.
3. Set readOnlyRootFilesystem: true and mount an emptyDir volume for writable temporary files.
4. Set automountServiceAccountToken: false on pods that do not require Kubernetes API access.
## Verification Checklist
- Run local linting, syntax validation, and type-checks before reporting completion.
- Ensure all created or modified files adhere to workspace boundaries and avoid uncommitted secrets.
- Verify tests or build commands exit cleanly with return code 0.
EOF---
name: "kube-linter-k8s-manifest-audit"
description: "Enforce production readiness and security guardrails on Kubernetes YAML and Helm charts."
metadata:
author: "StackRox / Red Hat"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "run kubelinter on manifests"
- "fix kubernetes pod security kubelinter"
- "audit helm chart kubelinter"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---Keep the runtime skill definition slim by avoiding embedded binary binaries or excessive linting rule documentation; KubeLinter's built-in check IDs are directly referenced by modern models.
Ensure directory permissions match your local agent execution user. In Cursor or Windsurf, confirm that global skill paths are included in workspace context settings.
Local Binary Validation & Workspace Linter Config Setup
Verify local KubeLinter availability and provision a declarative .kube-linter.yaml configuration.
Autonomous agents require the local CLI tool to validate changes against production baselines. Verify the binary exists and provide an in-repo configuration file (.kube-linter.yaml) to ensure deterministic rule evaluations across local agent interactions and continuous integration pipelines.
which kube-linter || (echo 'Installing kube-linter...' && go install golang.stackrox.io/kube-linter/cmd/kube-linter@latest)
cat << 'EOF' > .kube-linter.yaml
customChecks: []
checks:
addAllBuiltIn: true
exclude: []
EOFcustomChecks: []
checks:
addAllBuiltIn: true
exclude:
# Exclude checks here only if explicitly justified
- "unset-cpu-requirements" # Example override if unmetered namespace is usedExplicitly commiting a .kube-linter.yaml file into the root of the target repository prevents agents from guessing check names or altering severity thresholds during execution.
Do not execute KubeLinter inside containerized agent sandboxes without mounting the host binary or supplying a pre-baked Docker image containing both Helm and KubeLinter.
Intent Matching & Trigger Invocation
Engage the skill using frontmatter-matched triggers within the agent workspace context.
Provide the agent with explicit natural language instructions matching the triggers defined in the SKILL.md. This prompts the runtime to prioritize the security SOP over standard permissive code generation.
claude 'audit helm chart kubelinter in ./charts/ingress-gateway and fix any security check violations'Include the target path explicitly in the trigger invocation so the agent does not recurse through node_modules or unrelated directories.
Agents may attempt to disable failing checks in .kube-linter.yaml instead of repairing the manifest. The SOP strictly enforces fixing the resource definition directly.
Verification, Linting & Output Quality Gate
Execute automated self-healing checks and verify exit code 0 before accepting agent deliverables.
Before completing the request, require the agent to run the lint validation step directly. For Helm charts, the agent must run 'helm template' into 'kube-linter lint -' or use KubeLinter's native Helm support to confirm zero violations.
kube-linter lint manifests/ --config .kube-linter.yaml && helm template ./charts/ingress-gateway | kube-linter lint -Ensure git status checks reveal clean modifications only on security-context and resource blocks, avoiding unintended whitespace drift.
Helm template errors can mask KubeLinter failures if pipelines pipe stderr. Ensure standard error is not redirected to /dev/null during evaluation.
Real-World Scenario: Hardening a Legacy Payment Gateway Deployment and Helm Template
“We have an insecure payment gateway manifest in deploy/payment-service.yaml that triggers multiple warnings. Run kubelinter on manifests, fix kubernetes pod security kubelinter issues, and ensure production readiness.”
Runtime Troubleshooting & Failure Modes
Root Cause: The agent set securityContext on the PodSpec level rather than inside the specific ContainerSpec, or omitted emptyDir mounts for scratch directories.
containers:
- name: payment-api
image: payment-api:v1.2.0
securityContext:
readOnlyRootFilesystem: true
volumeMounts:
- mountPath: /tmp
name: tmp-volume
volumes:
- name: tmp-volume
emptyDir: {}Root Cause: KubeLinter invoked directly on a raw Helm chart directory that requires default or test values during template synthesis.
helm template payment-chart ./charts/payment-service --values ./charts/payment-service/values.yaml | kube-linter lint -Frequently Asked Questions (KubeLinter Kubernetes YAML & Helm Security Checks SOP)
Q:Can I use KubeLinter Kubernetes YAML & Helm Security Checks across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill conforms to the universal SKILL.md specification. Once installed under your shared skill directory (~/.agents/skills) or workspace root, Codex, Claude Code, Cursor, and Windsurf can read the triggers and follow the deterministic SOP.
Q:How does KubeLinter Kubernetes YAML & Helm Security Checks prevent context window overflow during long agent sessions?
The skill provides focused, deterministic procedural rules (such as specifying explicit resources, readOnlyRootFilesystem, and automountServiceAccountToken) rather than dumping large Kubernetes API schemas into the context window. It delegates rule evaluation to the local KubeLinter CLI binary.
Q:Does this skill require escalated root or container permissions?
No. The skill is audited with a security score of 98/100. It requires read-only manifest inspection and local workspace file editing permissions, without requiring cluster-admin privileges, root access, or inbound/outbound network connectivity.
Ready to equip your autonomous agent with KubeLinter Kubernetes YAML & Helm Security Checks?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.