From aef71663e473bb31d559018aec3746943a07cfcb Mon Sep 17 00:00:00 2001 From: Jordi Gil Date: Tue, 5 May 2026 13:47:13 -0400 Subject: [PATCH 1/7] feat(rh-developer): add debug-scc and debug-rbac skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add two new diagnostic skills backed by validated golden transcripts from Kubernaut demo scenarios: - debug-scc: Diagnoses SCC violations blocking pod creation — parses ReplicaSet FailedCreate events, identifies non-compliant securityContext fields (runAsUser, capabilities, allowPrivilegeEscalation), and checks ServiceAccount SCC bindings. - debug-rbac: Diagnoses RBAC permission failures causing 403 Forbidden errors — analyzes pod logs and readiness probes, identifies missing Role/RoleBinding for ServiceAccounts, and detects regression patterns where bindings are repeatedly removed. Both skills follow the existing debug-pod/debug-network pattern with human-in-the-loop checkpoints at each step. Update CLAUDE.md intent routing and skill chaining, and register both skills in .catalog/collection.yaml and collection.json. Co-authored-by: Cursor --- rh-developer/.catalog/collection.json | 22 +- rh-developer/.catalog/collection.yaml | 32 ++- rh-developer/CLAUDE.md | 4 + rh-developer/skills/debug-rbac/SKILL.md | 308 ++++++++++++++++++++++++ rh-developer/skills/debug-scc/SKILL.md | 301 +++++++++++++++++++++++ 5 files changed, 665 insertions(+), 2 deletions(-) create mode 100644 rh-developer/skills/debug-rbac/SKILL.md create mode 100644 rh-developer/skills/debug-scc/SKILL.md diff --git a/rh-developer/.catalog/collection.json b/rh-developer/.catalog/collection.json index 30d9585e..e8d972d4 100644 --- a/rh-developer/.catalog/collection.json +++ b/rh-developer/.catalog/collection.json @@ -10,7 +10,7 @@ "Automation" ], "contents": { - "description": "The pack provides 15 skills for developer workflows on OpenShift and RHEL, including two orchestration skills\nfor end-to-end containerize-and-deploy and structured incident investigation.\n", + "description": "The pack provides 17 skills for developer workflows on OpenShift and RHEL, including two orchestration skills\nfor end-to-end containerize-and-deploy and structured incident investigation.\n", "orchestration_skills": [ { "description": "End-to-end containerize and deploy", @@ -84,6 +84,16 @@ "name": "debug-container", "summary_markdown": "Diagnose Podman/Docker local container failures.\n**Use when:**\n- \"Container exits immediately locally\"\n- \"Cannot pull image locally\"\n**What it does:**\n- Inspects local container state and logs.\n- Complements OpenShift debug skills.\n" }, + { + "description": "OpenShift SCC violation diagnostics", + "name": "debug-scc", + "summary_markdown": "Diagnose Security Context Constraint violations blocking pod creation on OpenShift.\n**Use when:**\n- \"SCC violation\"\n- \"Pod blocked by security context constraint\"\n- \"FailedCreate forbidden\"\n**What it does:**\n- Parses SCC rejection messages from ReplicaSet events.\n- Identifies non-compliant securityContext fields (runAsUser, capabilities, privilege escalation).\n- Checks ServiceAccount SCC bindings and suggests targeted fixes.\n" + }, + { + "description": "OpenShift RBAC diagnostics", + "name": "debug-rbac", + "summary_markdown": "Diagnose RBAC permission failures causing 403 Forbidden errors on OpenShift.\n**Use when:**\n- \"RBAC denied\"\n- \"403 forbidden in pod logs\"\n- \"Missing RoleBinding\"\n**What it does:**\n- Analyzes pod logs for FORBIDDEN errors and readiness probe failures.\n- Identifies missing Role/RoleBinding for ServiceAccounts.\n- Detects regression patterns where bindings are repeatedly removed.\n" + }, { "description": "RHEL host diagnostics", "name": "debug-rhel", @@ -126,6 +136,16 @@ "skill_to_use": "incident-triage", "user_request": "\"Investigate this incident\" or \"root cause analysis\" or \"triage this alert\"" }, + { + "reason": "Parses SCC rejection messages and identifies non-compliant security context fields.", + "skill_to_use": "debug-scc", + "user_request": "\"SCC violation\" or \"pod blocked by security context\"" + }, + { + "reason": "Traces missing RoleBindings and ServiceAccount permissions.", + "skill_to_use": "debug-rbac", + "user_request": "\"RBAC denied\" or \"403 forbidden in pod logs\"" + }, { "reason": "Pre-flight before deploy or heavy debug.", "skill_to_use": "validate-environment", diff --git a/rh-developer/.catalog/collection.yaml b/rh-developer/.catalog/collection.yaml index f838e350..574d5bd8 100644 --- a/rh-developer/.catalog/collection.yaml +++ b/rh-developer/.catalog/collection.yaml @@ -23,7 +23,7 @@ summary: The rh-developer collection provides skills to detect projects, build i validate environments, and debug builds, pods, pipelines, networks, and hosts. contents: description: | - The pack provides 15 skills for developer workflows on OpenShift and RHEL, including two orchestration skills + The pack provides 17 skills for developer workflows on OpenShift and RHEL, including two orchestration skills for end-to-end containerize-and-deploy and structured incident investigation. skills: - name: detect-project @@ -148,6 +148,30 @@ contents: **What it does:** - Inspects local container state and logs. - Complements OpenShift debug skills. + - name: debug-scc + description: OpenShift SCC violation diagnostics + summary_markdown: | + Diagnose Security Context Constraint violations blocking pod creation on OpenShift. + **Use when:** + - "SCC violation" + - "Pod blocked by security context constraint" + - "FailedCreate forbidden" + **What it does:** + - Parses SCC rejection messages from ReplicaSet events. + - Identifies non-compliant securityContext fields (runAsUser, capabilities, privilege escalation). + - Checks ServiceAccount SCC bindings and suggests targeted fixes. + - name: debug-rbac + description: OpenShift RBAC diagnostics + summary_markdown: | + Diagnose RBAC permission failures causing 403 Forbidden errors on OpenShift. + **Use when:** + - "RBAC denied" + - "403 forbidden in pod logs" + - "Missing RoleBinding" + **What it does:** + - Analyzes pod logs for FORBIDDEN errors and readiness probe failures. + - Identifies missing Role/RoleBinding for ServiceAccounts. + - Detects regression patterns where bindings are repeatedly removed. - name: debug-rhel description: RHEL host diagnostics summary_markdown: | @@ -208,6 +232,12 @@ contents: - user_request: '"Investigate this incident" or "root cause analysis" or "triage this alert"' skill_to_use: incident-triage reason: Multi-resource investigation with Five Whys, guardrails, and due diligence. + - user_request: '"SCC violation" or "pod blocked by security context"' + skill_to_use: debug-scc + reason: Parses SCC rejection messages and identifies non-compliant security context fields. + - user_request: '"RBAC denied" or "403 forbidden in pod logs"' + skill_to_use: debug-rbac + reason: Traces missing RoleBindings and ServiceAccount permissions. - user_request: '"Check my tools" or "validate cluster access"' skill_to_use: validate-environment reason: Pre-flight before deploy or heavy debug. diff --git a/rh-developer/CLAUDE.md b/rh-developer/CLAUDE.md index 8a111786..55478f73 100644 --- a/rh-developer/CLAUDE.md +++ b/rh-developer/CLAUDE.md @@ -24,6 +24,8 @@ Match the user's request to the correct skill: | Build failure, BuildConfig error, S2I error, build logs, failed build | `/debug-build` | | Pod failure, CrashLoopBackOff, ImagePullBackOff, OOMKilled, Pending pod | `/debug-pod` | | Container issue, Podman/Docker failure, local container debug, container crash | `/debug-container` | +| SCC violation, pod blocked by SCC, security context constraint, FailedCreate forbidden | `/debug-scc` | +| RBAC denied, 403 forbidden, missing RoleBinding, ServiceAccount permission denied | `/debug-rbac` | | Network issue, DNS, Service connectivity, Route, NetworkPolicy, ingress | `/debug-network` | | Pipeline failure, Tekton, PipelineRun, TaskRun error, pipeline logs | `/debug-pipeline` | | RHEL issue, systemd, SELinux, firewall, journal logs, system service | `/debug-rhel` | @@ -43,6 +45,8 @@ Some workflows require multiple skills in sequence: - **Pre-flight check**: Run `/validate-environment` before any deployment skill - **Build failure recovery**: `/debug-build` -> fix -> `/s2i-build` retry - **Pod failure recovery**: `/debug-pod` or `/debug-network` -> fix -> `/deploy` retry +- **SCC violation recovery**: `/debug-scc` -> fix security context or grant SCC -> `/deploy` retry +- **RBAC failure recovery**: `/debug-rbac` -> create Role/RoleBinding -> verify pod readiness - **RHEL failure recovery**: `/debug-rhel` or `/debug-container` -> fix -> `/rhel-deploy` retry - **Incident triage**: `/incident-triage` -> identifies root cause -> routes to `/debug-pod`, `/debug-network`, or `/deploy` for targeted fix diff --git a/rh-developer/skills/debug-rbac/SKILL.md b/rh-developer/skills/debug-rbac/SKILL.md new file mode 100644 index 00000000..7999628c --- /dev/null +++ b/rh-developer/skills/debug-rbac/SKILL.md @@ -0,0 +1,308 @@ +--- +name: debug-rbac +description: | + Diagnose OpenShift RBAC permission failures that cause workloads to fail with 403 Forbidden errors when accessing the Kubernetes API. Automates multi-step diagnosis: pod logs for FORBIDDEN errors, readiness probe failures, ServiceAccount identification, RoleBinding/ClusterRoleBinding analysis, and remediation history for regression detection. Use this skill when pods are running but failing because their ServiceAccount lacks required API permissions. Triggers on /debug-rbac command or phrases like "RBAC denied", "403 forbidden", "pods can't list resources", "missing RoleBinding", "ServiceAccount permission denied". +model: inherit +color: cyan +metadata: + user_invocable: "true" +--- + +# /debug-rbac Skill + +Diagnose RBAC permission failures on OpenShift by analyzing pod logs, readiness probes, ServiceAccount bindings, and Role/RoleBinding configuration. + +## Overview + +``` +[Identify Deployment] → [Check Pod Status + Logs] → [Identify RBAC Errors] → [Analyze ServiceAccount] → [Check RoleBindings] → [Summary + Fix] +``` + +**This skill diagnoses:** +- Pods failing with 403 Forbidden errors against the Kubernetes API +- Readiness probes that check API access (`kubectl auth can-i`) returning "no" +- Missing or deleted RoleBindings/ClusterRoleBindings +- ServiceAccounts lacking required permissions (get, list, watch, create, etc.) +- Regression patterns where RBAC bindings are repeatedly removed + +## Prerequisites + +Before running this skill: +1. User is logged into an OpenShift cluster +2. User has access to the target namespace +3. Deployment or pod name is known (or can be identified from recent events) + +## Critical: Human-in-the-Loop Requirements + +See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. + +## When to Use This Skill + +Use `/debug-rbac` when a Deployment's pods are running but not ready, and pod logs show `FORBIDDEN` or `403` errors when calling the Kubernetes API. This typically manifests as readiness probe failures when the probe checks API access, or application-level errors when the workload needs to interact with Kubernetes resources. + +Do **not** use this skill when: +- Pods are blocked from being created entirely — use `/debug-scc` (SCC admission failures) +- Pods are crashing due to application bugs — use `/debug-pod` +- The issue is network connectivity — use `/debug-network` + +## Workflow + +### Step 1: Identify Target Deployment + +```markdown +## RBAC Debugging + +**Current OpenShift Context:** +- Cluster: [cluster] +- Namespace: [namespace] + +Which deployment would you like me to debug for RBAC issues? + +1. **Specify deployment name** - Enter the deployment name directly +2. **List deployments with issues** - Show deployments with unavailable or not-ready pods +3. **Search recent events** - Find pods with RBAC-related warning events + +Select an option or enter a deployment name: +``` + +**WAIT for user confirmation before proceeding.** + +If user selects "List deployments with issues": +Use kubernetes MCP `resources_list` for Deployments, filter to those with not-ready conditions: + +```markdown +## Deployments with Issues in [namespace] + +| Deployment | Available | Desired | Condition | +|------------|-----------|---------|-----------| +| [deploy-name] | 0 | 1 | MinimumReplicasUnavailable | + +Which deployment would you like me to debug? +``` + +**WAIT for user confirmation before proceeding.** + +### Step 2: Check Pod Status and Logs + +Use kubernetes MCP `pod_list` to find pods for the Deployment, then `resources_get` for pod details and `pod_logs` for container logs: + +```markdown +## Pod Analysis: [pod-name] + +**Pod Status:** +| Field | Value | +|-------|-------| +| Phase | Running | +| Ready | false | +| Conditions | ContainersNotReady | +| Restart Count | [count] | + +**Readiness Probe:** +| Field | Value | +|-------|-------| +| Type | [exec/httpGet/tcpSocket] | +| Command | [e.g., kubectl auth can-i list pods -n namespace] | +| Failure Count | [count] | +| Last Probe | [timestamp] | +| Message | [e.g., "probe returned: no"] | + +**Container Logs (last 50 lines):** + +[Highlight FORBIDDEN / 403 errors:] + +| Timestamp | Error | +|-----------|-------| +| [time] | FORBIDDEN: pods is forbidden: User "system:serviceaccount:[ns]:[sa]" cannot list resource "pods" in API group "" in namespace "[ns]" | +| [time] | FORBIDDEN: pods is forbidden... (repeated) | + +**Quick Assessment:** +[e.g., "Pod is running but readiness probe fails because the ServiceAccount cannot list pods. Logs confirm FORBIDDEN errors since [timestamp]."] + +Continue with ServiceAccount analysis? (yes/no) +``` + +**WAIT for user confirmation before proceeding.** + +### Step 3: Identify Required Permissions + +Based on the FORBIDDEN error messages and readiness probe command, determine what permissions are needed: + +```markdown +## Required Permissions Analysis + +**FORBIDDEN Errors Found:** +| Resource | Verb | API Group | Namespace | +|----------|------|-----------|-----------| +| pods | list | "" (core) | [namespace] | +| pods | get | "" (core) | [namespace] | +| [other resources from logs] | [verb] | [group] | [namespace] | + +**Readiness Probe Requires:** +| Permission | Currently Granted? | +|------------|-------------------| +| list pods in [namespace] | NO — probe returns "no" | + +**Application Function Requires:** +| Permission | Evidence | +|------------|----------| +| get pods in [namespace] | Container main loop calls `kubectl get pods` | +| [other] | [from log analysis] | + +**Minimum Role Needed:** +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: [sa-name]-role + namespace: [namespace] +rules: + - apiGroups: [""] + resources: ["pods"] + verbs: ["get", "list", "watch"] +``` + +Continue to check existing RoleBindings? (yes/no) +``` + +**WAIT for user confirmation before proceeding.** + +### Step 4: Analyze ServiceAccount and RoleBindings + +Use kubernetes MCP `resources_get` for the ServiceAccount, and `resources_list` for RoleBindings in the namespace: + +```markdown +## ServiceAccount & RoleBinding Analysis + +**ServiceAccount:** [sa-name] (namespace: [namespace]) +| Field | Value | +|-------|-------| +| Exists | Yes | +| Created | [timestamp] | +| Secrets | [count] | +| Image Pull Secrets | [count] | + +**RoleBindings in [namespace]:** +| RoleBinding | Role | Subjects | Grants Access? | +|-------------|------|----------|----------------| +| [binding-1] | [role-name] | [sa-1, sa-2] | [Yes/No — wrong SA] | +| [binding-2] | [role-name] | [sa-name] | [Missing — binding not found] | + +**ClusterRoleBindings (if accessible):** +| ClusterRoleBinding | ClusterRole | Subjects | Grants Access? | +|--------------------|-------------|----------|----------------| +| [binding] | [role] | [subjects] | [Yes/No] | + +[If listing RoleBindings is forbidden:] +**Note:** Agent lacks permission to list RoleBindings directly. Absence of the required binding is inferred from the FORBIDDEN errors in pod logs. + +**Assessment:** +[e.g., "No RoleBinding grants the metrics-collector ServiceAccount 'list pods' in demo-rbac. The binding was either never created, or was deleted."] + +Continue to diagnosis summary? (yes/no) +``` + +**WAIT for user confirmation before proceeding.** + +### Step 5: Present Diagnosis Summary + +```markdown +## RBAC Diagnosis Summary: [deployment-name] + +### Root Cause + +**Primary Issue:** [e.g., "Missing RoleBinding for ServiceAccount 'metrics-collector' — cannot list pods in namespace 'demo-rbac'"] + +| Category | Status | Details | +|----------|--------|---------| +| Pod Running | OK | Pod is scheduled and container is running | +| Pod Ready | FAIL | Readiness probe fails — API access denied | +| ServiceAccount | EXISTS | [sa-name] in [namespace] | +| RoleBinding | MISSING | No binding grants required permissions | +| API Access | DENIED | 403 FORBIDDEN on [verbs] [resources] | + +### Causal Chain (Five Whys) + +1. **Signal**: Deployment [name] has 0 available replicas (MinimumReplicasUnavailable) +2. **Why?** Pod readiness probe (`kubectl auth can-i list pods`) returns "no" +3. **Why?** ServiceAccount [sa-name] lacks a RoleBinding granting `list` on `pods` +4. **Why?** The required Role/RoleBinding is absent or was deleted +5. **Root Cause**: [e.g., "Missing RBAC resources for this ServiceAccount — the binding was never created or was removed by a cleanup process/GitOps drift"] + +### Recommended Actions + +**Option A: Create the missing Role and RoleBinding (recommended)** + +```bash +# Create the Role +oc create role [sa-name]-pod-reader \ + --verb=get,list,watch \ + --resource=pods \ + -n [namespace] + +# Create the RoleBinding +oc create rolebinding [sa-name]-pod-reader-binding \ + --role=[sa-name]-pod-reader \ + --serviceaccount=[namespace]:[sa-name] \ + -n [namespace] +``` + +**Option B: Use an existing ClusterRole** + +If a suitable ClusterRole already exists (e.g., `view`): + +```bash +oc create rolebinding [sa-name]-view \ + --clusterrole=view \ + --serviceaccount=[namespace]:[sa-name] \ + -n [namespace] +``` + +⚠️ **Note**: The `view` ClusterRole grants read access to most resources in the namespace. Use a custom Role (Option A) for least-privilege. + +**After applying the fix, verify:** + +```bash +# Check if the SA now has permission +oc auth can-i list pods -n [namespace] --as=system:serviceaccount:[namespace]:[sa-name] + +# Check pod readiness +oc get pods -n [namespace] -l app=[app-label] -o wide +``` + +### Regression Warning + +[If regression detected from remediation history:] +⚠️ **Regression detected**: [N] prior remediation attempts applied the same fix but it was subsequently undone. Investigate whether a GitOps controller, security audit script, or namespace policy is removing the RoleBinding. Ensure the binding is added to the authoritative source of truth (Helm chart, Kustomize overlay, ArgoCD Application) rather than applied ad-hoc. + +### Related Documentation + +- [OpenShift RBAC documentation](https://docs.openshift.com/container-platform/latest/authentication/using-rbac.html) +- [Kubernaut RBAC failure golden transcript](https://github.com/jordigilh/kubernaut-demo-scenarios/blob/feature/v1.4-new-scenarios/golden-transcripts/rbac-failure-rbacpolicydenied.json) + +--- + +Would you like me to: +1. Execute Option A (create Role + RoleBinding) +2. Execute Option B (bind existing ClusterRole) +3. Investigate who is removing the binding (if regression) +4. Dig deeper into a specific area +5. Exit debugging + +Select an option: +``` + +**WAIT for user confirmation before proceeding.** + +## Dependencies + +### Required MCP Servers +- `openshift` - Kubernetes/OpenShift resource access for Deployments, Pods, ServiceAccounts, Roles, RoleBindings, and Events + +### Related Skills +- `/debug-scc` - If pods are blocked from creation by SCC admission (different from RBAC) +- `/debug-pod` - If pods are crashing due to application issues, not RBAC +- `/debug-network` - If pods can't reach services (network, not API access) + +### Reference Documentation +- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and troubleshooting trees +- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification diff --git a/rh-developer/skills/debug-scc/SKILL.md b/rh-developer/skills/debug-scc/SKILL.md new file mode 100644 index 00000000..c449f987 --- /dev/null +++ b/rh-developer/skills/debug-scc/SKILL.md @@ -0,0 +1,301 @@ +--- +name: debug-scc +description: | + Diagnose OpenShift Security Context Constraint (SCC) violations that prevent pods from being created. Automates multi-step diagnosis: Deployment status, ReplicaSet FailedCreate events, security context field extraction, SCC rejection parsing, and ServiceAccount SCC binding analysis. Use this skill when pods are blocked from scheduling with "unable to validate against any security context constraint" errors. Triggers on /debug-scc command or phrases like "SCC violation", "pod blocked by SCC", "security context constraint", "FailedCreate forbidden", "unable to validate against any security context constraint". +model: inherit +color: cyan +metadata: + user_invocable: "true" +--- + +# /debug-scc Skill + +Diagnose OpenShift SCC violations that block pod creation by analyzing security context fields, SCC rejection messages, and ServiceAccount bindings. + +## Overview + +``` +[Identify Deployment] → [Check ReplicaSet Status] → [Parse SCC Rejections] → [Analyze SecurityContext] → [Check SA Bindings] → [Summary + Fix] +``` + +**This skill diagnoses:** +- Pods blocked by SCC admission (`FailedCreate` events) +- `runAsUser` violations (running as root when restricted) +- Forbidden capabilities (`NET_ADMIN`, `SYS_PTRACE`, etc.) +- `allowPrivilegeEscalation` rejections +- ServiceAccount lacking SCC bindings +- `hostUsers`, `hostNetwork`, `hostPID` violations + +## Prerequisites + +Before running this skill: +1. User is logged into an OpenShift cluster +2. User has access to the target namespace +3. Deployment or pod name is known (or can be identified from recent events) + +## Critical: Human-in-the-Loop Requirements + +See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. + +## When to Use This Skill + +Use `/debug-scc` when a Deployment has zero available replicas and ReplicaSet events show `FailedCreate` with messages containing "unable to validate against any security context constraint" or "is forbidden". This indicates the pod spec requests capabilities, UID/GID settings, or volume types that violate the namespace's SCC policy. + +Do **not** use this skill when pods are failing for other reasons (CrashLoopBackOff, ImagePullBackOff, OOMKilled) — use `/debug-pod` instead. + +## Workflow + +### Step 1: Identify Target Deployment + +```markdown +## SCC Violation Debugging + +**Current OpenShift Context:** +- Cluster: [cluster] +- Namespace: [namespace] + +Which deployment would you like me to debug for SCC violations? + +1. **Specify deployment name** - Enter the deployment name directly +2. **List deployments with issues** - Show deployments with unavailable replicas +3. **Search by event** - Find deployments with FailedCreate events + +Select an option or enter a deployment name: +``` + +**WAIT for user confirmation before proceeding.** + +If user selects "List deployments with issues": +Use kubernetes MCP `resources_list` for Deployments, filter to those with unavailable replicas: + +```markdown +## Deployments with Issues in [namespace] + +| Deployment | Available | Desired | Conditions | +|------------|-----------|---------|------------| +| [deploy-name] | 0 | 1 | ReplicaFailure | + +Which deployment would you like me to debug? +``` + +**WAIT for user confirmation before proceeding.** + +### Step 2: Get Deployment and ReplicaSet Status + +Use kubernetes MCP `resources_get` for the Deployment, then identify the failing ReplicaSet: + +```markdown +## Deployment Status: [deployment-name] + +**Deployment Info:** +| Field | Value | +|-------|-------| +| Namespace | [namespace] | +| Replicas | 0/[desired] available | +| Strategy | [RollingUpdate/Recreate] | +| Condition | [ReplicaFailure / MinimumReplicasUnavailable] | + +**ReplicaSets:** +| ReplicaSet | Desired | Ready | Status | +|------------|---------|-------|--------| +| [rs-name-new] | 1 | 0 | FailedCreate | +| [rs-name-old] | 0 | 0 | Scaled down | + +**Quick Assessment:** +[e.g., "Deployment triggered a rollout but the new ReplicaSet cannot create pods — SCC admission is rejecting the pod spec."] + +Continue with SCC rejection analysis? (yes/no) +``` + +**WAIT for user confirmation before proceeding.** + +### Step 3: Parse SCC Rejection Messages + +Use kubernetes MCP `events_list` filtered by namespace, and `resources_get` for the failing ReplicaSet to extract the `ReplicaFailure` condition message: + +```markdown +## SCC Rejection Analysis: [rs-name] + +**FailedCreate Events:** [count] occurrences since [first-seen] + +**SCC Violations Detected:** + +| Violation | SCC | Field | Current Value | Allowed | +|-----------|-----|-------|---------------|---------| +| [runAsUser] | restricted-v2 | .containers[0].runAsUser | 0 (root) | [range] | +| [capability] | restricted-v2 | .containers[0].capabilities.add | NET_ADMIN | not permitted | +| [escalation] | restricted-v2 | .containers[0].allowPrivilegeEscalation | true | false required | + +**SCCs Attempted:** +| SCC | Result | Reason | +|-----|--------|--------| +| restricted-v2 | Rejected | [specific violations] | +| restricted-v3 | Rejected | [specific violations] | +| anyuid | Forbidden | Not usable by user or serviceaccount | +| privileged | Forbidden | Not usable by user or serviceaccount | + +**Key Finding:** +[e.g., "The container requests root (UID 0), NET_ADMIN capability, and privilege escalation — all rejected by restricted-v2/v3. Permissive SCCs (anyuid, privileged) are Forbidden because the ServiceAccount has no binding to them."] + +Continue to inspect the container security context? (yes/no) +``` + +**WAIT for user confirmation before proceeding.** + +### Step 4: Analyze Container SecurityContext + +Use kubernetes MCP `resources_get` for the Deployment to extract the full security context: + +```markdown +## SecurityContext Analysis: [deployment-name] + +**Pod-level SecurityContext:** +| Field | Value | Compliant? | +|-------|-------|------------| +| runAsNonRoot | [true/false/unset] | [YES/NO] | +| seccompProfile | [RuntimeDefault/unset] | [YES/NO] | +| fsGroup | [value/unset] | [YES/NO] | +| hostUsers | [true/false/null] | [YES/NO — restricted-v3 requires false] | + +**Container-level SecurityContext (container: [name]):** +| Field | Value | Compliant? | +|-------|-------|------------| +| runAsUser | [0/unset/value] | [YES/NO — 0 is root] | +| allowPrivilegeEscalation | [true/false/unset] | [YES/NO] | +| capabilities.add | [list or none] | [YES/NO — restricted SCCs drop ALL] | +| capabilities.drop | [list or ALL] | [YES/NO] | +| privileged | [true/false/unset] | [YES/NO] | +| readOnlyRootFilesystem | [true/false/unset] | [INFO] | + +**Change History (from managedFields):** +| Timestamp | Manager | Fields Changed | +|-----------|---------|----------------| +| [time] | kubectl-patch | securityContext.runAsUser, capabilities.add, allowPrivilegeEscalation | +| [time] | kubectl-client-side-apply | initial creation | + +**Assessment:** +[e.g., "A kubectl patch at [timestamp] introduced root UID, NET_ADMIN, and privilege escalation — overriding the originally compliant spec."] + +Continue to check ServiceAccount SCC bindings? (yes/no) +``` + +**WAIT for user confirmation before proceeding.** + +### Step 5: Check ServiceAccount SCC Bindings + +Use kubernetes MCP `resources_list` for ServiceAccounts in the namespace. Note: listing cluster-scoped SecurityContextConstraints may be forbidden depending on RBAC — the skill handles this gracefully by inferring from rejection messages. + +```markdown +## ServiceAccount Analysis + +**ServiceAccount used by Deployment:** [sa-name] (namespace: [namespace]) + +**Available Information:** +| Check | Result | +|-------|--------| +| SA exists | [Yes/No] | +| Custom SA or default | [custom/default] | +| SCC bindings visible | [Yes/Forbidden — inferred from rejection messages] | + +**SCC Access (from rejection messages):** +| SCC | Access | +|-----|--------| +| restricted-v2 | Available (but pod spec violates it) | +| restricted-v3 | Available (but pod spec violates it) | +| anyuid | Forbidden — SA has no binding | +| privileged | Forbidden — SA has no binding | +| [others] | Forbidden — SA has no binding | + +**Assessment:** +[e.g., "The SA 'default' only has access to restricted-v2/v3. The pod spec must be fixed to comply with restricted SCC, OR the SA needs a RoleBinding to a permissive SCC (if elevated privileges are genuinely required)."] + +Continue to diagnosis summary? (yes/no) +``` + +**WAIT for user confirmation before proceeding.** + +### Step 6: Present Diagnosis Summary + +```markdown +## SCC Violation Diagnosis Summary: [deployment-name] + +### Root Cause + +**Primary Issue:** [e.g., "kubectl patch introduced privileged security context settings that violate all available SCCs"] + +| Category | Status | Details | +|----------|--------|---------| +| Pod Admission | BLOCKED | SCC rejects pod spec | +| SecurityContext | NON-COMPLIANT | [specific violations] | +| ServiceAccount | [OK/MISSING BINDING] | [sa-name] — [SCC access] | +| Change Attribution | [IDENTIFIED/UNKNOWN] | [manager and timestamp from managedFields] | + +### Causal Chain (Five Whys) + +1. **Signal**: [deployment] has 0 available replicas +2. **Why?** ReplicaSet [rs-name] cannot create pods — [N] FailedCreate events +3. **Why?** Every available SCC rejects the pod spec +4. **Why?** Container securityContext specifies [violations] +5. **Root Cause**: [e.g., "A kubectl patch at [timestamp] modified the securityContext to introduce non-compliant settings"] + +### Recommended Actions + +**Option A: Fix the SecurityContext (recommended if elevated privileges are NOT needed)** + +Remove the non-compliant fields to restore restricted SCC compliance: + +```bash +oc patch deployment [deployment-name] -n [namespace] --type json -p '[ + {"op": "remove", "path": "/spec/template/spec/containers/0/securityContext/runAsUser"}, + {"op": "replace", "path": "/spec/template/spec/containers/0/securityContext/allowPrivilegeEscalation", "value": false}, + {"op": "remove", "path": "/spec/template/spec/containers/0/securityContext/capabilities/add"} +]' +``` + +**Option B: Grant SCC binding (only if elevated privileges are genuinely required)** + +Create a RoleBinding to a permissive SCC for the ServiceAccount: + +```bash +oc adm policy add-scc-to-user anyuid -z [sa-name] -n [namespace] +``` + +⚠️ **Warning**: Granting anyuid/privileged SCCs weakens namespace security. Only use if the workload genuinely requires elevated privileges. + +**Option C: Rollback to previous revision** + +```bash +oc rollout undo deployment/[deployment-name] -n [namespace] +``` + +### Related Documentation + +- [OpenShift SCC documentation](https://docs.openshift.com/container-platform/latest/authentication/managing-security-context-constraints.html) +- [Kubernaut SCC violation golden transcript](https://github.com/jordigilh/kubernaut-demo-scenarios/blob/feature/v1.4-new-scenarios/golden-transcripts/scc-violation-sccviolationpodblocked.json) + +--- + +Would you like me to: +1. Execute Option A (fix SecurityContext) +2. Execute Option B (grant SCC binding) +3. Execute Option C (rollback) +4. Dig deeper into a specific area +5. Exit debugging + +Select an option: +``` + +**WAIT for user confirmation before proceeding.** + +## Dependencies + +### Required MCP Servers +- `openshift` - Kubernetes/OpenShift resource access for Deployments, ReplicaSets, Events, ServiceAccounts, and SecurityContextConstraints + +### Related Skills +- `/debug-pod` - If pods exist but are crashing (CrashLoopBackOff, OOMKilled) +- `/debug-rbac` - If pods run but fail with 403 Forbidden API errors (RBAC, not SCC) + +### Reference Documentation +- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and troubleshooting trees +- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification From be061ada29ef915e49473980d336fc476086d31a Mon Sep 17 00:00:00 2001 From: Jordi Gil Date: Thu, 7 May 2026 13:32:34 -0400 Subject: [PATCH 2/7] fix(rh-developer): align debug-scc and debug-rbac with SKILL_DESIGN_PRINCIPLES.md Address Gemini code review feedback on PR #79: - Reorder sections: Human-in-the-Loop before Prerequisites - Flesh out Prerequisites with Required MCP Servers/Tools, Verification Steps, Human Notification Protocol, and Security warning - Add structured MCP Tool/Parameters/Expected Output/Error Handling blocks to all workflow steps - Add Required MCP Tools subsection under Dependencies - Add Example Usage section - Use placeholder syntax () instead of hardcoded values - Improve frontmatter description with Use when / NOT for patterns Co-authored-by: Cursor --- rh-developer/skills/debug-rbac/SKILL.md | 234 +++++++++++++++++++----- rh-developer/skills/debug-scc/SKILL.md | 229 +++++++++++++++++++---- 2 files changed, 377 insertions(+), 86 deletions(-) diff --git a/rh-developer/skills/debug-rbac/SKILL.md b/rh-developer/skills/debug-rbac/SKILL.md index 7999628c..38017001 100644 --- a/rh-developer/skills/debug-rbac/SKILL.md +++ b/rh-developer/skills/debug-rbac/SKILL.md @@ -1,7 +1,16 @@ --- name: debug-rbac description: | - Diagnose OpenShift RBAC permission failures that cause workloads to fail with 403 Forbidden errors when accessing the Kubernetes API. Automates multi-step diagnosis: pod logs for FORBIDDEN errors, readiness probe failures, ServiceAccount identification, RoleBinding/ClusterRoleBinding analysis, and remediation history for regression detection. Use this skill when pods are running but failing because their ServiceAccount lacks required API permissions. Triggers on /debug-rbac command or phrases like "RBAC denied", "403 forbidden", "pods can't list resources", "missing RoleBinding", "ServiceAccount permission denied". + Diagnose OpenShift RBAC permission failures that cause workloads to fail with 403 Forbidden errors when accessing the Kubernetes API. Automates multi-step diagnosis: pod logs for FORBIDDEN errors, readiness probe failures, ServiceAccount identification, RoleBinding/ClusterRoleBinding analysis, and remediation history for regression detection. + + Use when: + - "403 forbidden when accessing Kubernetes API" + - "ServiceAccount permission denied" + - "pods can't list resources" + - "missing RoleBinding" + - User mentions "RBAC denied", "403 forbidden", "permission denied" + + NOT for SCC admission failures (use /debug-scc instead). model: inherit color: cyan metadata: @@ -12,43 +21,86 @@ metadata: Diagnose RBAC permission failures on OpenShift by analyzing pod logs, readiness probes, ServiceAccount bindings, and Role/RoleBinding configuration. -## Overview +## Critical: Human-in-the-Loop Requirements -``` -[Identify Deployment] → [Check Pod Status + Logs] → [Identify RBAC Errors] → [Analyze ServiceAccount] → [Check RoleBindings] → [Summary + Fix] -``` +1. **Before creating Role or RoleBinding resources** + - Display preview: the exact RBAC resources that will be created and what permissions they grant + - Ask: "Should I create these RBAC resources?" + - Wait for confirmation (yes/no) + +2. **Before binding broad ClusterRoles** (e.g., `view`, `edit`, `admin`) + - Display warning: broad ClusterRoles grant more permissions than the minimum required + - Ask: "Proceed with broad ClusterRole binding, or create a minimal custom Role instead?" + - Wait for confirmation -**This skill diagnoses:** -- Pods failing with 403 Forbidden errors against the Kubernetes API -- Readiness probes that check API access (`kubectl auth can-i`) returning "no" -- Missing or deleted RoleBindings/ClusterRoleBindings -- ServiceAccounts lacking required permissions (get, list, watch, create, etc.) -- Regression patterns where RBAC bindings are repeatedly removed +**Never assume approval** — always wait for explicit confirmation at each WAIT checkpoint. ## Prerequisites -Before running this skill: -1. User is logged into an OpenShift cluster -2. User has access to the target namespace -3. Deployment or pod name is known (or can be identified from recent events) +**Required MCP Servers:** `openshift` ([setup](../../docs/prerequisites.md)) -## Critical: Human-in-the-Loop Requirements +**Required MCP Tools:** +- `resources_get` (from openshift) — Retrieve Deployment, Pod, ServiceAccount, Role, and RoleBinding details +- `resources_list` (from openshift) — List Deployments, RoleBindings, and ClusterRoleBindings in a namespace +- `pod_list` (from openshift) — List pods for a Deployment +- `pod_logs` (from openshift) — Retrieve container logs to identify FORBIDDEN errors +- `events_list` (from openshift) — Fetch warning events related to RBAC failures + +**Verification Steps:** +1. Check `openshift` server is configured in `mcps.json` +2. Verify user is logged into an OpenShift cluster (`oc whoami` succeeds) +3. Verify user has access to the target namespace +4. If missing → Human Notification Protocol + +**Human Notification Protocol:** -See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +When prerequisites fail: +1. **Stop immediately** — No tool calls +2. **Report error:** + ``` + ❌ Cannot execute skill: MCP server `openshift` unavailable + 📋 Setup: See docs/prerequisites.md for cluster access configuration + ``` +3. **Request decision:** "How to proceed? (setup/skip/abort)" +4. **Wait for user input** + +**Security:** Never display credential values. ## When to Use This Skill -Use `/debug-rbac` when a Deployment's pods are running but not ready, and pod logs show `FORBIDDEN` or `403` errors when calling the Kubernetes API. This typically manifests as readiness probe failures when the probe checks API access, or application-level errors when the workload needs to interact with Kubernetes resources. +Use `/debug-rbac` when: +- A Deployment's pods are running but not ready, and pod logs show `FORBIDDEN` or `403` errors calling the Kubernetes API +- Readiness probes fail because they check API access (e.g., `kubectl auth can-i`) +- Application logs show permission denied errors when interacting with Kubernetes resources Do **not** use this skill when: -- Pods are blocked from being created entirely — use `/debug-scc` (SCC admission failures) -- Pods are crashing due to application bugs — use `/debug-pod` -- The issue is network connectivity — use `/debug-network` +- Pods are blocked from being created entirely → use `/debug-scc` (SCC admission failures) +- Pods are crashing due to application bugs → use `/debug-pod` +- The issue is network connectivity → use `/debug-network` ## Workflow +``` +[Identify Deployment] → [Check Pod Status + Logs] → [Identify RBAC Errors] → [Analyze ServiceAccount] → [Check RoleBindings] → [Summary + Fix] +``` + ### Step 1: Identify Target Deployment +**MCP Tool**: `resources_list` (from openshift) + +**Parameters**: +- `kind`: "Deployment" (resource type) +- `namespace`: "" (target namespace from user) + +**Expected Output**: List of Deployments with their availability and readiness conditions. + +**Error Handling**: +- If MCP server unavailable: follow Human Notification Protocol +- If namespace not found: ask user to confirm namespace name +- If no deployments found: report empty namespace, suggest checking namespace + +Present to user: + ```markdown ## RBAC Debugging @@ -58,17 +110,16 @@ Do **not** use this skill when: Which deployment would you like me to debug for RBAC issues? -1. **Specify deployment name** - Enter the deployment name directly -2. **List deployments with issues** - Show deployments with unavailable or not-ready pods -3. **Search recent events** - Find pods with RBAC-related warning events +1. **Specify deployment name** — Enter the deployment name directly +2. **List deployments with issues** — Show deployments with unavailable or not-ready pods +3. **Search recent events** — Find pods with RBAC-related warning events Select an option or enter a deployment name: ``` **WAIT for user confirmation before proceeding.** -If user selects "List deployments with issues": -Use kubernetes MCP `resources_list` for Deployments, filter to those with not-ready conditions: +If user selects "List deployments with issues", filter to those with not-ready conditions: ```markdown ## Deployments with Issues in [namespace] @@ -84,7 +135,36 @@ Which deployment would you like me to debug? ### Step 2: Check Pod Status and Logs -Use kubernetes MCP `pod_list` to find pods for the Deployment, then `resources_get` for pod details and `pod_logs` for container logs: +**MCP Tool**: `pod_list` (from openshift) + +**Parameters**: +- `namespace`: "" +- `labelSelector`: "=" (from Deployment `.spec.selector.matchLabels`) + +Then for each matching pod: + +**MCP Tool**: `resources_get` (from openshift) + +**Parameters**: +- `kind`: "Pod" (resource type) +- `name`: "" (from pod_list) +- `namespace`: "" + +**MCP Tool**: `pod_logs` (from openshift) + +**Parameters**: +- `name`: "" +- `namespace`: "" +- `tailLines`: 50 (integer, last N lines) + +**Expected Output**: Pod status with readiness conditions, and container logs containing FORBIDDEN/403 error lines. + +**Error Handling**: +- If no pods found: Deployment may have zero replicas; check if it's scaled down +- If logs empty: container may not have started; check container state +- If multiple pods: analyze the most recent one first + +Present to user: ```markdown ## Pod Analysis: [pod-name] @@ -125,7 +205,15 @@ Continue with ServiceAccount analysis? (yes/no) ### Step 3: Identify Required Permissions -Based on the FORBIDDEN error messages and readiness probe command, determine what permissions are needed: +Based on the FORBIDDEN error messages and readiness probe command from Step 2, determine what permissions are needed. This is an analysis step — no additional MCP tool calls required unless log data is insufficient. + +**Expected Output**: Table of required permissions extracted from FORBIDDEN error strings, plus a minimal Role definition. + +**Error Handling**: +- If FORBIDDEN messages are ambiguous: request more log lines with increased `tailLines` +- If no FORBIDDEN errors found: the issue may not be RBAC; suggest `/debug-pod` instead + +Present to user: ```markdown ## Required Permissions Analysis @@ -153,8 +241,8 @@ Based on the FORBIDDEN error messages and readiness probe command, determine wha apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: - name: [sa-name]-role - namespace: [namespace] + name: -role + namespace: rules: - apiGroups: [""] resources: ["pods"] @@ -168,7 +256,34 @@ Continue to check existing RoleBindings? (yes/no) ### Step 4: Analyze ServiceAccount and RoleBindings -Use kubernetes MCP `resources_get` for the ServiceAccount, and `resources_list` for RoleBindings in the namespace: +**MCP Tool**: `resources_get` (from openshift) + +**Parameters**: +- `kind`: "ServiceAccount" (resource type) +- `name`: "" (from Deployment `.spec.template.spec.serviceAccountName`, default: `default`) +- `namespace`: "" + +**MCP Tool**: `resources_list` (from openshift) + +**Parameters**: +- `kind`: "RoleBinding" (resource type) +- `namespace`: "" + +Optionally, if permissions allow: + +**MCP Tool**: `resources_list` (from openshift) + +**Parameters**: +- `kind`: "ClusterRoleBinding" (cluster-scoped) + +**Expected Output**: ServiceAccount details and all RoleBindings/ClusterRoleBindings, checked for whether any grant the required permissions to the target ServiceAccount. + +**Error Handling**: +- If listing RoleBindings is forbidden: note the limitation, infer from FORBIDDEN errors +- If ServiceAccount not found: report as a finding — SA may need to be created +- If multiple bindings exist: check each for matching subjects and sufficient verbs + +Present to user: ```markdown ## ServiceAccount & RoleBinding Analysis @@ -205,6 +320,16 @@ Continue to diagnosis summary? (yes/no) ### Step 5: Present Diagnosis Summary +Synthesize all findings into a structured summary with actionable remediation options. + +**Expected Output**: Root cause summary, causal chain, remediation commands, and regression warnings if applicable. + +**Error Handling**: +- If insufficient data from earlier steps: note gaps and recommend manual investigation +- If regression pattern detected (repeated remediation/deletion cycles): highlight prominently + +Present to user: + ```markdown ## RBAC Diagnosis Summary: [deployment-name] @@ -234,16 +359,16 @@ Continue to diagnosis summary? (yes/no) ```bash # Create the Role -oc create role [sa-name]-pod-reader \ +oc create role -pod-reader \ --verb=get,list,watch \ --resource=pods \ - -n [namespace] + -n # Create the RoleBinding -oc create rolebinding [sa-name]-pod-reader-binding \ - --role=[sa-name]-pod-reader \ - --serviceaccount=[namespace]:[sa-name] \ - -n [namespace] +oc create rolebinding -pod-reader-binding \ + --role=-pod-reader \ + --serviceaccount=: \ + -n ``` **Option B: Use an existing ClusterRole** @@ -251,10 +376,10 @@ oc create rolebinding [sa-name]-pod-reader-binding \ If a suitable ClusterRole already exists (e.g., `view`): ```bash -oc create rolebinding [sa-name]-view \ +oc create rolebinding -view \ --clusterrole=view \ - --serviceaccount=[namespace]:[sa-name] \ - -n [namespace] + --serviceaccount=: \ + -n ``` ⚠️ **Note**: The `view` ClusterRole grants read access to most resources in the namespace. Use a custom Role (Option A) for least-privilege. @@ -263,10 +388,10 @@ oc create rolebinding [sa-name]-view \ ```bash # Check if the SA now has permission -oc auth can-i list pods -n [namespace] --as=system:serviceaccount:[namespace]:[sa-name] +oc auth can-i list pods -n --as=system:serviceaccount:: # Check pod readiness -oc get pods -n [namespace] -l app=[app-label] -o wide +oc get pods -n -l app= -o wide ``` ### Regression Warning @@ -296,13 +421,26 @@ Select an option: ## Dependencies ### Required MCP Servers -- `openshift` - Kubernetes/OpenShift resource access for Deployments, Pods, ServiceAccounts, Roles, RoleBindings, and Events +- `openshift` — Kubernetes/OpenShift resource access for Deployments, Pods, ServiceAccounts, Roles, RoleBindings, and Events ([setup](../../docs/prerequisites.md)) + +### Required MCP Tools +- `resources_get` (from openshift) — Retrieve individual resource details (Deployment, Pod, ServiceAccount, Role, RoleBinding) +- `resources_list` (from openshift) — List resources by kind in a namespace (Deployments, RoleBindings, ClusterRoleBindings) +- `pod_list` (from openshift) — List pods matching label selectors +- `pod_logs` (from openshift) — Retrieve container logs for FORBIDDEN error analysis +- `events_list` (from openshift) — Fetch events filtered by involved object ### Related Skills -- `/debug-scc` - If pods are blocked from creation by SCC admission (different from RBAC) -- `/debug-pod` - If pods are crashing due to application issues, not RBAC -- `/debug-network` - If pods can't reach services (network, not API access) +- `/debug-scc` — If pods are blocked from creation by SCC admission (different from RBAC) +- `/debug-pod` — If pods are crashing due to application issues, not RBAC +- `/debug-network` — If pods can't reach services (network, not API access) ### Reference Documentation -- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and troubleshooting trees -- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification +- **Internal:** [docs/debugging-patterns.md](../../docs/debugging-patterns.md) — Common error patterns and troubleshooting trees +- **Official:** [Using RBAC - OpenShift](https://docs.openshift.com/container-platform/latest/authentication/using-rbac.html) + +## Example Usage + +**User**: My deployment `metrics-collector` in namespace `demo-rbac` shows 0/1 available. The pod is running but not ready. Logs show "FORBIDDEN: pods is forbidden". What's wrong? + +**Skill response**: The skill checks the pod status (Running but not Ready), examines logs to find FORBIDDEN errors on `list pods`, identifies the ServiceAccount (`metrics-collector`), lists RoleBindings in the namespace and finds none granting the required permissions. It presents a diagnosis showing the missing RoleBinding as root cause, detects a regression pattern if prior remediation attempts were undone, and offers two fix options: create a minimal custom Role+RoleBinding, or bind the broader `view` ClusterRole. diff --git a/rh-developer/skills/debug-scc/SKILL.md b/rh-developer/skills/debug-scc/SKILL.md index c449f987..81033fea 100644 --- a/rh-developer/skills/debug-scc/SKILL.md +++ b/rh-developer/skills/debug-scc/SKILL.md @@ -1,7 +1,16 @@ --- name: debug-scc description: | - Diagnose OpenShift Security Context Constraint (SCC) violations that prevent pods from being created. Automates multi-step diagnosis: Deployment status, ReplicaSet FailedCreate events, security context field extraction, SCC rejection parsing, and ServiceAccount SCC binding analysis. Use this skill when pods are blocked from scheduling with "unable to validate against any security context constraint" errors. Triggers on /debug-scc command or phrases like "SCC violation", "pod blocked by SCC", "security context constraint", "FailedCreate forbidden", "unable to validate against any security context constraint". + Diagnose OpenShift Security Context Constraint (SCC) violations that prevent pods from being created. Automates multi-step diagnosis: Deployment status, ReplicaSet FailedCreate events, security context field extraction, SCC rejection parsing, and ServiceAccount SCC binding analysis. + + Use when: + - "SCC violation blocking pod creation" + - "unable to validate against any security context constraint" + - "FailedCreate forbidden" + - "pod blocked by SCC" + - User mentions "SCC", "security context constraint", "FailedCreate" + + NOT for pods crashing after creation (use /debug-pod instead). model: inherit color: cyan metadata: @@ -12,41 +21,85 @@ metadata: Diagnose OpenShift SCC violations that block pod creation by analyzing security context fields, SCC rejection messages, and ServiceAccount bindings. -## Overview +## Critical: Human-in-the-Loop Requirements -``` -[Identify Deployment] → [Check ReplicaSet Status] → [Parse SCC Rejections] → [Analyze SecurityContext] → [Check SA Bindings] → [Summary + Fix] -``` +1. **Before any remediation action** (patch securityContext, grant SCC binding, rollback) + - Display preview: what will change and its security implications + - Ask: "Should I apply this fix?" + - Wait for confirmation (yes/no) + +2. **Before granting permissive SCCs** (anyuid, privileged) + - Display warning: granting elevated SCCs weakens namespace security + - Ask: "Type 'GRANT SCC' to confirm you understand the security implications" + - Verify exact match, cancel if mismatch -**This skill diagnoses:** -- Pods blocked by SCC admission (`FailedCreate` events) -- `runAsUser` violations (running as root when restricted) -- Forbidden capabilities (`NET_ADMIN`, `SYS_PTRACE`, etc.) -- `allowPrivilegeEscalation` rejections -- ServiceAccount lacking SCC bindings -- `hostUsers`, `hostNetwork`, `hostPID` violations +**Never assume approval** — always wait for explicit confirmation at each WAIT checkpoint. ## Prerequisites -Before running this skill: -1. User is logged into an OpenShift cluster -2. User has access to the target namespace -3. Deployment or pod name is known (or can be identified from recent events) +**Required MCP Servers:** `openshift` ([setup](../../docs/prerequisites.md)) -## Critical: Human-in-the-Loop Requirements +**Required MCP Tools:** +- `resources_get` (from openshift) — Retrieve Deployment, ReplicaSet, and ServiceAccount details +- `resources_list` (from openshift) — List Deployments, ReplicaSets, and ServiceAccounts in a namespace +- `events_list` (from openshift) — Fetch FailedCreate and SCC rejection events +- `pod_list` (from openshift) — List pods for a Deployment + +**Verification Steps:** +1. Check `openshift` server is configured in `mcps.json` +2. Verify user is logged into an OpenShift cluster (`oc whoami` succeeds) +3. Verify user has access to the target namespace +4. If missing → Human Notification Protocol + +**Human Notification Protocol:** + +When prerequisites fail: +1. **Stop immediately** — No tool calls +2. **Report error:** + ``` + ❌ Cannot execute skill: MCP server `openshift` unavailable + 📋 Setup: See docs/prerequisites.md for cluster access configuration + ``` +3. **Request decision:** "How to proceed? (setup/skip/abort)" +4. **Wait for user input** -See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +**Security:** Never display credential values. ## When to Use This Skill -Use `/debug-scc` when a Deployment has zero available replicas and ReplicaSet events show `FailedCreate` with messages containing "unable to validate against any security context constraint" or "is forbidden". This indicates the pod spec requests capabilities, UID/GID settings, or volume types that violate the namespace's SCC policy. +Use `/debug-scc` when: +- A Deployment has zero available replicas and ReplicaSet events show `FailedCreate` with "unable to validate against any security context constraint" +- Pod spec requests capabilities, UID/GID settings, or volume types that violate the namespace's SCC policy +- You see "is forbidden" errors referencing SecurityContextConstraints -Do **not** use this skill when pods are failing for other reasons (CrashLoopBackOff, ImagePullBackOff, OOMKilled) — use `/debug-pod` instead. +Do **not** use this skill when: +- Pods are crashing after creation (CrashLoopBackOff, OOMKilled) → use `/debug-pod` +- Pods fail with 403 Forbidden API errors → use `/debug-rbac` +- Image pull failures → use `/debug-pod` ## Workflow +``` +[Identify Deployment] → [Check ReplicaSet Status] → [Parse SCC Rejections] → [Analyze SecurityContext] → [Check SA Bindings] → [Summary + Fix] +``` + ### Step 1: Identify Target Deployment +**MCP Tool**: `resources_list` (from openshift) + +**Parameters**: +- `kind`: "Deployment" (resource type) +- `namespace`: "" (target namespace from user) + +**Expected Output**: List of Deployments with their availability status. + +**Error Handling**: +- If MCP server unavailable: follow Human Notification Protocol +- If namespace not found: ask user to confirm namespace name +- If no deployments found: report empty namespace, suggest checking namespace + +Present to user: + ```markdown ## SCC Violation Debugging @@ -56,17 +109,16 @@ Do **not** use this skill when pods are failing for other reasons (CrashLoopBack Which deployment would you like me to debug for SCC violations? -1. **Specify deployment name** - Enter the deployment name directly -2. **List deployments with issues** - Show deployments with unavailable replicas -3. **Search by event** - Find deployments with FailedCreate events +1. **Specify deployment name** — Enter the deployment name directly +2. **List deployments with issues** — Show deployments with unavailable replicas +3. **Search by event** — Find deployments with FailedCreate events Select an option or enter a deployment name: ``` **WAIT for user confirmation before proceeding.** -If user selects "List deployments with issues": -Use kubernetes MCP `resources_list` for Deployments, filter to those with unavailable replicas: +If user selects "List deployments with issues", filter to those with unavailable replicas: ```markdown ## Deployments with Issues in [namespace] @@ -82,7 +134,29 @@ Which deployment would you like me to debug? ### Step 2: Get Deployment and ReplicaSet Status -Use kubernetes MCP `resources_get` for the Deployment, then identify the failing ReplicaSet: +**MCP Tool**: `resources_get` (from openshift) + +**Parameters**: +- `kind`: "Deployment" (resource type) +- `name`: "" (from Step 1) +- `namespace`: "" + +Then retrieve the failing ReplicaSet: + +**MCP Tool**: `resources_list` (from openshift) + +**Parameters**: +- `kind`: "ReplicaSet" (resource type) +- `namespace`: "" +- Filter by owner reference matching the Deployment + +**Expected Output**: Deployment spec, conditions, and owned ReplicaSets with their status. + +**Error Handling**: +- If Deployment not found: ask user to verify name and namespace +- If no ReplicaSets found: Deployment may not have triggered a rollout yet + +Present to user: ```markdown ## Deployment Status: [deployment-name] @@ -111,7 +185,30 @@ Continue with SCC rejection analysis? (yes/no) ### Step 3: Parse SCC Rejection Messages -Use kubernetes MCP `events_list` filtered by namespace, and `resources_get` for the failing ReplicaSet to extract the `ReplicaFailure` condition message: +**MCP Tool**: `events_list` (from openshift) + +**Parameters**: +- `namespace`: "" +- Filter by `involvedObject.kind=ReplicaSet`, `involvedObject.name=`, `reason=FailedCreate` + +Then also: + +**MCP Tool**: `resources_get` (from openshift) + +**Parameters**: +- `kind`: "ReplicaSet" (resource type) +- `name`: "" (failing ReplicaSet from Step 2) +- `namespace`: "" + +Extract the `ReplicaFailure` condition message containing SCC rejection details. + +**Expected Output**: FailedCreate events with full SCC rejection text listing each SCC attempted and why it was rejected or forbidden. + +**Error Handling**: +- If no events found: events may have expired (default TTL is 1h); check ReplicaSet conditions instead +- If events are ambiguous: cross-reference with ReplicaSet `.status.conditions` + +Present to user: ```markdown ## SCC Rejection Analysis: [rs-name] @@ -144,7 +241,22 @@ Continue to inspect the container security context? (yes/no) ### Step 4: Analyze Container SecurityContext -Use kubernetes MCP `resources_get` for the Deployment to extract the full security context: +**MCP Tool**: `resources_get` (from openshift) + +**Parameters**: +- `kind`: "Deployment" (resource type) +- `name`: "" (from Step 1) +- `namespace`: "" + +Extract `.spec.template.spec.securityContext` (pod-level) and `.spec.template.spec.containers[*].securityContext` (container-level), plus `.metadata.managedFields` for change attribution. + +**Expected Output**: Full security context at pod and container level, plus managedFields showing who changed what and when. + +**Error Handling**: +- If securityContext is empty/unset: the issue may be implicit defaults conflicting with SCC; note this +- If managedFields unavailable: skip change attribution, note limitation + +Present to user: ```markdown ## SecurityContext Analysis: [deployment-name] @@ -183,7 +295,27 @@ Continue to check ServiceAccount SCC bindings? (yes/no) ### Step 5: Check ServiceAccount SCC Bindings -Use kubernetes MCP `resources_list` for ServiceAccounts in the namespace. Note: listing cluster-scoped SecurityContextConstraints may be forbidden depending on RBAC — the skill handles this gracefully by inferring from rejection messages. +**MCP Tool**: `resources_get` (from openshift) + +**Parameters**: +- `kind`: "ServiceAccount" (resource type) +- `name`: "" (from Deployment `.spec.template.spec.serviceAccountName`, default: `default`) +- `namespace`: "" + +Then attempt: + +**MCP Tool**: `resources_list` (from openshift) + +**Parameters**: +- `kind`: "SecurityContextConstraints" (cluster-scoped) + +**Expected Output**: ServiceAccount details and list of SCCs. If listing SCCs is RBAC-forbidden, infer SCC access from the rejection messages in Step 3. + +**Error Handling**: +- If listing SCCs is forbidden: gracefully degrade — use rejection messages to infer which SCCs were attempted and their result +- If ServiceAccount not found: report it; this would also cause pod creation failures + +Present to user: ```markdown ## ServiceAccount Analysis @@ -204,7 +336,6 @@ Use kubernetes MCP `resources_list` for ServiceAccounts in the namespace. Note: | restricted-v3 | Available (but pod spec violates it) | | anyuid | Forbidden — SA has no binding | | privileged | Forbidden — SA has no binding | -| [others] | Forbidden — SA has no binding | **Assessment:** [e.g., "The SA 'default' only has access to restricted-v2/v3. The pod spec must be fixed to comply with restricted SCC, OR the SA needs a RoleBinding to a permissive SCC (if elevated privileges are genuinely required)."] @@ -216,6 +347,16 @@ Continue to diagnosis summary? (yes/no) ### Step 6: Present Diagnosis Summary +Synthesize all findings into a structured summary with actionable remediation options. + +**Expected Output**: Root cause summary, causal chain, and three fix options with commands. + +**Error Handling**: +- If insufficient data from earlier steps: note gaps and recommend manual investigation +- If multiple violations found: prioritize by severity (root UID > capabilities > escalation) + +Present to user: + ```markdown ## SCC Violation Diagnosis Summary: [deployment-name] @@ -245,7 +386,7 @@ Continue to diagnosis summary? (yes/no) Remove the non-compliant fields to restore restricted SCC compliance: ```bash -oc patch deployment [deployment-name] -n [namespace] --type json -p '[ +oc patch deployment -n --type json -p '[ {"op": "remove", "path": "/spec/template/spec/containers/0/securityContext/runAsUser"}, {"op": "replace", "path": "/spec/template/spec/containers/0/securityContext/allowPrivilegeEscalation", "value": false}, {"op": "remove", "path": "/spec/template/spec/containers/0/securityContext/capabilities/add"} @@ -257,7 +398,7 @@ oc patch deployment [deployment-name] -n [namespace] --type json -p '[ Create a RoleBinding to a permissive SCC for the ServiceAccount: ```bash -oc adm policy add-scc-to-user anyuid -z [sa-name] -n [namespace] +oc adm policy add-scc-to-user anyuid -z -n ``` ⚠️ **Warning**: Granting anyuid/privileged SCCs weakens namespace security. Only use if the workload genuinely requires elevated privileges. @@ -265,7 +406,7 @@ oc adm policy add-scc-to-user anyuid -z [sa-name] -n [namespace] **Option C: Rollback to previous revision** ```bash -oc rollout undo deployment/[deployment-name] -n [namespace] +oc rollout undo deployment/ -n ``` ### Related Documentation @@ -290,12 +431,24 @@ Select an option: ## Dependencies ### Required MCP Servers -- `openshift` - Kubernetes/OpenShift resource access for Deployments, ReplicaSets, Events, ServiceAccounts, and SecurityContextConstraints +- `openshift` — Kubernetes/OpenShift resource access for Deployments, ReplicaSets, Events, ServiceAccounts, and SecurityContextConstraints ([setup](../../docs/prerequisites.md)) + +### Required MCP Tools +- `resources_get` (from openshift) — Retrieve individual resource details (Deployment, ReplicaSet, ServiceAccount) +- `resources_list` (from openshift) — List resources by kind in a namespace +- `events_list` (from openshift) — Fetch events filtered by involved object +- `pod_list` (from openshift) — List pods matching label selectors ### Related Skills -- `/debug-pod` - If pods exist but are crashing (CrashLoopBackOff, OOMKilled) -- `/debug-rbac` - If pods run but fail with 403 Forbidden API errors (RBAC, not SCC) +- `/debug-pod` — If pods exist but are crashing (CrashLoopBackOff, OOMKilled) +- `/debug-rbac` — If pods run but fail with 403 Forbidden API errors (RBAC, not SCC) ### Reference Documentation -- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and troubleshooting trees -- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification +- **Internal:** [docs/debugging-patterns.md](../../docs/debugging-patterns.md) — Common error patterns and troubleshooting trees +- **Official:** [Managing SCCs - OpenShift](https://docs.openshift.com/container-platform/latest/authentication/managing-security-context-constraints.html) + +## Example Usage + +**User**: My deployment `security-scanner` in namespace `tools` has 0 available replicas. Events say "unable to validate against any security context constraint". Can you help? + +**Skill response**: The skill identifies the deployment, finds FailedCreate events on the ReplicaSet, parses the SCC rejection messages to find that `runAsUser: 0` and `capabilities.add: [NET_ADMIN]` violate `restricted-v2`. It checks the ServiceAccount's SCC bindings, determines it only has access to restricted SCCs, and presents three options: patch the securityContext to remove violations, grant an `anyuid` SCC binding, or rollback to the previous revision. From fb5370a2630b19cbd2388a9d3bbf1dfaef0aaf8a Mon Sep 17 00:00:00 2001 From: Jordi Gil Date: Thu, 7 May 2026 13:35:20 -0400 Subject: [PATCH 3/7] fix(rh-developer): add license: Apache-2.0 to debug-scc and debug-rbac frontmatter Required by skill-linter CI check. Co-authored-by: Cursor --- rh-developer/skills/debug-rbac/SKILL.md | 1 + rh-developer/skills/debug-scc/SKILL.md | 1 + 2 files changed, 2 insertions(+) diff --git a/rh-developer/skills/debug-rbac/SKILL.md b/rh-developer/skills/debug-rbac/SKILL.md index 38017001..2978a535 100644 --- a/rh-developer/skills/debug-rbac/SKILL.md +++ b/rh-developer/skills/debug-rbac/SKILL.md @@ -13,6 +13,7 @@ description: | NOT for SCC admission failures (use /debug-scc instead). model: inherit color: cyan +license: Apache-2.0 metadata: user_invocable: "true" --- diff --git a/rh-developer/skills/debug-scc/SKILL.md b/rh-developer/skills/debug-scc/SKILL.md index 81033fea..598bc5f3 100644 --- a/rh-developer/skills/debug-scc/SKILL.md +++ b/rh-developer/skills/debug-scc/SKILL.md @@ -13,6 +13,7 @@ description: | NOT for pods crashing after creation (use /debug-pod instead). model: inherit color: cyan +license: Apache-2.0 metadata: user_invocable: "true" --- From 27ecbf170f8ff7eeffe5d75165726a2984fab4eb Mon Sep 17 00:00:00 2001 From: Jordi Gil Date: Thu, 7 May 2026 13:46:50 -0400 Subject: [PATCH 4/7] fix(rh-developer): add allowed-tools and input validation to debug-scc and debug-rbac - Declare allowed-tools in frontmatter restricting each skill to its read-only MCP tools (resources_get, resources_list, events_list, pod_list, and pod_logs for debug-rbac) - Add input validation guidance in Step 1 requiring Kubernetes RFC 1123 name validation before passing user-supplied identifiers to MCP tools Co-authored-by: Cursor --- rh-developer/skills/debug-rbac/SKILL.md | 8 ++++++++ rh-developer/skills/debug-scc/SKILL.md | 7 +++++++ 2 files changed, 15 insertions(+) diff --git a/rh-developer/skills/debug-rbac/SKILL.md b/rh-developer/skills/debug-rbac/SKILL.md index 2978a535..7b9bb32d 100644 --- a/rh-developer/skills/debug-rbac/SKILL.md +++ b/rh-developer/skills/debug-rbac/SKILL.md @@ -14,6 +14,12 @@ description: | model: inherit color: cyan license: Apache-2.0 +allowed-tools: + - resources_get + - resources_list + - events_list + - pod_list + - pod_logs metadata: user_invocable: "true" --- @@ -93,6 +99,8 @@ Do **not** use this skill when: - `kind`: "Deployment" (resource type) - `namespace`: "" (target namespace from user) +**Input Validation**: Verify deployment name and namespace conform to Kubernetes naming rules (lowercase alphanumeric and hyphens, 1-253 chars, RFC 1123). Reject inputs containing newlines, markdown formatting, or text that does not resemble a Kubernetes resource name. + **Expected Output**: List of Deployments with their availability and readiness conditions. **Error Handling**: diff --git a/rh-developer/skills/debug-scc/SKILL.md b/rh-developer/skills/debug-scc/SKILL.md index 598bc5f3..3f305575 100644 --- a/rh-developer/skills/debug-scc/SKILL.md +++ b/rh-developer/skills/debug-scc/SKILL.md @@ -14,6 +14,11 @@ description: | model: inherit color: cyan license: Apache-2.0 +allowed-tools: + - resources_get + - resources_list + - events_list + - pod_list metadata: user_invocable: "true" --- @@ -92,6 +97,8 @@ Do **not** use this skill when: - `kind`: "Deployment" (resource type) - `namespace`: "" (target namespace from user) +**Input Validation**: Verify deployment name and namespace conform to Kubernetes naming rules (lowercase alphanumeric and hyphens, 1-253 chars, RFC 1123). Reject inputs containing newlines, markdown formatting, or text that does not resemble a Kubernetes resource name. + **Expected Output**: List of Deployments with their availability status. **Error Handling**: From 0950cdca872596e149124d01e131fab3b8082dac Mon Sep 17 00:00:00 2001 From: Jordi Gil Date: Thu, 7 May 2026 13:48:25 -0400 Subject: [PATCH 5/7] fix(rh-developer): use space-delimited allowed-tools format Linter requires space-delimited string, not YAML array. Co-authored-by: Cursor --- rh-developer/skills/debug-rbac/SKILL.md | 7 +------ rh-developer/skills/debug-scc/SKILL.md | 6 +----- 2 files changed, 2 insertions(+), 11 deletions(-) diff --git a/rh-developer/skills/debug-rbac/SKILL.md b/rh-developer/skills/debug-rbac/SKILL.md index 7b9bb32d..7d2e7ff1 100644 --- a/rh-developer/skills/debug-rbac/SKILL.md +++ b/rh-developer/skills/debug-rbac/SKILL.md @@ -14,12 +14,7 @@ description: | model: inherit color: cyan license: Apache-2.0 -allowed-tools: - - resources_get - - resources_list - - events_list - - pod_list - - pod_logs +allowed-tools: resources_get resources_list events_list pod_list pod_logs metadata: user_invocable: "true" --- diff --git a/rh-developer/skills/debug-scc/SKILL.md b/rh-developer/skills/debug-scc/SKILL.md index 3f305575..eeaa47ce 100644 --- a/rh-developer/skills/debug-scc/SKILL.md +++ b/rh-developer/skills/debug-scc/SKILL.md @@ -14,11 +14,7 @@ description: | model: inherit color: cyan license: Apache-2.0 -allowed-tools: - - resources_get - - resources_list - - events_list - - pod_list +allowed-tools: resources_get resources_list events_list pod_list metadata: user_invocable: "true" --- From 84ecc94a09e44e4cfa2987d4d0c57375efe64a2f Mon Sep 17 00:00:00 2001 From: Jordi Gil Date: Fri, 8 May 2026 13:21:17 -0400 Subject: [PATCH 6/7] fix(rh-developer): align MCP tool names with actual openshift MCP server MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tested against the pinned openshift-mcp-server image from PR #93. Corrected tool names to match the actual MCP tool registry: - pod_list → pods_list / pods_list_in_namespace - pod_logs → pods_log Co-authored-by: Cursor --- rh-developer/skills/debug-rbac/SKILL.md | 16 ++++++++-------- rh-developer/skills/debug-scc/SKILL.md | 6 +++--- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/rh-developer/skills/debug-rbac/SKILL.md b/rh-developer/skills/debug-rbac/SKILL.md index 7d2e7ff1..44d64814 100644 --- a/rh-developer/skills/debug-rbac/SKILL.md +++ b/rh-developer/skills/debug-rbac/SKILL.md @@ -14,7 +14,7 @@ description: | model: inherit color: cyan license: Apache-2.0 -allowed-tools: resources_get resources_list events_list pod_list pod_logs +allowed-tools: resources_get resources_list events_list pods_list pods_list_in_namespace pods_log metadata: user_invocable: "true" --- @@ -44,8 +44,8 @@ Diagnose RBAC permission failures on OpenShift by analyzing pod logs, readiness **Required MCP Tools:** - `resources_get` (from openshift) — Retrieve Deployment, Pod, ServiceAccount, Role, and RoleBinding details - `resources_list` (from openshift) — List Deployments, RoleBindings, and ClusterRoleBindings in a namespace -- `pod_list` (from openshift) — List pods for a Deployment -- `pod_logs` (from openshift) — Retrieve container logs to identify FORBIDDEN errors +- `pods_list` (from openshift) — List pods for a Deployment +- `pods_log` (from openshift) — Retrieve container logs to identify FORBIDDEN errors - `events_list` (from openshift) — Fetch warning events related to RBAC failures **Verification Steps:** @@ -139,7 +139,7 @@ Which deployment would you like me to debug? ### Step 2: Check Pod Status and Logs -**MCP Tool**: `pod_list` (from openshift) +**MCP Tool**: `pods_list` (from openshift) **Parameters**: - `namespace`: "" @@ -151,10 +151,10 @@ Then for each matching pod: **Parameters**: - `kind`: "Pod" (resource type) -- `name`: "" (from pod_list) +- `name`: "" (from pods_list) - `namespace`: "" -**MCP Tool**: `pod_logs` (from openshift) +**MCP Tool**: `pods_log` (from openshift) **Parameters**: - `name`: "" @@ -430,8 +430,8 @@ Select an option: ### Required MCP Tools - `resources_get` (from openshift) — Retrieve individual resource details (Deployment, Pod, ServiceAccount, Role, RoleBinding) - `resources_list` (from openshift) — List resources by kind in a namespace (Deployments, RoleBindings, ClusterRoleBindings) -- `pod_list` (from openshift) — List pods matching label selectors -- `pod_logs` (from openshift) — Retrieve container logs for FORBIDDEN error analysis +- `pods_list` (from openshift) — List pods matching label selectors +- `pods_log` (from openshift) — Retrieve container logs for FORBIDDEN error analysis - `events_list` (from openshift) — Fetch events filtered by involved object ### Related Skills diff --git a/rh-developer/skills/debug-scc/SKILL.md b/rh-developer/skills/debug-scc/SKILL.md index eeaa47ce..8c3dab71 100644 --- a/rh-developer/skills/debug-scc/SKILL.md +++ b/rh-developer/skills/debug-scc/SKILL.md @@ -14,7 +14,7 @@ description: | model: inherit color: cyan license: Apache-2.0 -allowed-tools: resources_get resources_list events_list pod_list +allowed-tools: resources_get resources_list events_list pods_list pods_list_in_namespace metadata: user_invocable: "true" --- @@ -45,7 +45,7 @@ Diagnose OpenShift SCC violations that block pod creation by analyzing security - `resources_get` (from openshift) — Retrieve Deployment, ReplicaSet, and ServiceAccount details - `resources_list` (from openshift) — List Deployments, ReplicaSets, and ServiceAccounts in a namespace - `events_list` (from openshift) — Fetch FailedCreate and SCC rejection events -- `pod_list` (from openshift) — List pods for a Deployment +- `pods_list` (from openshift) — List pods for a Deployment **Verification Steps:** 1. Check `openshift` server is configured in `mcps.json` @@ -441,7 +441,7 @@ Select an option: - `resources_get` (from openshift) — Retrieve individual resource details (Deployment, ReplicaSet, ServiceAccount) - `resources_list` (from openshift) — List resources by kind in a namespace - `events_list` (from openshift) — Fetch events filtered by involved object -- `pod_list` (from openshift) — List pods matching label selectors +- `pods_list` (from openshift) — List pods matching label selectors ### Related Skills - `/debug-pod` — If pods exist but are crashing (CrashLoopBackOff, OOMKilled) From 6afb7e0bff219c7ce23523da40e3028378246fa6 Mon Sep 17 00:00:00 2001 From: Jordi Gil Date: Tue, 19 May 2026 08:16:55 -0400 Subject: [PATCH 7/7] fix: address review feedback on debug-scc and debug-rbac skills - Remove unused pods_list_in_namespace from allowed-tools in both skills - Fix broken golden-transcript links: pin to commit SHA on main instead of deleted feature branch Co-authored-by: Cursor --- rh-developer/skills/debug-rbac/SKILL.md | 4 ++-- rh-developer/skills/debug-scc/SKILL.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/rh-developer/skills/debug-rbac/SKILL.md b/rh-developer/skills/debug-rbac/SKILL.md index 44d64814..abd81600 100644 --- a/rh-developer/skills/debug-rbac/SKILL.md +++ b/rh-developer/skills/debug-rbac/SKILL.md @@ -14,7 +14,7 @@ description: | model: inherit color: cyan license: Apache-2.0 -allowed-tools: resources_get resources_list events_list pods_list pods_list_in_namespace pods_log +allowed-tools: resources_get resources_list events_list pods_list pods_log metadata: user_invocable: "true" --- @@ -406,7 +406,7 @@ oc get pods -n -l app= -o wide ### Related Documentation - [OpenShift RBAC documentation](https://docs.openshift.com/container-platform/latest/authentication/using-rbac.html) -- [Kubernaut RBAC failure golden transcript](https://github.com/jordigilh/kubernaut-demo-scenarios/blob/feature/v1.4-new-scenarios/golden-transcripts/rbac-failure-rbacpolicydenied.json) +- [Kubernaut RBAC failure golden transcript](https://github.com/jordigilh/kubernaut-demo-scenarios/blob/d3447fce75e51e4486ebb5e73dbe2ad9ecf552bf/golden-transcripts/rbac-failure-rbacpolicydenied.json) --- diff --git a/rh-developer/skills/debug-scc/SKILL.md b/rh-developer/skills/debug-scc/SKILL.md index 8c3dab71..960753ce 100644 --- a/rh-developer/skills/debug-scc/SKILL.md +++ b/rh-developer/skills/debug-scc/SKILL.md @@ -14,7 +14,7 @@ description: | model: inherit color: cyan license: Apache-2.0 -allowed-tools: resources_get resources_list events_list pods_list pods_list_in_namespace +allowed-tools: resources_get resources_list events_list pods_list metadata: user_invocable: "true" --- @@ -416,7 +416,7 @@ oc rollout undo deployment/ -n ### Related Documentation - [OpenShift SCC documentation](https://docs.openshift.com/container-platform/latest/authentication/managing-security-context-constraints.html) -- [Kubernaut SCC violation golden transcript](https://github.com/jordigilh/kubernaut-demo-scenarios/blob/feature/v1.4-new-scenarios/golden-transcripts/scc-violation-sccviolationpodblocked.json) +- [Kubernaut SCC violation golden transcript](https://github.com/jordigilh/kubernaut-demo-scenarios/blob/d3447fce75e51e4486ebb5e73dbe2ad9ecf552bf/golden-transcripts/scc-violation-sccviolationpodblocked.json) ---