Kube Audit Kit

Kube Audit Kit - Read-Only Kubernetes Security Audit Toolkit

This Skill uses a standardized, scripted workflow to export Kubernetes cluster resources in read-only mode, sanitize them, group applications, and perform a deep security audit. The entire process strictly follows the read-only principle and does not modify any cluster state.

Core Principles

• Read-only: only get/list operations, never apply/patch/delete
• Full coverage: dynamically discover all resource types without hardcoding lists
• Scripted: core logic runs through Python scripts for stability

Quick Start

Prerequisites

1. Environment setup:

   uv sync
   

   See SETUP.md for details.

2. Verify kubectl:

   kubectl config get-contexts
   

Run an audit

When a user requests an audit, follow these steps strictly:

Set the output directory first (important!):

# Set the output directory to output/ under the current working directory
# This ensures output files are generated in the user's working directory, not the SKILL install directory
export KUBE_AUDIT_OUTPUT="$(pwd)/output"

Use the progress checklist:

Audit progress:
- [ ] Step 1: Export - Dynamic discovery and full resource export
- [ ] Step 2: Sanitize - Remove metadata and status fields
- [ ] Step 3: Group - Associate applications by workload topology
- [ ] Step 4: Audit - Dual-layer security audit

Step 1: Export

# Keep the environment variable effective for each command
export KUBE_AUDIT_OUTPUT="$(pwd)/output" && \
uv run python scripts/export.py --context <context> --namespace <namespace>

Output: {OUTPUT_BASE}/export/

Step 2: Sanitize

export KUBE_AUDIT_OUTPUT="$(pwd)/output" && \
uv run python scripts/sanitize.py --context <context> --namespace <namespace>

Output: {OUTPUT_BASE}/sanitize/, {OUTPUT_BASE}/sanitize_fields/

Step 3: Group

export KUBE_AUDIT_OUTPUT="$(pwd)/output" && \
uv run python scripts/group_apps.py --context <context> --namespace <namespace>

Output: {OUTPUT_BASE}/group/, {OUTPUT_BASE}/ungrouped_resources.txt

Step 4: Audit

Phase 1 - Script-based static scan:

export KUBE_AUDIT_OUTPUT="$(pwd)/output" && \
uv run python scripts/audit.py --context <context> --namespace <namespace>

Output:

• {OUTPUT_BASE}/audit/audit_results.json - structured audit results
• {OUTPUT_BASE}/audit/configmap_to_secret.csv - ConfigMap sensitive data
• {OUTPUT_BASE}/audit/secret_to_configmap.csv - Secret non-sensitive data
• {OUTPUT_BASE}/audit/rbac_issues.csv - RBAC audit results
• {OUTPUT_BASE}/audit/network_security.csv - network security audit results
• {OUTPUT_BASE}/audit/hostpath_mounts.csv - hostPath mount findings
• {OUTPUT_BASE}/audit/security_policies.csv - seccomp/AppArmor results
• {OUTPUT_BASE}/audit/pdb_and_secrets.csv - PDB/Secret/ServiceAccount results

Phase 2 - AI expert deep review:

AI independently reviews results without relying on phase 1 output:

