What it does. Scores Kubernetes resource manifests with Kubesec to flag misconfiguration and privilege-escalation risk before deployment, mapping each finding back to the securityContext change that fixes it. Use when gating manifests in CI, reviewing YAML or a rendered chart before it reaches a cluster, or explaining why a manifest scored negatively. Keywords: Kubesec, manifest score, securityContext, readOnlyRootFilesystem, runAsNonRoot, CI gate. Do not use for scanning built images for CVEs - use scanning-docker-images-with-trivy; for admission-time enforcement use implementing-opa-gatekeeper-for-policy-enforcement. Part of mukul975/Anthropic-Cybersecurity-Skills (817 security skills) (mukul975/Anthropic-Cybersecurity-Skills).
Install
npx skills add mukul975/Anthropic-Cybersecurity-Skills --skill scanning-kubernetes-manifests-with-kubesec, or copy the skill folder into ~/.claude/skills/scanning-kubernetes-manifests-with-kubesec/.- Raw file:
curl -sL https://raw.githubusercontent.com/mukul975/Anthropic-Cybersecurity-Skills/HEAD/skills/scanning-kubernetes-manifests-with-kubesec/SKILL.md
SKILL.md (verbatim)
name: scanning-kubernetes-manifests-with-kubesec
description: >-
Scores Kubernetes resource manifests with Kubesec to flag misconfiguration and
privilege-escalation risk before deployment, mapping each finding back to the
securityContext change that fixes it. Use when gating manifests in CI, reviewing YAML or a
rendered chart before it reaches a cluster, or explaining why a manifest scored negatively.
Keywords: Kubesec, manifest score, securityContext, readOnlyRootFilesystem, runAsNonRoot, CI
gate. Do not use for scanning built images for CVEs - use scanning-docker-images-with-trivy;
for admission-time enforcement use implementing-opa-gatekeeper-for-policy-enforcement.
domain: cybersecurity
subdomain: container-security
tags:
- kubesec
- kubernetes
- manifest-scanning
- security-scanning
- devsecops
- misconfiguration
- static-analysis
- ci-cd
version: '1.0'
author: mahipal
license: Apache-2.0
nist_csf:
- PR.PS-01
- PR.IR-01
- ID.AM-08
- DE.CM-01
mitre_attack:
- T1610
- T1611
- T1609
- T1525
- T1068
Scanning Kubernetes Manifests with Kubesec
Overview
Kubesec is an open-source security risk analysis tool developed by ControlPlane that inspects Kubernetes resource manifests for common exploitable risks such as privilege escalation, writable host mounts, and excessive capabilities. It assigns a numerical security score to each resource and provides actionable recommendations for hardening. Kubesec can be used as a CLI binary, Docker container, kubectl plugin, admission webhook, or REST API endpoint.
When to Use
- When conducting security assessments that involve scanning kubernetes manifests with kubesec
- When following incident response procedures for related security events
- When performing scheduled security testing or auditing activities
- When validating security controls through hands-on testing
Prerequisites
- Kubernetes manifest files (YAML/JSON) for Deployments, Pods, DaemonSets, StatefulSets
- Docker or Go runtime for local installation
- kubectl access for scanning live cluster resources
- CI/CD pipeline access for automated scanning integration
Core Concepts
Security Scoring System
Kubesec assigns a score to each Kubernetes resource based on security checks:
- Positive scores: Awarded for security-enhancing configurations (readOnlyRootFilesystem, runAsNonRoot)
- Zero or negative scores: Indicate missing security controls or dangerous configurations
- Critical advisories: Flagged configurations that represent immediate security risks
Check Categories
- Privilege Controls: Checks for privileged containers, host PID/network access, root execution
- Capabilities: Identifies excessive Linux capabilities (SYS_ADMIN, NET_RAW)
- Volume Mounts: Detects dangerous host path mounts and writable sensitive paths
- Resource Limits: Validates presence of CPU/memory resource constraints
- Security Context: Verifies seccomp profiles, AppArmor annotations, SELinux contexts
Installation
Binary Installation
# Linux/macOS
curl -sSL https://github.com/controlplaneio/kubesec/releases/latest/download/kubesec_linux_amd64.tar.gz | \
tar xz -C /usr/local/bin/ kubesec
# Verify installation
kubesec version
Docker Installation
docker pull kubesec/kubesec:v2
# Scan a manifest file
docker run -i kubesec/kubesec:v2 scan /dev/stdin < deployment.yaml
kubectl Plugin
kubectl krew install kubesec-scan
kubectl kubesec-scan pod mypod -n default
Practical Scanning
Scanning a Single Manifest
# Scan a deployment manifest
kubesec scan deployment.yaml
# Scan with JSON output
kubesec scan -o json deployment.yaml
# Scan from stdin
cat pod.yaml | kubesec scan -
Sample Output
[
{
"object": "Pod/web-app.default",
"valid": true,
"fileName": "pod.yaml",
"message": "Passed with a score of 3 points",
"score": 3,
"scoring": {
"passed": [
{
"id": "ReadOnlyRootFilesystem",
"selector": "containers[] .securityContext .readOnlyRootFilesystem == true",
"reason": "An immutable root filesystem prevents applications from writing to their local disk",
"points": 1
},
{
"id": "RunAsNonRoot",
"selector": "containers[] .securityContext .runAsNonRoot == true",
"reason": "Force the running image to run as a non-root user",
"points": 1
},
{
"id": "LimitsCPU",
"selector": "containers[] .resources .limits .cpu",
"reason": "Enforcing CPU limits prevents DOS via resource exhaustion",
"points": 1
}
],
"advise": [
{
"id": "ApparmorAny",
"selector": "metadata .annotations .\"container.apparmor.security.beta.kubernetes.io/nginx\"",
"reason": "Well defined AppArmor policies reduce the attack surface of the container",
"points": 3
},
{
"id": "ServiceAccountName",
"selector": ".spec .serviceAccountName",
"reason": "Service accounts restrict Kubernetes API access and should be configured",
"points": 3
}
]
}
}
]
Scanning Multiple Resources
# Scan all YAML files in a directory
for file in manifests/*.yaml; do
echo "=== Scanning $file ==="
kubesec scan "$file"
done
# Scan multi-document YAML
kubesec scan multi-resource.yaml
Using the HTTP API
# Scan via the public API
curl -sSX POST --data-binary @deployment.yaml \
https://v2.kubesec.io/scan
# Run a local API server
kubesec http --port 8080 &
# Scan against local server
curl -sSX POST --data-binary @deployment.yaml \
http://localhost:8080/scan
CI/CD Integration
GitHub Actions
name: Kubesec Scan
on: [pull_request]
jobs:
kubesec:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Kubesec
run: |
curl -sSL https://github.com/controlplaneio/kubesec/releases/latest/download/kubesec_linux_amd64.tar.gz | \
tar xz -C /usr/local/bin/ kubesec
- name: Scan Manifests
run: |
FAIL=0
for file in k8s/*.yaml; do
SCORE=$(kubesec scan "$file" | jq '.[0].score')
echo "$file: score=$SCORE"
if [ "$SCORE" -lt 0 ]; then
echo "FAIL: $file has critical issues (score: $SCORE)"
FAIL=1
fi
done
exit $FAIL
GitLab CI
kubesec-scan:
stage: security
image: kubesec/kubesec:v2
script:
- |
for file in k8s/*.yaml; do
kubesec scan "$file" > /tmp/result.json
SCORE=$(cat /tmp/result.json | jq '.[0].score')
if [ "$SCORE" -lt 0 ]; then
echo "CRITICAL: $file scored $SCORE"
cat /tmp/result.json | jq '.[0].scoring.critical'
exit 1
fi
done
artifacts:
paths:
- kubesec-results/
Admission Webhook
Deploy Kubesec as a ValidatingWebhookConfiguration to reject insecure manifests at deploy time:
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
name: kubesec-webhook
webhooks:
- name: kubesec.controlplane.io
rules:
- apiGroups: [""]
apiVersions: ["v1"]
operations: ["CREATE", "UPDATE"]
resources: ["pods"]
- apiGroups: ["apps"]
apiVersions: ["v1"]
operations: ["CREATE", "UPDATE"]
resources: ["deployments", "daemonsets", "statefulsets"]
clientConfig:
service:
name: kubesec-webhook
namespace: kube-system
path: /scan
failurePolicy: Fail
sideEffects: None
admissionReviewVersions: ["v1"]
Security Checks Reference
Critical Checks (Negative Score)
| Check |
Selector |
Risk |
| Privileged |
securityContext.privileged == true |
Full host access |
| HostPID |
spec.hostPID == true |
Process namespace escape |
| HostNetwork |
spec.hostNetwork == true |
Network namespace escape |
| SYS_ADMIN |
capabilities.add contains SYS_ADMIN |
Near-root capability |
Best Practice Checks (Positive Score)
| Check |
Points |
Description |
| ReadOnlyRootFilesystem |
+1 |
Prevents filesystem writes |
| RunAsNonRoot |
+1 |
Non-root process execution |
| RunAsUser > 10000 |
+1 |
High UID reduces collision risk |
| LimitsCPU |
+1 |
Prevents CPU resource exhaustion |
| LimitsMemory |
+1 |
Prevents memory resource exhaustion |
| RequestsCPU |
+1 |
Ensures scheduler resource awareness |
| ServiceAccountName |
+3 |
Explicit service account |
| AppArmor annotation |
+3 |
Kernel-level MAC enforcement |
| Seccomp profile |
+4 |
Syscall filtering |
References
Other files in this skill
assets/template.md (verbatim)
Kubesec Manifest Scanning Assessment Template
Scan Configuration
| Field |
Value |
| Scan Date |
|
| Kubesec Version |
|
| Manifests Scanned |
|
| Minimum Score Threshold |
|
| Scan Mode (CLI/API/Webhook) |
|
| Assessed By |
|
Scan Results Summary
| Metric |
Value |
| Total Resources Scanned |
|
| Critical Findings (score < 0) |
|
| Warnings (score < 5) |
|
| Passed (score >= 5) |
|
| Average Score |
|
Critical Findings
| Resource |
File |
Score |
Critical Check |
Remediation |
|
|
|
|
|
| # |
Check ID |
Affected Resources |
Points Gain |
Effort |
| 1 |
|
|
|
|
| 2 |
|
|
|
|
| 3 |
|
|
|
|
CI/CD Gate Configuration
Sign-Off
| Role |
Name |
Date |
| Security Engineer |
|
|
| DevOps Lead |
|
|
references/api-reference.md (verbatim)
API Reference: Scanning Kubernetes Manifests with Kubesec
Kubesec CLI Commands
| Command |
Description |
kubesec scan <file> |
Scan a manifest file |
kubesec scan -o json <file> |
JSON output |
kubesec http --port 8080 |
Start local API server |
kubesec version |
Show version info |
Kubesec HTTP API
| Method |
Endpoint |
Description |
| POST |
https://v2.kubesec.io/scan |
Public scan API |
| POST |
http://localhost:8080/scan |
Local scan API |
Critical Checks (Negative Score)
| Check |
Selector |
Risk |
| Privileged |
securityContext.privileged == true |
Full host access |
| HostPID |
spec.hostPID == true |
Process namespace escape |
| HostNetwork |
spec.hostNetwork == true |
Network namespace escape |
| SYS_ADMIN |
capabilities.add contains SYS_ADMIN |
Near-root capability |
Best Practice Checks (Positive Score)
| Check |
Points |
Description |
| ReadOnlyRootFilesystem |
+1 |
Prevents filesystem writes |
| RunAsNonRoot |
+1 |
Non-root execution |
| RunAsUser > 10000 |
+1 |
High UID |
| LimitsCPU |
+1 |
CPU limits set |
| LimitsMemory |
+1 |
Memory limits set |
| ServiceAccountName |
+3 |
Explicit service account |
| AppArmor annotation |
+3 |
MAC enforcement |
| Seccomp profile |
+4 |
Syscall filtering |
Python Libraries
| Library |
Version |
Purpose |
subprocess |
stdlib |
Execute kubesec CLI |
requests |
>=2.28 |
HTTP API fallback |
json |
stdlib |
Parse scan results |
References
references/standards.md (verbatim)
Standards and References - Kubesec Manifest Scanning
Industry Standards
CIS Kubernetes Benchmark v1.9
- Section 5.2: Pod Security Standards -- Kubesec validates privileged mode, host namespaces
- Section 5.7: General Policies -- Service account configuration, resource limits
- Maps directly to kubesec scoring checks for container security contexts
NIST SP 800-190: Application Container Security Guide
- Section 3.1: Image vulnerabilities and configuration defects
- Section 3.4: Orchestrator security -- manifest validation before deployment
- Section 4.1: Countermeasures for image vulnerabilities
Kubernetes Pod Security Standards (PSS)
- Privileged: No restrictions (kubesec score = lowest)
- Baseline: Prevents known privilege escalation (kubesec validates hostPID, hostNetwork, privileged)
- Restricted: Best practices enforcement (kubesec validates all recommended controls)
Compliance Mapping
| Kubesec Check |
CIS Control |
NIST 800-190 |
PCI DSS |
| Privileged containers |
5.2.1 |
3.4.4 |
2.2 |
| Host PID namespace |
5.2.2 |
3.4.2 |
2.2 |
| Host network |
5.2.4 |
3.4.3 |
1.3 |
| Root execution |
5.2.6 |
3.4.1 |
7.1 |
| ReadOnlyRootFilesystem |
5.2.8 |
4.1.2 |
2.2 |
| Resource limits |
5.4.1 |
4.3.1 |
2.2 |
| Service accounts |
5.1.5 |
3.4.5 |
7.2 |
- Kubescape: NSA/CISA framework compliance scanning
- Checkov: Infrastructure-as-code security scanning (covers Kubernetes)
- Datree: Policy enforcement with custom rules
- OPA/Gatekeeper: Runtime policy enforcement as admission controller
Integration Points
- Pre-commit hooks for developer feedback
- CI/CD pipeline gates to prevent insecure deployments
- Admission webhooks for runtime enforcement
- IDE plugins for shift-left security
references/workflows.md (verbatim)
Workflows - Kubesec Manifest Scanning
Scanning Workflow
Pre-Commit Scanning
- Developer writes Kubernetes manifest locally
- Pre-commit hook runs
kubesec scan on changed YAML files
- If score < 0 (critical issues), commit is blocked with remediation guidance
- Developer fixes issues and retries commit
CI/CD Pipeline Integration
- Pull request created with manifest changes
- CI job runs kubesec scan on all manifests in PR
- Results posted as PR comment with score breakdown
- Gate: PR blocked if any manifest scores below threshold
- Merge allowed only after all manifests pass minimum score
Admission Control
- Developer applies manifest via kubectl or GitOps
- ValidatingWebhook intercepts the API request
- Kubesec webhook scans the manifest in real-time
- If critical issues found, admission is denied with explanation
- Clean manifests are admitted to the cluster
Scoring Improvement Process
1. Run kubesec scan on target manifest
2. Review "advise" section for point-earning improvements
3. Review "critical" section for must-fix issues
4. Apply fixes in priority order:
a. Remove critical issues (privileged, hostPID, hostNetwork)
b. Add seccomp profile (+4 points)
c. Add AppArmor annotation (+3 points)
d. Set readOnlyRootFilesystem (+1 point)
e. Set runAsNonRoot (+1 point)
f. Add resource limits (+1 point each)
5. Re-scan to verify improved score
6. Commit and push hardened manifest
Continuous Monitoring Workflow
Scheduled Cluster Scanning
- CronJob runs daily scan of all deployed resources
- Extracts manifests from live cluster:
kubectl get deploy -o yaml
- Runs kubesec scan on each resource
- Compares scores against previous scan results
- Alerts on score regressions or new critical findings
- Generates weekly security posture report
Score Trending
Week 1: Average score 2.3 (baseline)
Week 2: Average score 3.1 (+0.8 improvement)
Week 3: Average score 4.5 (+1.4 improvement)
Week 4: Average score 5.2 (+0.7 improvement -- target: 6.0)
Back to mukul975/Anthropic-Cybersecurity-Skills (817 security skills) or Agent skills.