1. Independent analysis: traverse {OUTPUT_BASE}/group/*/ and read all original YAML files
2. Deep review: identify risks not covered by script rules
   • business logic risks (e.g., plaintext private keys, hardcoded passwords)
   • architecture risks (e.g., missing NetworkPolicy, overly broad RBAC)
   • configuration drift risks (e.g., latest images, missing resource limits)
3. Supplement findings: if sensitive data was missed, append to the CSV files
4. Report summary: merge phase 1 findings with AI analysis into {OUTPUT_BASE}/audit/audit_report.md

Report template: see audit_report_template.md in the same directory.

Key requirements:

• Must read original YAML files, not just audit_results.json
• Every application must have specific analysis; avoid vague statements like "not reviewed"
• If script misses sensitive data, update the CSV files to keep data complete

Output Structure

output/{context}/{namespace}/
├── export/              # raw export data
├── sanitize/            # sanitized data
├── sanitize_fields/     # sanitization records
├── group/               # application grouping
│   └── {app_name}/
│       ├── *.yaml            # grouped resource files
│       └── config_usage.json # CM/Secret usage record
├── ungrouped_resources.txt   # orphan resources
└── audit/               # audit results
    ├── audit_results.json        # static analysis results
    ├── configmap_to_secret.csv   # sensitive data in ConfigMaps
    ├── secret_to_configmap.csv   # non-sensitive data in Secrets
    ├── rbac_issues.csv            # RBAC audit results
    ├── network_security.csv       # network security audit results
    ├── hostpath_mounts.csv        # hostPath mount findings
    ├── security_policies.csv      # seccomp/AppArmor results
    ├── pdb_and_secrets.csv        # PDB/Secret/ServiceAccount results
    └── audit_report.md           # final AI-generated report

Reference Docs

• QUICKSTART.md: 30-second quick start
• WORKFLOW.md: full workflow and implementation details
• SETUP.md: environment setup and dependency installation
• EXAMPLES.md: output examples and typical scenarios

User Interaction Conventions

Planning Phase

Received. Target: Context `{ctx}`, Namespace `{ns}`.

Execution plan:
1. Set the output directory environment variable: export KUBE_AUDIT_OUTPUT="$(pwd)/output"
2. [Export] Dynamic discovery and full resource export → scripts/export.py
3. [Sanitize] Remove metadata and status fields → scripts/sanitize.py
4. [Group] Associate applications by workload topology → scripts/group_apps.py
5. [Audit] Dual-layer security audit (static scan + AI expert review) → scripts/audit.py

Output directory: $(pwd)/output/{ctx}/{ns}/

Start?

Execution Phase

Output a summary after each step (each command must include the environment variable):

✅ [Export completed] Scanned 32 resource types, exported 150 YAMLs
   Output: output/{ctx}/{ns}/export/

Results Phase

✅ [Audit completed] Static report and AI expert analysis merged

📊 Audit stats:
- Applications: 12
- Critical risks: X (see audit_results.json)
- Warning risks: Y
- Info recommendations: Z

📁 Output directory: output/{ctx}/{ns}/
📄 Full audit report: output/{ctx}/{ns}/audit/audit_report.md

⚠️ Security reminder: the output/ directory contains decrypted Secret data. Please delete it securely after the audit!

Path Conventions

{OUTPUT_BASE} = output/{context}/{namespace}/

Output path mechanism

All paths are computed by get_output_paths() in scripts/utils.py, with the following precedence:

1. Environment variable KUBE_AUDIT_OUTPUT (recommended)

   • Set in SKILL.md before running: export KUBE_AUDIT_OUTPUT="$(pwd)/output"
   • Ensures output files are created in the user's working directory
   • Avoids writing to the SKILL installation directory

2. Current working directory (fallback)

   • If the environment variable is not set, use Path.cwd() / "output"
   • Note: when a SKILL runs, cwd may be the SKILL directory

Why the environment variable?

When the SKILL is invoked, the Agent switches to the SKILL installation directory to run scripts. Using Path.cwd() directly would write to the wrong location.

By setting KUBE_AUDIT_OUTPUT="$(pwd)/output" before each command, you ensure:

• $(pwd) resolves to the user's working directory
• Python scripts read the environment variable and write to the intended path
• Output always lands in the user's working directory, regardless of where the SKILL is called

Key Design Decisions

Volume vs EnvVar distinction

ConfigMaps/Secrets usage determines whether sensitive data is scanned:

• Volume mount: skip sensitive scanning (treated as application config files)
• EnvVar reference: scan for sensitive data (may include passwords/keys)

config_usage.json records the usage type for each ConfigMap/Secret.

Permission error handling

Scripts use a fault-tolerant approach:

• If a single resource type is denied, skip it and show a warning
• Other resource types continue normally
• The final report notes which checks are missing due to insufficient permissions

Use a dedicated audit service account (see SETUP.md).

Security Reminder

Warning: the output/ directory contains decrypted Secret data.

After the audit:

• Keep audit_report.md (it does not contain sensitive data)
• Securely delete other directories or store them encrypted
• Do not commit output/ to version control