From 462cae792928a01c0b4d568fc5a2d2b21878c53b Mon Sep 17 00:00:00 2001 From: Daniele Martinoli Date: Tue, 24 Feb 2026 17:42:47 +0100 Subject: [PATCH 01/20] Enhance pack card display and search functionality; add plugin titles - Updated the pack card title to prioritize displaying the plugin title, followed by the plugin name and pack name. - Enhanced the search functionality to include searching by plugin title in addition to name, description, skills, and agents. - Introduced a new JSON file for plugin titles to improve consistency and clarity in the UI. - Added a new section in the pack details modal to display the plugin name if it differs from the title, improving user awareness of plugin identity. Signed-off-by: Daniele Martinoli --- docs/app.js | 30 +- docs/plugins.json | 17 + ocp-admin/.claude-plugin/plugin.json | 2 +- rh-sre/.claude-plugin/plugin.json | 2 +- rh-sre/.mcp.json | 12 +- rh-sre/README.md | 4 +- rh-sre/agents/remediator.md | 171 ++- rh-sre/docs/ansible/aap-job-execution.md | 532 ++++++++ .../docs/ansible/playbook-integration-aap.md | 667 ++++++++++ .../testing/aap-integration-test-guide.md | 649 ++++++++++ rh-sre/skills/mcp-aap-validator/SKILL.md | 51 +- rh-sre/skills/playbook-executor/SKILL.md | 1153 ++++++++++++----- rh-sre/skills/playbook-generator/SKILL.md | 111 +- .../.claude-plugin/plugin.json | 2 +- rh-virt/.claude-plugin/plugin.json | 2 +- scripts/generate_pack_data.py | 68 +- 16 files changed, 3045 insertions(+), 428 deletions(-) create mode 100644 docs/plugins.json create mode 100644 rh-sre/docs/ansible/aap-job-execution.md create mode 100644 rh-sre/docs/ansible/playbook-integration-aap.md create mode 100644 rh-sre/docs/testing/aap-integration-test-guide.md diff --git a/docs/app.js b/docs/app.js index 28c321bf..f6a5061b 100644 --- a/docs/app.js +++ b/docs/app.js @@ -130,7 +130,7 @@ function createPackCard(pack) { } const titleText = document.createElement('span'); - titleText.textContent = pack.plugin.name || pack.name; + titleText.textContent = pack.plugin.title || pack.plugin.name || pack.name; h3.appendChild(titleText); div.appendChild(h3); @@ -360,10 +360,11 @@ function handleSearch(event) { // Filter packs const filteredPacks = allPacks.filter(pack => { - // Search in pack name, description, skills, agents + // Search in pack name, title, description, skills, agents const searchText = [ pack.name, pack.plugin.name, + pack.plugin.title, pack.plugin.description, ...pack.skills.map(s => s.name + ' ' + s.description), ...pack.agents.map(a => a.name + ' ' + a.description) @@ -451,7 +452,7 @@ function showPackDetails(packName) { titleGroup.className = 'modal-title-group'; const h2 = document.createElement('h2'); - h2.textContent = pack.plugin.name || pack.name; + h2.textContent = pack.plugin.title || pack.plugin.name || pack.name; titleGroup.appendChild(h2); // Owner subtitle @@ -512,6 +513,29 @@ function showPackDetails(packName) { header.appendChild(desc); } + // Plugin name field (if different from title) + if (pack.plugin.name && pack.plugin.name !== pack.plugin.title) { + const pluginNameDiv = document.createElement('div'); + pluginNameDiv.style.marginTop = '1rem'; + pluginNameDiv.style.fontSize = '0.9rem'; + pluginNameDiv.style.color = 'var(--text-muted)'; + + const label = document.createElement('strong'); + label.textContent = 'Plugin name: '; + label.style.color = 'var(--text-primary)'; + pluginNameDiv.appendChild(label); + + const nameCode = document.createElement('code'); + nameCode.textContent = pack.plugin.name; + nameCode.style.backgroundColor = 'rgba(238, 0, 0, 0.1)'; + nameCode.style.padding = '0.25rem 0.5rem'; + nameCode.style.borderRadius = '4px'; + nameCode.style.fontSize = '0.85rem'; + pluginNameDiv.appendChild(nameCode); + + header.appendChild(pluginNameDiv); + } + details.appendChild(header); // Create modal body diff --git a/docs/plugins.json b/docs/plugins.json new file mode 100644 index 00000000..4d89311a --- /dev/null +++ b/docs/plugins.json @@ -0,0 +1,17 @@ +{ + "rh-sre": { + "title": "Red Hat SRE Agentic Skills Collection" + }, + "rh-virt": { + "title": "Red Hat Virtualization Agentic Collection" + }, + "rh-developer": { + "title": "Red Hat Developer Agentic Skills Collection" + }, + "rh-ocp-admin": { + "title": "Red Hat OpenShift Administration Agentic Skills Collection" + }, + "rh-support-engineer": { + "title": "Red Hat Support Engineer Agentic Skills Collection" + } +} \ No newline at end of file diff --git a/ocp-admin/.claude-plugin/plugin.json b/ocp-admin/.claude-plugin/plugin.json index d0931c07..d71ca0fe 100644 --- a/ocp-admin/.claude-plugin/plugin.json +++ b/ocp-admin/.claude-plugin/plugin.json @@ -1,5 +1,5 @@ { - "name": "OpenShift Administration Agentic Skills Collection", + "name": "rh-ocp-admin", "version": "1.0.0", "description": "Automation capabilities for OpenShift Container Platform cluster management, workload orchestration, security policies, and operational tasks.", "author": { diff --git a/rh-sre/.claude-plugin/plugin.json b/rh-sre/.claude-plugin/plugin.json index 47050c59..3731cfd2 100644 --- a/rh-sre/.claude-plugin/plugin.json +++ b/rh-sre/.claude-plugin/plugin.json @@ -1,5 +1,5 @@ { - "name": "Red Hat SRE Agentic Skills Collection", + "name": "rh-sre", "version": "1.0.0", "description": "Site reliability engineering tools and automation for managing Red Hat platforms and infrastructure.", "author": { diff --git a/rh-sre/.mcp.json b/rh-sre/.mcp.json index 0bbcee23..662b7fff 100644 --- a/rh-sre/.mcp.json +++ b/rh-sre/.mcp.json @@ -25,26 +25,18 @@ }, "aap-mcp-job-management": { "type": "http", - "url": "https://${AAP_SERVER}/job_management/mcp", + "url": "https://${AAP_MCP_SERVER}/job_management/mcp", "headers": { "Authorization": "Bearer ${AAP_API_TOKEN}" }, - "env": { - "AAP_SERVER": "${AAP_SERVER}", - "AAP_API_TOKEN": "${AAP_API_TOKEN}" - }, "description": "Ansible Automation Platform (AAP) job management MCP server for managing job templates, job executions, and workflows" }, "aap-mcp-inventory-management": { "type": "http", - "url": "https://${AAP_SERVER}/inventory_management/mcp", + "url": "https://${AAP_MCP_SERVER}/inventory_management/mcp", "headers": { "Authorization": "Bearer ${AAP_API_TOKEN}" }, - "env": { - "AAP_SERVER": "${AAP_SERVER}", - "AAP_API_TOKEN": "${AAP_API_TOKEN}" - }, "description": "Ansible Automation Platform (AAP) inventory management MCP server for managing inventories, hosts, and groups" } } diff --git a/rh-sre/README.md b/rh-sre/README.md index 51a55346..8be80be9 100644 --- a/rh-sre/README.md +++ b/rh-sre/README.md @@ -232,8 +232,8 @@ Generate Ansible remediation playbooks following Red Hat best practices. - Includes error handling and rollback steps - Follows Red Hat standards -### 6. **playbook-executor** - Ansible Playbook Execution -Execute Ansible playbooks and track job status (requires separate ansible-mcp-server configuration). +### 6. **playbook-executor** - AAP Playbook Execution +Execute Ansible playbooks via AAP (Ansible Automation Platform) with dry-run capabilities, real-time monitoring, and comprehensive reporting. **Use when:** - "Execute this remediation playbook" diff --git a/rh-sre/agents/remediator.md b/rh-sre/agents/remediator.md index dd84ef0c..60a5eaeb 100644 --- a/rh-sre/agents/remediator.md +++ b/rh-sre/agents/remediator.md @@ -80,6 +80,26 @@ tools: ["All"] You are a Red Hat remediation specialist helping SREs analyze, prioritize, and remediate CVE vulnerabilities on RHEL systems. +## ๐Ÿšจ CRITICAL: You MUST Use Skills via Tool Calls + +**MANDATORY REQUIREMENT**: You MUST invoke skills using the Skill tool, NOT by generating text responses. + +โŒ **WRONG** - Generating text pretending to use a skill: +``` +I'll invoke the cve-impact skill to analyze the CVE... +[then generating text without actually calling the tool] +``` + +โœ… **CORRECT** - Actually invoking skills using slash command format: +``` +Execute the `/cve-impact` skill: +"Analyze CVE-2026-23116 and assess its impact on the fleet" +``` + +**Verification**: After EVERY workflow step, check your tool use count. If you have "0 tool uses", you are doing it WRONG and must start over using actual tool calls. + +**Skill Reference Format**: Use the slash command format (e.g., `/cve-impact`, `/playbook-generator`) to invoke skills, matching the pattern used in the rh-developer collection. + ## Your Core Responsibilities 1. **Impact Analysis** - Assess CVE severity, affected systems, and business risk @@ -109,14 +129,14 @@ When a user requests CVE analysis or remediation, orchestrate skills in this wor ### 1. Impact Analysis (If Requested or Needed) -**Invoke the cve-impact skill** using the Skill tool: +**๐Ÿ”ง ACTION REQUIRED: Execute the `/cve-impact` skill** +Invoke the `/cve-impact` skill with the instruction: ``` -Skill: cve-impact -Args: CVE-ID [system-filter] +"Analyze CVE-XXXX-YYYY and assess its impact on affected systems" ``` -The skill will: +**Expected behavior**: The skill will: - Consult `docs/insights/vulnerability-logic.md` for Red Hat Lightspeed CVE assessment methodology - Consult `docs/references/cvss-scoring.md` for CVSS interpretation guidelines - Use `get_cve` (lightspeed-mcp vulnerability toolset) to retrieve CVE metadata @@ -129,14 +149,14 @@ The skill will: ### 2. Validate CVE -**Invoke the cve-validation skill** using the Skill tool: +**๐Ÿ”ง ACTION REQUIRED: Execute the `/cve-validation` skill** +Invoke the `/cve-validation` skill with the instruction: ``` -Skill: cve-validation -Args: CVE-ID +"Validate CVE-XXXX-YYYY format, existence, and remediation availability" ``` -The skill will: +**Expected behavior**: The skill will: - Validate CVE format (CVE-YYYY-NNNNN) - Check CVE exists in Red Hat Lightspeed database - Verify CVSS score, severity, and affected packages @@ -147,14 +167,14 @@ The skill will: ### 3. Gather Context -**Invoke the system-context skill** using the Skill tool: +**๐Ÿ”ง ACTION REQUIRED: Execute the `/system-context` skill** +Invoke the `/system-context` skill with the instruction: ``` -Skill: system-context -Args: CVE-ID [system-filter] +"Gather system context for CVE-XXXX-YYYY: identify affected systems, RHEL versions, and deployment environments" ``` -The skill will: +**Expected behavior**: The skill will: - Identify affected systems using `get_cve_systems` (lightspeed-mcp vulnerability toolset) - Gather detailed system information using `get_host_details` (lightspeed-mcp inventory toolset) - Analyze RHEL versions, environments (dev/staging/prod), and system criticality @@ -165,14 +185,16 @@ The skill will: ### 4. Generate Playbook -**Invoke the playbook-generator skill** using the Skill tool: +**๐Ÿ”ง ACTION REQUIRED: Execute the `/playbook-generator` skill** + +**CRITICAL**: This is where most agents fail. You MUST actually invoke the `/playbook-generator` skill, NOT generate playbook text yourself. +Invoke the `/playbook-generator` skill with the instruction: ``` -Skill: playbook-generator -Args: CVE-ID system-list [cve-type] [strategy] +"Generate an Ansible remediation playbook for CVE-XXXX-YYYY targeting systems [list of system UUIDs]. Apply Red Hat best practices and RHEL-specific patterns from documentation." ``` -The skill will: +**Expected behavior**: The skill will: - Consult documentation (cve-remediation-templates.md, package-management.md) - Detect CVE type (kernel, service, SELinux, batch) automatically - Generate playbook using `create_vulnerability_playbook` (lightspeed-mcp remediations toolset) @@ -180,66 +202,68 @@ The skill will: - Validate playbook YAML syntax and completeness - Return production-ready Ansible playbook -**Your role**: Present the generated playbook to the user and IMMEDIATELY ask for execution confirmation. DO NOT provide manual execution options first - the automated execution via playbook-executor skill is the primary workflow. +**Your role**: Present the generated playbook to the user. -### 5. Execute Playbook (With User Confirmation) +**๐Ÿšจ CRITICAL**: The playbook-generator skill **ONLY GENERATES** playbooks. It does **NOT EXECUTE** them. After generation, you MUST proceed to Step 5 to invoke the playbook-executor skill for execution. -**CRITICAL**: After generating the playbook, you MUST: - -1. **Show playbook preview** to the user (first 20-30 lines or key sections) -2. **Ask for execution confirmation**: "Would you like me to execute this playbook now?" -3. **If user approves** โ†’ Invoke playbook-executor skill -4. **If user declines** โ†’ Provide alternative execution options (see below) - -**Automated Execution (Primary Method)**: - -When user approves, invoke the **playbook-executor skill** using the Skill tool: +### 5. Execute Playbook (With User Confirmation) -``` -Skill: playbook-executor -Args: playbook-yaml-content CVE-ID -``` +**๐Ÿšจ CRITICAL HANDOFF**: The playbook-generator skill **GENERATED** the playbook. Now you MUST invoke the playbook-executor skill to **EXECUTE** it via AAP MCP. -The skill will: -- Create job template in AAP (if not already exists) using `job-template-creator` skill -- Launch job from template using `job_templates_launch_retrieve` (aap-mcp-job-management) -- Receive job_id and initial status -- Poll job status using `jobs_retrieve` periodically -- Track status transitions until completion -- Alternative: Use `playbook-executor` skill for direct execution (requires separate configuration) -- Report execution results with job details (duration, timestamps) -- Clean up temporary playbook file from `/tmp/` after completion -- Suggest verification using remediation-verifier skill +**โŒ DO NOT**: +- Run `ansible-playbook` command via Shell tool +- Execute playbooks using local Ansible CLI +- Attempt any direct playbook execution -**Your role**: Monitor the skill's execution progress. When the skill reports COMPLETED status, congratulate the user and suggest verification. If execution fails, provide the skill's troubleshooting guidance and offer to retry. +**โœ… ALWAYS**: +- Invoke `/playbook-executor` skill for all playbook execution +- Use AAP MCP tools (not ansible-playbook CLI) +- Let playbook-executor handle job monitoring and status -**Alternative Execution Options** (If user declines automated execution): +**User Confirmation Flow**: -If the user prefers manual execution, provide these options: +1. **Show playbook preview** - Display key tasks and explain what will happen +2. **Offer dry-run** - Ask: "Run dry-run first via AAP? (recommended)" +3. **If dry-run approved** - Invoke playbook-executor with dry-run mode +4. **Show dry-run results** - Display simulated changes from AAP +5. **If execution approved** - Invoke playbook-executor for actual execution +6. **Monitor progress** - playbook-executor streams AAP job events in real-time +7. **Generate report** - playbook-executor provides comprehensive execution summary -**Manual CLI Execution**: -- Prerequisites: ansible-core 2.9+, SSH access, sudo privileges -- Command: `ansible-playbook -i inventory remediation-CVE-XXXX-YYYY.yml --become` -- Save playbook to file first: `cat > remediation-CVE-XXXX-YYYY.yml << 'EOF' ... EOF` +**๐Ÿ”ง ACTION REQUIRED: Execute the `/playbook-executor` skill** -**Ansible Automation Platform (AAP)**: -- Import playbook to AAP project repository -- Create job template with inventory and credentials -- Execute via AAP web console +Invoke the `/playbook-executor` skill with the instruction: +``` +"Execute the generated playbook for CVE-XXXX-YYYY on target systems using AAP job template [ID]. Start with dry-run (check mode) if user requested it. Monitor job status until completion and report results." +``` -**Ansible Tower**: -- Similar to AAP workflow for legacy Tower installations +**Expected behavior**: The skill will: +- Validate AAP MCP server availability (via mcp-aap-validator) +- Select or guide creation of suitable job template +- Add playbook to AAP project repository +- Offer dry-run execution (job_type="check") +- If approved, launch actual execution (job_type="run") +- Poll job status with `jobs_retrieve` +- Stream progress from `jobs_job_events_list` +- Generate comprehensive report with: + - Per-host statistics (`jobs_job_host_summaries_list`) + - Full console output (`jobs_stdout_retrieve`) + - Task timeline + - AAP URL for detailed view +- Handle errors with specific troubleshooting + +**Your role**: After execution completes successfully, suggest verification with remediation-verifier skill. If execution fails, present the skill's error report and offer to relaunch for failed hosts only. ### 6. Verify Deployment (Optional) -**Invoke the remediation-verifier skill** using the Skill tool (if user requests verification): +**๐Ÿ”ง ACTION REQUIRED: Execute the `/remediation-verifier` skill** (if user requests verification) +Invoke the `/remediation-verifier` skill with the instruction: ``` -Skill: remediation-verifier -Args: CVE-ID system-list +"Verify remediation success for CVE-XXXX-YYYY on systems [list of system UUIDs]. Check CVE status, package versions, and service health." ``` -The skill will: +**Expected behavior**: The skill will: - Check CVE status in Lightspeed using `get_cve` and `get_cve_systems` - Verify package versions were updated using `get_host_details` - Confirm affected services are running properly @@ -296,20 +320,25 @@ Estimated Execution Time: ~X minutes ## Important Reminders -- **Orchestrate skills, don't call MCP tools directly** - Always use the Skill tool to invoke specialized skills for each workflow step: - - Step 1: cve-impact skill for CVE risk assessment - - Step 2: cve-validation skill for CVE validation - - Step 3: system-context skill for gathering system information - - Step 4: playbook-generator skill for creating remediation playbooks - - Step 5: playbook-executor skill for executing playbooks (AFTER user confirmation) - - Step 6: remediation-verifier skill for post-remediation verification +- **๐Ÿšจ YOU MUST USE ACTUAL TOOL CALLS** - Do NOT generate text responses pretending to invoke skills. You MUST actually invoke the skills using the slash command format shown in each workflow step above. Check your tool use count - if it's 0, you're doing it wrong. + +- **Orchestrate skills, don't call MCP tools directly** - Always invoke specialized skills using the slash command format for each workflow step: + - Step 1: `/cve-impact` for CVE risk assessment + - Step 2: `/cve-validation` for CVE validation + - Step 3: `/system-context` for gathering system information + - Step 4: `/playbook-generator` for creating remediation playbooks + - Step 5: `/playbook-executor` for executing playbooks (AFTER user confirmation) + - Step 6: `/remediation-verifier` for post-remediation verification + - **Skills handle documentation** - Skills automatically consult relevant docs (cve-remediation-templates.md, package-management.md) and use MCP tools. You don't need to read docs or call tools directly. -- Test in non-production environments first -- Back up systems before remediation -- Schedule maintenance windows for critical systems -- Verify remediation success after execution -- Document the remediation for compliance/audit purposes - **Always ask for execution confirmation** - Before invoking playbook-executor skill, show the playbook preview and explicitly ask: "Would you like me to execute this playbook now?" Wait for user approval. +- **Safety practices**: + - Test in non-production environments first + - Back up systems before remediation + - Schedule maintenance windows for critical systems + - Verify remediation success after execution + - Document the remediation for compliance/audit purposes + Remember: Your goal is to make CVE remediation efficient, safe, and reliable for SREs managing RHEL systems. diff --git a/rh-sre/docs/ansible/aap-job-execution.md b/rh-sre/docs/ansible/aap-job-execution.md new file mode 100644 index 00000000..ba71b423 --- /dev/null +++ b/rh-sre/docs/ansible/aap-job-execution.md @@ -0,0 +1,532 @@ +--- +title: AAP Job Execution Guide +category: ansible +sources: + - title: Red Hat Ansible Automation Platform Documentation + url: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6 + date_accessed: 2024-01-20 + - title: AAP Job Templates + url: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/using_automation_execution/controller-job-templates + date_accessed: 2024-01-20 +tags: [aap, job-execution, playbook, dry-run, check-mode] +semantic_keywords: [aap job execution, ansible check mode, dry-run remediation, job template requirements, aap url structure] +use_cases: [playbook-executor, remediator] +related_docs: [playbook-integration-aap.md, cve-remediation-templates.md] +last_updated: 2024-01-20 +--- + +# AAP Job Execution Guide + +## Overview + +This guide covers executing Ansible remediation playbooks through AAP (Ansible Automation Platform), including dry-run testing, job monitoring, and result interpretation. + +## Job Template Requirements for Remediation + +### Minimum Requirements + +For a job template to be suitable for CVE remediation, it must have: + +1. **Inventory**: Contains target systems identified in CVE analysis +2. **Project**: Contains or can receive remediation playbooks from Git +3. **Credentials**: + - Machine credential (SSH) for host access + - Privilege escalation enabled (sudo/become) +4. **Execution Environment**: Compatible with RHEL versions of target systems + +### Recommended Settings + +- **Prompt on Launch - Variables**: Allow passing CVE-specific parameters +- **Prompt on Launch - Limit**: Allow targeting specific hosts at runtime +- **Job Type**: Should support both "Run" and "Check" modes +- **Verbosity**: Set to at least "1 (Verbose)" for debugging +- **Timeout**: Set generous timeout (30+ minutes for large-scale remediations) +- **Enable Webhook**: Optional for CI/CD integration + +### Example Template Configuration + +```yaml +Name: CVE Remediation Template +Job Type: Run +Inventory: Production Servers +Project: Remediation Playbooks +Playbook: playbooks/remediation/remediation-template.yml +Credentials: + - SSH Credential (Machine) + - Privilege Escalation: Yes +Prompt on Launch: + - Variables: Yes + - Limit: Yes +Options: + - Enable Privilege Escalation: Yes + - Allow Simultaneous: No +``` + +## Dry-Run vs Production Execution + +### Dry-Run (Check Mode) + +**Purpose**: Simulate playbook execution without making actual changes. + +**Use When**: +- Testing new remediation playbooks +- Validating changes before production +- Identifying potential issues (permissions, package availability, dependencies) +- Understanding impact scope + +**How to Execute**: +```json +{ + "job_type": "check", + "extra_vars": {...} +} +``` + +**What It Does**: +- Gathers facts from target systems +- Evaluates conditionals and variables +- Simulates task execution +- Reports **would change** counts +- Does NOT apply any changes + +**Limitations**: +- Some modules don't support check mode (command, shell, raw) +- Services that would restart are not actually restarted +- Can't detect runtime failures that occur during actual execution +- Package dependencies may not be fully validated + +**Output Interpretation**: +``` +PLAY RECAP ************************************************************* +prod-web-01 : ok=8 changed=3 unreachable=0 failed=0 +prod-web-02 : ok=8 changed=3 unreachable=0 failed=0 +prod-web-03 : ok=8 changed=3 unreachable=0 failed=0 + +"changed=3" means 3 tasks WOULD make changes +"failed=0" means no errors detected in check mode +``` + +### Production Execution (Run Mode) + +**Purpose**: Apply actual changes to systems. + +**Use When**: +- Dry-run passed successfully +- User has approved changes +- Maintenance window scheduled (if required) +- Backups completed + +**How to Execute**: +```json +{ + "job_type": "run", + "extra_vars": {...} +} +``` + +**What It Does**: +- Executes all playbook tasks +- Applies actual changes (package updates, config modifications, service restarts) +- Reports real results +- Can trigger system reboots if specified + +**Best Practices**: +1. Always run dry-run first +2. Review dry-run results carefully +3. Ensure maintenance window if downtime expected +4. Have rollback plan ready +5. Monitor execution in real-time +6. Verify success after completion + +## Job Type Parameter + +### job_type: "check" + +**API Parameter**: +```json +{ + "id": "10", + "requestBody": { + "job_type": "check" + } +} +``` + +**Equivalent Command Line**: +```bash +ansible-playbook playbook.yml --check +``` + +**Behavior**: +- Runs in check mode (dry-run) +- No actual changes applied +- Reports what WOULD happen +- Useful for validation + +### job_type: "run" + +**API Parameter**: +```json +{ + "id": "10", + "requestBody": { + "job_type": "run" + } +} +``` + +**Equivalent Command Line**: +```bash +ansible-playbook playbook.yml +``` + +**Behavior**: +- Runs in execution mode +- Applies actual changes +- Reports what DID happen +- Production execution + +## Interpreting Job Results + +### Job Status Values + +| Status | Meaning | Action | +|--------|---------|--------| +| `pending` | Job queued, not yet started | Wait for execution | +| `waiting` | Waiting for resources/dependencies | Monitor for start | +| `running` | Currently executing | Monitor progress | +| `successful` | Completed without errors | Verify changes | +| `failed` | Completed with errors | Review error logs | +| `error` | Job could not execute | Check configuration | +| `canceled` | User cancelled job | N/A | + +### Per-Host Statistics + +**ok**: Number of tasks that executed successfully without changes +**changed**: Number of tasks that made actual changes +**failed**: Number of tasks that failed +**unreachable**: Number of hosts that couldn't be reached +**rescued**: Number of tasks that recovered from failures +**ignored**: Number of failed tasks that were ignored + +**Success Criteria**: +- `failed: 0` AND `unreachable: 0` = Success +- `changed > 0` = Remediation applied changes +- `ok > 0` = Some tasks ran successfully + +**Failure Indicators**: +- `failed > 0` = At least one task failed +- `unreachable > 0` = Host connectivity issues +- `ok: 0` AND `changed: 0` = Nothing executed successfully + +### Task Timeline Interpretation + +Example timeline: +``` +1. โœ… Gather Facts (2s) +2. โœ… Check disk space (1s) +3. โœ… Backup configuration (3s) +4. โœ… Update package httpd (45s) +5. โš ๏ธ Restart httpd service (FAILED on prod-web-03) +6. โœ… Verify service status (2s) +``` + +**Analysis**: +- Tasks 1-4: Successful across all hosts +- Task 5: Failed on one host (prod-web-03) +- Task 6: Likely skipped on failed host + +**Action**: +- Investigate why httpd restart failed on prod-web-03 +- Check logs for that specific host +- Verify httpd package was actually installed +- Relaunch job for failed host after fixing issue + +## AAP URL Structure + +### Job Details URL + +**Format**: +``` +https://{AAP_SERVER}/#/jobs/playbook/{JOB_ID} +``` + +**Example**: +``` +https://aap.example.com/#/jobs/playbook/1235 +``` + +**What It Shows**: +- Real-time job status +- Live output stream +- Per-host statistics +- Task-level details +- Error messages +- Job parameters used + +### Template URL + +**Format**: +``` +https://{AAP_SERVER}/#/templates/job_template/{TEMPLATE_ID}/details +``` + +**Example**: +``` +https://aap.example.com/#/templates/job_template/10/details +``` + +### Project URL + +**Format**: +``` +https://{AAP_SERVER}/#/projects/{PROJECT_ID}/details +``` + +## Troubleshooting Common Execution Failures + +### Connection Failures + +**Symptoms**: +- `unreachable: 1` in host statistics +- "SSH timeout" errors +- "Connection refused" messages + +**Common Causes**: +1. SSH service not running on target +2. Firewall blocking port 22 +3. Network connectivity issues +4. Wrong SSH credentials + +**Troubleshooting Steps**: +```bash +# Test SSH connectivity +ssh -i /path/to/key user@target-host + +# Check SSH service +systemctl status sshd + +# Verify firewall rules +firewall-cmd --list-all + +# Test network connectivity +ping target-host +``` + +**Resolution**: +- Fix SSH service or network issues +- Update credentials in AAP +- Relaunch job after fixing + +### Permission Errors + +**Symptoms**: +- `failed: 1` with "Permission denied" errors +- "sudo: required but not available" messages +- "This command has to be run under the root user" errors + +**Common Causes**: +1. Privilege escalation not enabled +2. User doesn't have sudo rights +3. SELinux blocking operation +4. File permissions incorrect + +**Troubleshooting Steps**: +```bash +# Check sudo access +sudo -l + +# Test privilege escalation +sudo whoami + +# Check SELinux status +getenforce + +# Review SELinux denials +ausearch -m avc -ts recent +``` + +**Resolution**: +- Enable "Privilege Escalation" in job template +- Grant sudo rights to SSH user +- Adjust SELinux policies +- Fix file permissions + +### Package Manager Issues + +**Symptoms**: +- "No package X available" errors +- "Repository not found" messages +- "Dependency problems" errors +- Package installation timeouts + +**Common Causes**: +1. Repository not configured or unavailable +2. Package name incorrect +3. Network issues accessing repos +4. Insufficient disk space + +**Troubleshooting Steps**: +```bash +# Check repository configuration +dnf repolist + +# Test package availability +dnf info httpd + +# Check disk space +df -h + +# Verify repository URLs +dnf repolist -v +``` + +**Resolution**: +- Configure required repositories +- Verify package names +- Fix network issues +- Free up disk space + +### Service Restart Failures + +**Symptoms**: +- `failed: 1` on service restart tasks +- "Failed to restart X.service" errors +- "Unit not found" messages +- Service timeout errors + +**Common Causes**: +1. Service not installed +2. Configuration errors +3. Service dependencies not met +4. Systemd issues + +**Troubleshooting Steps**: +```bash +# Check if service exists +systemctl status httpd + +# Verify service file +systemctl cat httpd + +# Check service logs +journalctl -u httpd -n 50 + +# Test manual restart +systemctl restart httpd +``` + +**Resolution**: +- Ensure service is installed +- Fix configuration errors +- Start required dependencies first +- Review systemd logs + +### Disk Space Issues + +**Symptoms**: +- "No space left on device" errors +- Package installation failures +- Download failures + +**Common Causes**: +1. /var partition full +2. /tmp partition full +3. Log files consuming space + +**Troubleshooting Steps**: +```bash +# Check disk usage +df -h + +# Find large files +du -sh /var/* | sort -hr | head -10 + +# Check package cache size +du -sh /var/cache/dnf +``` + +**Resolution**: +- Clean package cache: `dnf clean all` +- Remove old logs: `journalctl --vacuum-time=7d` +- Remove unused packages: `dnf autoremove` + +## Job Monitoring Best Practices + +### Real-Time Monitoring + +1. **Watch AAP Web UI**: Real-time output and status +2. **Monitor Task Progress**: Track which tasks are running +3. **Check Per-Host Stats**: Identify failing hosts early +4. **Review Event Log**: See task-level events as they occur + +### Alert Configuration + +Configure notifications for: +- Job failures +- Long-running jobs (timeout warnings) +- Partial successes (some hosts failed) + +### Post-Execution Verification + +After job completes: +1. **Review per-host statistics**: Ensure all hosts succeeded +2. **Check full output**: Look for warnings or errors +3. **Verify actual changes**: Confirm packages updated, services restarted +4. **Run remediation-verifier**: Validate CVE status changed + +## Performance Optimization + +### Parallelism + +AAP can run tasks in parallel across multiple hosts. Configure: +- **Forks**: Number of parallel processes (default: 5) +- **Instance Groups**: Distribute jobs across multiple AAP nodes +- **Job Slicing**: Split large inventories into parallel jobs + +### Timeout Settings + +Set appropriate timeouts based on: +- Number of target systems +- Package size to download +- Network bandwidth +- System resources + +**Recommended Timeouts**: +- Small remediations (1-10 hosts): 10 minutes +- Medium remediations (10-50 hosts): 30 minutes +- Large remediations (50+ hosts): 60+ minutes + +## Security Considerations + +### Credential Management + +- Use AAP credential vault for secrets +- Rotate credentials regularly +- Limit credential scope to necessary hosts +- Never hardcode credentials in playbooks + +### Audit Logging + +AAP automatically logs: +- Who launched the job +- When it was launched +- What parameters were used +- Full execution output +- Final job status + +**Retention**: Configure appropriate log retention for compliance. + +### Change Control + +Integrate AAP jobs with change management: +- Require approval workflows for production +- Document job execution in change tickets +- Link jobs to CVE remediation tracking +- Maintain audit trail + +## Related Documentation + +- [Playbook Integration with AAP](./playbook-integration-aap.md) - How to add playbooks to AAP +- [CVE Remediation Templates](./cve-remediation-templates.md) - Playbook patterns +- [Package Management](../rhel/package-management.md) - RHEL package update best practices diff --git a/rh-sre/docs/ansible/playbook-integration-aap.md b/rh-sre/docs/ansible/playbook-integration-aap.md new file mode 100644 index 00000000..2f9935af --- /dev/null +++ b/rh-sre/docs/ansible/playbook-integration-aap.md @@ -0,0 +1,667 @@ +--- +title: Playbook Integration with AAP +category: ansible +sources: + - title: Red Hat Ansible Automation Platform Documentation + url: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6 + date_accessed: 2024-01-20 + - title: AAP Projects + url: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/using_automation_execution/controller-projects + date_accessed: 2024-01-20 +tags: [aap, playbooks, git-integration, project-sync, version-control] +semantic_keywords: [aap project integration, playbook git workflow, project sync process, playbook versioning] +use_cases: [playbook-executor, job-template-creator] +related_docs: [aap-job-execution.md, cve-remediation-templates.md] +last_updated: 2024-01-20 +--- + +# Playbook Integration with AAP + +## Overview + +This guide explains how to integrate generated Ansible remediation playbooks with AAP (Ansible Automation Platform) through Git-based projects. AAP requires playbooks to be stored in version control (Git) and synced to projects before execution. + +## Workflow Overview + +```mermaid +graph LR + A[Generate Playbook] --> B[Add to Git Repo] + B --> C[Commit & Push] + C --> D[Sync AAP Project] + D --> E[Playbook Available in AAP] + E --> F[Create/Use Job Template] + F --> G[Execute Playbook] +``` + +## Git Repository Structure + +### Recommended Directory Layout + +``` +ansible-remediation-playbooks/ +โ”œโ”€โ”€ README.md +โ”œโ”€โ”€ .gitignore +โ”œโ”€โ”€ playbooks/ +โ”‚ โ”œโ”€โ”€ remediation/ +โ”‚ โ”‚ โ”œโ”€โ”€ remediation-CVE-2025-49794.yml +โ”‚ โ”‚ โ”œโ”€โ”€ remediation-CVE-2025-50123.yml +โ”‚ โ”‚ โ””โ”€โ”€ remediation-template.yml +โ”‚ โ”œโ”€โ”€ verification/ +โ”‚ โ”‚ โ””โ”€โ”€ verify-remediation.yml +โ”‚ โ””โ”€โ”€ rollback/ +โ”‚ โ””โ”€โ”€ rollback-template.yml +โ”œโ”€โ”€ roles/ +โ”‚ โ”œโ”€โ”€ common/ +โ”‚ โ”œโ”€โ”€ package-update/ +โ”‚ โ””โ”€โ”€ service-restart/ +โ”œโ”€โ”€ inventories/ +โ”‚ โ”œโ”€โ”€ production.ini +โ”‚ โ”œโ”€โ”€ staging.ini +โ”‚ โ””โ”€โ”€ development.ini +โ”œโ”€โ”€ group_vars/ +โ”‚ โ””โ”€โ”€ all.yml +โ””โ”€โ”€ host_vars/ +``` + +**Key Directories**: +- `playbooks/remediation/` - CVE remediation playbooks +- `playbooks/verification/` - Post-remediation verification +- `playbooks/rollback/` - Rollback procedures +- `roles/` - Shared Ansible roles +- `inventories/` - Inventory files (optional if using AAP inventories) +- `group_vars/` and `host_vars/` - Variable files + +### .gitignore Configuration + +```gitignore +# Ansible +*.retry +.vault_pass +*.swp +*~ + +# Logs +*.log + +# Credentials (NEVER commit) +**/credentials.* +**/secrets.* +**/.env + +# Temporary files +/tmp/ +.DS_Store +``` + +## Adding Playbooks to Git Repository + +### Method 1: Existing Repository + +If you already have a Git repository configured in AAP: + +#### Step 1: Clone Repository (if not already local) + +```bash +# Clone the repository +git clone https://github.com/your-org/ansible-remediation-playbooks.git +cd ansible-remediation-playbooks +``` + +#### Step 2: Add Generated Playbook + +```bash +# Create remediation directory if it doesn't exist +mkdir -p playbooks/remediation + +# Add the playbook (replace with actual content) +cat > playbooks/remediation/remediation-CVE-2025-49794.yml << 'EOF' +--- +- name: Remediate CVE-2025-49794 + hosts: all + become: true + + tasks: + - name: Check disk space + # ... playbook content ... +EOF +``` + +#### Step 3: Commit Changes + +```bash +# Stage the new playbook +git add playbooks/remediation/remediation-CVE-2025-49794.yml + +# Create descriptive commit message +git commit -m "Add remediation playbook for CVE-2025-49794 + +- Target CVE: CVE-2025-49794 (Critical, CVSS 9.8) +- Affected package: httpd +- Remediation: Update to httpd-2.4.57-8.el9 +- Target systems: Production web servers +- Requires: Brief service restart (~10s downtime) +" +``` + +#### Step 4: Push to Remote + +```bash +# Push to main branch (or your default branch) +git push origin main +``` + +#### Step 5: Sync AAP Project + +**Via AAP Web UI**: +1. Navigate to **Automation Execution** โ†’ **Projects** +2. Find your project (e.g., "Remediation Playbooks") +3. Click the **Sync** button (๐Ÿ”„ icon) +4. Wait for status to change to "Successful" (green checkmark) +5. Verify playbook appears in project's playbook list + +**Via AAP API** (if available): +```bash +curl -X POST \ + "${AAP_SERVER}/api/controller/v2/projects/${PROJECT_ID}/update/" \ + -H "Authorization: Bearer ${AAP_API_TOKEN}" +``` + +### Method 2: New Repository + +If you need to create a new repository for remediation playbooks: + +#### Step 1: Initialize Local Repository + +```bash +# Create project directory +mkdir ansible-remediation-playbooks +cd ansible-remediation-playbooks + +# Initialize Git +git init +``` + +#### Step 2: Create Directory Structure + +```bash +# Create directory structure +mkdir -p playbooks/{remediation,verification,rollback} +mkdir -p roles +mkdir -p inventories +mkdir -p {group_vars,host_vars} +``` + +#### Step 3: Create README + +```bash +cat > README.md << 'EOF' +# Ansible Remediation Playbooks + +CVE remediation playbooks for Red Hat Enterprise Linux systems. + +## Directory Structure + +- `playbooks/remediation/` - CVE remediation playbooks +- `playbooks/verification/` - Post-remediation verification +- `playbooks/rollback/` - Rollback procedures +- `roles/` - Shared Ansible roles +- `inventories/` - Inventory files (if not using AAP inventories) + +## Naming Convention + +Remediation playbooks: `remediation-CVE-YYYY-NNNNN.yml` + +## Usage + +Playbooks are executed via AAP job templates. See internal documentation +for execution procedures. + +## Best Practices + +1. Always test in non-production first +2. Review playbook in dry-run (check) mode +3. Backup systems before remediation +4. Verify remediation success after execution +5. Document changes in commit messages +EOF +``` + +#### Step 4: Create .gitignore + +```bash +cat > .gitignore << 'EOF' +*.retry +.vault_pass +*.swp +*~ +*.log +**/credentials.* +**/secrets.* +**/.env +/tmp/ +.DS_Store +EOF +``` + +#### Step 5: Add First Playbook + +```bash +# Add your generated playbook +cat > playbooks/remediation/remediation-CVE-2025-49794.yml << 'EOF' +# [Your playbook content here] +EOF +``` + +#### Step 6: Initial Commit + +```bash +# Stage all files +git add . + +# Create initial commit +git commit -m "Initial commit: Add remediation playbooks structure + +- Directory structure for remediation, verification, rollback +- README with project documentation +- .gitignore for security +- First remediation playbook: CVE-2025-49794 +" +``` + +#### Step 7: Create Remote Repository + +**On GitHub**: +1. Go to https://github.com/new +2. Enter repository name: `ansible-remediation-playbooks` +3. Choose visibility (Private recommended for security) +4. **Do NOT** initialize with README (you already have one) +5. Click "Create repository" +6. Copy the repository URL + +**On GitLab**: +1. Go to "New Project" +2. Enter project name +3. Choose visibility +4. **Uncheck** "Initialize with README" +5. Create project +6. Copy the repository URL + +#### Step 8: Connect and Push + +```bash +# Add remote +git remote add origin + +# Rename branch to main (if needed) +git branch -M main + +# Push to remote +git push -u origin main +``` + +#### Step 9: Add Project to AAP + +**Via AAP Web UI**: +1. Navigate to **Automation Execution** โ†’ **Projects** +2. Click **Add** button +3. Fill in project form: + - **Name**: "Remediation Playbooks" + - **Organization**: Select your organization + - **Source Control Type**: Git + - **Source Control URL**: `` + - **Source Control Branch**: `main` + - **Source Control Credential**: (if private repo) +4. Click **Save** +5. AAP will automatically sync +6. Wait for status "Successful" + +## Project Sync Process + +### Understanding Project Sync + +**What Happens During Sync**: +1. AAP connects to Git repository +2. Fetches latest commits from specified branch +3. Downloads playbooks and related files +4. Updates project playbook list +5. Makes playbooks available for job templates + +**Sync Triggers**: +- Manual: Click Sync button in AAP Web UI +- Automatic: Configured update interval (optional) +- Webhook: Git push triggers AAP sync (optional) +- Pre-launch: Job template can auto-sync before execution + +### Sync Verification + +**Check Sync Status**: +```bash +# Via MCP tool +projects_list(search="Remediation") + +# Look for: +# - status: "successful" +# - scm_revision: Latest commit SHA +# - last_update_failed: false +``` + +**Verify Playbook Available**: +1. In AAP Web UI, go to Projects +2. Click on your project +3. View "Playbooks" tab +4. Confirm new playbook appears in list + +### Troubleshooting Sync Issues + +**Sync Failed - Authentication**: +``` +Error: Authentication failed +``` +**Cause**: Invalid or missing Git credentials +**Fix**: +- Update Source Control Credential in project settings +- Verify credential has read access to repository +- For private repos, ensure SSH key or token is valid + +**Sync Failed - Network**: +``` +Error: Failed to connect to repository +``` +**Cause**: Network connectivity issues or firewall +**Fix**: +- Verify repository URL is correct +- Check AAP server can reach Git server +- Review firewall rules + +**Sync Failed - Branch Not Found**: +``` +Error: Branch 'main' not found +``` +**Cause**: Specified branch doesn't exist +**Fix**: +- Verify branch name in project settings +- Check repository has commits on that branch +- Update branch name to match repository + +**Playbook Not Appearing**: +``` +Sync successful but playbook not in list +``` +**Cause**: Playbook not in correct path or format +**Fix**: +- Verify playbook is in repository root or subdirectory +- Check playbook has .yml or .yaml extension +- Ensure playbook is valid Ansible syntax +- Re-sync project after fixing + +## Playbook Versioning Strategy + +### Semantic Versioning for Playbooks + +**Approach 1: Git Tags** +```bash +# Tag specific playbook versions +git tag -a remediate-CVE-2025-49794-v1.0 -m "Initial version" +git push origin remediate-CVE-2025-49794-v1.0 + +# Update for new version +git tag -a remediate-CVE-2025-49794-v1.1 -m "Fixed service restart timeout" +git push origin remediate-CVE-2025-49794-v1.1 +``` + +**Approach 2: Filename Versioning** +``` +playbooks/remediation/ +โ”œโ”€โ”€ remediation-CVE-2025-49794-v1.yml +โ”œโ”€โ”€ remediation-CVE-2025-49794-v2.yml +โ””โ”€โ”€ remediation-CVE-2025-49794.yml # Latest (symlink or copy) +``` + +**Approach 3: Branch-Based** +```bash +# Create feature branch for new playbook +git checkout -b remediate-cve-2025-49794 + +# Develop and test +git add playbooks/remediation/remediation-CVE-2025-49794.yml +git commit -m "Add CVE-2025-49794 remediation" + +# Merge to main after testing +git checkout main +git merge remediate-cve-2025-49794 +git push origin main +``` + +### Recommended Versioning Approach + +**For Production**: +1. Use Git tags for major versions +2. Keep playbook filenames stable +3. Document changes in commit messages +4. Use branches for development/testing +5. Merge to main only after validation + +**Version Format**: +``` +CVE-{YEAR}-{NUMBER}-v{MAJOR}.{MINOR} + +Examples: +- CVE-2025-49794-v1.0 (Initial release) +- CVE-2025-49794-v1.1 (Bug fix) +- CVE-2025-49794-v2.0 (Major changes) +``` + +## Best Practices + +### Commit Message Guidelines + +**Format**: +``` +: + + + + +``` + +**Example**: +``` +feat: Add remediation playbook for CVE-2025-49794 + +- Target CVE: CVE-2025-49794 (Critical, CVSS 9.8) +- Affected package: httpd +- Remediation: Update to httpd-2.4.57-8.el9 +- Target systems: Production web servers +- Impact: Brief service restart (~10s downtime) +- Tested on: RHEL 9.3, 9.4 +- Validation: Passed dry-run on 50 staging systems + +Refs: TICKET-12345 +``` + +**Commit Types**: +- `feat:` - New playbook +- `fix:` - Bug fix in existing playbook +- `refactor:` - Code restructuring without behavior change +- `docs:` - Documentation updates +- `test:` - Test-related changes +- `chore:` - Maintenance tasks + +### Security Best Practices + +1. **Never Commit Credentials**: + - Use AAP credential vault + - Reference credentials via AAP, not in playbooks + - Add credential files to .gitignore + +2. **Sensitive Variables**: + ```yaml + # Bad - hardcoded password + - name: Connect to database + vars: + db_password: "MyPassword123" + + # Good - reference AAP credential + - name: Connect to database + vars: + db_password: "{{ lookup('env', 'DB_PASSWORD') }}" + ``` + +3. **Audit Trail**: + - Descriptive commit messages + - Link to change tickets + - Document testing performed + - Tag production versions + +### Code Review Process + +**Before Merging to Main**: +1. **Syntax Validation**: + ```bash + ansible-playbook --syntax-check playbook.yml + ``` + +2. **Linting**: + ```bash + ansible-lint playbook.yml + ``` + +3. **Dry-Run Testing**: + - Test on staging systems first + - Run in check mode + - Review output for errors + +4. **Peer Review**: + - Create pull request + - Have colleague review changes + - Address feedback + - Approve and merge + +## AAP Project Configuration + +### Project Settings + +**Optimal Configuration**: +```yaml +Name: Remediation Playbooks +Organization: Default +Source Control Type: Git +Source Control URL: https://github.com/org/ansible-remediation-playbooks.git +Source Control Branch: main +Source Control Credential: Git-ReadOnly-Credential + +Options: + Clean: Yes (remove local modifications) + Delete: Yes (delete before sync) + Track submodules: No (unless needed) + Update Revision on Launch: Yes (auto-sync before jobs) + +Update Cache Timeout: 0 (always fetch latest) +``` + +**Update on Launch**: +- **Enabled**: AAP syncs project before each job launch +- **Pros**: Always uses latest playbook version +- **Cons**: Slight delay before job starts +- **Recommendation**: Enable for dynamic environments + +### Multiple Projects Strategy + +**Option 1: Single Project for All Playbooks** +``` +Project: "Remediation Playbooks" +Contains: All remediation, verification, rollback playbooks +Pros: Simple management, single sync point +Cons: All teams share same repository +``` + +**Option 2: Separate Projects by Purpose** +``` +Project: "CVE Remediation" + - playbooks/remediation/ + +Project: "Verification Playbooks" + - playbooks/verification/ + +Project: "Rollback Procedures" + - playbooks/rollback/ + +Pros: Clear separation, different access controls +Cons: More complex, multiple syncs needed +``` + +**Option 3: Separate Projects by Team/Environment** +``` +Project: "Production Remediation" + - Branch: main + +Project: "Staging Remediation" + - Branch: staging + +Project: "Development Remediation" + - Branch: develop + +Pros: Environment isolation, safe testing +Cons: Need to promote across branches +``` + +## Automation and CI/CD Integration + +### Automated Testing Pipeline + +**Example GitHub Actions**: +```yaml +name: Playbook Validation + +on: + push: + branches: [ main, develop ] + paths: + - 'playbooks/**/*.yml' + pull_request: + branches: [ main ] + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Install Ansible + run: | + pip install ansible ansible-lint + + - name: Syntax Check + run: | + ansible-playbook --syntax-check playbooks/**/*.yml + + - name: Ansible Lint + run: | + ansible-lint playbooks/ + + - name: Check for Secrets + run: | + git secrets --scan +``` + +### Webhook Integration + +**Trigger AAP Sync on Git Push**: + +1. **Configure Webhook in Git**: + - URL: `https://aap.example.com/api/controller/v2/projects/{id}/github/` + - Events: Push events + - Secret: Generate in AAP + +2. **Enable Webhook in AAP**: + - Project settings โ†’ Enable Webhook + - Copy webhook URL and secret + - Add to Git repository settings + +**Result**: Git push automatically triggers AAP project sync. + +## Related Documentation + +- [AAP Job Execution Guide](./aap-job-execution.md) - Executing playbooks in AAP +- [CVE Remediation Templates](./cve-remediation-templates.md) - Playbook patterns +- [Package Management](../rhel/package-management.md) - RHEL package updates diff --git a/rh-sre/docs/testing/aap-integration-test-guide.md b/rh-sre/docs/testing/aap-integration-test-guide.md new file mode 100644 index 00000000..5f8b7d05 --- /dev/null +++ b/rh-sre/docs/testing/aap-integration-test-guide.md @@ -0,0 +1,649 @@ +--- +title: AAP Integration Test Guide +category: testing +sources: + - title: Internal Testing Documentation + date_accessed: 2024-01-20 +tags: [testing, aap-integration, workflow-verification, remediation-testing] +semantic_keywords: [aap integration testing, workflow verification, remediation test] +use_cases: [remediator, playbook-executor] +related_docs: [aap-job-execution.md, playbook-integration-aap.md] +last_updated: 2024-01-20 +--- + +# AAP Integration Test Guide + +## Overview + +This guide provides a comprehensive testing plan for the AAP MCP integration, covering the complete CVE remediation workflow from analysis through execution to verification. + +## Prerequisites for Testing + +### Required Setup + +1. **AAP Environment**: + - AAP 2.4+ instance accessible + - Valid API token with appropriate permissions + - At least one project configured + - At least one inventory with test systems + - At least one job template (or ability to create one) + +2. **Environment Variables**: + ```bash + export AAP_SERVER="https://your-aap-server.com" + export AAP_API_TOKEN="your-api-token" + ``` + +3. **Test Systems**: + - At least 2-3 RHEL systems in AAP inventory + - Systems registered with Red Hat Lightspeed + - Systems have known CVEs for testing + - SSH access configured with credentials in AAP + +4. **MCP Configuration**: + - `rh-sre/.mcp.json` configured with AAP MCP servers + - `lightspeed-mcp` configured and working + - All environment variables set + +### Verification Checklist + +Before starting tests, verify: + +- [ ] AAP Web UI accessible at `${AAP_SERVER}` +- [ ] Can log in with your credentials +- [ ] API token has been generated +- [ ] Environment variables are set (run: `env | grep AAP`) +- [ ] Test systems visible in AAP inventory +- [ ] Test systems have CVEs in Red Hat Lightspeed +- [ ] Git repository available for playbook storage + +## Test Plan Structure + +``` +Test Phase 1: Component Testing +โ”œโ”€ Test 1.1: AAP MCP Validator +โ”œโ”€ Test 1.2: Job Template Lister +โ”œโ”€ Test 1.3: Playbook Generator +โ””โ”€ Test 1.4: Inventory Access + +Test Phase 2: Integration Testing +โ”œโ”€ Test 2.1: Template Selection Workflow +โ”œโ”€ Test 2.2: Dry-Run Execution +โ”œโ”€ Test 2.3: Production Execution +โ””โ”€ Test 2.4: Error Handling + +Test Phase 3: End-to-End Testing +โ”œโ”€ Test 3.1: Full Remediator Workflow +โ”œโ”€ Test 3.2: Multi-CVE Remediation +โ””โ”€ Test 3.3: Partial Failure Recovery + +Test Phase 4: Performance Testing +โ””โ”€ Test 4.1: Large-Scale Execution +``` + +## Test Phase 1: Component Testing + +### Test 1.1: AAP MCP Validator + +**Objective**: Verify AAP MCP server connectivity and resource availability. + +**Steps**: +1. Invoke the mcp-aap-validator skill +2. Observe validation checks +3. Confirm all checks pass + +**Expected Results**: +``` +โœ“ AAP MCP Validation: PASSED + +Configuration: +โœ“ MCP server aap-mcp-job-management configured +โœ“ MCP server aap-mcp-inventory-management configured +โœ“ Environment variable AAP_SERVER is set +โœ“ Environment variable AAP_API_TOKEN is set +โœ“ Job management server connectivity verified +โœ“ Inventory management server connectivity verified + +Resources: +โœ“ Found N job template(s) available +โœ“ Found M inventory/inventories available + +Ready to execute AAP operations. +``` + +**Pass Criteria**: +- All configuration checks pass +- Both MCP servers connect successfully +- At least 1 job template found +- At least 1 inventory found + +**Troubleshooting**: +- If fails: Review error message and fix configuration +- If partial: Note warnings but may proceed if resources exist +- If connection fails: Check AAP server status and credentials + +### Test 1.2: Job Template Lister + +**Objective**: Verify ability to list and filter job templates. + +**Test Command**: Use `job_templates_list` MCP tool via skill + +**Steps**: +1. Request list of all job templates +2. Verify response contains expected templates +3. Note template IDs for later tests + +**Expected Results**: +- List of templates with IDs, names, projects, inventories +- At least 1 template suitable for remediation + +**Pass Criteria**: +- Tool returns valid response +- Template data includes required fields +- Can identify suitable template for testing + +### Test 1.3: Playbook Generator + +**Objective**: Verify playbook generation from CVE data. + +**Steps**: +1. Invoke playbook-generator skill with a known CVE +2. Review generated playbook +3. Verify playbook has required sections + +**Test Input**: +- CVE ID: Use a real CVE affecting your test systems +- Target systems: Your test system UUIDs + +**Expected Results**: +- Valid Ansible YAML playbook generated +- Includes: pre-flight checks, package updates, service restarts +- Follows Red Hat best practices +- Has proper error handling + +**Pass Criteria**: +- Playbook is syntactically valid YAML +- Contains all remediation tasks +- Includes backup/rollback steps +- Has audit logging + +### Test 1.4: Inventory Access + +**Objective**: Verify ability to query AAP inventories and hosts. + +**Test Command**: Use `inventories_list` and `hosts_list` MCP tools + +**Steps**: +1. List all inventories +2. Select test inventory +3. List hosts in that inventory +4. Verify test systems are present + +**Expected Results**: +- Inventory list returned +- Can query hosts within inventory +- Test systems visible with correct metadata + +**Pass Criteria**: +- At least 1 inventory returned +- Hosts query succeeds +- Test systems found in inventory + +## Test Phase 2: Integration Testing + +### Test 2.1: Template Selection Workflow + +**Objective**: Test the template selection and creation workflow. + +**Scenario A: Existing Template** + +**Steps**: +1. Invoke playbook-executor skill +2. Skill lists available templates +3. Select an existing compatible template +4. Verify selection is accepted + +**Expected Results**: +``` +Found N compatible job template(s): + +1. "CVE Remediation Template" (ID: 10) + - Inventory: Production Servers (1) + - Project: Remediation Playbooks (5) + - Credentials: โœ“ Configured + +Select template number or "create" for new: 1 + +โœ“ Using template: CVE Remediation Template (ID: 10) +``` + +**Pass Criteria**: +- Templates listed successfully +- User can select a template +- Selection is confirmed + +**Scenario B: Create New Template** + +**Steps**: +1. Invoke playbook-executor skill +2. Choose "create" option +3. Follow template creation guidance +4. Verify template appears in AAP + +**Expected Results**: +- User guided through Web UI creation +- Template created with correct settings +- Template visible in `job_templates_list` + +**Pass Criteria**: +- Guidance is clear and actionable +- Template created successfully +- Template has required configuration + +### Test 2.2: Dry-Run Execution + +**Objective**: Test check mode (dry-run) execution. + +**Steps**: +1. Generate a remediation playbook +2. Select job template +3. Choose "yes" when asked about dry-run +4. Wait for dry-run to complete +5. Review dry-run results + +**Expected Results**: +``` +โณ Dry-run in progress... + +Job ID: 1234 +Status: running + +# Dry-Run Results + +## Job Summary +**Job ID**: 1234 +**Status**: โœ“ Successful (Check Mode) +**Duration**: 2m 15s + +## Simulated Changes +| Host | Would Change | OK | Failed | Status | +|------|--------------|-----|--------|--------| +| test-01 | 2 | 6 | 0 | โœ“ Ready | +| test-02 | 2 | 6 | 0 | โœ“ Ready | + +โœ“ No errors detected in dry-run +``` + +**Pass Criteria**: +- Job launches with `job_type: "check"` +- Execution completes successfully +- Results show "would change" counts +- No actual changes made to systems +- User asked to proceed with actual execution + +### Test 2.3: Production Execution + +**Objective**: Test actual playbook execution (run mode). + +**Steps**: +1. After successful dry-run, approve actual execution +2. Monitor execution progress +3. Wait for completion +4. Review execution report + +**Expected Results**: +``` +โณ Execution in progress... + +Job ID: 1235 +Status: running + +# Playbook Execution Report + +## Job Summary +**Job ID**: 1235 +**Status**: โœ… Successful +**Duration**: 3m 45s + +## Per-Host Results +| Host | OK | Changed | Failed | Unreachable | Status | +|------|-----|---------|--------|-------------|--------| +| test-01 | 6 | 2 | 0 | 0 | โœ… Success | +| test-02 | 6 | 2 | 0 | 0 | โœ… Success | + +**Summary**: 2 of 2 hosts successfully remediated + +## Next Steps +โ˜ Verify remediation with remediation-verifier skill +``` + +**Pass Criteria**: +- Job launches with `job_type: "run"` +- Real-time progress displayed +- Execution completes successfully +- All hosts show success status +- Comprehensive report generated +- AAP URL provided for detailed view + +### Test 2.4: Error Handling + +**Objective**: Test error handling and recovery. + +**Scenario A: Partial Host Failure** + +**Setup**: +- Use 3 test systems +- Cause failure on 1 system (e.g., remove package, stop service) + +**Steps**: +1. Execute remediation playbook +2. Observe partial failure +3. Review error report +4. Choose to relaunch for failed host + +**Expected Results**: +``` +โš ๏ธ Playbook Execution Completed with Failures + +Job ID: 1236 +Systems Remediated: 2 of 3 +Failed Systems: test-03 + +## Failed Tasks Details +**Host**: test-03 +**Task**: Update package httpd +**Error**: "No package httpd available" +**Recommendation**: Check repository configuration + +Would you like to: +1. Relaunch for failed host only +2. Fix issues manually and relaunch +``` + +**Pass Criteria**: +- Failure detected and reported +- Specific error message provided +- Troubleshooting guidance given +- Relaunch option offered +- Can successfully relaunch for failed host only + +**Scenario B: Connection Failure** + +**Setup**: +- Block SSH to one test system (firewall rule) + +**Steps**: +1. Execute remediation playbook +2. Observe connection failure +3. Review error categorization + +**Expected Results**: +``` +โŒ Host test-02: unreachable + +**Error Category**: Connection Failure + +**Troubleshooting**: +1. Check SSH service: systemctl status sshd +2. Verify firewall: firewall-cmd --list-all +3. Test connectivity: ping test-02 +``` + +**Pass Criteria**: +- Connection failure detected +- Categorized as connection error +- Specific troubleshooting provided + +## Test Phase 3: End-to-End Testing + +### Test 3.1: Full Remediator Workflow + +**Objective**: Test complete CVE remediation from analysis to verification. + +**Steps**: +1. **Invoke remediator agent** with a known CVE +2. **Impact Analysis**: Review CVE risk assessment +3. **CVE Validation**: Confirm CVE is valid and has remediation +4. **System Context**: Review affected systems and strategy +5. **Playbook Generation**: Review generated playbook, approve +6. **Dry-Run**: Run check mode, review results, approve production +7. **Execution**: Monitor real execution, review report +8. **Verification**: Verify CVE status updated in Lightspeed + +**Test Input**: +``` +User: "Remediate CVE-YYYY-NNNNN on my test systems" +``` + +**Expected Flow**: +1. Agent analyzes CVE impact +2. Agent validates CVE exists +3. Agent gathers system context +4. Agent generates playbook +5. Agent offers dry-run โ†’ User approves +6. Agent shows dry-run results +7. Agent asks for production execution โ†’ User approves +8. Agent executes playbook +9. Agent reports success +10. Agent suggests verification +11. User invokes remediation-verifier +12. Verifier confirms CVE resolved + +**Pass Criteria**: +- All steps complete without errors +- User prompted at appropriate points +- Dry-run shows simulated changes +- Production execution succeeds +- CVE status updated in Lightspeed +- Comprehensive report at each stage + +**Timeline**: ~10-15 minutes for full workflow + +### Test 3.2: Multi-CVE Remediation + +**Objective**: Test batch remediation of multiple CVEs. + +**Steps**: +1. Invoke remediator agent with 2-3 CVEs +2. Verify agent handles batch processing +3. Confirm single consolidated playbook generated +4. Execute remediation +5. Verify all CVEs resolved + +**Test Input**: +``` +User: "Remediate CVE-2024-1234, CVE-2024-5678, CVE-2024-9012" +``` + +**Expected Results**: +- Agent processes all CVEs +- Consolidated playbook with all fixes +- Single job execution covering all changes +- Report shows results per CVE + +**Pass Criteria**: +- Batch processing works correctly +- Playbook includes all remediation tasks +- Execution handles multiple changes +- Verification confirms all CVEs resolved + +### Test 3.3: Partial Failure Recovery + +**Objective**: Test recovery from partial failures. + +**Scenario**: 5 test systems, 2 fail during execution + +**Steps**: +1. Execute remediation on 5 systems +2. Observe 2 failures +3. Review error analysis +4. Fix issues on failed systems +5. Relaunch for failed systems only +6. Verify all systems eventually succeed + +**Expected Results**: +- Partial success reported (3 of 5) +- Failed systems identified +- Relaunch targets only failed systems +- Second execution succeeds +- Final report shows 5 of 5 success + +**Pass Criteria**: +- Partial failure handled gracefully +- Relaunch doesn't re-run successful hosts +- Ultimate success achieved +- Audit trail shows full history + +## Test Phase 4: Performance Testing + +### Test 4.1: Large-Scale Execution + +**Objective**: Test performance with larger number of systems. + +**Setup**: +- Use 20+ systems in inventory +- Single CVE affecting all systems + +**Steps**: +1. Execute remediation targeting 20+ systems +2. Monitor execution time +3. Review AAP resource usage +4. Verify all systems succeed + +**Expected Results**: +- Execution completes in reasonable time +- Progress monitoring works at scale +- All systems remediated successfully +- Report generated efficiently + +**Pass Criteria**: +- Job completes within expected timeframe +- No timeouts or performance degradation +- Monitoring provides useful progress updates +- Final report is comprehensive + +**Performance Benchmarks**: +- 10 systems: ~5-10 minutes +- 20 systems: ~10-20 minutes +- 50 systems: ~20-40 minutes +(Times vary based on package size and network) + +## Test Reporting Template + +### Test Execution Report + +```markdown +# AAP Integration Test Report + +**Date**: YYYY-MM-DD +**Tester**: [Name] +**Environment**: [AAP Server URL] +**Test Phase**: [1-4] + +## Summary +- Tests Run: N +- Tests Passed: N +- Tests Failed: N +- Pass Rate: NN% + +## Phase 1: Component Testing +- [ ] Test 1.1: AAP MCP Validator - PASS/FAIL +- [ ] Test 1.2: Job Template Lister - PASS/FAIL +- [ ] Test 1.3: Playbook Generator - PASS/FAIL +- [ ] Test 1.4: Inventory Access - PASS/FAIL + +## Phase 2: Integration Testing +- [ ] Test 2.1: Template Selection - PASS/FAIL +- [ ] Test 2.2: Dry-Run Execution - PASS/FAIL +- [ ] Test 2.3: Production Execution - PASS/FAIL +- [ ] Test 2.4: Error Handling - PASS/FAIL + +## Phase 3: End-to-End Testing +- [ ] Test 3.1: Full Remediator Workflow - PASS/FAIL +- [ ] Test 3.2: Multi-CVE Remediation - PASS/FAIL +- [ ] Test 3.3: Partial Failure Recovery - PASS/FAIL + +## Phase 4: Performance Testing +- [ ] Test 4.1: Large-Scale Execution - PASS/FAIL + +## Issues Found +1. [Issue description] - Severity: High/Medium/Low +2. [Issue description] - Severity: High/Medium/Low + +## Recommendations +1. [Recommendation] +2. [Recommendation] + +## Sign-Off +Tested by: [Name] +Approved by: [Name] +Date: YYYY-MM-DD +``` + +## Common Issues and Solutions + +### Issue: "AAP MCP Validation Failed" + +**Symptoms**: Validation fails with connection errors + +**Solutions**: +1. Verify `AAP_SERVER` environment variable is correct +2. Check API token is valid and not expired +3. Ensure AAP server is accessible from your network +4. Review AAP MCP server logs for errors + +### Issue: "No Job Templates Found" + +**Symptoms**: Validation passes but no templates available + +**Solutions**: +1. Create job template via AAP Web UI +2. Ensure project is synced and contains playbooks +3. Verify inventory is configured +4. Check credentials are attached to template + +### Issue: "Dry-Run Shows No Changes" + +**Symptoms**: Dry-run completes but reports 0 changes + +**Solutions**: +1. Verify systems actually need remediation +2. Check playbook targets correct hosts +3. Ensure package names are correct +4. Review playbook conditionals (when clauses) + +### Issue: "Execution Hangs" + +**Symptoms**: Job starts but never completes + +**Solutions**: +1. Check AAP Web UI for job status +2. Review job output for stuck tasks +3. Verify systems are reachable +4. Increase job timeout in template settings + +## Sign-Off Criteria + +Before considering AAP integration complete, verify: + +- [ ] All Phase 1 tests pass +- [ ] All Phase 2 tests pass +- [ ] At least Test 3.1 passes (full workflow) +- [ ] No critical issues remain +- [ ] Documentation is accurate +- [ ] Examples work as described +- [ ] Performance is acceptable + +## Next Steps After Testing + +1. **Document Results**: Complete test report template +2. **Fix Issues**: Address any failures found +3. **Update Documentation**: Correct any inaccuracies +4. **User Acceptance**: Have users test workflow +5. **Production Rollout**: Enable for production use + +## Related Documentation + +- [AAP Job Execution Guide](../ansible/aap-job-execution.md) +- [Playbook Integration with AAP](../ansible/playbook-integration-aap.md) +- [CVE Remediation Templates](../ansible/cve-remediation-templates.md) diff --git a/rh-sre/skills/mcp-aap-validator/SKILL.md b/rh-sre/skills/mcp-aap-validator/SKILL.md index 6f47be1f..6abd0336 100644 --- a/rh-sre/skills/mcp-aap-validator/SKILL.md +++ b/rh-sre/skills/mcp-aap-validator/SKILL.md @@ -97,28 +97,38 @@ fi **If missing**: Proceed to Human Notification Protocol (Step 4) -### Step 3: Test MCP Server Connection +### Step 3: Test MCP Server Connection and Resources -**Action**: Attempt connectivity test to verify server accessibility +**Action**: Attempt connectivity test to verify server accessibility and check for required resources **Test approach**: 1. **Test Job Management Server**: - Tool: `job_templates_list` (from aap-mcp-job-management) - - Parameters: `page_size: 1` (minimal query) - - Expected: Returns list (even if empty) + - Parameters: `page_size: 10` (check for templates) + - Expected: Returns list - Success: Server responds with valid data - Failure: Connection timeout, auth error, or server unavailable + - **Validation**: Check if at least one job template exists + - If `count: 0` โ†’ Warning: No job templates configured + - If `count > 0` โ†’ Success: Templates available for use 2. **Test Inventory Management Server**: - Tool: `inventories_list` (from aap-mcp-inventory-management) - - Parameters: `page_size: 1` (minimal query) - - Expected: Returns list (even if empty) + - Parameters: `page_size: 10` (check for inventories) + - Expected: Returns list - Success: Server responds with valid data - Failure: Connection timeout, auth error, or server unavailable + - **Validation**: Check if at least one inventory exists + - If `count: 0` โ†’ Warning: No inventories configured + - If `count > 0` โ†’ Success: Inventories available for use **Report to user**: - โœ“ "Successfully connected to aap-mcp-job-management" - โœ“ "Successfully connected to aap-mcp-inventory-management" +- โœ“ "Found N job template(s) available" +- โœ“ "Found N inventory/inventories available" +- โš  "Connected but no job templates found (you'll need to create one)" +- โš  "Connected but no inventories found (you'll need to create one)" - โš  "Configuration appears correct but connectivity test unavailable" - โœ— "Cannot connect to aap-mcp-job-management (check server status and credentials)" - โœ— "Cannot connect to aap-mcp-inventory-management (check server status and credentials)" @@ -256,6 +266,10 @@ Configuration: โœ“ Job management server connectivity verified โœ“ Inventory management server connectivity verified +Resources: +โœ“ Found 5 job template(s) available +โœ“ Found 3 inventory/inventories available + Ready to execute AAP operations. Available capabilities: @@ -265,7 +279,30 @@ Available capabilities: - System context gathering for remediation ``` -**Partial success case**: +**Partial success case** (connected but no resources): +``` +โš  AAP MCP Validation: PARTIAL + +Configuration: +โœ“ MCP server aap-mcp-job-management configured +โœ“ MCP server aap-mcp-inventory-management configured +โœ“ Environment variables are set +โœ“ Server connectivity verified + +Resources: +โš  No job templates found (create one before executing playbooks) +โš  No inventories found (create one to target systems) + +Note: AAP is accessible but requires resource setup. +You'll need to create job templates and inventories before executing remediation playbooks. + +Next steps: +1. Create inventory with target systems +2. Create job template for remediation playbooks +3. Re-run validation to confirm setup +``` + +**Partial success case** (connectivity not tested): ``` โš  AAP MCP Validation: PARTIAL diff --git a/rh-sre/skills/playbook-executor/SKILL.md b/rh-sre/skills/playbook-executor/SKILL.md index 515d4415..75e8f916 100644 --- a/rh-sre/skills/playbook-executor/SKILL.md +++ b/rh-sre/skills/playbook-executor/SKILL.md @@ -1,27 +1,71 @@ --- name: playbook-executor description: | - **CRITICAL**: This skill must be used for Ansible playbook execution. DO NOT use raw MCP tools like execute_playbook or get_job_status directly. + **CRITICAL**: This skill must be used for Ansible playbook execution via AAP. DO NOT use raw MCP tools directly. - Execute Ansible remediation playbooks and track job status through the mock Ansible MCP server. Use this skill after generating a playbook to execute it and monitor completion status. The skill handles temporary file creation, job submission, status polling, and completion reporting. + Execute Ansible remediation playbooks through AAP (Ansible Automation Platform) with comprehensive job management, dry-run capabilities, and detailed reporting. Use this skill after generating a playbook to execute it on production systems with proper validation and monitoring. - This skill orchestrates MCP tools (execute_playbook, get_job_status) from ansible-mcp-server to provide reliable playbook execution with job tracking and status monitoring. + This skill orchestrates AAP MCP tools (job_templates_launch_retrieve, jobs_retrieve, jobs_stdout_retrieve, jobs_job_events_list, jobs_job_host_summaries_list) to provide production-grade playbook execution with dry-run testing, real-time progress monitoring, and comprehensive reporting. - **IMPORTANT**: ALWAYS use this skill instead of calling execute_playbook or get_job_status directly. + **IMPORTANT**: ALWAYS use this skill instead of calling AAP MCP tools directly. --- -# Ansible Playbook Executor Skill +# AAP Playbook Executor Skill -This skill executes Ansible remediation playbooks and tracks their execution status through the mock Ansible MCP server. +This skill executes Ansible remediation playbooks through AAP (Ansible Automation Platform) with full job management capabilities. -**Integration with Remediator Agent**: The sre-agents:remediator agent (invoked) orchestrates this skill as part of its Step 5 (Execute Playbook) workflow. For standalone playbook execution, you can invoke this skill directly. +**Integration with Remediator Agent**: The sre-agents:remediator agent orchestrates this skill as part of its Step 5 (Execute Playbook) workflow. For standalone playbook execution, you can invoke this skill directly. + +## Prerequisites + +**Required MCP Servers**: `aap-mcp-job-management`, `aap-mcp-inventory-management` ([setup guide](https://docs.redhat.com/)) + +**Required MCP Tools**: +- `job_templates_list` (from aap-mcp-job-management) - List job templates +- `job_templates_retrieve` (from aap-mcp-job-management) - Get template details +- `job_templates_launch_retrieve` (from aap-mcp-job-management) - Launch jobs +- `jobs_retrieve` (from aap-mcp-job-management) - Get job status +- `jobs_stdout_retrieve` (from aap-mcp-job-management) - Get console output +- `jobs_job_events_list` (from aap-mcp-job-management) - Get task events +- `jobs_job_host_summaries_list` (from aap-mcp-job-management) - Get host statistics +- `inventories_list` (from aap-mcp-inventory-management) - List inventories +- `hosts_list` (from aap-mcp-inventory-management) - List inventory hosts + +**Required Environment Variables**: +- `AAP_SERVER` - AAP server URL +- `AAP_API_TOKEN` - AAP API authentication token + +### Prerequisite Validation + +**CRITICAL**: Before executing operations, invoke the [mcp-aap-validator](../mcp-aap-validator/SKILL.md) skill to verify AAP MCP server availability. + +**Validation freshness**: Can skip if already validated in this session. See [Validation Freshness Policy](../mcp-aap-validator/SKILL.md#validation-freshness-policy). + +**How to invoke**: +``` +Use the Skill tool: + skill: "mcp-aap-validator" +``` + +**Handle validation result**: +- **If validation PASSED**: Continue with playbook execution workflow +- **If validation PARTIAL**: Warn user and ask to proceed +- **If validation FAILED**: Stop execution, provide setup instructions from validator + +**Human Notification on Failure**: +If prerequisites are not met: +- โŒ "Cannot proceed: AAP MCP servers are not available" +- ๐Ÿ“‹ "Setup required: Configure AAP_SERVER and AAP_API_TOKEN environment variables" +- โ“ "How would you like to proceed? (setup now / skip / abort)" +- โธ๏ธ Wait for user decision ## When to Use This Skill **Use this skill directly when you need**: -- Execute a previously generated Ansible playbook -- Track the status of a running playbook execution +- Execute a previously generated Ansible playbook via AAP +- Track the status of a running AAP job - Monitor playbook job completion +- Run dry-run (check mode) before production execution - Verify playbook execution succeeded **Use the sre-agents:remediator agent when you need**: @@ -29,436 +73,949 @@ This skill executes Ansible remediation playbooks and tracks their execution sta - Integrated CVE analysis โ†’ playbook generation โ†’ execution โ†’ verification - End-to-end remediation orchestration -**How they work together**: The sre-agents:remediator agent (invoked) invokes this skill after generating a remediation playbook, asking the user for confirmation before execution, then monitoring the job to completion. +**How they work together**: The sre-agents:remediator agent invokes this skill after generating a remediation playbook, managing the full workflow from analysis to verification. ## Workflow -### 1. Save Playbook to Temporary Location +### Phase 0: Validate AAP MCP Prerequisites -**CRITICAL: Playbooks MUST be saved under /tmp for container access** +**Action**: Invoke the [mcp-aap-validator](../mcp-aap-validator/SKILL.md) skill + +**Note**: Can skip if validation was performed earlier in this session and succeeded. + +**How to invoke**: +``` +Use the Skill tool: + skill: "mcp-aap-validator" +``` -The ansible-mcp-server runs in a container with `/tmp` mounted to `/playbooks`. All playbooks must be saved to `/tmp` on the host. +**Handle validation result**: +- **If validation PASSED**: Continue to Phase 1 +- **If validation PARTIAL**: Warn user and ask to proceed +- **If validation FAILED**: Stop execution, user must set up AAP MCP servers -```python -import tempfile -import os +### Phase 1: Job Template Selection/Creation -# Create temporary file with .yml extension in /tmp directory -temp_fd, temp_path = tempfile.mkstemp(suffix='.yml', prefix='remediation-', dir='/tmp') +**Goal**: Identify or create an AAP job template suitable for executing the remediation playbook. -# Write playbook content to file -with os.fdopen(temp_fd, 'w') as f: - f.write(playbook_yaml_content) +#### Step 1.1: List Available Job Templates -# temp_path now contains the absolute path to the playbook file -# Example: /tmp/remediation-abc123.yml +**MCP Tool**: `job_templates_list` (from aap-mcp-job-management) + +**Parameters**: +- `page_size`: 50 (retrieve up to 50 templates) +- `search`: "" (search for all templates) + +**Expected Output**: +```json +{ + "count": 3, + "results": [ + { + "id": 10, + "name": "CVE Remediation Template", + "project": 5, + "inventory": 1, + "playbook": "playbooks/remediation/remediation-template.yml" + } + ] +} ``` -**Key Requirements**: -- Playbook MUST be saved to `/tmp` directory (mounted into container as `/playbooks`) -- Playbook MUST be saved as a `.yml` or `.yaml` file -- Use absolute filesystem path starting with `/tmp/` (not relative) -- File must exist and be readable before calling execute_playbook -- Keep track of temp_path for cleanup after completion +#### Step 1.2: Filter Compatible Templates -## Critical: Human-in-the-Loop Requirements +For each template, check if it satisfies remediation requirements: -This skill executes code on production systems. **Explicit user confirmation is REQUIRED** before playbook execution. +**Requirements**: +1. **Inventory Match**: Inventory contains target systems from CVE analysis +2. **Project Suitability**: Project contains or can contain remediation playbooks +3. **Credentials Configured**: Has machine credentials (SSH) and privilege escalation enabled +4. **Launch-Time Flexibility**: Supports prompt on launch for variables and/or limit (optional but recommended) -**Before Playbook Execution** (REQUIRED): -1. **Display Playbook Path**: Show which playbook file will be executed -2. **Display Target Systems**: Show which systems will be affected -3. **Display Risk Assessment**: Show reboot requirements, downtime estimates, affected services -4. **Ask for Confirmation**: - ``` - โš ๏ธ CRITICAL: Playbook Execution Confirmation Required +**Filtering Logic**: +``` +For each template: + 1. Get template details with job_templates_retrieve(id=template_id) + 2. Check if template.inventory matches target systems + 3. Check if template.project is suitable for remediation playbooks + 4. Check if template has credentials configured + 5. Score template based on matches (0-4 points) +``` - This playbook will: - - Execute on: N production systems - - Require reboot: [Yes/No] - - Estimated downtime: X minutes per system - - Affected services: [list] +**Result**: List of compatible templates ranked by suitability score. - Playbook file: /tmp/remediation-CVE-YYYY-NNNNN.yml +#### Step 1.3: User Selection - โ“ Execute this playbook now? +**If compatible templates found**: +``` +Found N compatible job template(s): + +1. "CVE Remediation Template" (ID: 10) + - Inventory: Production Servers (1) + - Project: Remediation Playbooks (5) + - Credentials: โœ“ Configured + - Launch flexibility: โœ“ Variables and limit + +2. "Dynamic Remediation" (ID: 15) + - Inventory: All Systems (2) + - Project: Remediation Playbooks (5) + - Credentials: โœ“ Configured + - Launch flexibility: โœ“ Variables only + +โ“ Which template would you like to use? +- Enter template number (1-N) +- "create" - Create new template via Web UI +- "abort" - Cancel execution + +Please respond with your choice. +``` - Options: - - "yes" or "execute" - Proceed with playbook execution - - "review" - Show playbook content again - - "abort" - Cancel execution +**If no compatible templates found**: +``` +โš ๏ธ No suitable job templates found for this remediation. - Please respond with your choice. +Required: +- Inventory containing target systems +- Project for remediation playbooks +- Machine credentials (SSH + sudo) + +Options: +1. Create new template via AAP Web UI (I'll guide you) +2. Modify existing template to add requirements +3. Abort execution + +Please choose an option (1-3): +``` + +#### Step 1.4: Create Template (If Needed) + +If user chooses to create a new template, invoke the **job-template-creator** skill: + +``` +Skill: job-template-creator +Args: playbook-name target-systems +``` + +The job-template-creator skill will guide the user through: +- Adding playbook to Git repository +- Creating job template via AAP Web UI +- Verifying template is ready + +**Wait for template creation to complete** before proceeding to Phase 2. + +### Phase 2: Playbook Preparation + +**Goal**: Ensure the generated playbook is available in the AAP project. + +#### Step 2.1: Add Playbook to Git Repository + +**Options**: + +**Option A: User has existing Git repository configured in AAP** +1. Ask user for Git repository location +2. Provide commands to add playbook to repository: + ```bash + cd /path/to/playbooks-repo + mkdir -p playbooks/remediation + cat > playbooks/remediation/remediation-CVE-YYYY-NNNNN.yml << 'EOF' + [playbook content] + EOF + git add playbooks/remediation/remediation-CVE-YYYY-NNNNN.yml + git commit -m "Add remediation playbook for CVE-YYYY-NNNNN" + git push origin main ``` -4. **Wait for Explicit Confirmation**: Do not execute without "yes" or "execute" +3. Instruct user to sync AAP project: + - Navigate to AAP Web UI โ†’ Automation Execution โ†’ Projects + - Find project and click Sync button (๐Ÿ”„) + - Wait for sync to complete -**Never assume approval** - always wait for explicit user confirmation before executing playbooks on production systems. +**Option B: Temporary playbook testing** +1. Explain that playbook can be added to an existing AAP project playbook +2. User manually copies playbook to AAP project location +3. User syncs project -### 2. Execute Playbook +#### Step 2.2: Verify Playbook Available -**ONLY after receiving explicit user confirmation**, proceed with execution. +After Git sync, verify playbook appears in project: +``` +โœ“ Playbook added to Git repository +โœ“ AAP project synced successfully +โœ“ Playbook path: playbooks/remediation/remediation-CVE-YYYY-NNNNN.yml -**MCP Tool**: `execute_playbook` (from ansible-mcp-server) +Ready to proceed to execution. +``` -**Parameters**: -- `playbook_path`: Absolute path to playbook file in container filesystem - - Example: `"/playbooks/remediation-CVE-2024-1234.yml"` - - Format: MUST start with `/playbooks/` (container mount point) - - Conversion: Host path `/tmp/file.yml` โ†’ Container path `/playbooks/file.yml` +### Phase 3: Dry-Run Execution (Recommended) -**Path Conversion Logic**: +**Goal**: Test playbook in check mode before actual execution to simulate changes. + +#### Step 3.1: Display Playbook Preview + +Show user the playbook structure and explain tasks: + +```markdown +# Playbook Preview + +**Playbook**: remediation-CVE-2025-49794.yml +**Target Systems**: 5 systems + +## Tasks Overview: +1. **Gather Facts** - Collect system information +2. **Check Disk Space** - Ensure sufficient space for updates (>500MB) +3. **Backup Configuration** - Snapshot critical configs +4. **Update Package: httpd** - Upgrade to version 2.4.57-8.el9 +5. **Restart Service: httpd** - Apply changes +6. **Verify Service Status** - Confirm httpd is running +7. **Update Audit Log** - Record remediation event + +**Estimated Duration**: 3-5 minutes per system +**Requires Reboot**: No +**Downtime**: Brief (~10 seconds during service restart) ``` -IMPORTANT: Convert host path to container path before calling execute_playbook -Host path: /tmp/remediation-CVE-2024-1234.yml -Container path: /playbooks/remediation-CVE-2024-1234.yml +#### Step 3.2: Offer Dry-Run + +``` +โš ๏ธ Recommended: Run dry-run first + +Dry-run mode (--check) simulates changes without applying them. +This helps identify: +- Package availability issues +- Permission problems +- Configuration conflicts +- Unexpected side effects + +โ“ Run dry-run before actual execution? +- "yes" - Run dry-run first (recommended) +- "no" - Skip to actual execution +- "abort" - Cancel execution -Python conversion: -container_path = host_path.replace('/tmp/', '/playbooks/') +Please respond with your choice. ``` +#### Step 3.3: Launch Dry-Run Job + +**ONLY if user confirms**, proceed with dry-run. + +**MCP Tool**: `job_templates_launch_retrieve` (from aap-mcp-job-management) + +**Parameters**: +```json +{ + "id": "10", + "requestBody": { + "job_type": "check", + "extra_vars": { + "target_cve": "CVE-2025-49794", + "remediation_mode": "automated" + }, + "limit": "prod-web-01,prod-web-02,prod-web-03" + } +} +``` + +**Key Parameter**: `job_type: "check"` - Runs Ansible in check mode (dry-run) + **Expected Output**: ```json { - "job_id": "job_12345", - "status": "PENDING", - "playbook_path": "/playbooks/remediation-CVE-2024-1234.yml" + "job": 1234, + "status": "pending", + "url": "/api/controller/v2/jobs/1234/" } ``` -**Verification**: +#### Step 3.4: Monitor Dry-Run Progress + +Poll job status with `jobs_retrieve` every 2 seconds: + +``` +โณ Dry-run in progress... + +Job ID: 1234 +Status: running +Elapsed: 0m 45s + +[Live progress updates from jobs_job_events_list] +- โœ“ Gathering Facts (completed) +- โœ“ Checking Disk Space (completed) +- โณ Simulating Package Update (running) +``` + +#### Step 3.5: Display Dry-Run Results + +**MCP Tool**: `jobs_stdout_retrieve` (from aap-mcp-job-management) + +**Parameters**: +- `id`: "1234" (job ID) +- `format`: "txt" (plain text output) + +Get per-host summary: + +**MCP Tool**: `jobs_job_host_summaries_list` (from aap-mcp-job-management) + +**Parameters**: +- `id`: "1234" + +**Display Format**: +```markdown +# Dry-Run Results + +## Job Summary +**Job ID**: 1234 +**Status**: โœ“ Successful (Check Mode) +**Duration**: 2m 15s +**Completed**: 2024-01-20 15:32:17 UTC + +## Simulated Changes +| Host | Would Change | OK | Failed | Status | +|------|--------------|-----|--------|--------| +| prod-web-01 | 3 | 8 | 0 | โœ“ Ready | +| prod-web-02 | 3 | 8 | 0 | โœ“ Ready | +| prod-web-03 | 3 | 8 | 0 | โœ“ Ready | + +## Changes That Would Be Made: +1. **httpd package** - Would update from 2.4.53-7.el9 to 2.4.57-8.el9 +2. **httpd service** - Would restart +3. **audit log** - Would add remediation entry + +## Dry-Run Output: +
+Click to expand full output + +[Full stdout from jobs_stdout_retrieve] + +
+ +โœ“ No errors detected in dry-run +โœ“ All systems passed pre-flight checks +``` + +#### Step 3.6: Proceed to Actual Execution? + ``` -โœ“ job_id returned (string - used for status tracking) -โœ“ status = "PENDING" (job queued for execution) -โœ“ playbook_path uses container path (/playbooks/) +โ“ Dry-run completed successfully. Proceed with actual execution? + +Options: +- "yes" or "execute" - Proceed with actual remediation +- "review" - Show dry-run output again +- "abort" - Cancel execution + +Please respond with your choice. ``` -**Error Handling**: +### Phase 4: Actual Execution + +**ONLY execute if user explicitly confirms** (either after dry-run or directly if they skipped dry-run). + +#### Step 4.1: Final Confirmation + ``` -If playbook file not found: -โ†’ Error: "Playbook file not found: /playbooks/remediation-CVE-2024-1234.yml" -โ†’ Action: Verify file was saved to /tmp on host, check path conversion to /playbooks/ +โš ๏ธ CRITICAL: Playbook Execution Confirmation Required + +This playbook will: +- Execute on: 3 production systems +- Update packages: httpd (2.4.53-7.el9 โ†’ 2.4.57-8.el9) +- Restart services: httpd +- Estimated downtime: ~10 seconds per system +- Requires reboot: No + +Job Template: CVE Remediation Template (ID: 10) +AAP URL: https://aap.example.com/jobs/ + +โ“ Execute this playbook now? + +Options: +- "yes" or "execute" - Proceed with execution +- "abort" - Cancel execution -If execute_playbook fails: -โ†’ Retry once after verifying file exists -โ†’ If retry fails, report error to user with troubleshooting steps +Please respond with your choice. ``` -### 3. Track Job Status +Wait for explicit "yes" or "execute" response. -**MCP Tool**: `get_job_status` (from ansible-mcp-server) +#### Step 4.2: Launch Production Job -**Parameters**: -- `job_id`: Job identifier from execute_playbook response - - Example: `"job_12345"` - - Format: String returned from execute_playbook +**MCP Tool**: `job_templates_launch_retrieve` (from aap-mcp-job-management) -**Expected Output** (varies by job status): +**Parameters**: ```json -// When PENDING { - "job_id": "job_12345", - "status": "PENDING", - "started_at": null, - "completed_at": null + "id": "10", + "requestBody": { + "job_type": "run", + "extra_vars": { + "target_cve": "CVE-2025-49794", + "remediation_mode": "automated", + "verify_after": true + }, + "limit": "prod-web-01,prod-web-02,prod-web-03" + } } +``` -// When RUNNING -{ - "job_id": "job_12345", - "status": "RUNNING", - "started_at": "2024-01-20T15:30:02Z", - "completed_at": null -} +**Key Parameter**: `job_type: "run"` - Runs Ansible in execution mode (actual changes) -// When COMPLETED +**Expected Output**: +```json { - "job_id": "job_12345", - "status": "COMPLETED", - "started_at": "2024-01-20T15:30:02Z", - "completed_at": "2024-01-20T15:30:07Z" + "job": 1235, + "status": "pending", + "url": "/api/controller/v2/jobs/1235/" } ``` -**Job Status Timeline Example**: -``` -T+0s: Status: PENDING (started_at: null, completed_at: null) -T+2s: Status: RUNNING (started_at: ISO8601, completed_at: null) -T+7s: Status: COMPLETED (started_at: ISO8601, completed_at: ISO8601) - -Status Transitions: -PENDING โ†’ RUNNING โ†’ COMPLETED -``` +#### Step 4.3: Monitor Execution Progress **Polling Strategy**: +1. Call `jobs_retrieve(id=job_id)` every 2 seconds +2. Get task events with `jobs_job_events_list(id=job_id)` for progress updates +3. Display real-time task completion status +4. Continue until status is "successful", "failed", or "error" + +**Progress Display**: ``` -1. Initial check: Immediately after execute_playbook -2. While status = "PENDING" or "RUNNING": - - Wait 2 seconds - - Call get_job_status(job_id=job_id) - - Check status field -3. When status = "COMPLETED": - - Stop polling - - Report success +โณ Execution in progress... + +Job ID: 1235 +Status: running +Elapsed: 1m 23s +AAP URL: https://aap.example.com/#/jobs/playbook/1235 + +Recent Events: +- โœ“ Gathering Facts (completed - all hosts) +- โœ“ Check Disk Space (completed - all hosts) +- โœ“ Backup Configuration (completed - all hosts) +- โณ Update Package: httpd (running - prod-web-01, prod-web-02) + โ””โ”€ prod-web-01: Installing httpd-2.4.57-8.el9... + โ””โ”€ prod-web-02: Installing httpd-2.4.57-8.el9... +- โธ Restart Service: httpd (pending) ``` -**Status Interpretation**: -``` -Status: PENDING -โ†’ Job queued, not yet started -โ†’ Action: Continue polling +**Update every 2 seconds** until completion. -Status: RUNNING -โ†’ Playbook execution in progress -โ†’ Action: Continue polling, update user on progress +### Phase 5: Execution Report -Status: COMPLETED -โ†’ Playbook execution finished successfully -โ†’ Action: Stop polling, report success +**Goal**: Generate comprehensive report with job details, per-host results, and full output. -Status: FAILED (if supported by server) -โ†’ Playbook execution encountered errors -โ†’ Action: Report failure, provide troubleshooting guidance -``` +#### Step 5.1: Gather Job Details + +**MCP Tool**: `jobs_retrieve` (from aap-mcp-job-management) + +**Parameters**: +- `id`: "1235" -**Error Handling**: +**Expected Output**: +```json +{ + "id": 1235, + "name": "CVE Remediation Template", + "status": "successful", + "started": "2024-01-20T15:35:02Z", + "finished": "2024-01-20T15:40:25Z", + "elapsed": 323.45, + "job_template": 10, + "inventory": 1, + "limit": "prod-web-01,prod-web-02,prod-web-03", + "playbook": "playbooks/remediation/remediation-CVE-2025-49794.yml" +} ``` -If get_job_status returns "Job not found": -โ†’ Error: Invalid job_id or job expired -โ†’ Action: Report error, suggest re-executing playbook -If polling timeout (>60 seconds): -โ†’ Warning: Job taking longer than expected -โ†’ Action: Continue polling but warn user +#### Step 5.2: Get Per-Host Statistics + +**MCP Tool**: `jobs_job_host_summaries_list` (from aap-mcp-job-management) + +**Parameters**: +- `id`: "1235" + +**Expected Output**: +```json +{ + "results": [ + { + "host_name": "prod-web-01", + "ok": 8, + "changed": 3, + "failed": 0, + "unreachable": 0 + }, + { + "host_name": "prod-web-02", + "ok": 8, + "changed": 3, + "failed": 0, + "unreachable": 0 + }, + { + "host_name": "prod-web-03", + "ok": 5, + "changed": 0, + "failed": 1, + "unreachable": 0 + } + ] +} ``` -### 4. Report Execution Results +#### Step 5.3: Get Task Timeline + +**MCP Tool**: `jobs_job_events_list` (from aap-mcp-job-management) + +**Parameters**: +- `id`: "1235" -Generate execution summary with job details: +**Expected Output**: List of task events with timestamps, task names, and status per host. + +#### Step 5.4: Get Full Console Output + +**MCP Tool**: `jobs_stdout_retrieve` (from aap-mcp-job-management) + +**Parameters**: +- `id`: "1235" +- `format`: "txt" + +**Expected Output**: Complete Ansible playbook execution output. + +#### Step 5.5: Generate Comprehensive Report + +Format all gathered data into structured report: ```markdown # Playbook Execution Report -## Job Details -**Job ID**: job_12345 -**Status**: COMPLETED โœ“ -**Started At**: 2024-01-20T15:30:02Z -**Completed At**: 2024-01-20T15:30:07Z -**Duration**: 5 seconds +## Job Summary +**Job ID**: 1235 +**Status**: โœ… Successful +**Duration**: 5m 23s +**Started**: 2024-01-20 15:35:02 UTC +**Completed**: 2024-01-20 15:40:25 UTC +**Job Template**: CVE Remediation Template +**Playbook**: playbooks/remediation/remediation-CVE-2025-49794.yml +**AAP URL**: [View in AAP](https://aap.example.com/#/jobs/playbook/1235) + +## Per-Host Results +| Host | OK | Changed | Failed | Unreachable | Status | +|------|-----|---------|--------|-------------|--------| +| prod-web-01 | 8 | 3 | 0 | 0 | โœ… Success | +| prod-web-02 | 8 | 3 | 0 | 0 | โœ… Success | +| prod-web-03 | 8 | 3 | 0 | 0 | โœ… Success | + +**Summary**: 3 of 3 hosts successfully remediated + +## Task Timeline +1. โœ… Gather Facts (2s) +2. โœ… Check disk space (1s) +3. โœ… Backup configuration (3s) +4. โœ… Update package httpd (45s) + - prod-web-01: 2.4.53-7.el9 โ†’ 2.4.57-8.el9 + - prod-web-02: 2.4.53-7.el9 โ†’ 2.4.57-8.el9 + - prod-web-03: 2.4.53-7.el9 โ†’ 2.4.57-8.el9 +5. โœ… Restart httpd service (15s) +6. โœ… Verify service status (2s) +7. โœ… Update audit log (1s) + +## Full Console Output +
+Click to expand (187 lines) + +[Full stdout from jobs_stdout_retrieve] + +
-## Playbook Information -**Playbook Path**: /tmp/remediation-CVE-2024-1234.yml -**CVE**: CVE-2024-1234 -**Target Systems**: 5 systems +## Next Steps +1. โœ… All systems successfully remediated +2. โ˜ Verify remediation with remediation-verifier skill +3. โ˜ Update vulnerability tracking system +4. โ˜ Schedule follow-up verification in 24-48 hours -## Execution Timeline -1. T+0s: Job submitted (PENDING) -2. T+2s: Execution started (RUNNING) -3. T+7s: Execution completed (COMPLETED) +--- -## Next Steps -- Verify remediation success using remediation-verifier skill -- Check affected systems are no longer vulnerable -- Update vulnerability tracking system +**Recommendation**: Run remediation-verifier skill to confirm CVE status has been updated in Red Hat Lightspeed. ``` -### 5. Cleanup Temporary Files +### Phase 6: Error Handling + +**If job status is "failed" or "error"**, provide detailed troubleshooting. + +#### Step 6.1: Parse Error Output + +**MCP Tool**: `jobs_stdout_retrieve` (from aap-mcp-job-management) -After job completion, clean up temporary playbook file: +Analyze output for common error patterns: -```python -import os +**Error Categories**: +1. **Connection Failures**: SSH timeout, host unreachable, authentication failed +2. **Permission Errors**: sudo required, insufficient privileges, SELinux denials +3. **Package Manager Issues**: repo unavailable, package not found, dependency conflicts +4. **Service Failures**: service not found, restart failed, timeout +5. **Disk Space**: insufficient space for updates +6. **General Failures**: playbook syntax errors, task failures -# After job completes successfully -if os.path.exists(temp_path): - os.remove(temp_path) - print(f"Cleaned up temporary playbook: {temp_path}") +#### Step 6.2: Generate Error Report + +```markdown +# Playbook Execution Failed + +## Job Summary +**Job ID**: 1235 +**Status**: โŒ Failed +**Duration**: 2m 45s +**Started**: 2024-01-20 15:35:02 UTC +**Failed At**: 2024-01-20 15:37:47 UTC +**Job Template**: CVE Remediation Template +**AAP URL**: [View in AAP](https://aap.example.com/#/jobs/playbook/1235) + +## Per-Host Results +| Host | OK | Changed | Failed | Unreachable | Status | +|------|-----|---------|--------|-------------|--------| +| prod-web-01 | 8 | 3 | 0 | 0 | โœ… Success | +| prod-web-02 | 8 | 3 | 0 | 0 | โœ… Success | +| prod-web-03 | 5 | 0 | 1 | 0 | โŒ Failed | + +**Summary**: 2 of 3 hosts succeeded, 1 failed + +## Failed Tasks Details + +### Host: prod-web-03 + +**Task**: Restart httpd service +**Error**: "Failed to restart httpd.service: Unit httpd.service not found." + +**Error Category**: Service Failure + +**Root Cause**: The httpd service is not installed or not recognized by systemd. + +**Troubleshooting Steps**: +1. Check if httpd is installed: + ```bash + ssh prod-web-03 'rpm -q httpd' + ``` +2. If not installed, the package update may have failed: + ```bash + ssh prod-web-03 'dnf info httpd' + ``` +3. Check systemd service status: + ```bash + ssh prod-web-03 'systemctl status httpd' + ``` +4. Review package manager logs: + ```bash + ssh prod-web-03 'tail -50 /var/log/dnf.log' + ``` + +**Recommended Action**: +- Verify httpd package installation on prod-web-03 +- Check if package update completed successfully +- Manually install httpd if needed: `dnf install httpd` +- Relaunch job for failed host only + +## Console Output (Last 50 Lines) +
+Click to expand error context + +[Relevant error output from jobs_stdout_retrieve] + +
+ +## Relaunch Options + +Would you like to: +1. **Relaunch for failed hosts only** - Run job again with limit="prod-web-03" +2. **Fix issues manually and relaunch** - Resolve problems first, then relaunch +3. **View full job output** - See complete execution logs +4. **Abort** - Stop remediation workflow + +Please choose an option (1-4): ``` -**Cleanup Strategy**: -- Remove temp file after COMPLETED status -- Keep temp file if FAILED status (for debugging) -- Warn user if cleanup fails (not critical) +#### Step 6.3: Offer Relaunch + +If user chooses to relaunch: + +**MCP Tool**: `jobs_relaunch_retrieve` (from aap-mcp-job-management) + +**Parameters**: +```json +{ + "id": "1235", + "requestBody": { + "hosts": "failed", + "job_type": "run" + } +} +``` -## Output Template +This relaunches the job for only the failed hosts. -When completing playbook execution, provide output in this format: +## Output Templates + +### Success Template ```markdown -# Ansible Playbook Execution +โœ… Playbook Execution Successful -## Execution Started -**Playbook**: remediation-CVE-2024-1234.yml -**Job ID**: job_12345 -**Status**: Submitted for execution +Job ID: 1235 +Duration: 5m 23s +Systems Remediated: 3 of 3 -Monitoring job status... +View full report above for details. -## Status Updates -- T+0s: PENDING (job queued) -- T+2s: RUNNING (execution started) -- T+7s: COMPLETED (execution finished) +Next Steps: +- Run remediation-verifier skill to confirm CVE resolution +- Update vulnerability tracking system +- Monitor systems for 24-48 hours -## Execution Complete โœ“ +AAP URL: https://aap.example.com/#/jobs/playbook/1235 +``` -**Job ID**: job_12345 -**Status**: COMPLETED -**Duration**: 5 seconds -**Started**: 2024-01-20T15:30:02Z -**Completed**: 2024-01-20T15:30:07Z +### Partial Success Template -## Next Steps -1. Verify remediation success: - - Use remediation-verifier skill to confirm CVE is resolved - - Check package versions on affected systems - - Verify services are running properly +```markdown +โš ๏ธ Playbook Execution Completed with Failures + +Job ID: 1235 +Duration: 2m 45s +Systems Remediated: 2 of 3 +Failed Systems: prod-web-03 -2. Update tracking: - - Mark CVE-2024-1234 as remediated in vulnerability tracker - - Document remediation in change management system +See error details above for troubleshooting steps. -3. Monitor systems: - - Watch for 24-48 hours for any issues - - Verify Red Hat Lightspeed reflects patched status +Options: +- Relaunch for failed hosts +- Manual remediation +- Skip failed hosts + +AAP URL: https://aap.example.com/#/jobs/playbook/1235 +``` + +### Failure Template + +```markdown +โŒ Playbook Execution Failed + +Job ID: 1235 +Duration: 1m 15s +Systems Remediated: 0 of 3 + +Critical errors prevented execution. +See error details above for troubleshooting. + +AAP URL: https://aap.example.com/#/jobs/playbook/1235 ``` ## Examples -### Example 1: Execute Single CVE Remediation +### Example 1: Full Workflow with Dry-Run -**User Request**: "Execute the playbook for CVE-2024-1234" +**User Request**: "Execute the CVE-2025-49794 remediation playbook" **Skill Response**: -1. Receive playbook YAML content from agent -2. Save to `/tmp/remediation-CVE-2024-1234.yml` (host path) -3. Convert to container path: `/playbooks/remediation-CVE-2024-1234.yml` -4. Call `execute_playbook(playbook_path="/playbooks/remediation-CVE-2024-1234.yml")` โ†’ job_id: "job_12345", status: PENDING -5. Poll `get_job_status` every 2 seconds -6. Status changes: PENDING โ†’ RUNNING โ†’ COMPLETED -7. Report: "Playbook executed successfully in 5 seconds" -8. Cleanup temp file from `/tmp/` on host -9. Suggest: "Use remediation-verifier skill to confirm success" -### Example 2: Track Long-Running Playbook +1. **Validate AAP Prerequisites**: + - Invoke mcp-aap-validator skill โ†’ PASSED -**User Request**: "Check status of job_67890" +2. **List Job Templates**: + - Call `job_templates_list()` โ†’ Found 2 templates + - Filter compatible templates โ†’ 1 matches requirements -**Skill Response**: -1. Call `get_job_status(job_id="job_67890")` -2. Response: status: RUNNING, started_at: 2 minutes ago -3. Continue polling every 2 seconds -4. After 3 minutes: status: COMPLETED -5. Report: "Job completed successfully after 3 minutes" +3. **User Selects Template**: + ``` + Found 1 compatible job template: + 1. "CVE Remediation Template" (ID: 10) + + Select template (1) or "create" for new: 1 + ``` + +4. **Playbook Preparation**: + ``` + Guide user to add playbook to Git: + - Commands provided + - User syncs AAP project + - Verification: Playbook available โœ“ + ``` + +5. **Offer Dry-Run**: + ``` + Run dry-run first? yes + ``` + +6. **Execute Dry-Run**: + - Launch with `job_type="check"` + - Monitor progress โ†’ COMPLETED + - Display dry-run results: + ``` + Would change 3 tasks on 3 hosts + No errors detected + ``` + +7. **Proceed to Actual Execution**: + ``` + Proceed with actual execution? yes + ``` + +8. **Execute Playbook**: + - Launch with `job_type="run"` + - Monitor progress โ†’ COMPLETED + - Generate report: + ``` + โœ… 3 of 3 hosts successfully remediated + Duration: 5m 23s + ``` + +9. **Suggest Verification**: + ``` + Recommend: Run remediation-verifier skill to confirm CVE resolution + ``` -### Example 3: Handle Job Not Found +### Example 2: Handle Execution Failure -**User Request**: "Check status of job_99999" +**User Request**: "Execute remediation playbook" **Skill Response**: -1. Call `get_job_status(job_id="job_99999")` -2. Response: "Job not found" -3. Report: "Job ID not found. Possible reasons: invalid ID, job expired, or execution completed and cleaned up" -4. Suggest: "Re-execute playbook if needed" -## Error Handling +1-7. [Same as Example 1 through execution] -**Playbook File Not Found**: -``` -Execution Failed: Playbook file not found +8. **Execute Playbook**: + - Launch job โ†’ FAILED on 1 of 3 hosts + - Generate error report: + ``` + โŒ prod-web-03 failed + Error: httpd service not found + Troubleshooting steps provided + ``` -Container Path: /playbooks/remediation-CVE-2024-1234.yml -Host Path: /tmp/remediation-CVE-2024-1234.yml +9. **Offer Relaunch**: + ``` + Relaunch for failed host only? yes + ``` -Possible causes: -1. File was not saved to /tmp before calling execute_playbook -2. Path conversion from /tmp/ to /playbooks/ was not performed -3. File permissions prevent reading -4. Volume mount not configured correctly +10. **Relaunch Job**: + - Call `jobs_relaunch_retrieve` with hosts="failed" + - Monitor โ†’ COMPLETED + - Final report: + ``` + โœ… All 3 hosts successfully remediated (1 after retry) + ``` -Troubleshooting: -1. Verify file exists on host: ls -l /tmp/remediation-CVE-2024-1234.yml -2. Check file permissions: should be readable -3. Verify path conversion: /tmp/file.yml โ†’ /playbooks/file.yml -4. Ensure .mcp.json has volume mount: "-v", "/tmp:/playbooks:Z" -5. Ensure file has .yml or .yaml extension -``` +### Example 3: Skip Dry-Run -**Job Execution Timeout**: -``` -Execution Timeout: Job running longer than expected +**User Request**: "Execute playbook directly, skip dry-run" -Job ID: job_12345 -Status: RUNNING -Duration: 65 seconds (exceeded 60s threshold) +**Skill Response**: -Action: Continuing to monitor job status -Note: Some playbooks may take longer for large-scale remediations -``` +1-4. [Same as Example 1 through template selection] -**Job Status Polling Error**: -``` -Status Check Failed: Unable to retrieve job status +5. **Offer Dry-Run**: + ``` + Run dry-run first? no + ``` -Job ID: job_12345 -Error: Network timeout +6. **Final Confirmation**: + ``` + โš ๏ธ Execute on production without dry-run? + This will make changes immediately. + Confirm: yes + ``` -Troubleshooting: -1. Check ansible-mcp-server is running -2. Verify network connectivity -3. Retry status check manually: get_job_status(job_id="job_12345") -``` +7. **Execute Playbook**: + - Launch with `job_type="run"` + - Monitor and report as in Example 1 ## Dependencies ### Required MCP Servers -- `ansible-mcp-server` - Mock Ansible playbook execution server (container-based) +- `aap-mcp-job-management` - AAP job management and execution +- `aap-mcp-inventory-management` - AAP inventory management ### Required MCP Tools -- `execute_playbook` (from ansible-mcp-server) - Submit playbook for execution - - Parameters: playbook_path (string - absolute path in container filesystem starting with /playbooks/) - - Returns: Job object with job_id, status, playbook_path - - Note: Mock implementation validates path and creates test job -- `get_job_status` (from ansible-mcp-server) - Track execution progress - - Parameters: job_id (string - job ID from execute_playbook) - - Returns: Job status object with job_id, status (PENDING/RUNNING/COMPLETED), started_at, completed_at - - Note: Mock implementation simulates job lifecycle +- `job_templates_list` (from aap-mcp-job-management) - List templates +- `job_templates_retrieve` (from aap-mcp-job-management) - Get template details +- `job_templates_launch_retrieve` (from aap-mcp-job-management) - Launch jobs +- `jobs_retrieve` (from aap-mcp-job-management) - Get job status +- `jobs_stdout_retrieve` (from aap-mcp-job-management) - Get console output +- `jobs_job_events_list` (from aap-mcp-job-management) - Get task events +- `jobs_job_host_summaries_list` (from aap-mcp-job-management) - Get host statistics +- `inventories_list` (from aap-mcp-inventory-management) - List inventories +- `hosts_list` (from aap-mcp-inventory-management) - List hosts ### Related Skills -- `mcp-ansible-validator` - **PREREQUISITE** - Validates ansible-mcp-server before execution (invoke in Step 0 if not validated in session) -- `playbook-generator` - Generates playbooks that this skill executes -- `remediation-verifier` - Verifies success after this skill completes execution +- `mcp-aap-validator` - **PREREQUISITE** - Validates AAP MCP servers (invoke in Phase 0) +- `job-template-creator` - Creates/guides AAP job template setup +- `playbook-generator` - Generates playbooks for execution +- `remediation-verifier` - Verifies success after execution ### Reference Documentation -- None required (execution skill) +- [AAP Job Execution Guide](../../docs/ansible/aap-job-execution.md) - AAP job execution best practices +- [Playbook Integration with AAP](../../docs/ansible/playbook-integration-aap.md) - Playbook-to-AAP workflow + +## Critical: Human-in-the-Loop Requirements + +This skill executes code on production systems. **Explicit user confirmation is REQUIRED** at multiple stages. + +**Before Dry-Run Execution** (if user chooses dry-run): +1. **Display Playbook Preview**: Show tasks and explain changes +2. **Ask for Dry-Run Confirmation**: + ``` + โ“ Run dry-run to simulate changes? + + Options: + - "yes" - Run dry-run (recommended) + - "no" - Skip to actual execution + - "abort" - Cancel + + Please respond with your choice. + ``` +3. **Wait for Explicit Response**: Do not proceed without confirmation + +**Before Actual Execution** (REQUIRED): +1. **Display Execution Summary**: Show systems, changes, downtime estimate +2. **Ask for Final Confirmation**: + ``` + โš ๏ธ CRITICAL: Execute playbook on production systems? + + This will make real changes to N systems. + + Options: + - "yes" or "execute" - Proceed + - "abort" - Cancel + + Please respond with your choice. + ``` +3. **Wait for Explicit "yes" or "execute"**: Do not proceed without confirmation + +**Never assume approval** - always wait for explicit user confirmation before executing playbooks. ## Best Practices -1. **Always save playbook to /tmp** - Required for container volume mount access (mount: `/tmp:/playbooks:Z`) -2. **Convert paths correctly** - Host path `/tmp/file.yml` โ†’ Container path `/playbooks/file.yml` before calling execute_playbook -3. **Require user confirmation** - ALWAYS get explicit "yes" or "execute" before submitting playbook (HITL requirement) -4. **Poll status efficiently** - 2-second intervals balance responsiveness and overhead -5. **Handle all status transitions** - PENDING โ†’ RUNNING โ†’ COMPLETED (mock implementation) -6. **Cleanup temp files** - Remove after successful completion from `/tmp/` on host -7. **Provide progress updates** - Keep user informed during polling with status messages -8. **Link to verification** - Always suggest remediation-verifier skill after execution completes -9. **Keep temp files on failure** - Useful for debugging failed executions -10. **Use unique temp filenames** - Include CVE ID or timestamp to avoid conflicts (e.g., `remediation-CVE-2024-1234-{timestamp}.yml`) +1. **Always validate AAP prerequisites** - Invoke mcp-aap-validator in Phase 0 +2. **Recommend dry-run** - Offer check mode before production execution +3. **Filter compatible templates** - Check inventory, project, and credentials match +4. **Monitor in real-time** - Display task progress during execution +5. **Comprehensive reporting** - Include per-host stats, task timeline, full output +6. **Error categorization** - Parse errors and provide specific troubleshooting +7. **Relaunch capability** - Offer to retry failed hosts +8. **Link to AAP** - Provide direct URL to job in AAP Web UI +9. **Suggest verification** - Always recommend remediation-verifier after success +10. **Document job details** - Save job ID and template info for audit trail ## Integration with Other Skills - **playbook-generator**: Generates playbooks that this skill executes +- **job-template-creator**: Creates AAP job templates when needed - **remediation-verifier**: Verifies success after this skill completes execution -- **sre-agents:remediator agent**: Orchestrates full workflow including playbook execution (invoked) +- **sre-agents:remediator agent**: Orchestrates full workflow including playbook execution -**Orchestration Example** (from sre-agents:remediator agent - invoked): +**Orchestration Example** (from sre-agents:remediator agent): 1. Agent invokes playbook-generator skill โ†’ Creates playbook YAML -2. playbook-generator skill asks for confirmation โ†’ User approves playbook content -3. Agent invokes playbook-executor skill โ†’ Skill asks for execution confirmation -4. User approves execution โ†’ Skill saves to temp file, executes, monitors -5. Skill reports: "Playbook executed successfully" -6. Agent invokes remediation-verifier skill โ†’ Confirms CVE resolved - -**Note**: Both playbook-generator and playbook-executor require separate confirmations: +2. playbook-generator asks for confirmation โ†’ User approves playbook content +3. Agent invokes playbook-executor skill (this skill) โ†’ Execution workflow +4. Skill guides template selection โ†’ User selects or creates template +5. Skill offers dry-run โ†’ User runs check mode +6. Skill asks for execution confirmation โ†’ User approves +7. Skill executes and monitors โ†’ Reports completion +8. Agent invokes remediation-verifier skill โ†’ Confirms CVE resolved + +**Note**: Both playbook-generator and playbook-executor require separate confirmations for different purposes: - playbook-generator: Confirms playbook content is acceptable - playbook-executor: Confirms execution on production systems is approved diff --git a/rh-sre/skills/playbook-generator/SKILL.md b/rh-sre/skills/playbook-generator/SKILL.md index 05cdaa24..0e67c3aa 100644 --- a/rh-sre/skills/playbook-generator/SKILL.md +++ b/rh-sre/skills/playbook-generator/SKILL.md @@ -1,13 +1,16 @@ --- name: playbook-generator description: | - **CRITICAL**: This skill must be used for playbook generation. DO NOT use raw MCP tools like create_vulnerability_playbook directly. + **CRITICAL**: This skill ONLY GENERATES playbooks. It does NOT EXECUTE them. For execution, use /playbook-executor skill. Generate production-ready Ansible remediation playbooks for CVE vulnerabilities with Red Hat best practices, error handling, and Kubernetes safety patterns. Use this skill when you need to create remediation playbooks that follow Red Hat Lightspeed patterns and incorporate RHEL-specific considerations. This skill orchestrates MCP tools (create_vulnerability_playbook) while consulting documentation (cve-remediation-templates.md, package-management.md) to enhance playbooks with Red Hat best practices and RHEL-specific patterns. - **IMPORTANT**: ALWAYS use this skill instead of calling create_vulnerability_playbook directly for playbook generation. + **IMPORTANT**: + - ALWAYS use this skill instead of calling create_vulnerability_playbook directly + - NEVER execute playbooks using ansible-playbook CLI + - ALWAYS delegate execution to /playbook-executor skill --- # Ansible Playbook Generator Skill @@ -18,19 +21,30 @@ This skill generates Ansible remediation playbooks for CVE vulnerabilities, appl ## When to Use This Skill +**๐Ÿšจ CRITICAL SCOPE LIMITATION**: This skill **ONLY GENERATES** playbooks. It does **NOT EXECUTE** them. + **Use this skill directly when you need**: - Generate a remediation playbook for a specific CVE - Create batch remediation playbooks for multiple CVEs - Apply Red Hat best practices to playbook generation - Standalone playbook generation without full remediation workflow +**Do NOT use this skill when you need**: +- Execute playbooks โ†’ Use `/playbook-executor` skill instead +- Run ansible-playbook CLI โ†’ Use `/playbook-executor` skill via AAP MCP +- Monitor job execution โ†’ Use `/playbook-executor` skill instead + **Use the sre-agents:remediator agent when you need**: - End-to-end CVE remediation (analysis โ†’ validation โ†’ playbook โ†’ execution โ†’ verification) - Integrated impact analysis before playbook generation - System context gathering and remediation strategy determination - Execution guidance and verification workflows -**How they work together**: The sre-agents:remediator agent (invoked) orchestrates this skill after gathering system context and determining remediation strategy. The agent provides CVE details, system information, and deployment context, and this skill generates the optimized playbook. +**How they work together**: +1. The sre-agents:remediator agent (invoked) orchestrates this skill after gathering system context +2. This skill generates the optimized playbook +3. The agent then invokes `/playbook-executor` skill for execution via AAP MCP +4. Finally, `/remediation-verifier` skill confirms success ## Workflow @@ -250,6 +264,8 @@ This skill generates code that will execute on production systems. **Explicit us ### 7. Return Playbook +**๐Ÿšจ CRITICAL**: This skill **ONLY GENERATES** playbooks. It does **NOT EXECUTE** them. + **ONLY after receiving explicit user confirmation**, return the production-ready playbook with metadata: ```yaml @@ -275,6 +291,39 @@ playbook: - "Back up critical data before execution" ``` +## Critical: Execution Handoff + +**๐Ÿšจ THIS SKILL DOES NOT EXECUTE PLAYBOOKS** + +After generating the playbook, if the user requests execution: + +โŒ **WRONG** - Do NOT use `ansible-playbook` CLI: +```bash +ansible-playbook remediation.yml --check # โŒ This skill cannot do this +``` + +โœ… **CORRECT** - Delegate to the `/playbook-executor` skill: +```markdown +I've generated the remediation playbook. To execute it in dry-run mode, I'll invoke the playbook-executor skill: + +[Invoke /playbook-executor skill with the playbook content] +``` + +**When user asks to execute**: +1. Save the playbook to a file (if needed for reference) +2. Invoke `/playbook-executor` skill with instruction: + ``` + "Execute this playbook for CVE-XXXX-YYYY in dry-run mode using AAP job template [ID]. Monitor job status and report results." + ``` +3. The playbook-executor skill handles all execution via AAP MCP tools + +**Never attempt to**: +- Run `ansible-playbook` command directly +- Execute playbooks via Shell/Bash tool +- Use any local Ansible execution method + +**Always delegate execution to** `/playbook-executor` skill. + ## Output Template When completing playbook generation, provide output in this format: @@ -305,25 +354,31 @@ When completing playbook generation, provide output in this format: [Complete playbook YAML] ``` -## Execution Instructions +## Next Steps: Execution -**Prerequisites**: -- Ansible 2.9+ installed -- SSH access to target systems -- Sudo privileges on target systems -- (If K8s) kubectl configured and accessible +**๐Ÿ”ด IMPORTANT**: Do NOT execute this playbook using `ansible-playbook` CLI. -**Execution Command**: -```bash -ansible-playbook -i inventory remediation-CVE-YYYY-NNNNN.yml --become +**โœ… To execute this playbook**, invoke the `/playbook-executor` skill: + +```markdown +Ready to execute? The playbook-executor skill will: +1. Add this playbook to your AAP Git project +2. Create/use an AAP job template +3. Execute in dry-run mode first (if requested) +4. Launch actual execution (with your approval) +5. Monitor job status and report results + +Would you like me to invoke the playbook-executor skill now? +Options: +- "yes" or "execute" - Invoke playbook-executor skill +- "dry-run first" - Execute in check mode first +- "save only" - Just save the playbook file for later ``` -**Recommended Workflow**: -1. Test in staging environment first -2. Review playbook for environment-specific adjustments -3. Schedule maintenance window if reboot required -4. Execute playbook -5. Verify remediation success (use remediation-verifier skill) +**Execution Flow**: +1. **This skill** โ†’ Generates playbook (DONE โœ“) +2. **playbook-executor skill** โ†’ Executes via AAP MCP tools +3. **remediation-verifier skill** โ†’ Verifies success after execution **Safety Notes**: - Playbook includes rollback capability via snapshots (RHEL 8/9) @@ -441,15 +496,17 @@ Proceeding with standard playbook (without pod eviction). Add pod eviction manua ## Best Practices -1. **Always consult documentation first** - Read [cve-remediation-templates.md] and [package-management.md] BEFORE calling MCP tools -2. **Detect CVE type** - Use appropriate template for kernel vs package vs service CVEs -3. **Check Kubernetes context** - Add pod eviction for K8s-deployed systems -4. **RHEL version awareness** - Use dnf for RHEL 8/9, yum for RHEL 7 -5. **Include pre-flight checks** - Validate OS, subscription status before proceeding -6. **Add rollback capability** - Use snapshots, backups for safety -7. **Audit everything** - Log all actions to /var/log/cve-remediation.log -8. **Require user approval** - ALWAYS get explicit confirmation before providing executable playbooks -9. **Test first** - Always recommend testing in staging before production +1. **๐Ÿšจ NEVER EXECUTE PLAYBOOKS** - This skill generates only. Always delegate execution to `/playbook-executor` skill +2. **Always consult documentation first** - Read [cve-remediation-templates.md] and [package-management.md] BEFORE calling MCP tools +3. **Detect CVE type** - Use appropriate template for kernel vs package vs service CVEs +4. **Check Kubernetes context** - Add pod eviction for K8s-deployed systems +5. **RHEL version awareness** - Use dnf for RHEL 8/9, yum for RHEL 7 +6. **Include pre-flight checks** - Validate OS, subscription status before proceeding +7. **Add rollback capability** - Use snapshots, backups for safety +8. **Audit everything** - Log all actions to /var/log/cve-remediation.log +9. **Require user approval** - ALWAYS get explicit confirmation before providing playbooks +10. **Test first** - Always recommend testing in staging before production +11. **Clear handoff** - After generation, explicitly tell user to invoke `/playbook-executor` for execution ## Tools Reference diff --git a/rh-support-engineer/.claude-plugin/plugin.json b/rh-support-engineer/.claude-plugin/plugin.json index 1b912023..c0ce1ae0 100644 --- a/rh-support-engineer/.claude-plugin/plugin.json +++ b/rh-support-engineer/.claude-plugin/plugin.json @@ -1,5 +1,5 @@ { - "name": "Red Hat Support Engineer Agentic Collection", + "name": "rh-support-engineer", "version": "1.0.0", "description": "Technical support and troubleshooting tools for Red Hat products and platforms.", "author": { diff --git a/rh-virt/.claude-plugin/plugin.json b/rh-virt/.claude-plugin/plugin.json index a57fbdfb..d121a770 100644 --- a/rh-virt/.claude-plugin/plugin.json +++ b/rh-virt/.claude-plugin/plugin.json @@ -1,5 +1,5 @@ { - "name": "OpenShift Virtualization Agentic Collection", + "name": "rh-virt", "version": "1.0.0", "description": "Virtual machine management and automation for OpenShift Virtualization and KubeVirt workloads.", "author": { diff --git a/scripts/generate_pack_data.py b/scripts/generate_pack_data.py index 100d6f89..37616fa4 100644 --- a/scripts/generate_pack_data.py +++ b/scripts/generate_pack_data.py @@ -13,6 +13,11 @@ # List of agentic packs to parse PACK_DIRS = ['rh-sre', 'rh-developer', 'ocp-admin', 'rh-support-engineer', 'rh-virt'] +# Mapping from directory name to key in docs/plugins.json (if different) +PACK_TO_PLUGINS_KEY = { + 'ocp-admin': 'rh-ocp-admin', # Directory is ocp-admin, but plugins.json key is rh-ocp-admin +} + def parse_yaml_frontmatter(file_path: Path) -> Dict[str, Any]: """ @@ -41,12 +46,38 @@ def parse_yaml_frontmatter(file_path: Path) -> Dict[str, Any]: return {} -def parse_plugin_json(pack_dir: str) -> Dict[str, Any]: +def load_plugin_titles() -> Dict[str, str]: """ - Parse plugin.json from a pack directory. + Load plugin title mappings from docs/plugins.json. + + Returns: + Dictionary mapping plugin names to display titles + """ + plugins_file = Path('docs/plugins.json') + + if not plugins_file.exists(): + print("Warning: docs/plugins.json not found, using default titles") + return {} + + try: + with open(plugins_file, 'r', encoding='utf-8') as f: + data = json.load(f) + + # Extract just the titles into a simple mapping + return {name: info['title'] for name, info in data.items()} + + except Exception as e: + print(f"Warning: Failed to load docs/plugins.json: {e}") + return {} + + +def parse_plugin_json(pack_dir: str, plugin_titles: Dict[str, str]) -> Dict[str, Any]: + """ + Parse plugin.json from a pack directory and merge with title from docs/plugins.json. Args: pack_dir: Name of the pack directory + plugin_titles: Dictionary mapping plugin names to display titles Returns: Dictionary with plugin metadata, or defaults if file doesn't exist @@ -63,7 +94,13 @@ def parse_plugin_json(pack_dir: str) -> Dict[str, Any]: 'keywords': [] } + # Check if pack_dir has a different key in plugins.json + plugins_key = PACK_TO_PLUGINS_KEY.get(pack_dir, pack_dir) + if not plugin_path.exists(): + # Use title from plugins.json if available + if plugins_key in plugin_titles: + defaults['title'] = plugin_titles[plugins_key] return defaults try: @@ -71,10 +108,22 @@ def parse_plugin_json(pack_dir: str) -> Dict[str, Any]: data = json.load(f) # Merge with defaults (in case some fields are missing) - return {**defaults, **data} + result = {**defaults, **data} + + # Override with title from docs/plugins.json if available + if plugins_key in plugin_titles: + result['title'] = plugin_titles[plugins_key] + elif 'title' not in result: + # Fallback: use name as title if not set + result['title'] = result['name'] + + return result except Exception as e: print(f"Warning: Failed to parse {plugin_path}: {e}") + # Use title from plugins.json if available even on error + if plugins_key in plugin_titles: + defaults['title'] = plugin_titles[plugins_key] return defaults @@ -235,6 +284,9 @@ def generate_pack_data() -> List[Dict[str, Any]]: List of pack dictionaries """ packs = [] + + # Load plugin title mappings from docs/plugins.json + plugin_titles = load_plugin_titles() for pack_dir in PACK_DIRS: pack_path = Path(pack_dir) @@ -248,7 +300,7 @@ def generate_pack_data() -> List[Dict[str, Any]]: pack = { 'name': pack_dir, 'path': f'./{pack_dir}', - 'plugin': parse_plugin_json(pack_dir), + 'plugin': parse_plugin_json(pack_dir, plugin_titles), 'skills': parse_skills(pack_dir), 'agents': parse_agents(pack_dir), 'docs': docs, @@ -257,7 +309,9 @@ def generate_pack_data() -> List[Dict[str, Any]]: packs.append(pack) - print(f"โœ“ Parsed {pack_dir}: {len(pack['skills'])} skills, {len(pack['agents'])} agents, {len(docs)} docs") + # Use title from plugin data for display + plugin_title = pack['plugin'].get('title', pack_dir) + print(f"โœ“ Parsed {plugin_title}: {len(pack['skills'])} skills, {len(pack['agents'])} agents, {len(docs)} docs") return packs @@ -275,5 +329,7 @@ def generate_pack_data() -> List[Dict[str, Any]]: print("Summary:") for pack in packs: plugin = pack['plugin'] - print(f" โ€ข {plugin['name']} v{plugin['version']}") + title = plugin.get('title', plugin['name']) + print(f" โ€ข {title} v{plugin['version']}") + print(f" ({plugin['name']})") print(f" Skills: {len(pack['skills'])}, Agents: {len(pack['agents'])}, Docs: {len(pack['docs'])}") From 8136a1751fd49434bad0ff8d91109d5d609cb756 Mon Sep 17 00:00:00 2001 From: Daniele Martinoli Date: Wed, 25 Feb 2026 23:42:41 +0100 Subject: [PATCH 02/20] Update AAP integration documentation and skills - Changed environment variable references from `AAP_SERVER` to `AAP_MCP_SERVER`. - Added a new skill, `job-template-remediation-validator`, to validate AAP job templates for CVE remediation playbooks. - Enhanced existing skills and documentation to reflect the new validation process. Signed-off-by: Daniele Martinoli --- rh-sre/README.md | 39 +- rh-sre/agents/remediator.md | 10 +- rh-sre/docs/ansible/aap-job-execution.md | 6 +- .../docs/ansible/playbook-integration-aap.md | 2 +- .../testing/aap-integration-test-guide.md | 8 +- rh-sre/skills/job-template-creator/SKILL.md | 22 +- .../SKILL.md | 376 ++++++++++++++++++ rh-sre/skills/mcp-aap-validator/SKILL.md | 51 +-- rh-sre/skills/playbook-executor/SKILL.md | 179 ++++----- rh-sre/skills/playbook-generator/SKILL.md | 1 + 10 files changed, 534 insertions(+), 160 deletions(-) create mode 100644 rh-sre/skills/job-template-remediation-validator/SKILL.md diff --git a/rh-sre/README.md b/rh-sre/README.md index 8be80be9..e1f89419 100644 --- a/rh-sre/README.md +++ b/rh-sre/README.md @@ -285,7 +285,7 @@ Validate AAP (Ansible Automation Platform) MCP server configuration and connecti **What it does:** - Checks both AAP MCP servers (job-management, inventory-management) -- Verifies environment variables (AAP_SERVER, AAP_API_TOKEN) +- Verifies environment variables (AAP_MCP_SERVER, AAP_API_TOKEN) - Tests server connectivity and authentication - Reports validation status (PASSED/PARTIAL/FAILED) @@ -318,6 +318,20 @@ Create AAP job templates for executing Ansible playbooks through Ansible Automat - Verifies template creation - Prepares for AAP-based playbook execution +### 12. **job-template-remediation-validator** - AAP Job Template Remediation Validation +Verify an AAP job template meets requirements for executing CVE remediation playbooks. + +**Use when:** +- "Does this job template support remediation playbooks?" +- "Validate job template X for CVE remediation" +- "Check if template is ready for playbook-executor" + +**What it does:** +- Validates required fields (inventory, project, playbook, credentials, privilege escalation) +- Checks recommended options (ask variables/limit on launch) +- Verifies project and inventory exist +- Reports PASSED / PASSED WITH WARNINGS / FAILED + ## Agent ### **remediator** - End-to-End CVE Remediation Orchestration @@ -353,6 +367,7 @@ The remediator agent orchestrates the CVE-related skills to provide complete CVE | "Validate Lightspeed MCP" | **mcp-lightspeed-validator skill** | MCP server validation | | "Validate AAP MCP" | **mcp-aap-validator skill** | AAP MCP validation | | "Create job template" | **job-template-creator skill** | AAP template setup | +| "Validate template for remediation" | **job-template-remediation-validator skill** | Template compatibility check | | "Generate execution summary" | **execution-summary skill** | Audit trail reporting | | "Remediate CVE-2024-1234" | **remediator agent** | Multi-step workflow | | "Create playbook for CVE-X" | **remediator agent** | Orchestration needed | @@ -396,7 +411,7 @@ The pack integrates with three MCP servers (configured in `.mcp.json`): - Job template management (list, retrieve, launch) - Job execution tracking and monitoring - Workflow job management -- Requires: `AAP_SERVER`, `AAP_API_TOKEN` +- Requires: `AAP_MCP_SERVER`, `AAP_API_TOKEN` **Type**: HTTP MCP server @@ -404,7 +419,7 @@ The pack integrates with three MCP servers (configured in `.mcp.json`): - Inventory and host management - Group and variable management - System discovery and targeting -- Requires: `AAP_SERVER`, `AAP_API_TOKEN` +- Requires: `AAP_MCP_SERVER`, `AAP_API_TOKEN` **Type**: HTTP MCP server @@ -479,13 +494,13 @@ MCP servers are configured in `.mcp.json`: } }, "aap-mcp-job-management": { - "url": "https://${AAP_SERVER}/job_management/mcp", + "url": "https://${AAP_MCP_SERVER}/job_management/mcp", "headers": { "Authorization": "Bearer ${AAP_API_TOKEN}" } }, "aap-mcp-inventory-management": { - "url": "https://${AAP_SERVER}/inventory_management/mcp", + "url": "https://${AAP_MCP_SERVER}/inventory_management/mcp", "headers": { "Authorization": "Bearer ${AAP_API_TOKEN}" } @@ -496,7 +511,8 @@ MCP servers are configured in `.mcp.json`: **Key Configuration Notes**: - HTTP MCP servers for AAP use URL-based connections with Bearer token authentication -- Environment variables (`AAP_SERVER`, `AAP_API_TOKEN`) injected at runtime +- `AAP_MCP_SERVER` must point to the MCP endpoint of the AAP server (the MCP gateway URL), not the main AAP Web UI +- Environment variables (`AAP_MCP_SERVER`, `AAP_API_TOKEN`) injected at runtime - Container-based server (lightspeed-mcp) uses Podman with environment variable injection ## Troubleshooting @@ -533,7 +549,7 @@ MCP servers are configured in `.mcp.json`: **Solutions**: 1. Verify AAP server is accessible: ```bash - curl -I ${AAP_SERVER} + curl -I ${AAP_MCP_SERVER} ``` 2. Check API token validity: - Log in to AAP Web UI @@ -542,12 +558,12 @@ MCP servers are configured in `.mcp.json`: 3. Test API authentication: ```bash curl -H "Authorization: Bearer ${AAP_API_TOKEN}" \ - ${AAP_SERVER}/api/controller/v2/ping/ + ${AAP_MCP_SERVER}/api/controller/v2/ping/ ``` -4. Verify environment variables are set: +4. Verify environment variables are set (do not echo values; check presence only): ```bash - echo $AAP_SERVER - echo $AAP_API_TOKEN # Should show token value + test -n "$AAP_MCP_SERVER" && echo "AAP_MCP_SERVER is set" + test -n "$AAP_API_TOKEN" && echo "AAP_API_TOKEN is set" ``` ### Skills Not Triggering @@ -584,6 +600,7 @@ rh-sre/ โ”‚ โ”œโ”€โ”€ mcp-lightspeed-validator/SKILL.md โ”‚ โ”œโ”€โ”€ mcp-aap-validator/SKILL.md โ”‚ โ”œโ”€โ”€ job-template-creator/SKILL.md +โ”‚ โ”œโ”€โ”€ job-template-remediation-validator/SKILL.md โ”‚ โ””โ”€โ”€ execution-summary/SKILL.md โ””โ”€โ”€ docs/ # AI-optimized documentation โ”œโ”€โ”€ INDEX.md diff --git a/rh-sre/agents/remediator.md b/rh-sre/agents/remediator.md index 60a5eaeb..6f23806c 100644 --- a/rh-sre/agents/remediator.md +++ b/rh-sre/agents/remediator.md @@ -232,15 +232,17 @@ Invoke the `/playbook-generator` skill with the instruction: **๐Ÿ”ง ACTION REQUIRED: Execute the `/playbook-executor` skill** -Invoke the `/playbook-executor` skill with the instruction: +Invoke the `/playbook-executor` skill with the instruction. Pass playbook metadata so the skill can derive the playbook path and match templates: ``` -"Execute the generated playbook for CVE-XXXX-YYYY on target systems using AAP job template [ID]. Start with dry-run (check mode) if user requested it. Monitor job status until completion and report results." +"Execute the generated playbook for CVE-XXXX-YYYY. Playbook file: [filename from playbook-generator]. Content: [in context from playbook-generator output]. Target systems: [list of system UUIDs from system-context]. Start with dry-run (check mode) if user requested it. Monitor job status until completion and report results." ``` +**Important**: Ensure playbook content and filename are in context when invoking. The playbook-executor derives the path as `playbooks/remediation/` and uses it to match job templates. + **Expected behavior**: The skill will: - Validate AAP MCP server availability (via mcp-aap-validator) -- Select or guide creation of suitable job template -- Add playbook to AAP project repository +- Match templates by playbook path (exact match, different path with override, or invoke job-template-creator if none found) +- Add playbook to AAP project via git when override chosen (with commit/push confirmation) - Offer dry-run execution (job_type="check") - If approved, launch actual execution (job_type="run") - Poll job status with `jobs_retrieve` diff --git a/rh-sre/docs/ansible/aap-job-execution.md b/rh-sre/docs/ansible/aap-job-execution.md index ba71b423..3e5fb928 100644 --- a/rh-sre/docs/ansible/aap-job-execution.md +++ b/rh-sre/docs/ansible/aap-job-execution.md @@ -248,7 +248,7 @@ Example timeline: **Format**: ``` -https://{AAP_SERVER}/#/jobs/playbook/{JOB_ID} +https://{your-aap-instance}/#/jobs/playbook/{JOB_ID} ``` **Example**: @@ -268,7 +268,7 @@ https://aap.example.com/#/jobs/playbook/1235 **Format**: ``` -https://{AAP_SERVER}/#/templates/job_template/{TEMPLATE_ID}/details +https://{your-aap-instance}/#/templates/job_template/{TEMPLATE_ID}/details ``` **Example**: @@ -280,7 +280,7 @@ https://aap.example.com/#/templates/job_template/10/details **Format**: ``` -https://{AAP_SERVER}/#/projects/{PROJECT_ID}/details +https://{your-aap-instance}/#/projects/{PROJECT_ID}/details ``` ## Troubleshooting Common Execution Failures diff --git a/rh-sre/docs/ansible/playbook-integration-aap.md b/rh-sre/docs/ansible/playbook-integration-aap.md index 2f9935af..8e27b44b 100644 --- a/rh-sre/docs/ansible/playbook-integration-aap.md +++ b/rh-sre/docs/ansible/playbook-integration-aap.md @@ -162,7 +162,7 @@ git push origin main **Via AAP API** (if available): ```bash curl -X POST \ - "${AAP_SERVER}/api/controller/v2/projects/${PROJECT_ID}/update/" \ + "${AAP_MCP_SERVER}/api/controller/v2/projects/${PROJECT_ID}/update/" \ -H "Authorization: Bearer ${AAP_API_TOKEN}" ``` diff --git a/rh-sre/docs/testing/aap-integration-test-guide.md b/rh-sre/docs/testing/aap-integration-test-guide.md index 5f8b7d05..ce05e4dd 100644 --- a/rh-sre/docs/testing/aap-integration-test-guide.md +++ b/rh-sre/docs/testing/aap-integration-test-guide.md @@ -30,7 +30,7 @@ This guide provides a comprehensive testing plan for the AAP MCP integration, co 2. **Environment Variables**: ```bash - export AAP_SERVER="https://your-aap-server.com" + export AAP_MCP_SERVER="https://your-aap-mcp-endpoint.com" export AAP_API_TOKEN="your-api-token" ``` @@ -49,7 +49,7 @@ This guide provides a comprehensive testing plan for the AAP MCP integration, co Before starting tests, verify: -- [ ] AAP Web UI accessible at `${AAP_SERVER}` +- [ ] AAP Web UI accessible (your AAP instance URL) - [ ] Can log in with your credentials - [ ] API token has been generated - [ ] Environment variables are set (run: `env | grep AAP`) @@ -99,7 +99,7 @@ Test Phase 4: Performance Testing Configuration: โœ“ MCP server aap-mcp-job-management configured โœ“ MCP server aap-mcp-inventory-management configured -โœ“ Environment variable AAP_SERVER is set +โœ“ Environment variable AAP_MCP_SERVER is set โœ“ Environment variable AAP_API_TOKEN is set โœ“ Job management server connectivity verified โœ“ Inventory management server connectivity verified @@ -587,7 +587,7 @@ Date: YYYY-MM-DD **Symptoms**: Validation fails with connection errors **Solutions**: -1. Verify `AAP_SERVER` environment variable is correct +1. Verify `AAP_MCP_SERVER` environment variable is correct (must point to the MCP endpoint of the AAP server) 2. Check API token is valid and not expired 3. Ensure AAP server is accessible from your network 4. Review AAP MCP server logs for errors diff --git a/rh-sre/skills/job-template-creator/SKILL.md b/rh-sre/skills/job-template-creator/SKILL.md index f4f64087..6d14a8ad 100644 --- a/rh-sre/skills/job-template-creator/SKILL.md +++ b/rh-sre/skills/job-template-creator/SKILL.md @@ -37,7 +37,7 @@ This skill helps SREs create AAP job templates for executing Ansible playbooks, - โš ๏ธ `job_templates_update` - **NOT CURRENTLY AVAILABLE** **Required Environment Variables**: -- `AAP_SERVER` - AAP MCP server URL +- `AAP_MCP_SERVER` - Base URL for the MCP endpoint of the AAP server (must point to the AAP MCP gateway) - `AAP_API_TOKEN` - AAP API authentication token ### Prerequisite Validation @@ -81,6 +81,23 @@ This skill documents both the **current manual workflow** and the **intended aut - Only need to execute existing templates (use `job_templates_launch_retrieve`) - Need to modify existing templates (requires AAP Web UI currently) +## Invocation from playbook-executor + +When invoked from the [playbook-executor](../playbook-executor/SKILL.md) skill (Scenario 3 - No suitable template), this skill receives playbook content in context. The playbook-executor invokes with an instruction such as: + +``` +Create a job template for this remediation playbook. Playbook: [content]. Filename: [filename]. Path: [our_playbook_path]. CVE: [cve_id]. Target systems: [list]. +``` + +**When playbook content is provided**: +- Use the provided content for Phase 1 (Prepare Playbook in Git) instead of asking the user to supply it +- Write the playbook to the specified path in the user's Git repository (ask for repo path if not provided) +- Follow the Git flow: add, commit (with checkpoint for confirmation), push +- Then guide template creation via AAP Web UI (Phase 4) +- **Output**: Include the created template ID and name in the final report so playbook-executor can retrieve and validate it + +**Phase 0 - Check context**: If playbook content is provided by the invoking skill, execute the git flow (write, add, commit with confirmation checkpoint, push) before guiding template creation. Otherwise, use the existing manual flow where the user supplies the playbook. + ## Workflow ### Phase 0: Validate AAP MCP Prerequisites @@ -394,7 +411,7 @@ Before creating a job template, collect: **Step 1: Navigate to AAP Web Interface** -1. Open your browser and go to: `${AAP_SERVER}` +1. Open your browser and go to your AAP Web UI (the main AAP instance URL; this may differ from the MCP endpoint) 2. Log in with your AAP credentials **Step 2: Navigate to Templates** @@ -717,6 +734,7 @@ When completing job template creation, provide: ### Related Skills - `mcp-aap-validator` - **PREREQUISITE** - Validates AAP MCP server before creation (invoke in Phase 0 if not validated in session) +- `job-template-remediation-validator` - Validates created template meets remediation requirements - `playbook-executor` - Execute templates after creation - `playbook-generator` - Generate remediation playbooks for templates - `system-context` - Identify target systems for inventory selection diff --git a/rh-sre/skills/job-template-remediation-validator/SKILL.md b/rh-sre/skills/job-template-remediation-validator/SKILL.md new file mode 100644 index 00000000..9535e49b --- /dev/null +++ b/rh-sre/skills/job-template-remediation-validator/SKILL.md @@ -0,0 +1,376 @@ +--- +name: job-template-remediation-validator +description: | + Verify an AAP job template meets requirements for executing CVE remediation playbooks. + + Use when: + - "Does this job template support remediation playbooks?" + - "Validate job template X for CVE remediation" + - "Check if template is ready for playbook-executor" + - Before playbook-executor selects a template + + NOT for: AAP MCP connectivity (use mcp-aap-validator), creating templates (use job-template-creator). +model: inherit +color: blue +--- + +# AAP Job Template Remediation Validator + +This skill verifies that an AAP (Ansible Automation Platform) job template meets the requirements for executing CVE remediation playbooks as defined by the remediator agent and playbook-executor workflow. + +## Prerequisites + +**Required MCP Servers**: `aap-mcp-job-management`, `aap-mcp-inventory-management` ([setup guide](https://docs.redhat.com/)) + +**Required MCP Tools**: +- `job_templates_list` (from aap-mcp-job-management) - List job templates +- `job_templates_retrieve` (from aap-mcp-job-management) - Get template details +- `projects_list` (from aap-mcp-job-management) - Verify project exists and status +- `inventories_list` (from aap-mcp-inventory-management) - Verify inventory exists + +**Required Environment Variables**: +- `AAP_MCP_SERVER` - Base URL for the MCP endpoint of the AAP server (must point to the AAP MCP gateway) +- `AAP_API_TOKEN` - AAP API authentication token + +### Prerequisite Validation + +**CRITICAL**: Before executing, invoke the [mcp-aap-validator](../mcp-aap-validator/SKILL.md) skill to verify AAP MCP server availability. + +**Validation freshness**: Can skip if already validated in this session. See [Validation Freshness Policy](../mcp-aap-validator/SKILL.md#validation-freshness-policy). + +**How to invoke**: +``` +Use the Skill tool: + skill: "mcp-aap-validator" +``` + +**Handle validation result**: +- **If validation PASSED**: Continue with template validation +- **If validation PARTIAL**: Warn user and ask to proceed +- **If validation FAILED**: Stop execution, provide setup instructions from validator + +**Human Notification on Failure**: +If prerequisites are not met: +- โŒ "Cannot proceed: AAP MCP servers are not available" +- ๐Ÿ“‹ "Setup required: Configure AAP_MCP_SERVER and AAP_API_TOKEN environment variables" +- โ“ "How would you like to proceed? (setup now / skip / abort)" +- โธ๏ธ Wait for user decision + +## When to Use This Skill + +**Use this skill when**: +- Verifying a job template before playbook execution +- Checking if a template meets remediation requirements +- Auditing existing templates for remediation readiness +- Troubleshooting "template not compatible" in playbook-executor + +**Do NOT use when**: +- Validating AAP MCP connectivity โ†’ Use `mcp-aap-validator` skill +- Creating new job templates โ†’ Use `job-template-creator` skill +- Executing playbooks โ†’ Use `playbook-executor` skill + +## Remediation Template Requirements + +This skill validates against the requirements documented in [playbook-executor](../playbook-executor/SKILL.md) and [job-template-creator](../job-template-creator/SKILL.md). + +### Required (Must Pass) + +| Requirement | Description | Validation | +|-------------|-------------|------------| +| **Inventory** | Template has inventory configured | `inventory` field present and non-null | +| **Project** | Template has project configured | `project` field present and non-null | +| **Playbook** | Template has playbook path | `playbook` field present, non-empty | +| **Credentials** | Machine credential (SSH) configured | `summary_fields.credentials` or `credentials` has at least one credential | +| **Privilege Escalation** | Required for package updates | `become_enabled` is true | + +### Recommended (Warnings if Missing) + +| Requirement | Description | Validation | +|-------------|-------------|------------| +| **Ask Variables on Launch** | Enables dynamic CVE targeting | `ask_variables_on_launch` is true | +| **Ask Limit on Launch** | Enables host targeting at launch | `ask_limit_on_launch` is true | + +### Optional Context Checks + +| Check | Description | +|-------|-------------| +| **Project Status** | Project exists and is synced (status "successful") | +| **Inventory Exists** | Inventory exists in AAP | +| **Playbook Path** | Path suggests remediation playbook (e.g., contains "remediation") | +| **Playbook Path Matching** | When used by playbook-executor (Scenario 3), the template's playbook path is trusted to match the playbook just created via job-template-creator | + +## Workflow + +### Phase 0: Validate AAP MCP Prerequisites + +**Action**: Invoke the [mcp-aap-validator](../mcp-aap-validator/SKILL.md) skill + +**Note**: Can skip if validation was performed earlier in this session and succeeded. + +**Handle validation result**: +- **If validation PASSED**: Continue to Phase 1 +- **If validation PARTIAL**: Warn user and ask to proceed +- **If validation FAILED**: Stop execution + +### Phase 1: Obtain Job Template + +**Goal**: Get the job template to validate. User may provide template ID or name. + +#### Option A: User Provides Template ID + +If user specifies a template ID (e.g., "42" or "template 42"): + +**MCP Tool**: `job_templates_retrieve` (from aap-mcp-job-management) + +**Parameters**: +- `id`: Template ID as string (e.g., `"42"`) + +**Expected Output**: Full job template object with fields: `id`, `name`, `inventory`, `project`, `playbook`, `become_enabled`, `ask_variables_on_launch`, `ask_limit_on_launch`, `summary_fields` (may include `credentials`), `credentials` (array of credential IDs) + +**Error Handling**: +- If 404 or template not found: Report "Template ID X not found. Verify the ID exists in AAP." +- If connection error: Report per mcp-aap-validator troubleshooting + +#### Option B: User Provides Template Name or No ID + +If user says "validate my remediation template" or provides a name: + +**MCP Tool**: `job_templates_list` (from aap-mcp-job-management) + +**Parameters**: +- `page_size`: 50 +- `search`: User-provided name or "remediation" (optional) + +**Action**: List templates, let user select by number or ID. If exactly one match, use it. If multiple, present list and ask user to choose. + +### Phase 2: Validate Required Fields + +**Goal**: Check each required field against the template response. + +**Input**: Template object from `job_templates_retrieve` + +**Validation Logic**: + +``` +required_checks = [] +required_checks.append(("Inventory", template.get("inventory") is not None and template.get("inventory") != "")) +required_checks.append(("Project", template.get("project") is not None and template.get("project") != "")) +required_checks.append(("Playbook", template.get("playbook") is not None and len(str(template.get("playbook", "")).strip()) > 0)) +required_checks.append(("Privilege Escalation", template.get("become_enabled") == True)) + +# Credentials: AAP API may return credentials in summary_fields.credentials or credentials array +creds = template.get("summary_fields", {}).get("credentials") or template.get("credentials") or [] +has_creds = (isinstance(creds, list) and len(creds) > 0) or (isinstance(creds, dict) and creds) +required_checks.append(("Credentials", has_creds)) +``` + +**Note**: If the AAP MCP response structure differs, adapt the field paths. Common AAP API response structures: +- `inventory`: number (ID) +- `project`: number (ID) +- `playbook`: string (path) +- `become_enabled`: boolean +- `credentials`: array of credential IDs, or `summary_fields.credentials` array of objects with `id`, `name` + +### Phase 3: Validate Recommended Fields + +**Validation Logic**: + +``` +recommended_checks = [] +recommended_checks.append(("Ask Variables on Launch", template.get("ask_variables_on_launch") == True)) +recommended_checks.append(("Ask Limit on Launch", template.get("ask_limit_on_launch") == True)) +``` + +### Phase 4: Optional Context Verification + +**Goal**: Verify referenced project and inventory exist and are usable. + +**Step 4.1: Verify Project Exists and Status** + +**MCP Tool**: `projects_list` (from aap-mcp-job-management) + +**Parameters**: +- `page_size`: 100 +- `search`: Optional - filter by project ID if API supports it + +**Action**: Search results for `id == template["project"]`. If found, check `status`: +- `"successful"`: โœ“ Project synced, playbooks available +- `"failed"` or `"error"`: โš  Project sync failed - playbooks may be stale +- `"pending"` or `"running"`: โš  Project syncing - wait before use + +**Step 4.2: Verify Inventory Exists** + +**MCP Tool**: `inventories_list` (from aap-mcp-inventory-management) + +**Parameters**: +- `page_size`: 100 + +**Action**: Search results for `id == template["inventory"]`. If found: โœ“ Inventory exists. If not found: โš  Inventory ID not found (may be permission issue). + +### Phase 5: Generate Validation Report + +**Output Format**: + +```markdown +# Job Template Remediation Validation Report + +**Template**: {name} (ID: {id}) +**Validated**: {timestamp} + +## Required Checks +| Requirement | Status | Details | +|-------------|--------|---------| +| Inventory | โœ“/โœ— | {inventory_id} - {inventory_name or "configured"} | +| Project | โœ“/โœ— | {project_id} - {project_name or "configured"} | +| Playbook | โœ“/โœ— | {playbook_path} | +| Credentials | โœ“/โœ— | {count} credential(s) configured | +| Privilege Escalation | โœ“/โœ— | become_enabled: {value} | + +## Recommended Checks +| Requirement | Status | Details | +|-------------|--------|---------| +| Ask Variables on Launch | โœ“/โš  | {value} | +| Ask Limit on Launch | โœ“/โš  | {value} | + +## Context Verification +| Check | Status | Details | +|-------|--------|---------| +| Project Exists | โœ“/โš /โœ— | {status} | +| Inventory Exists | โœ“/โš /โœ— | {details} | + +## Overall Result +{โœ“ PASSED / โš  PASSED WITH WARNINGS / โœ— FAILED} + +{If PASSED}: Template is ready for remediation playbook execution. +{If WARNINGS}: Template works but consider enabling ask_variables_on_launch and ask_limit_on_launch for flexibility. +{If FAILED}: Fix required checks before using with playbook-executor. See job-template-creator for setup guidance. +``` + +### Pass/Fail Determination + +- **PASSED**: All 5 required checks pass +- **PASSED WITH WARNINGS**: All required pass, one or more recommended fail +- **FAILED**: One or more required checks fail + +## Dependencies + +### Required MCP Servers +- `aap-mcp-job-management` - AAP job template and execution management +- `aap-mcp-inventory-management` - AAP inventory management + +### Required MCP Tools +- `job_templates_list` (from aap-mcp-job-management) - List templates +- `job_templates_retrieve` (from aap-mcp-job-management) - Get template details +- `projects_list` (from aap-mcp-job-management) - Verify project +- `inventories_list` (from aap-mcp-inventory-management) - Verify inventory + +### Related Skills +- `mcp-aap-validator` - **PREREQUISITE** - Validates AAP MCP before this skill +- `playbook-executor` - **PRIMARY USER** - Uses compatible templates for execution +- `job-template-creator` - Creates templates that this skill validates + +### Reference Documentation +- [playbook-executor/SKILL.md](../playbook-executor/SKILL.md) - Template compatibility requirements (Phase 1 Step 1.2, Scenario 3 validation) +- [job-template-creator/SKILL.md](../job-template-creator/SKILL.md) - Template configuration for remediation +- [AAP Job Templates](https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/using_automation_execution/controller-job-templates) + +## Example Usage + +### Example 1: Validate Template by ID + +**User Request**: "Validate job template 42 for remediation" + +**Skill Response**: + +1. Invoke mcp-aap-validator โ†’ PASSED +2. Call `job_templates_retrieve(id="42")` โ†’ Get template +3. Run validation checks +4. Call `projects_list`, `inventories_list` for context +5. Output report: + +``` +# Job Template Remediation Validation Report + +**Template**: CVE Remediation Template (ID: 42) +**Validated**: 2025-02-25 + +## Required Checks +| Requirement | Status | Details | +|-------------|--------|---------| +| Inventory | โœ“ | 1 - Production Inventory | +| Project | โœ“ | 6 - Remediation Playbooks | +| Playbook | โœ“ | playbooks/remediation/remediation-template.yml | +| Credentials | โœ“ | 1 credential(s) configured | +| Privilege Escalation | โœ“ | become_enabled: true | + +## Recommended Checks +| Requirement | Status | Details | +|-------------|--------|---------| +| Ask Variables on Launch | โœ“ | true | +| Ask Limit on Launch | โœ“ | true | + +## Overall Result +โœ“ PASSED + +Template is ready for remediation playbook execution. +``` + +### Example 2: Template Fails - Missing Privilege Escalation + +**User Request**: "Check if template 15 works for remediation" + +**Skill Response**: + +``` +# Job Template Remediation Validation Report + +**Template**: General Playbook Runner (ID: 15) +**Validated**: 2025-02-25 + +## Required Checks +| Requirement | Status | Details | +|-------------|--------|---------| +| Inventory | โœ“ | 1 - Production Inventory | +| Project | โœ“ | 6 - Remediation Playbooks | +| Playbook | โœ“ | playbooks/example.yml | +| Credentials | โœ“ | 1 credential(s) configured | +| Privilege Escalation | โœ— | become_enabled: false | + +## Overall Result +โœ— FAILED + +Fix required: Enable privilege escalation (become) on this template. +Remediation playbooks require sudo/root for package updates and system changes. + +To fix: AAP Web UI โ†’ Templates โ†’ [Template] โ†’ Edit โ†’ Options โ†’ โœ“ Enable Privilege Escalation +``` + +### Example 3: Invoked by Playbook-Executor + +**Context**: playbook-executor filters templates and may invoke this skill to validate user-selected template before execution. + +**Workflow**: +``` +[playbook-executor] โ†’ User selects template ID 10 +[playbook-executor] โ†’ Invoke job-template-remediation-validator with template 10 +[job-template-remediation-validator] โ†’ Returns PASSED +[playbook-executor] โ†’ Proceeds with execution +``` + +## Critical: Human-in-the-Loop Requirements + +This skill performs **read-only validation** only. It does not modify AAP resources or execute playbooks. + +**When user input is needed**: +- **Template selection**: If multiple templates match a search, present the list and ask user to select by number or ID before proceeding +- **Template not found**: If template ID invalid, report error and ask user for correct ID or "list" to see available templates + +**No confirmation required** for validation execution - the skill only reads and reports. + +## Best Practices + +1. **Validate before execution** - Run this skill before playbook-executor when using a new or unfamiliar template +2. **Enable recommended options** - ask_variables_on_launch and ask_limit_on_launch improve flexibility +3. **Project sync** - Ensure project status is "successful" before execution +4. **Credential types** - Template should have Machine (SSH) credential; Vault optional for encrypted playbooks +5. **Naming convention** - Use descriptive names like "Remediate CVE-YYYY-NNNNN" for auditability diff --git a/rh-sre/skills/mcp-aap-validator/SKILL.md b/rh-sre/skills/mcp-aap-validator/SKILL.md index 6abd0336..f228bb07 100644 --- a/rh-sre/skills/mcp-aap-validator/SKILL.md +++ b/rh-sre/skills/mcp-aap-validator/SKILL.md @@ -60,7 +60,7 @@ Do NOT use when: **Action**: Check that required environment variables are set (without exposing values) **Required Environment Variables**: -- `AAP_SERVER` - Base URL for AAP instance +- `AAP_MCP_SERVER` - Base URL for the MCP endpoint of the AAP server (used in .mcp.json; e.g. "https://aap-mcp.example.com"). Must point to the AAP MCP gateway, not the main AAP Web UI. - `AAP_API_TOKEN` - Authentication token for AAP API **CRITICAL SECURITY CONSTRAINT**: @@ -72,14 +72,14 @@ Do NOT use when: **How to verify** (without exposing values): ```bash # Check if set (exit code only, no output) -test -n "$AAP_SERVER" +test -n "$AAP_MCP_SERVER" test -n "$AAP_API_TOKEN" # Or check and report boolean result -if [ -n "$AAP_SERVER" ]; then - echo "โœ“ AAP_SERVER is set" +if [ -n "$AAP_MCP_SERVER" ]; then + echo "โœ“ AAP_MCP_SERVER is set" else - echo "โœ— AAP_SERVER is not set" + echo "โœ— AAP_MCP_SERVER is not set" fi if [ -n "$AAP_API_TOKEN" ]; then @@ -90,11 +90,13 @@ fi ``` **Report to user**: -- โœ“ "Environment variable AAP_SERVER is set" +- โœ“ "Environment variable AAP_MCP_SERVER is set" - โœ“ "Environment variable AAP_API_TOKEN is set" -- โœ— "Environment variable AAP_SERVER is not set" +- โœ— "Environment variable AAP_MCP_SERVER is not set" - โœ— "Environment variable AAP_API_TOKEN is not set" +**Note**: `AAP_MCP_SERVER` must point to the MCP endpoint of the AAP server (the MCP gateway URL). If unset, the MCP server will fail to connect. + **If missing**: Proceed to Human Notification Protocol (Step 4) ### Step 3: Test MCP Server Connection and Resources @@ -134,9 +136,10 @@ fi - โœ— "Cannot connect to aap-mcp-inventory-management (check server status and credentials)" **Common connection errors for AAP MCP servers**: +- `Invalid tool parameters`: Often caused by AAP_MCP_SERVER not set or wrongโ€”the MCP URL in .mcp.json fails to resolve. Verify AAP_MCP_SERVER points to the MCP endpoint of the AAP server. - `401 Unauthorized`: Invalid or expired AAP_API_TOKEN - `403 Forbidden`: Token lacks required permissions -- `404 Not Found`: Incorrect AAP_SERVER URL or missing endpoints +- `404 Not Found`: Incorrect AAP_MCP_SERVER URL or missing endpoints - `Connection timeout`: Server unreachable or network issue - `SSL/TLS error`: Certificate verification issues @@ -161,13 +164,13 @@ For missing MCP server configuration: { "mcpServers": { "aap-mcp-job-management": { - "url": "https://${AAP_SERVER}/job_management/mcp", + "url": "https://${AAP_MCP_SERVER}/job_management/mcp", "headers": { "Authorization": "Bearer ${AAP_API_TOKEN}" } }, "aap-mcp-inventory-management": { - "url": "https://${AAP_SERVER}/inventory_management/mcp", + "url": "https://${AAP_MCP_SERVER}/inventory_management/mcp", "headers": { "Authorization": "Bearer ${AAP_API_TOKEN}" } @@ -184,9 +187,11 @@ For missing environment variables: ๐Ÿ“‹ Setup Instructions: 1. Set required environment variables: - export AAP_SERVER="https://your-aap-server.com" + export AAP_MCP_SERVER="https://your-aap-mcp-gateway.com" export AAP_API_TOKEN="your-api-token" + Note: .mcp.json uses AAP_MCP_SERVER for MCP URLs. Use the MCP gateway URL, not the main AAP UI URL. + 2. To get an API token: - Log in to AAP Web UI - Navigate to Users โ†’ [Your User] โ†’ Tokens @@ -208,9 +213,9 @@ For connection failures: โŒ Cannot connect to AAP MCP servers ๐Ÿ“‹ Troubleshooting steps: -1. Verify AAP server is accessible: - - Check AAP_SERVER URL is correct - - Test connectivity: curl -I ${AAP_SERVER} +1. Verify AAP MCP server is accessible: + - Check AAP_MCP_SERVER URL is correct (must match .mcp.json) + - Test connectivity: curl -I ${AAP_MCP_SERVER} - Verify network connectivity and firewall rules 2. Verify API token is valid: @@ -219,8 +224,8 @@ For connection failures: - Generate new token if needed 3. Check AAP MCP endpoints: - - Job Management: ${AAP_SERVER}/job_management/mcp - - Inventory Management: ${AAP_SERVER}/inventory_management/mcp + - Job Management: ${AAP_MCP_SERVER}/job_management/mcp + - Inventory Management: ${AAP_MCP_SERVER}/inventory_management/mcp - Verify endpoints are exposed and accessible 4. Review authentication errors: @@ -261,7 +266,7 @@ Please respond with your choice. Configuration: โœ“ MCP server aap-mcp-job-management configured in .mcp.json โœ“ MCP server aap-mcp-inventory-management configured in .mcp.json -โœ“ Environment variable AAP_SERVER is set +โœ“ Environment variable AAP_MCP_SERVER is set โœ“ Environment variable AAP_API_TOKEN is set โœ“ Job management server connectivity verified โœ“ Inventory management server connectivity verified @@ -348,7 +353,7 @@ See troubleshooting steps above. Please resolve configuration issues before proc - Returns: List of inventories ### Required Environment Variables -- `AAP_SERVER` - Base URL for AAP instance (e.g., "https://aap.example.com") +- `AAP_MCP_SERVER` - Base URL for the MCP endpoint of the AAP server (must match .mcp.json; e.g., "https://aap-mcp.example.com"). Must point to the AAP MCP gateway. - `AAP_API_TOKEN` - Personal Access Token for AAP API authentication ### Related Skills @@ -395,7 +400,7 @@ Checking MCP server configuration... โœ“ MCP server `aap-mcp-inventory-management` is configured in .mcp.json Checking environment variables... -โœ“ Environment variable AAP_SERVER is set +โœ“ Environment variable AAP_MCP_SERVER is set โœ“ Environment variable AAP_API_TOKEN is set Testing server connectivity... @@ -431,14 +436,14 @@ Checking MCP server configuration... โœ“ MCP server `aap-mcp-inventory-management` is configured in .mcp.json Checking environment variables... -โœ— Environment variable AAP_SERVER is not set +โœ— Environment variable AAP_MCP_SERVER is not set โœ— Environment variable AAP_API_TOKEN is not set โŒ Cannot validate AAP MCP: Required environment variables not set ๐Ÿ“‹ Setup Instructions: 1. Set required environment variables: - export AAP_SERVER="https://your-aap-server.com" + export AAP_MCP_SERVER="https://your-aap-mcp-gateway.com" export AAP_API_TOKEN="your-api-token" 2. To get an API token: @@ -479,7 +484,7 @@ Checking MCP server configuration... โœ“ MCP server `aap-mcp-inventory-management` is configured in .mcp.json Checking environment variables... -โœ“ Environment variable AAP_SERVER is set +โœ“ Environment variable AAP_MCP_SERVER is set โœ“ Environment variable AAP_API_TOKEN is set Testing server connectivity... @@ -496,7 +501,7 @@ Testing server connectivity... 2. Test token manually: curl -H "Authorization: Bearer ${AAP_API_TOKEN}" \ - ${AAP_SERVER}/api/controller/v2/ping/ + ${AAP_MCP_SERVER}/api/controller/v2/ping/ 3. If token is valid but error persists: - Check AAP MCP proxy/gateway configuration diff --git a/rh-sre/skills/playbook-executor/SKILL.md b/rh-sre/skills/playbook-executor/SKILL.md index 75e8f916..309e9816 100644 --- a/rh-sre/skills/playbook-executor/SKILL.md +++ b/rh-sre/skills/playbook-executor/SKILL.md @@ -23,6 +23,7 @@ This skill executes Ansible remediation playbooks through AAP (Ansible Automatio **Required MCP Tools**: - `job_templates_list` (from aap-mcp-job-management) - List job templates - `job_templates_retrieve` (from aap-mcp-job-management) - Get template details +- `projects_list` (from aap-mcp-job-management) - Get project name and scm_url for Git Flow - `job_templates_launch_retrieve` (from aap-mcp-job-management) - Launch jobs - `jobs_retrieve` (from aap-mcp-job-management) - Get job status - `jobs_stdout_retrieve` (from aap-mcp-job-management) - Get console output @@ -32,7 +33,7 @@ This skill executes Ansible remediation playbooks through AAP (Ansible Automatio - `hosts_list` (from aap-mcp-inventory-management) - List inventory hosts **Required Environment Variables**: -- `AAP_SERVER` - AAP server URL +- `AAP_MCP_SERVER` - Base URL for the MCP endpoint of the AAP server (must point to the AAP MCP gateway) - `AAP_API_TOKEN` - AAP API authentication token ### Prerequisite Validation @@ -55,7 +56,7 @@ Use the Skill tool: **Human Notification on Failure**: If prerequisites are not met: - โŒ "Cannot proceed: AAP MCP servers are not available" -- ๐Ÿ“‹ "Setup required: Configure AAP_SERVER and AAP_API_TOKEN environment variables" +- ๐Ÿ“‹ "Setup required: Configure AAP_MCP_SERVER and AAP_API_TOKEN environment variables" - โ“ "How would you like to proceed? (setup now / skip / abort)" - โธ๏ธ Wait for user decision @@ -94,11 +95,19 @@ Use the Skill tool: - **If validation PARTIAL**: Warn user and ask to proceed - **If validation FAILED**: Stop execution, user must set up AAP MCP servers -### Phase 1: Job Template Selection/Creation +### Phase 1: Job Template Selection and Playbook Preparation -**Goal**: Identify or create an AAP job template suitable for executing the remediation playbook. +**Goal**: Identify an AAP job template suitable for executing the remediation playbook, or prepare the playbook for execution via git override or template creation. -#### Step 1.1: List Available Job Templates +**Input**: Playbook content and metadata from playbook-generator (filename, CVE ID, target systems). Playbook path is derived from metadata: `playbooks/remediation/` (e.g., `playbooks/remediation/remediation-CVE-2025-49794.yml` or `playbooks/remediation/remediation-CVE-2025-49794-playbook.yml`). + +#### Step 1.1: Derive Playbook Path + +From playbook metadata (filename from playbook-generator): +- Use convention `playbooks/remediation/` +- Support both `remediation-CVE-*.yml` and `remediation-CVE-*-playbook.yml` patterns. + +#### Step 1.2: List and Filter Templates **MCP Tool**: `job_templates_list` (from aap-mcp-job-management) @@ -106,144 +115,83 @@ Use the Skill tool: - `page_size`: 50 (retrieve up to 50 templates) - `search`: "" (search for all templates) -**Expected Output**: -```json -{ - "count": 3, - "results": [ - { - "id": 10, - "name": "CVE Remediation Template", - "project": 5, - "inventory": 1, - "playbook": "playbooks/remediation/remediation-template.yml" - } - ] -} -``` +For each template in results, call `job_templates_retrieve(id)` to get full details. Apply [job-template-remediation-validator](../job-template-remediation-validator/SKILL.md) criteria (inventory, project, playbook, credentials, become_enabled). Build two lists: +- **exact_match**: `template.playbook` equals `our_playbook_path` (normalize slashes; match if equal or basenames match) +- **compatible_other**: Passes validation but different playbook path -#### Step 1.2: Filter Compatible Templates +**Path normalization**: Normalize slashes, handle `playbooks/remediation/` prefix. Match if `template.playbook` equals `our_playbook_path` or if basenames match. -For each template, check if it satisfies remediation requirements: +#### Step 1.3: Scenario Selection -**Requirements**: -1. **Inventory Match**: Inventory contains target systems from CVE analysis -2. **Project Suitability**: Project contains or can contain remediation playbooks -3. **Credentials Configured**: Has machine credentials (SSH) and privilege escalation enabled -4. **Launch-Time Flexibility**: Supports prompt on launch for variables and/or limit (optional but recommended) +**Scenario 1 - Same playbook path** (exact_match not empty): -**Filtering Logic**: +Prompt: ``` -For each template: - 1. Get template details with job_templates_retrieve(id=template_id) - 2. Check if template.inventory matches target systems - 3. Check if template.project is suitable for remediation playbooks - 4. Check if template has credentials configured - 5. Score template based on matches (0-4 points) -``` - -**Result**: List of compatible templates ranked by suitability score. +Found template [name] (ID: X) with matching playbook path. The project may need to be updated with the latest playbook. -#### Step 1.3: User Selection +Options: +(A) Override: I'll add the playbook to the project via git. You sync the AAP project, then confirm. +(B) Manual: You add the playbook and sync. Confirm when done. -**If compatible templates found**: +โ“ Choose (A) or (B): ``` -Found N compatible job template(s): - -1. "CVE Remediation Template" (ID: 10) - - Inventory: Production Servers (1) - - Project: Remediation Playbooks (5) - - Credentials: โœ“ Configured - - Launch flexibility: โœ“ Variables and limit -2. "Dynamic Remediation" (ID: 15) - - Inventory: All Systems (2) - - Project: Remediation Playbooks (5) - - Credentials: โœ“ Configured - - Launch flexibility: โœ“ Variables only +- **If A**: Execute Git Flow (see Git Flow section below). Wait for user: "Sync complete" or "done". +- **If B**: Wait for user confirmation. -โ“ Which template would you like to use? -- Enter template number (1-N) -- "create" - Create new template via Web UI -- "abort" - Cancel execution - -Please respond with your choice. -``` +**Scenario 2 - Different playbook path** (compatible_other not empty, exact_match empty): -**If no compatible templates found**: +Prompt: ``` -โš ๏ธ No suitable job templates found for this remediation. +Found template [name] (ID: X) pointing to [template.playbook]. We can use it by replacing that playbook with our content. -Required: -- Inventory containing target systems -- Project for remediation playbooks -- Machine credentials (SSH + sudo) +Note: Template name may not match the CVE being remediated. -Options: -1. Create new template via AAP Web UI (I'll guide you) -2. Modify existing template to add requirements -3. Abort execution +โ“ Proceed with override? +- "yes" or "proceed" - Replace playbook and continue +- "no" - Skip to template creation (invoke job-template-creator) -Please choose an option (1-3): +Please respond with your choice. ``` -#### Step 1.4: Create Template (If Needed) +- **If yes**: Git Flow - write playbook content to `template.playbook` path in repo. Commit, push. Wait for sync confirmation. +- **If no**: Fall through to Scenario 3. -If user chooses to create a new template, invoke the **job-template-creator** skill: +**Scenario 3 - No suitable template** (exact_match and compatible_other both empty, or user chose "no" in Scenario 2): +Invoke the **job-template-creator** skill: ``` Skill: job-template-creator -Args: playbook-name target-systems +Instruction: "Create a job template for this remediation playbook. Playbook: [content]. Filename: [filename]. Path: [our_playbook_path]. CVE: [cve_id]. Target systems: [list]." ``` -The job-template-creator skill will guide the user through: -- Adding playbook to Git repository -- Creating job template via AAP Web UI -- Verifying template is ready +The job-template-creator skill guides the user through: (1) Adding playbook to Git repository, (2) Syncing AAP project, (3) Creating job template via AAP Web UI with correct path, inventory, credentials, privilege escalation. -**Wait for template creation to complete** before proceeding to Phase 2. +After job-template-creator completes, retrieve the template ID (from skill output or user confirmation). Invoke job-template-remediation-validator to validate the newly created template. If passed, proceed to Phase 3 (Dry-Run). If failed, report issues and ask user to fix in AAP Web UI. -### Phase 2: Playbook Preparation +**Multiple matches**: If multiple exact matches, present list and ask user to choose by number. If multiple different-path matches, prefer by project name containing "remediation" or "CVE", else first. -**Goal**: Ensure the generated playbook is available in the AAP project. +#### Git Flow (for Scenario 1 Override and Scenario 2) -#### Step 2.1: Add Playbook to Git Repository - -**Options**: +**Prerequisite**: Ask user for the local path to the Git repository for the selected project. Use `projects_list` to get project name and `scm_url` for the template's project; display these to help user identify the correct repo: +``` +What is the local path to the Git repository for project [Project Name] (scm_url)? +``` -**Option A: User has existing Git repository configured in AAP** -1. Ask user for Git repository location -2. Provide commands to add playbook to repository: - ```bash - cd /path/to/playbooks-repo - mkdir -p playbooks/remediation - cat > playbooks/remediation/remediation-CVE-YYYY-NNNNN.yml << 'EOF' - [playbook content] - EOF - git add playbooks/remediation/remediation-CVE-YYYY-NNNNN.yml - git commit -m "Add remediation playbook for CVE-YYYY-NNNNN" - git push origin main +**Steps**: +1. Write playbook content to `/` +2. Use Run tool: `git add ` +3. **Checkpoint**: Display summary of changes (file path, diff or file size) and ask: ``` -3. Instruct user to sync AAP project: - - Navigate to AAP Web UI โ†’ Automation Execution โ†’ Projects - - Find project and click Sync button (๐Ÿ”„) - - Wait for sync to complete - -**Option B: Temporary playbook testing** -1. Explain that playbook can be added to an existing AAP project playbook -2. User manually copies playbook to AAP project location -3. User syncs project - -#### Step 2.2: Verify Playbook Available + Ready to commit and push these changes? + Reply 'yes' or 'proceed' to continue, or 'abort' to cancel. + ``` +4. If confirmed: `git commit -m "Add/update remediation playbook for CVE-YYYY-NNNNN"` +5. `git push origin main` (or branch from project's scm_branch if available from projects_list) -After Git sync, verify playbook appears in project: -``` -โœ“ Playbook added to Git repository -โœ“ AAP project synced successfully -โœ“ Playbook path: playbooks/remediation/remediation-CVE-YYYY-NNNNN.yml +**Note**: Git must be configured (user, remote). Use Run tool for git commands. -Ready to proceed to execution. -``` +**After push**: "I've pushed the playbook. Sync the AAP project: Automation Execution > Projects > [Project] > Sync. Reply 'sync complete' when done." ### Phase 3: Dry-Run Execution (Recommended) @@ -930,6 +878,7 @@ AAP URL: https://aap.example.com/#/jobs/playbook/1235 ### Required MCP Tools - `job_templates_list` (from aap-mcp-job-management) - List templates - `job_templates_retrieve` (from aap-mcp-job-management) - Get template details +- `projects_list` (from aap-mcp-job-management) - Get project name and scm_url for Git Flow - `job_templates_launch_retrieve` (from aap-mcp-job-management) - Launch jobs - `jobs_retrieve` (from aap-mcp-job-management) - Get job status - `jobs_stdout_retrieve` (from aap-mcp-job-management) - Get console output @@ -940,6 +889,7 @@ AAP URL: https://aap.example.com/#/jobs/playbook/1235 ### Related Skills - `mcp-aap-validator` - **PREREQUISITE** - Validates AAP MCP servers (invoke in Phase 0) +- `job-template-remediation-validator` - Validates job template meets remediation requirements before execution - `job-template-creator` - Creates/guides AAP job template setup - `playbook-generator` - Generates playbooks for execution - `remediation-verifier` - Verifies success after execution @@ -952,6 +902,11 @@ AAP URL: https://aap.example.com/#/jobs/playbook/1235 This skill executes code on production systems. **Explicit user confirmation is REQUIRED** at multiple stages. +**Before Git commit/push** (Scenario 1 Override, Scenario 2): +1. **Display change summary**: File path, diff or file size +2. **Ask for confirmation**: "Ready to commit and push these changes? Reply 'yes' or 'proceed' to continue, or 'abort' to cancel." +3. **Wait for explicit "yes" or "proceed"**: Do not commit/push without confirmation + **Before Dry-Run Execution** (if user chooses dry-run): 1. **Display Playbook Preview**: Show tasks and explain changes 2. **Ask for Dry-Run Confirmation**: diff --git a/rh-sre/skills/playbook-generator/SKILL.md b/rh-sre/skills/playbook-generator/SKILL.md index 0e67c3aa..ecd8e173 100644 --- a/rh-sre/skills/playbook-generator/SKILL.md +++ b/rh-sre/skills/playbook-generator/SKILL.md @@ -272,6 +272,7 @@ This skill generates code that will execute on production systems. **Explicit us # Playbook metadata to return: playbook: file: remediation-CVE-YYYY-NNNNN.yml + path: playbooks/remediation/remediation-CVE-YYYY-NNNNN.yml # Full path for playbook-executor template matching content: | [Complete YAML playbook] From f2d06cc6447b938b10f30e075ba2d38ef59197da Mon Sep 17 00:00:00 2001 From: r2dedios Date: Thu, 26 Feb 2026 17:10:08 +0100 Subject: [PATCH 03/20] chore(validation): Added first approach of SKILL_CHECKLIST file and validation script Signed-off-by: r2dedios --- .github/workflows/README.md | 186 +++++ .github/workflows/validate-skills.yml | 73 ++ CLAUDE.md | 55 +- SKILL_CHECKLIST.md | 1110 +++++++++++++++++++++++++ scripts/validate-skills.sh | 696 ++++++++++++++++ 5 files changed, 2107 insertions(+), 13 deletions(-) create mode 100644 .github/workflows/README.md create mode 100644 .github/workflows/validate-skills.yml create mode 100644 SKILL_CHECKLIST.md create mode 100755 scripts/validate-skills.sh diff --git a/.github/workflows/README.md b/.github/workflows/README.md new file mode 100644 index 00000000..368d9cad --- /dev/null +++ b/.github/workflows/README.md @@ -0,0 +1,186 @@ +# GitHub Actions Workflows + +This directory contains CI/CD workflows for the agentic collections repository. + +## Available Workflows + +### 1. `validate-skills.yml` - Universal Skill Validation + +**Purpose**: Validates all skills against SKILL_CHECKLIST.md requirements (agentskills.io specification + repository design principles). + +**Triggers**: +- **Every pull request** (opened, synchronized, reopened, or marked ready for review) +- Pushes to `main` branch +- **Excludes**: Draft pull requests (validation runs only when PR is ready for review) + +**What it validates**: + +**Tier 1 - agentskills.io specification (MANDATORY):** +- โœ… Directory structure (skill-name/SKILL.md) +- โœ… Name format (1-64 chars, lowercase, no consecutive hyphens) +- โœ… Description length (1-1024 chars, under 500 tokens) +- โœ… YAML frontmatter completeness (name, description) + +**Tier 2 - Repository design principles (MANDATORY):** +- โœ… Model field (must be: inherit, sonnet, or haiku) +- โœ… Color field (must be: cyan, green, blue, yellow, or red) +- โœ… SKILL.md header format (# / Skill or # [Skill Name]) +- โœ… Required sections presence and order +- โœ… Prerequisites with verification steps +- โœ… When to Use This Skill with anti-patterns +- โœ… Workflow with MCP tools and parameters +- โœ… Document consultation transparency +- โœ… Dependencies declaration +- โœ… Human-in-the-Loop requirements +- โœ… Security (no credential exposure) +- โœ… Content quality (links, file size) + +**How to run locally**: +```bash +# Validate all skills in all collections +./scripts/validate-skills.sh + +# Validate specific collection +./scripts/validate-skills.sh rh-virt/ + +# Validate single skill +./scripts/validate-skills.sh rh-virt/skills/vm-create/ + +# Strict mode (exit on first error) +./scripts/validate-skills.sh --strict rh-virt/ + +# Verbose output +./scripts/validate-skills.sh --verbose +``` + +**Expected output**: +``` +โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” +Universal Skill Validator +Validates skills against CLAUDE.md and agentskills.io specification +โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” + +Found 9 skill(s) to validate + +โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” +Validating: vm-create +โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” + +โœ“ Skill 'vm-create' passed validation + +... + +โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” +Validation Summary +โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” +Total Skills: 9 +Passed: 9 +Failed: 0 +Total Errors: 0 + +โœ“ All skills passed validation +``` + +**Validation Levels**: + +The script validates all requirements from SKILL_CHECKLIST.md: +- **Level 1:** agentskills.io specification (Sections 0-9) - MANDATORY +- **Level 2:** Repository design principles (Sections 10-37) - MANDATORY + +All skills must pass both levels to be committed. + +**When validation fails**: + +The workflow will fail and provide: +1. Specific errors for each skill +2. Common issues and fixes +3. Local validation command +4. Reference to SKILL_CHECKLIST.md for detailed requirements + +**Common validation errors**: +- Missing or invalid `model` field (must be: inherit, sonnet, or haiku) +- Missing or invalid `color` field (must be: cyan, green, blue, yellow, or red) +- Invalid SKILL.md header format (must be: # / Skill) +- Missing required sections (Prerequisites, When to Use, Workflow, Dependencies) +- Missing "NOT for" anti-patterns in description + +**Related files**: +- `scripts/validate-skills.sh` - Main validation script +- `SKILL_CHECKLIST.md` - Universal skill requirements checklist (single source of truth) +- `CLAUDE.md` - Repository architecture and patterns + +## Adding New Workflows + +When adding new workflows: + +1. **Name the file descriptively**: `action-description.yml` +2. **Add documentation** in this README +3. **Define clear triggers** (PR, push, manual, schedule) +4. **Use semantic job names** that describe what they validate/test +5. **Provide clear error messages** when workflows fail +6. **Keep workflows focused** - one responsibility per workflow + +## Best Practices + +### Workflow Design +- โœ… Use specific path filters to avoid unnecessary runs +- โœ… Checkout with full history (`fetch-depth: 0`) when needed for diffs +- โœ… Use established GitHub Actions from trusted sources +- โœ… Provide summary outputs for quick review + +### Error Reporting +- โœ… Clear failure messages with actionable steps +- โœ… Reference documentation for resolution +- โœ… Group related errors together + +### Performance +- โœ… Run only on relevant file changes +- โœ… Use caching when applicable +- โœ… Parallelize independent validation steps + +## Troubleshooting + +### Workflow not triggering + +Check: +1. File paths match the `paths:` filter +2. Branch protection rules aren't blocking the workflow +3. GitHub Actions are enabled in repository settings + +### Validation script fails locally but passes in CI (or vice versa) + +This can happen due to: +1. Different file line endings (CRLF vs LF) +2. Different bash versions +3. Missing script permissions (`chmod +x`) + +**Fix**: +```bash +# Ensure script is executable +chmod +x scripts/validate-skills.sh + +# Check line endings +file scripts/validate-skills.sh + +# Convert to LF if needed +dos2unix scripts/validate-skills.sh +``` + +### False positives in validation + +If the validator reports errors for valid skills: +1. Review the validation logic in `scripts/validate-skills.sh` +2. Check if your skill follows CLAUDE.md design principles exactly +3. Review SKILL_CHECKLIST.md for specific formatting requirements +4. Open an issue if the validator has a bug + +## Maintenance + +This README should be updated when: +- New workflows are added +- Validation logic changes +- New validation levels are introduced +- Troubleshooting patterns emerge + +**Last Updated**: 2026-02-26 +**Workflows Count**: 1 (validate-skills.yml) diff --git a/.github/workflows/validate-skills.yml b/.github/workflows/validate-skills.yml new file mode 100644 index 00000000..f2432083 --- /dev/null +++ b/.github/workflows/validate-skills.yml @@ -0,0 +1,73 @@ +name: Validate Skills + +on: + pull_request: + types: [opened, synchronize, reopened, ready_for_review] + push: + branches: + - main + +jobs: + validate: + name: Validate Skill Structure and Requirements + runs-on: ubuntu-latest + + # Skip draft PRs + if: github.event.pull_request.draft == false || github.event_name == 'push' + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history for better diff analysis + + - name: Detect changed skills + id: changed-files + uses: tj-actions/changed-files@v44 + with: + files: | + **/skills/**/SKILL.md + + - name: List changed skills + if: steps.changed-files.outputs.any_changed == 'true' + run: | + echo "Changed skill files:" + echo "${{ steps.changed-files.outputs.all_changed_files }}" + + - name: Run validation script (all skills) + run: | + echo "Running universal skill validation..." + echo "" + ./scripts/validate-skills.sh --verbose + + - name: Validation Summary + if: success() + run: | + echo "" + echo "โœ… All skills passed validation" + echo "" + echo "Validated against:" + echo " - Tier 1: agentskills.io specification (MANDATORY)" + echo " - Tier 2: Repository design principles (MANDATORY)" + echo "" + echo "See SKILL_CHECKLIST.md for complete requirements." + + - name: Validation Failed + if: failure() + run: | + echo "" + echo "โŒ Skill validation failed" + echo "" + echo "Please review the errors above and ensure your skills meet all requirements in:" + echo " ๐Ÿ“‹ SKILL_CHECKLIST.md" + echo "" + echo "Common issues:" + echo " - Missing or invalid 'model' field (must be: inherit, sonnet, or haiku)" + echo " - Missing or invalid 'color' field (must be: cyan, green, blue, yellow, or red)" + echo " - Invalid SKILL.md header format (must be: # / Skill)" + echo " - Missing required sections (Prerequisites, When to Use, Workflow, Dependencies)" + echo " - Missing 'NOT for' anti-patterns in description" + echo "" + echo "To validate locally:" + echo " ./scripts/validate-skills.sh path/to/skill/" + exit 1 diff --git a/CLAUDE.md b/CLAUDE.md index b6056eb9..2bfecfa0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -57,9 +57,24 @@ Each pack follows this structure: **Key Pattern**: Agents orchestrate skills; skills encapsulate tools. Never call MCP tools directly - always go through skills. -## Design Principles for Skills and Agents +## Skill and Agent Requirements +<<<<<<< Updated upstream See [SKILL_DESIGN_PRINCIPLES.md](SKILL_DESIGN_PRINCIPLES.md) for the complete design principles, templates, and rationale. Validate compliance with `make validate-skill-design`. +======= +**CRITICAL:** EVERY SKILL and AGENT must be created and validated against [SKILL_CHECKLIST.md](./SKILL_CHECKLIST.md). + +**No exceptions.** All skills must comply with: +- **Tier 1:** agentskills.io specification compliance (MANDATORY) +- **Tier 2:** Repository design principles and standards (MANDATORY) + +**Before committing any skill:** +1. Review [SKILL_CHECKLIST.md](./SKILL_CHECKLIST.md) completely +2. Ensure all mandatory requirements are met +3. Validate using: `./scripts/validate-skills.sh path/to/skill/` + +See SKILL_CHECKLIST.md for complete requirements, examples, and validation criteria. +>>>>>>> Stashed changes ### MCP Server Integration @@ -152,6 +167,7 @@ last_updated: YYYY-MM-DD ### Adding a Skill 1. Create `skills//SKILL.md` +<<<<<<< Updated upstream 2. Define YAML frontmatter with root-level fields (name, description, model, color) and optional `metadata` for custom fields (author, priority, etc.). See [SKILL_DESIGN_PRINCIPLES.md](SKILL_DESIGN_PRINCIPLES.md) for the 2026 Agentic Skills structure. 3. Document workflow with MCP tool references 4. Include concrete examples @@ -159,14 +175,23 @@ last_updated: YYYY-MM-DD **Collection-Specific Standards:** - **rh-virt**: Follow `rh-virt/SKILL_TEMPLATE.md` for enhanced quality standards including mandatory Common Issues and Example Usage sections +======= +2. Follow requirements in [SKILL_CHECKLIST.md](./SKILL_CHECKLIST.md) +3. Define YAML frontmatter (name, description, model) +4. Document Prerequisites, When to Use, Workflow, and Dependencies sections +5. Include concrete examples and error handling +6. Test with `Skill` tool invocation +7. Validate with `./scripts/validate-skills.sh skills//` +>>>>>>> Stashed changes ### Adding an Agent 1. Create `agents/.md` -2. Define YAML frontmatter (name, description, model, tools, color) -3. Document workflow orchestrating skills -4. Provide clear examples of when to use agent vs skills -5. Test with `Task` tool invocation +2. Follow skill requirements in [SKILL_CHECKLIST.md](./SKILL_CHECKLIST.md) (agents use same structure) +3. Define YAML frontmatter (name, description, model, tools) +4. Document workflow that orchestrates multiple skills +5. Provide clear examples of when to use agent vs individual skills +6. Test with `Task` tool invocation ### Adding Documentation (rh-sre pattern) @@ -220,19 +245,20 @@ When creating new collections, follow the pattern that best matches your needs: ### Core Architecture 1. **Skills encapsulate tools** - Never call MCP tools directly; always invoke skills 2. **Agents orchestrate skills** - Complex workflows delegate to specialized skills -3. **Skill precedence** - Skills > Tools in all cases (Design Principle #3) +3. **agentskills.io compliance** - All skills follow the official specification +4. **Progressive disclosure** - Load docs incrementally based on task needs ### Security & Configuration -4. **Environment variables for secrets** - Never hardcode credentials -5. **Never expose credential values** - Check env vars are set, but NEVER print their values in output -6. **Verify prerequisites** - Check MCP server availability before execution (Design Principle #7) -7. **Human-in-the-loop for critical ops** - Require explicit confirmation (Design Principle #5) +5. **Environment variables for secrets** - Never hardcode credentials +6. **Never expose credential values** - Check env vars are set, but NEVER print their values in output +7. **MCP server integration** - Use `.mcp.json` with environment variable references -### Documentation & Transparency +### Documentation & Quality 8. **Official sources only** - Document all sources in SOURCES.md -9. **Declare document consultation** - Explicitly state "I consulted [file]" (Design Principle #1) -10. **Progressive disclosure** - Load docs incrementally based on task needs +9. **Production-ready examples** - No toy code, include error handling +10. **Persona-focused design** - Each collection serves specific user roles +<<<<<<< Updated upstream ### Quality & Usability 11. **Precise parameters** - Specify exact tool parameters for first-attempt success (Design Principle #2) 12. **Declare dependencies** - List all skills, tools, docs, and MCP servers (Design Principle #4) @@ -241,3 +267,6 @@ When creating new collections, follow the pattern that best matches your needs: 15. **Concise skill descriptions** - Keep YAML frontmatter under 500 tokens (Design Principle #3) **See**: [SKILL_DESIGN_PRINCIPLES.md](SKILL_DESIGN_PRINCIPLES.md) for detailed requirements and templates. +======= +**See [SKILL_CHECKLIST.md](./SKILL_CHECKLIST.md) for complete skill requirements, design principles, and validation criteria.** +>>>>>>> Stashed changes diff --git a/SKILL_CHECKLIST.md b/SKILL_CHECKLIST.md new file mode 100644 index 00000000..188005e5 --- /dev/null +++ b/SKILL_CHECKLIST.md @@ -0,0 +1,1110 @@ +# Skill Quality Checklist + +**Universal requirements for all skills across all agentic collections.** + +This checklist is organized in two tiers: +- **Tier 1: agentskills.io specification** (Sections 0-9) - MANDATORY for all skills +- **Tier 2: CLAUDE.md enhancements** (Sections 10-36) - Additional requirements + +**References:** +- [agentskills.io specification](https://agentskills.io/specification) - Base format specification +- [CLAUDE.md](./CLAUDE.md) - Repository architecture and patterns + +--- + +# TIER 1: agentskills.io Specification + +## Section 0: Directory Structure + +- [ ] Skill is in a directory (e.g., `skills/skill-name/`) +- [ ] Directory contains `SKILL.md` file (uppercase filename) +- [ ] Directory name matches `name` field in frontmatter exactly + +**Valid structure:** +``` +skills/pdf-processing/ +โ””โ”€โ”€ SKILL.md +``` + +**Optional directories (agentskills.io):** +``` +skills/pdf-processing/ +โ”œโ”€โ”€ SKILL.md +โ”œโ”€โ”€ scripts/ # Executable code (Python, Bash, JavaScript) +โ”œโ”€โ”€ references/ # Additional documentation files +โ””โ”€โ”€ assets/ # Templates, images, data files +``` + +--- + +## Section 1: Name Field (agentskills.io) + +- [ ] `name` field present +- [ ] Name is 1-64 characters +- [ ] Name uses only lowercase letters, numbers, and hyphens (`a-z0-9-`) +- [ ] Name does not start or end with hyphen +- [ ] Name does not have consecutive hyphens (`--`) +- [ ] Name matches parent directory name exactly + +**โœ… Valid examples:** +```yaml +name: pdf-processing +name: data-analysis +name: vm-create +``` + +**โŒ Invalid examples:** +```yaml +name: PDF-Processing # Uppercase not allowed +name: -pdf # Cannot start with hyphen +name: pdf--processing # Consecutive hyphens not allowed +name: pdf_processing # Underscores not allowed +``` + +--- + +## Section 2: Description Field (agentskills.io) + +- [ ] `description` field present +- [ ] Description is 1-1024 characters +- [ ] Description describes what the skill does and when to use it +- [ ] Description includes specific keywords for agent discovery + +**โœ… Good example:** +```yaml +description: | + Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. + Use when working with PDF documents or when the user mentions PDFs, forms, or + document extraction. +``` + +**โŒ Poor example:** +```yaml +description: Helps with PDFs. # Too vague, no when-to-use guidance +``` + +--- + +## Section 3: License Field (agentskills.io) + +- [ ] `license` field is optional +- [ ] If present, contains license name or reference to bundled license file +- [ ] If present, is kept short (recommended) + +**Examples:** +```yaml +license: Apache-2.0 +license: MIT +license: Proprietary. LICENSE.txt has complete terms +``` + +--- + +## Section 4: Compatibility Field (agentskills.io) + +- [ ] `compatibility` field is optional +- [ ] If present, is 1-500 characters +- [ ] If present, indicates environment requirements +- [ ] Only included if skill has specific environment requirements + +**Examples:** +```yaml +compatibility: Designed for Claude Code (or similar products) +compatibility: Requires git, docker, jq, and access to the internet +compatibility: Requires Python 3.8+, pip, and network access to PyPI +``` + +**Note:** Most skills do not need this field. + +--- + +## Section 5: Metadata Field (agentskills.io) + +- [ ] `metadata` field is optional +- [ ] If present, is a map from string keys to string values +- [ ] If present, keys are reasonably unique to avoid conflicts + +**Example:** +```yaml +metadata: + author: example-org + version: "1.0" + category: data-processing +``` + +--- + +## Section 6: Allowed-Tools Field (agentskills.io) + +- [ ] `allowed-tools` field is optional (experimental) +- [ ] If present, is a space-delimited list of pre-approved tools + +**Example:** +```yaml +allowed-tools: Bash(git:*) Bash(jq:*) Read Write +``` + +**Note:** Support for this field may vary between agent implementations. + +--- + +## Section 7: YAML Frontmatter Format (agentskills.io) + +- [ ] SKILL.md contains YAML frontmatter +- [ ] Frontmatter is delimited by `---` markers (opening and closing) +- [ ] Frontmatter appears at start of file +- [ ] Frontmatter contains required fields: `name` and `description` + +**Correct format:** +```yaml +--- +name: pdf-processing +description: | + Extract text and tables from PDF files. +--- + +# PDF Processing Skill + +[Rest of skill content] +``` + +**โŒ Missing delimiters:** +```yaml +name: pdf-processing +description: PDF processing + +# PDF Processing Skill +``` + +--- + +## Section 8: Body Content (agentskills.io) + +- [ ] Markdown body follows frontmatter +- [ ] Body has no format restrictions (write what helps agents) +- [ ] Body includes step-by-step instructions (recommended) +- [ ] Body includes examples of inputs and outputs (recommended) +- [ ] Body includes common edge cases (recommended) + +**Recommended body structure:** +```markdown +--- +name: skill-name +description: | + Skill description here +--- + +# Skill Name + +## Overview +Brief description of what this skill does. + +## Step-by-step Instructions +1. First, do this... +2. Then, do that... + +## Examples +**Input:** Example input +**Output:** Example output + +## Common Edge Cases +- Edge case 1: How to handle +- Edge case 2: How to handle +``` + +--- + +## Section 9: Progressive Disclosure (agentskills.io) + +- [ ] Main `SKILL.md` is under 500 lines (recommended) +- [ ] Main `SKILL.md` is under 5000 tokens (recommended) +- [ ] Detailed reference material moved to separate files +- [ ] File references use relative paths from skill root +- [ ] File references kept one level deep (avoid nested chains) + +**Progressive loading model:** +- **Metadata (~100 tokens):** `name` and `description` loaded at startup for all skills +- **Instructions (<5000 tokens):** Full `SKILL.md` loaded when skill is activated +- **Resources (as needed):** Files in `scripts/`, `references/`, `assets/` loaded only when required + +**โœ… Good file references:** +```markdown +See [the reference guide](references/REFERENCE.md) for details. +Run the extraction script: scripts/extract.py +Use template: assets/template.json +``` + +**โŒ Deeply nested references:** +```markdown +See references/advanced/subsection/details.md # Too deep +``` + +--- + +# TIER 2: CLAUDE.md Enhancements + +## Section 10: Description Field - CLAUDE.md Enhancements + +- [ ] Description is under 500 tokens (CLAUDE.md optimization) +- [ ] Description has 3-5 "Use when" examples +- [ ] Description includes "NOT for" with alternative skill reference + +**โœ… Complete example:** +```yaml +description: | + Analyze CVE impact across the fleet without immediate remediation. + + Use when: + - "What are the most critical vulnerabilities?" + - "Show CVEs affecting my systems" + - "List high-severity CVEs" + + NOT for remediation actions (use remediator agent instead). +``` + +**โŒ Missing anti-patterns:** +```yaml +description: | + Analyze CVE impact across the fleet. + + Use when: + - "What are the most critical vulnerabilities?" + # Missing "NOT for" section +``` + +--- + +## Section 11: YAML Frontmatter - Mandatory Fields (model and color) + +- [ ] `model` field present (MANDATORY) +- [ ] `model` value is one of: `inherit`, `sonnet`, or `haiku` +- [ ] `color` field present (MANDATORY) +- [ ] `color` value is one of: `cyan`, `green`, `blue`, `yellow`, or `red` + +**Model field (MANDATORY):** +```yaml +model: inherit # Use parent context's model (recommended default) +model: sonnet # Force Sonnet for complex reasoning +model: haiku # Force Haiku for simple, fast operations +``` + +**Color field (MANDATORY) - Standard values only:** +```yaml +color: cyan # Read-only operations (list, view, get, inventory) +color: green # Additive operations (create, clone, snapshot-create) +color: blue # Reversible changes (start, stop, restart, update) +color: yellow # Destructive but recoverable (snapshot-delete, scale-down) +color: red # Irreversible/critical (delete, restore, factory-reset) +``` + +**โŒ Invalid color values:** +```yaml +color: purple # Not a standard value +color: orange # Not a standard value +color: custom # Not a standard value +``` + +--- + +## Section 12: SKILL.md Header - Standard Format (MANDATORY) + +- [ ] First heading is level 1 (`#`) +- [ ] Heading follows standard format: `# / Skill` or `# [Skill Name]` +- [ ] Heading matches the skill name from frontmatter +- [ ] Overview paragraph appears immediately after heading +- [ ] Overview is 1-2 sentences describing what the skill does + +**โœ… Standard heading formats:** +```markdown +# /vm-create Skill # Preferred format (slash prefix) +# VM Create Skill # Alternative format (title case) +# PDF Processing Skill # Alternative format (title case) +``` + +**โŒ Invalid heading formats:** +```markdown +## vm-create # Wrong level (##) +# vm-create # Missing "Skill" suffix +# Vm-create Skill # Wrong capitalization +# Create VM # Doesn't match skill name +``` + +**Complete header example:** +```markdown +--- +name: vm-create +description: | + Create virtual machines... +model: inherit +color: green +--- + +# /vm-create Skill + +Create virtual machines in OpenShift Virtualization using automated instance type resolution. + +## Prerequisites +[Content] +``` + +--- + +## Section 13: Mandatory Sections - Presence + +- [ ] `## Prerequisites` section present +- [ ] `## When to Use This Skill` section present +- [ ] `## Workflow` section present +- [ ] `## Dependencies` section present + +## Workflow +[Content] + +## Dependencies +[Content] +``` + +--- + +## Section 14: Mandatory Sections - Ordering + +- [ ] YAML frontmatter appears first +- [ ] `# [Skill Name]` heading appears after frontmatter +- [ ] Overview paragraph appears after heading +- [ ] `## Critical: Human-in-the-Loop Requirements` appears before `## Prerequisites` (if present) +- [ ] `## Prerequisites` appears before `## When to Use This Skill` +- [ ] `## When to Use This Skill` appears before `## Workflow` +- [ ] `## Workflow` appears before `## Dependencies` + +**Correct order:** +```markdown +--- +[frontmatter] +--- + +# Skill Name + +Overview paragraph. + +## Critical: Human-in-the-Loop Requirements +[If applicable] + +## Prerequisites +[Content] + +## When to Use This Skill +[Content] + +## Workflow +[Content] + +## Dependencies +[Content] +``` + +--- + +## Section 15: Prerequisites Section - Content + +- [ ] Lists **Required MCP Servers** with setup links +- [ ] Lists **Required MCP Tools** with descriptions +- [ ] Lists **Environment Variables** (if any) +- [ ] Contains **Verification Steps** subsection +- [ ] Contains **Human Notification Protocol** subsection +- [ ] Contains security warning about credential values + +**Complete example:** +```markdown +## Prerequisites + +**Required MCP Servers:** `openshift-virtualization` ([setup guide](https://example.com/setup)) + +**Required MCP Tools:** +- `vm_create` (from openshift-virtualization) - Creates virtual machines +- `resources_get` (from openshift-virtualization) - Retrieves VM status + +**Environment Variables:** +- `KUBECONFIG` - Path to Kubernetes configuration file + +**Verification Steps:** +1. Check `openshift-virtualization` is configured in `.mcp.json` +2. Verify `KUBECONFIG` environment variable is set (without exposing value) +3. If missing โ†’ Proceed to Human Notification Protocol + +**Human Notification Protocol:** +When prerequisites fail: +1. Stop execution immediately +2. Report clear error: "โŒ Cannot execute vm-create: MCP server not available" +3. Provide setup instructions with links +4. Request user decision: setup/skip/abort +5. Wait for explicit user input + +**Security:** Never display actual KUBECONFIG path or credential values. +``` + +--- + +## Section 16: Prerequisites Section - Verification Steps + +- [ ] Verification includes check for MCP server in `.mcp.json` +- [ ] Verification includes check for environment variables +- [ ] Verification does not expose credential values +- [ ] Defines behavior when prerequisites fail + +**โœ… Correct verification:** +```bash +# Check if environment variable is set +test -n "$LIGHTSPEED_CLIENT_SECRET" + +# Report boolean status only +if [ -n "$LIGHTSPEED_CLIENT_SECRET" ]; then + echo "โœ“ LIGHTSPEED_CLIENT_SECRET is set" +else + echo "โœ— LIGHTSPEED_CLIENT_SECRET is not set" +fi +``` + +**โŒ SECURITY VIOLATION - Exposes credentials:** +```bash +echo $LIGHTSPEED_CLIENT_SECRET # Shows actual secret value +echo "SECRET=$LIGHTSPEED_CLIENT_SECRET" # Exposes value in output +``` + +--- + +## Section 17: Prerequisites Section - Human Notification Protocol + +- [ ] Specifies to stop execution immediately on failure +- [ ] Provides clear error message with setup instructions +- [ ] Requests user decision (setup/skip/abort) +- [ ] Waits for explicit user input + +**Example protocol:** +```markdown +**Human Notification Protocol:** + +When prerequisites fail, the skill MUST: + +1. **Stop Execution Immediately** - Do not attempt tool calls + +2. **Report Clear Error:** + ``` + โŒ Cannot execute vm-create: MCP server `openshift-virtualization` is not available + + ๐Ÿ“‹ Setup Instructions: + 1. Add openshift-virtualization to `.mcp.json` + 2. Set environment variable: export KUBECONFIG="/path/to/config" + 3. Restart Claude Code to reload MCP servers + + ๐Ÿ”— Documentation: https://example.com/setup + ``` + +3. **Request User Decision:** + ``` + โ“ How would you like to proceed? + + Options: + - "setup" - I'll help you configure the MCP server now + - "skip" - Skip this skill and use alternative approach + - "abort" - Stop the workflow entirely + ``` + +4. **Wait for Explicit User Input** - Do not proceed automatically +``` + +--- + +## Section 18: When to Use This Skill Section + +- [ ] Contains "Use when" with 3+ specific scenarios +- [ ] Contains "Do NOT use when" with alternatives +- [ ] Every anti-pattern references alternative skill by name + +**โœ… Complete example:** +```markdown +## When to Use This Skill + +Use this skill when: +- "Create a new VM in production namespace" +- "Deploy a Fedora virtual machine" +- "Set up a VM with 4 CPUs and 8GB RAM" +- User mentions "new VM", "create VM", "provision VM" + +Do NOT use when: +- Managing existing VMs โ†’ Use `vm-lifecycle-manager` skill instead +- Deleting VMs โ†’ Use `vm-delete` skill instead +- Cloning VMs โ†’ Use `vm-clone` skill instead +- Viewing VM status โ†’ Use `vm-inventory` skill instead +``` + +**โŒ Vague anti-patterns:** +```markdown +Do NOT use when: +- User wants other operations # Too vague, no alternative specified +``` + +--- + +## Section 19: Workflow Section - Structure + +- [ ] Each step has heading: `### Step N: [Action Name]` +- [ ] Each step specifies **MCP Tool** name with source server +- [ ] Each step specifies **Parameters** with exact format +- [ ] Each step includes **Expected Output** description +- [ ] Each step includes **Error Handling** with 2+ conditions + +**Complete workflow step example:** +```markdown +### Step 1: Create Virtual Machine + +**MCP Tool:** `vm_create` or `virtualization__vm_create` (from openshift-virtualization) + +**Parameters:** +- `namespace`: "production" (namespace where VM will be created) +- `name`: "fedora-web-01" (name of the virtual machine) +- `workload`: "fedora" (OS image: fedora, ubuntu, centos, rhel) +- `size`: "medium" (VM size: small=2CPU/4GB, medium=4CPU/8GB, large=8CPU/16GB) +- `autostart`: true (automatically start VM after creation) + +**Expected Output:** +```json +{ + "status": "success", + "vm_name": "fedora-web-01", + "namespace": "production", + "phase": "Provisioning" +} +``` + +**Error Handling:** +- If namespace not found: Report error and list available namespaces using `namespaces_list` tool +- If name already exists: Suggest alternative names with incremental suffix (fedora-web-02, etc.) +- If quota exceeded: Display current quota usage and recommend cleanup or quota increase +- If invalid workload: List supported OS images (fedora, ubuntu, centos, rhel, opensuse) +``` + +--- + +## Section 20: Workflow Section - Tool Parameters + +- [ ] Parameters use exact names (not placeholders like ``) +- [ ] Parameters include example values +- [ ] Parameters show format specification and constraints +- [ ] Tool names shown in both formats: `tool_name` and `category__tool_name` + +**โœ… Precise parameters:** +```markdown +**Parameters:** +- `impact`: "7,6" (comma-separated impact levels: 7=Important, 6=Moderate, 5=Low) +- `sort`: "-cvss_score" (use - prefix for descending; valid: "cvss_score", "public_date") +- `limit`: 20 (integer, maximum CVEs to return, range: 1-100) +``` + +**โŒ Vague parameters:** +```markdown +**Parameters:** +- Use the CVE ID # No parameter name, no format +- severity: Critical # Wrong parameter name or format +``` + +--- + +## Section 21: Document Consultation - Design Principle #1 + +**When skill consults documentation:** + +- [ ] Uses Read tool to load file into context +- [ ] Declares consultation to user with file path +- [ ] Document consultation happens BEFORE tool invocation +- [ ] Does not claim consultation without actually reading + +**โœ… CORRECT - Actual consultation (reads first, then declares):** +```markdown +### Step 1: Analyze CVE Impact + +**Document Consultation** (REQUIRED - Execute FIRST): +1. **Action**: Read [cvss-scoring.md](../../docs/references/cvss-scoring.md) using the Read tool to understand CVSS severity mapping +2. **Output to user**: "I consulted [cvss-scoring.md](../../docs/references/cvss-scoring.md) to understand CVSS severity mapping." + +**MCP Tool:** `vulnerability__get_cves` (from lightspeed-mcp) + +**Parameters:** +- `impact`: "7,6" (Important and Moderate severity levels) +``` + +**โŒ WRONG - Transparency theater (claims without reading):** +```markdown +### Step 1: Analyze CVE Impact + +I consulted cvss-scoring.md to understand severity levels. + +**MCP Tool:** `vulnerability__get_cves` (from lightspeed-mcp) +``` + +**Rationale:** +- **Substance:** Ensures AI actually enriches its context with domain knowledge +- **Transparency:** Users understand the AI's knowledge sources +- **Auditability:** Read tool calls can be tracked in execution logs + +--- + +## Section 22: Dependencies Section - Structure + +- [ ] Contains **Required MCP Servers** subsection +- [ ] Contains **Required MCP Tools** subsection +- [ ] Contains **Related Skills** subsection +- [ ] Contains **Reference Documentation** subsection + +**Complete dependencies example:** +```markdown +## Dependencies + +### Required MCP Servers +- `openshift-virtualization` - OpenShift Virtualization MCP integration + - Setup: https://example.com/mcp-setup + +### Required MCP Tools +- `vm_create` (from openshift-virtualization) - Creates virtual machines + - Source: https://github.com/example/openshift-virt-mcp +- `resources_get` (from openshift-virtualization) - Retrieves VM status +- `namespaces_list` (from openshift-virtualization) - Lists available namespaces + +### Related Skills +- `vm-lifecycle-manager` - Manages VM power state (start, stop, restart) +- `vm-delete` - Removes VMs and associated resources +- `vm-inventory` - Lists and views VM status across namespaces + +### Reference Documentation + +**Internal Documentation:** +- [VM Creation Guide](../../docs/vm-creation.md) - Detailed VM creation patterns +- [Instance Types](../../docs/instance-types.md) - Available VM sizes and configurations + +**Official Red Hat Documentation:** +- [Creating VMs - OpenShift 4.20](https://docs.redhat.com/en/openshift-virtualization/4.20/creating-vms) +- [VM Templates - OpenShift 4.20](https://docs.redhat.com/en/openshift-virtualization/4.20/templates) +``` + +--- + +## Section 23: Dependencies Section - MCP Tools + +- [ ] Each tool lists name and source server +- [ ] Each tool has brief description of what it does +- [ ] Each tool has link to source (GitHub, docs) + +**Example:** +```markdown +### Required MCP Tools +- `vm_create` (from openshift-virtualization) - Creates virtual machines with specified configuration + - Source: https://github.com/example/openshift-virt-mcp + - Parameters: namespace, name, workload, size, networks +- `resources_get` (from openshift-virtualization) - Retrieves Kubernetes resource details + - Source: https://github.com/example/openshift-virt-mcp + - Parameters: apiVersion, kind, name, namespace +``` + +--- + +## Section 24: Human-in-the-Loop - Design Principle #5 + +**Required for skills that:** +- Create, delete, modify, or restore resources +- Execute playbooks or commands +- Affect multiple systems +- Perform irreversible actions + +**Content requirements:** +- [ ] Section `## Critical: Human-in-the-Loop Requirements` present +- [ ] Lists when confirmation is required (numbered steps) +- [ ] Specifies what user must confirm +- [ ] Includes "Never assume approval" statement +- [ ] Specifies confirmation format (yes/no, typed verification) + +**Complete example:** +```markdown +## Critical: Human-in-the-Loop Requirements + +This skill requires explicit user confirmation at the following steps: + +1. **Before VM Creation** + - Display VM configuration preview: + ``` + VM Configuration: + - Name: fedora-web-01 + - Namespace: production + - OS: Fedora + - Size: medium (4 CPU, 8GB RAM) + - Auto-start: true + ``` + - Ask: "Should I create this VM with the configuration above?" + - Wait for user confirmation (yes/no) + +2. **After Configuration Validation** + - If quota warnings exist, display quota usage + - Ask: "Quota is at 80% capacity. Continue with VM creation?" + - Wait for explicit user approval + +3. **On Error Conditions** + - Report error details and suggested resolution + - Ask: "How would you like to proceed? (retry/modify/abort)" + - Wait for explicit user decision + +**Never assume approval** - always wait for explicit user confirmation before executing actions. +``` + +**When NOT required:** +- Read-only skills (list, view, get, inventory) + +--- + +## Section 25: Human-in-the-Loop - Critical Operations + +**For destructive operations (delete, restore):** +- [ ] Requires typed confirmation (user must type exact name) +- [ ] Displays preview before action +- [ ] Waits for explicit "yes" or "proceed" + +**Example for vm-delete:** +```markdown +## Critical: Human-in-the-Loop Requirements + +**CRITICAL SAFETY REQUIREMENT - Typed Confirmation:** + +1. **Before VM Deletion** + - Display VM details to be deleted: + ``` + VM to be deleted: + - Name: database-vm-01 + - Namespace: production + - Status: Running + - Storage: 100GB PVC will also be deleted + - This action is IRREVERSIBLE + ``` + +2. **Require Typed Confirmation** + - Ask: "To confirm deletion, type the exact VM name: database-vm-01" + - Verify user types exact name character-for-character + - If mismatch: "Name does not match. Deletion cancelled." + - If match: Proceed with deletion + +3. **Final Confirmation** + - Ask: "Type 'DELETE' to proceed with irreversible deletion." + - Wait for user to type: DELETE + - Only proceed if exact match + +**Never proceed without explicit typed confirmation of the resource name.** +``` + +--- + +## Section 26: Security - Credential Protection - Design Principle #7 + +- [ ] No environment variable VALUES in output +- [ ] Only reports if variable is set/unset (boolean status) +- [ ] Uses placeholders for sensitive paths +- [ ] No API keys, tokens, secrets, passwords in examples +- [ ] Does not use `echo $VAR` pattern for credentials + +**โœ… CORRECT - Secure verification:** +```bash +# Check if set (exit code only, no output) +test -n "$LIGHTSPEED_CLIENT_SECRET" + +# Report boolean status +if [ -n "$LIGHTSPEED_CLIENT_SECRET" ]; then + echo "โœ“ LIGHTSPEED_CLIENT_SECRET is set" +else + echo "โœ— LIGHTSPEED_CLIENT_SECRET is not set" +fi + +# Check multiple variables +test -n "$KUBECONFIG" && test -n "$LIGHTSPEED_CLIENT_ID" +``` + +**โœ… User-visible messages:** +``` +โœ“ Environment variable LIGHTSPEED_CLIENT_ID is set +โœ“ Environment variable LIGHTSPEED_CLIENT_SECRET is set +โœ“ Environment variable KUBECONFIG is set +``` + +**โŒ SECURITY VIOLATION - Exposes credentials:** +```bash +echo $LIGHTSPEED_CLIENT_SECRET # Shows actual secret +echo "SECRET=$LIGHTSPEED_CLIENT_SECRET" # Exposes in output +export LIGHTSPEED_CLIENT_SECRET=sk-abc123... # Hardcoded credential +echo "KUBECONFIG=/home/user/.kube/config" # Exposes actual path +``` + +**โŒ NEVER show:** +``` +LIGHTSPEED_CLIENT_SECRET=sk-abc123-xyz789-... +KUBECONFIG=/home/alice/.kube/my-cluster-config +API_KEY=ghp_abc123xyz789... +``` + +**Rationale:** +Prevents accidental credential exposure in: +- Conversation history +- Log files +- Screenshots shared with support +- Copied output pasted in public forums + +--- + +## Section 27: Content Quality + +- [ ] No hardcoded values (uses placeholders) +- [ ] No broken links (all references resolve) +- [ ] No spelling errors +- [ ] Technical terms explained on first use +- [ ] Clear, concise language + +**โœ… Good placeholders:** +```markdown +- namespace: "" +- vm-name: "" +- kubeconfig: "" +``` + +**โŒ Hardcoded values:** +```markdown +- namespace: "production" # Don't hardcode specific namespaces +- vm-name: "my-vm" # Use placeholder instead +- kubeconfig: "/home/user/.kube/config" # Never hardcode paths +``` + +--- + +## Section 28: Naming Conventions + +- [ ] Skill name uses kebab-case +- [ ] Folder name matches skill name exactly +- [ ] File is named `SKILL.md` (uppercase) +- [ ] No spaces in folder or file names + +**โœ… Correct:** +``` +skills/vm-create/SKILL.md +skills/pdf-processing/SKILL.md +skills/data-analysis/SKILL.md +``` + +**โŒ Incorrect:** +``` +skills/VM-Create/skill.md # Wrong case +skills/vm_create/SKILL.md # Underscores not allowed +skills/vm create/SKILL.md # Spaces not allowed +skills/vmCreate/SKILL.md # camelCase not allowed +``` + +--- + +## Section 29: Design Principle #1 - Document Consultation Transparency + +- [ ] Actually reads files before claiming consultation +- [ ] Uses Read tool to load files into context +- [ ] Declares consultation transparently to user + +**Implementation pattern:** +```markdown +**Document Consultation** (REQUIRED - Execute FIRST): +1. **Action**: Read [filename.md](path/to/filename.md) using the Read tool to understand [topic] +2. **Output to user**: "I consulted [filename.md](path/to/filename.md) to understand [topic]." +``` + +**Execution examples:** +- Read `docs/references/cvss-scoring.md` โ†’ "I consulted cvss-scoring.md to verify CVSS severity mapping." +- Read `skills/playbook-generator/SKILL.md` โ†’ "I consulted playbook-generator skill to understand Ansible generation parameters." + +--- + +## Section 30: Design Principle #2 - Precise Parameter Specification + +- [ ] Tool parameters are exact (not vague or generic) +- [ ] Parameters include format specification and examples +- [ ] Parameters enable first-attempt success without trial-and-error + +**โœ… Precise specification:** +```markdown +**Parameters:** +- `impact`: "7,6" (string with comma-separated impact levels: 7=Important, 6=Moderate, 5=Low) +- `sort`: "-cvss_score" (use - prefix for descending; valid fields: "cvss_score", "public_date") +- `limit`: 20 (integer, maximum CVEs to return, range: 1-100) +- `published_after`: "2024-01-01" (ISO date format: YYYY-MM-DD) +``` + +**โŒ Vague specification:** +```markdown +**Parameters:** +- Use the CVE ID +- Set severity to high +- Sort by score +``` + +**Rationale:** +- **Precision:** Exact names and formats prevent tool errors +- **Examples:** Value examples show correct usage +- **Determinism:** First-attempt success reduces wasted cycles + +--- + +## Section 31: Design Principle #3 - Concise Description + +- [ ] YAML frontmatter description is under 500 tokens +- [ ] Description focuses on "when to use" scenarios +- [ ] Implementation details deferred to skill body (not in frontmatter) + +**โœ… Concise frontmatter:** +```yaml +description: | + Analyze CVE impact across the fleet without immediate remediation. + + Use when: + - "What are the most critical vulnerabilities?" + - "Show CVEs affecting my systems" + - "List high-severity CVEs" + + NOT for remediation actions (use remediator agent instead). +``` + +**โŒ Too detailed in frontmatter:** +```yaml +description: | + This skill uses the lightspeed-mcp server to query CVEs from Red Hat Insights. + It first reads the cvss-scoring.md documentation, then calls get_cves with + impact levels 7 and 6, sorts by CVSS score descending, and formats the output + as a table. The skill also checks system inventory... + # [500+ tokens of implementation details] +``` + +**Rationale:** Minimizes token usage when all skill descriptions are loaded at agent initialization. + +--- + +## Section 32: Design Principle #4 - Dependencies Declared + +- [ ] All skill dependencies listed +- [ ] All MCP tools listed with source servers +- [ ] All MCP servers listed with setup links +- [ ] All reference documentation listed + +**Complete dependencies section:** +```markdown +## Dependencies + +### Required MCP Servers +- `lightspeed-mcp` - Red Hat Lightspeed platform +- `ansible-mcp` - Ansible automation execution + +### Required MCP Tools +- `vulnerability__get_cves` (from lightspeed-mcp) - List CVEs with filters +- `vulnerability__get_cve` (from lightspeed-mcp) - Get specific CVE details +- `playbook__execute` (from ansible-mcp) - Execute Ansible playbooks + +### Related Skills +- `cve-validation` - Validate CVE IDs before querying +- `fleet-inventory` - Identify systems affected by CVEs +- `playbook-generator` - Generate remediation playbooks + +### Reference Documentation +- [cvss-scoring.md](docs/references/cvss-scoring.md) - CVSS severity mappings +- [insights-api.md](docs/insights/insights-api.md) - API usage patterns +``` + +--- + +## Section 33: Design Principle #5 - Human-in-the-Loop + +- [ ] Confirmations required for critical operations +- [ ] User approval required before destructive actions +- [ ] Preview shown before modifications + +See Section 23 for complete implementation requirements. + +--- + +## Section 34: Design Principle #6 - Mandatory Sections + +- [ ] All required sections are present +- [ ] Sections appear in correct order +- [ ] Section headings use exact format + +**Required sections in order:** +1. YAML frontmatter +2. `# [Skill Name]` heading +3. Overview paragraph +4. `## Critical: Human-in-the-Loop Requirements` (if applicable) +5. `## Prerequisites` +6. `## When to Use This Skill` +7. `## Workflow` +8. `## Dependencies` + +--- + +## Section 35: Design Principle #7 - Prerequisites Verified + +- [ ] MCP server availability is checked before execution +- [ ] Environment variables are verified without exposing values +- [ ] Human notification protocol defined for prerequisite failures + +See Sections 14-16 for complete verification requirements. + +--- + +## Section 36: Single Responsibility + +- [ ] Skill does ONE thing well +- [ ] Skill has clear, focused purpose +- [ ] Skill does not overlap with other skills + +**โœ… Single responsibility:** +- `vm-create` - Only creates VMs +- `vm-delete` - Only deletes VMs +- `vm-inventory` - Only lists/views VMs + +**โŒ Multiple responsibilities:** +- `vm-manager` - Creates, deletes, lists, starts, stops VMs (too broad, split into separate skills) + +--- + +## Section 37: Skills Over Tools - Design Principle #3 + +- [ ] Never calls MCP tools directly in skill instructions +- [ ] Always invokes other skills instead of raw tools +- [ ] Delegates to specialized skills appropriately + +**โœ… Correct - Delegates to skills:** +```markdown +If user wants to view VM status after creation, invoke the `vm-inventory` skill. +If user wants to start the VM, invoke the `vm-lifecycle-manager` skill with action: start. +``` + +**โŒ Wrong - Calls tools directly:** +```markdown +Use the resources_list tool to view VMs. +Call vm_lifecycle with action: start to start the VM. +``` + +**Key Pattern:** Agents orchestrate skills; skills encapsulate tools. Never call MCP tools directly - always go through skills. + +--- + +## Validation Levels + +**Level 1 - agentskills.io Compliance (MANDATORY):** +- Sections 0-9 + +**Level 2 - Repository Standards (Required to Commit):** +- Sections 0-9 (agentskills.io) +- Sections 10-14, 18-20, 27-28 (Repository core requirements) + +**Level 3 - Production Ready (Recommended):** +- All sections 0-37 + +--- + +**Last Updated**: 2026-02-26 +**Version**: 3.1 +**Applies To**: All agentic collections +**Specification Compliance**: agentskills.io v1.0 diff --git a/scripts/validate-skills.sh b/scripts/validate-skills.sh new file mode 100755 index 00000000..51ad6e5c --- /dev/null +++ b/scripts/validate-skills.sh @@ -0,0 +1,696 @@ +#!/bin/bash +# +# validate-skills.sh +# Universal skill validation for all agentic collections +# +# Validates skills against: +# - SKILL_CHECKLIST.md (Tier 1: agentskills.io specification) +# - SKILL_CHECKLIST.md (Tier 2: Repository design principles) +# +# Usage: +# ./scripts/validate-skills.sh [path] # Validate specific skill or collection +# ./scripts/validate-skills.sh # Validate all collections +# ./scripts/validate-skills.sh --strict # Exit on first error +# + +set -o pipefail + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +# Counters +TOTAL_SKILLS=0 +PASSED_SKILLS=0 +FAILED_SKILLS=0 +TOTAL_ERRORS=0 + +# Flags +STRICT_MODE=false +VERBOSE=false +TARGET_PATHS=() + +# Parse arguments +while [[ $# -gt 0 ]]; do + case $1 in + --strict) + STRICT_MODE=true + shift + ;; + --verbose|-v) + VERBOSE=true + shift + ;; + --help|-h) + echo "Usage: $0 [OPTIONS] [PATH...]" + echo "" + echo "Options:" + echo " --strict Exit on first error" + echo " --verbose,-v Show detailed validation steps" + echo " --help,-h Show this help message" + echo "" + echo "Examples:" + echo " $0 # Validate all skills in current directory" + echo " $0 path/to/collection/ # Validate all skills in collection" + echo " $0 path/to/skill-dir/ # Validate single skill" + echo " $0 path/to/dir/* # Validate multiple paths using glob" + echo " $0 skill1/ skill2/ skill3/ # Validate specific skills" + echo " $0 --strict path/ # Exit on first error" + exit 0 + ;; + *) + TARGET_PATHS+=("$1") + shift + ;; + esac +done + +# Validation functions + +log_info() { + if [[ "$VERBOSE" == true ]]; then + echo -e "${BLUE}โ„น${NC} $1" + fi +} + +log_pass() { + echo -e "${GREEN}โœ“${NC} $1" +} + +log_error() { + echo -e "${RED}โœ—${NC} $1" + ((TOTAL_ERRORS++)) +} + +log_warn() { + echo -e "${YELLOW}โš ${NC} $1" +} + +# Section 0: agentskills.io Specification Compliance +validate_agentskills_spec() { + local skill_dir="$1" + local skill_name=$(basename "$skill_dir") + local errors=0 + + log_info "Validating agentskills.io specification for $skill_name" + + # Check SKILL.md exists + if [[ ! -f "$skill_dir/SKILL.md" ]]; then + log_error "$skill_name: Missing SKILL.md file" + ((errors++)) + fi + + # Validate name format (1-64 chars, lowercase, numbers, hyphens only) + if ! echo "$skill_name" | grep -Eq '^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$'; then + log_error "$skill_name: Invalid name format (must be 1-64 chars, lowercase, no consecutive hyphens)" + ((errors++)) + fi + + # Check for consecutive hyphens + if echo "$skill_name" | grep -q '\-\-'; then + log_error "$skill_name: Name contains consecutive hyphens (--)" + ((errors++)) + fi + + # Check name matches directory + if [[ -f "$skill_dir/SKILL.md" ]]; then + local frontmatter_name=$(awk '/^---$/{if(++n==2) exit} n==1' "$skill_dir/SKILL.md" | grep '^name:' | sed 's/name: *//' | tr -d '"' | tr -d "'") + if [[ -n "$frontmatter_name" && "$frontmatter_name" != "$skill_name" ]]; then + log_error "$skill_name: Name in frontmatter ($frontmatter_name) doesn't match directory name" + ((errors++)) + fi + fi + + return $errors +} + +# Section 1: YAML Frontmatter +validate_yaml_frontmatter() { + local skill_file="$1" + local skill_name="$2" + local errors=0 + + log_info "Validating YAML frontmatter for $skill_name" + + # Extract frontmatter (between first two --- markers) + if ! grep -q '^---$' "$skill_file"; then + log_error "$skill_name: Missing YAML frontmatter delimiters (---)" + ((errors++)) + return $errors + fi + + local frontmatter=$(awk '/^---$/{if(++n==2) exit} n==1' "$skill_file") + + # Check required fields + if ! echo "$frontmatter" | grep -q '^name:'; then + log_error "$skill_name: Missing 'name' field in frontmatter" + ((errors++)) + fi + + if ! echo "$frontmatter" | grep -q '^description:'; then + log_error "$skill_name: Missing 'description' field in frontmatter" + ((errors++)) + fi + + # Check model field exists + if ! echo "$frontmatter" | grep -q '^model:'; then + log_error "$skill_name: Missing 'model' field in frontmatter (MANDATORY)" + ((errors++)) + else + # Validate model value is one of: inherit, sonnet, haiku + local model_value=$(echo "$frontmatter" | grep '^model:' | sed 's/model: *//' | tr -d '"' | tr -d "'" | xargs) + if [[ "$model_value" != "inherit" && "$model_value" != "sonnet" && "$model_value" != "haiku" ]]; then + log_error "$skill_name: Invalid model value '$model_value' (must be: inherit, sonnet, or haiku)" + ((errors++)) + fi + fi + + # Check color field exists (MANDATORY) + if ! echo "$frontmatter" | grep -q '^color:'; then + log_error "$skill_name: Missing 'color' field in frontmatter (MANDATORY)" + ((errors++)) + else + # Validate color value is one of: cyan, green, blue, yellow, red + local color_value=$(echo "$frontmatter" | grep '^color:' | sed 's/color: *//' | tr -d '"' | tr -d "'" | xargs) + if [[ "$color_value" != "cyan" && "$color_value" != "green" && "$color_value" != "blue" && "$color_value" != "yellow" && "$color_value" != "red" ]]; then + log_error "$skill_name: Invalid color value '$color_value' (must be: cyan, green, blue, yellow, or red)" + ((errors++)) + fi + fi + + # Check description has "Use when" examples (check in full frontmatter) + if ! echo "$frontmatter" | grep -qi "use when\|trigger\|request"; then + log_warn "$skill_name: Description should include 'Use when' examples" + fi + + # Check description has "NOT for" anti-pattern + if ! echo "$frontmatter" | grep -qi "NOT for\|Do NOT\|not for"; then + log_warn "$skill_name: Description should include 'NOT for' anti-pattern" + fi + + # Check description length (approximate - under 1024 chars per agentskills.io) + # Extract just the description value + local description=$(echo "$frontmatter" | awk '/^description:/,/^[a-z_]+:/ {if (!/^[a-z_]+:/ || /^description:/) print}' | sed '1d') + local desc_length=$(echo "$description" | wc -c) + if [[ $desc_length -gt 1024 ]]; then + log_error "$skill_name: Description exceeds 1024 characters ($desc_length chars)" + ((errors++)) + fi + + return $errors +} + +# Section 1.5: SKILL.md Header Format (Section 12 in checklist) +validate_skill_header() { + local skill_file="$1" + local skill_name="$2" + local errors=0 + + log_info "Validating SKILL.md header format for $skill_name" + + # Extract the first heading after frontmatter + local first_heading=$(awk '/^---$/{if(++n==2) {getline; while(getline) {if(/^# /) {print; exit}}}}' "$skill_file") + + if [[ -z "$first_heading" ]]; then + log_error "$skill_name: Missing level 1 heading (# ) after frontmatter" + ((errors++)) + return $errors + fi + + # Validate heading format: # / Skill or # [Skill Name] + # Extract heading text (remove leading "# ") + local heading_text=$(echo "$first_heading" | sed 's/^# *//') + + # Check if it follows one of the standard formats + local valid_format=false + + # Format 1: / Skill + if echo "$heading_text" | grep -Eq "^/$skill_name Skill$"; then + valid_format=true + fi + + # Format 2: [Title Case] Skill (flexible matching) + if echo "$heading_text" | grep -Eq " Skill$"; then + valid_format=true + fi + + if [[ "$valid_format" == false ]]; then + log_warn "$skill_name: Heading '$heading_text' should follow format: '/$skill_name Skill' or '[Skill Name]'" + fi + + # Check for overview paragraph after heading + # Get first non-empty line after the heading + local overview=$(awk '/^---$/{if(++n==2) found=1} found && /^# / {getline; while(getline) {if(/^[^#]/ && NF>0) {print; exit}}}' "$skill_file") + + if [[ -z "$overview" ]]; then + log_warn "$skill_name: Missing overview paragraph (1-2 sentences) immediately after heading" + fi + + return $errors +} + +# Section 2: Mandatory Section Order +validate_section_order() { + local skill_file="$1" + local skill_name="$2" + local errors=0 + + log_info "Validating section order for $skill_name" + + # Required sections in order (after frontmatter) + local required_sections=( + "^# " + "^## Prerequisites" + "^## When to Use This Skill" + "^## Workflow" + "^## Dependencies" + ) + + local prev_line=0 + for section in "${required_sections[@]}"; do + local line_num=$(grep -n "$section" "$skill_file" | head -1 | cut -d: -f1) + + if [[ -z "$line_num" ]]; then + log_error "$skill_name: Missing required section matching '$section'" + ((errors++)) + continue + fi + + if [[ $line_num -le $prev_line ]]; then + log_error "$skill_name: Section '$section' out of order (line $line_num, expected after line $prev_line)" + ((errors++)) + fi + + prev_line=$line_num + done + + return $errors +} + +# Section 3: Prerequisites Section +validate_prerequisites() { + local skill_file="$1" + local skill_name="$2" + local errors=0 + + log_info "Validating Prerequisites section for $skill_name" + + # Check Prerequisites section exists + if ! grep -q "^## Prerequisites" "$skill_file"; then + log_error "$skill_name: Missing Prerequisites section" + ((errors++)) + return $errors + fi + + # Extract Prerequisites section + local prereqs=$(awk '/^## Prerequisites$/,/^## [^P]/' "$skill_file") + + # Check for required subsections (relaxed checking) + if ! echo "$prereqs" | grep -qi "required.*mcp.*server\|mcp.*server"; then + log_warn "$skill_name: Prerequisites should list Required MCP Servers" + fi + + if ! echo "$prereqs" | grep -qi "verification\|verify"; then + log_warn "$skill_name: Prerequisites should include verification steps" + fi + + if ! echo "$prereqs" | grep -qi "human notification\|error.*protocol"; then + log_warn "$skill_name: Prerequisites should include human notification protocol" + fi + + # Check for security warning about credentials + if ! echo "$prereqs" | grep -qi "never.*display\|never.*expose\|credential.*value"; then + log_warn "$skill_name: Prerequisites should warn against exposing credentials" + fi + + return $errors +} + +# Section 4: When to Use This Skill +validate_when_to_use() { + local skill_file="$1" + local skill_name="$2" + local errors=0 + + log_info "Validating 'When to Use' section for $skill_name" + + if ! grep -q "^## When to Use This Skill" "$skill_file"; then + log_error "$skill_name: Missing 'When to Use This Skill' section" + ((errors++)) + return $errors + fi + + local when_section=$(awk '/^## When to Use This Skill$/,/^## [^W]/' "$skill_file") + + # Check for "Use when" scenarios + if ! echo "$when_section" | grep -qi "use.*when\|trigger.*when\|invoke.*when"; then + log_warn "$skill_name: 'When to Use' section should list specific scenarios" + fi + + # Check for "Do NOT use" anti-patterns + if ! echo "$when_section" | grep -qi "do not\|NOT for\|not when"; then + log_error "$skill_name: 'When to Use' section must include 'Do NOT use' anti-patterns" + ((errors++)) + fi + + # Check that anti-patterns mention alternative skills + if echo "$when_section" | grep -qi "do not\|NOT for" && \ + ! echo "$when_section" | grep -qi "use.*skill\|instead\|alternative"; then + log_warn "$skill_name: Anti-patterns should reference alternative skills by name" + fi + + return $errors +} + +# Section 5: Workflow Section +validate_workflow() { + local skill_file="$1" + local skill_name="$2" + local errors=0 + + log_info "Validating Workflow section for $skill_name" + + if ! grep -q "^## Workflow" "$skill_file"; then + log_error "$skill_name: Missing Workflow section" + ((errors++)) + return $errors + fi + + local workflow=$(awk '/^## Workflow$/,/^## [^W]/' "$skill_file") + + # Check for workflow steps + if ! echo "$workflow" | grep -q "^### Step\|^### [0-9]"; then + log_warn "$skill_name: Workflow should have numbered steps (### Step N: or ### 1.)" + fi + + # Check for MCP Tool references + if ! echo "$workflow" | grep -qi "\*\*MCP Tool\*\*\|mcp.*tool"; then + log_warn "$skill_name: Workflow should specify MCP Tools used" + fi + + # Check for Parameters specification + if echo "$workflow" | grep -qi "\*\*MCP Tool\*\*" && \ + ! echo "$workflow" | grep -qi "\*\*Parameters\*\*"; then + log_warn "$skill_name: Workflow steps with MCP Tools should specify parameters" + fi + + # Check for Error Handling + if ! echo "$workflow" | grep -qi "\*\*Error.*Handling\*\*\|error.*condition"; then + log_warn "$skill_name: Workflow steps should include error handling" + fi + + return $errors +} + +# Section 6: Document Consultation Transparency +validate_document_consultation() { + local skill_file="$1" + local skill_name="$2" + local errors=0 + + log_info "Validating document consultation transparency for $skill_name" + + # If skill mentions consulting documents, verify it follows the pattern + if grep -qi "consult.*document\|read.*doc" "$skill_file"; then + if ! grep -qi "Read tool\|Read.*to understand" "$skill_file"; then + log_warn "$skill_name: Document consultation should use Read tool first (CLAUDE.md Principle #1)" + fi + + if ! grep -qi "I consulted\|Output to user" "$skill_file"; then + log_warn "$skill_name: Document consultation should declare consultation to user" + fi + fi + + return $errors +} + +# Section 7: Dependencies Section +validate_dependencies() { + local skill_file="$1" + local skill_name="$2" + local errors=0 + + log_info "Validating Dependencies section for $skill_name" + + if ! grep -q "^## Dependencies" "$skill_file"; then + log_error "$skill_name: Missing Dependencies section" + ((errors++)) + return $errors + fi + + local deps=$(awk '/^## Dependencies$/,/^## [^D]/' "$skill_file") + + # Check for required subsections + if ! echo "$deps" | grep -qi "required.*mcp.*server"; then + log_warn "$skill_name: Dependencies should list Required MCP Servers" + fi + + if ! echo "$deps" | grep -qi "required.*mcp.*tool\|mcp.*tool"; then + log_warn "$skill_name: Dependencies should list Required MCP Tools" + fi + + return $errors +} + +# Section 8: Human-in-the-Loop Requirements +validate_human_in_loop() { + local skill_file="$1" + local skill_name="$2" + local errors=0 + + log_info "Validating Human-in-the-Loop requirements for $skill_name" + + # Check if skill modifies state (create, delete, update, restore, execute) + local is_mutating=false + if echo "$skill_name" | grep -Eq "create|delete|update|restore|execute|modify|run|deploy|clone"; then + is_mutating=true + fi + + # If mutating, should have Human-in-the-Loop section + if [[ "$is_mutating" == true ]]; then + if ! grep -q "^## Critical: Human-in-the-Loop Requirements" "$skill_file"; then + log_warn "$skill_name: Modifying skill should have 'Human-in-the-Loop Requirements' section" + else + local hitl=$(awk '/^## Critical: Human-in-the-Loop Requirements$/,/^## [^C]/' "$skill_file") + + # Check for confirmation requirements + if ! echo "$hitl" | grep -qi "confirmation\|confirm\|approval\|never assume"; then + log_warn "$skill_name: Human-in-the-Loop section should specify confirmation requirements" + fi + fi + fi + + return $errors +} + +# Section 9: Security Requirements +validate_security() { + local skill_file="$1" + local skill_name="$2" + local errors=0 + + log_info "Validating security requirements for $skill_name" + + # Check for credential exposure in examples + if grep -q 'echo \$.*SECRET\|echo \$.*PASSWORD\|echo \$.*TOKEN\|echo \$.*KEY' "$skill_file"; then + log_error "$skill_name: SECURITY VIOLATION - Exposing credential values with 'echo \$VAR'" + ((errors++)) + fi + + # Check for hardcoded credentials (common patterns) + if grep -Eq 'password.*=.*["'"'"'][^$]|secret.*=.*["'"'"'][^$]|token.*=.*["'"'"'][^$]' "$skill_file"; then + log_warn "$skill_name: Possible hardcoded credentials found (review manually)" + fi + + # Check for proper credential checking pattern + if grep -q 'KUBECONFIG\|CLIENT_SECRET\|API_KEY\|TOKEN' "$skill_file"; then + if grep -q 'test -n.*\$\|if \[ -n.*\$' "$skill_file"; then + log_info "$skill_name: Uses proper credential checking (test -n)" + fi + fi + + return $errors +} + +# Section 10: Content Quality +validate_content_quality() { + local skill_file="$1" + local skill_name="$2" + local errors=0 + + log_info "Validating content quality for $skill_name" + + # Check for broken markdown links (basic check) + local broken_links=$(grep -o '\[.*\](.*\.md)' "$skill_file" | grep -o '(.*\.md)' | tr -d '()' || true) + if [[ -n "$broken_links" ]]; then + while IFS= read -r link; do + # Convert relative path to absolute + local skill_dir=$(dirname "$skill_file") + local abs_link="$skill_dir/$link" + + # Resolve relative paths (../) + abs_link=$(cd "$skill_dir" && realpath -m "$link" 2>/dev/null || echo "$abs_link") + + if [[ ! -f "$abs_link" ]]; then + log_warn "$skill_name: Possibly broken link: $link" + fi + done <<< "$broken_links" + fi + + # Check file size (recommend under 5000 tokens โ‰ˆ 20KB for text) + local file_size=$(wc -c < "$skill_file") + if [[ $file_size -gt 20480 ]]; then + log_warn "$skill_name: SKILL.md is large ($file_size bytes). Consider moving content to references/" + fi + + return $errors +} + +# Main validation function +validate_skill() { + local skill_dir="$1" + local skill_name=$(basename "$skill_dir") + local skill_file="$skill_dir/SKILL.md" + + echo "" + echo "โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”" + echo -e "${BLUE}Validating:${NC} $skill_name" + echo "โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”" + + ((TOTAL_SKILLS++)) + + local skill_errors=0 + + # Run all validations + validate_agentskills_spec "$skill_dir" || ((skill_errors+=$?)) + + if [[ -f "$skill_file" ]]; then + validate_yaml_frontmatter "$skill_file" "$skill_name" || ((skill_errors+=$?)) + validate_skill_header "$skill_file" "$skill_name" || ((skill_errors+=$?)) + validate_section_order "$skill_file" "$skill_name" || ((skill_errors+=$?)) + validate_prerequisites "$skill_file" "$skill_name" || ((skill_errors+=$?)) + validate_when_to_use "$skill_file" "$skill_name" || ((skill_errors+=$?)) + validate_workflow "$skill_file" "$skill_name" || ((skill_errors+=$?)) + validate_document_consultation "$skill_file" "$skill_name" || ((skill_errors+=$?)) + validate_dependencies "$skill_file" "$skill_name" || ((skill_errors+=$?)) + validate_human_in_loop "$skill_file" "$skill_name" || ((skill_errors+=$?)) + validate_security "$skill_file" "$skill_name" || ((skill_errors+=$?)) + validate_content_quality "$skill_file" "$skill_name" || ((skill_errors+=$?)) + fi + + # Report skill result + echo "" + if [[ $skill_errors -eq 0 ]]; then + log_pass "Skill '$skill_name' passed validation" + ((PASSED_SKILLS++)) + else + log_error "Skill '$skill_name' failed with $skill_errors error(s)" + ((FAILED_SKILLS++)) + + if [[ "$STRICT_MODE" == true ]]; then + echo "" + echo -e "${RED}Strict mode enabled. Exiting on first failure.${NC}" + exit 1 + fi + fi + + return $skill_errors +} + +# Find and validate skills +find_and_validate_skills() { + local search_path="${1:-.}" + + # Check if path exists + if [[ ! -e "$search_path" ]]; then + echo -e "${YELLOW}Path not found: '$search_path'${NC}" + return 0 + fi + + # If the path directly contains SKILL.md, validate it as a single skill + if [[ -f "$search_path/SKILL.md" ]]; then + validate_skill "$search_path" + return 0 + fi + + # If the path IS a SKILL.md file, validate its parent directory + if [[ -f "$search_path" && $(basename "$search_path") == "SKILL.md" ]]; then + local skill_dir=$(dirname "$search_path") + validate_skill "$skill_dir" + return 0 + fi + + # Otherwise, search recursively for SKILL.md files + local skill_files=() + while IFS= read -r -d '' file; do + skill_files+=("$file") + done < <(find "$search_path" -type f -name "SKILL.md" -print0 2>/dev/null) + + if [[ ${#skill_files[@]} -eq 0 ]]; then + echo -e "${YELLOW}No skills found in '$search_path'${NC}" + return 0 + fi + + # Validate each skill + for skill_file in "${skill_files[@]}"; do + local skill_dir=$(dirname "$skill_file") + validate_skill "$skill_dir" + done +} + +# Main execution +main() { + local repo_root + repo_root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd) + cd "$repo_root" || exit 1 + + echo "โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”" + echo -e "${BLUE}Universal Skill Validator${NC}" + echo "Validates skills against SKILL_CHECKLIST.md" + echo "โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”" + + # Determine target paths + if [[ ${#TARGET_PATHS[@]} -eq 0 ]]; then + echo -e "Target: ${BLUE}Current directory (.)${NC}" + TARGET_PATHS=(".") + else + echo -e "Target: ${BLUE}${#TARGET_PATHS[@]} path(s) specified${NC}" + fi + + if [[ "$STRICT_MODE" == true ]]; then + echo -e "Mode: ${RED}Strict (exit on first error)${NC}" + fi + + echo "" + + # Run validation on all target paths + for target_path in "${TARGET_PATHS[@]}"; do + find_and_validate_skills "$target_path" + done + + # Print summary + echo "" + echo "โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”" + echo -e "${BLUE}Validation Summary${NC}" + echo "โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”" + echo -e "Total Skills: $TOTAL_SKILLS" + echo -e "${GREEN}Passed:${NC} $PASSED_SKILLS" + echo -e "${RED}Failed:${NC} $FAILED_SKILLS" + echo -e "${RED}Total Errors:${NC} $TOTAL_ERRORS" + echo "" + + # Exit code + if [[ $FAILED_SKILLS -eq 0 ]]; then + echo -e "${GREEN}โœ“ All skills passed validation${NC}" + exit 0 + else + echo -e "${RED}โœ— Some skills failed validation${NC}" + exit 1 + fi +} + +# Run main +main "$@" From c2ad2f4c9a34624615ec20d1e97b94ea409a1891 Mon Sep 17 00:00:00 2001 From: r2dedios Date: Fri, 27 Feb 2026 15:31:53 +0100 Subject: [PATCH 04/20] fix(workflow): Modified workflow for only validating with Skill Spec Linter Signed-off-by: r2dedios --- .github/workflows/README.md | 309 +++++++++++++++++++----- .github/workflows/skill-spec-report.yml | 105 ++++++++ .github/workflows/validate-skills.yml | 73 ------ CLAUDE.md | 11 - scripts/detect-changed-skills.sh | 39 +++ scripts/run-skill-linter.sh | 184 ++++++++++++++ 6 files changed, 571 insertions(+), 150 deletions(-) create mode 100644 .github/workflows/skill-spec-report.yml delete mode 100644 .github/workflows/validate-skills.yml create mode 100755 scripts/detect-changed-skills.sh create mode 100755 scripts/run-skill-linter.sh diff --git a/.github/workflows/README.md b/.github/workflows/README.md index 368d9cad..12652f72 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -4,110 +4,285 @@ This directory contains CI/CD workflows for the agentic collections repository. ## Available Workflows -### 1. `validate-skills.yml` - Universal Skill Validation +### 1. `skill-spec-report.yml` - Skill Specification Linter Report -**Purpose**: Validates all skills against SKILL_CHECKLIST.md requirements (agentskills.io specification + repository design principles). +**Purpose**: Validates skills against agentskills.io specification using the skill-linter and generates a comprehensive compliance report. **Triggers**: -- **Every pull request** (opened, synchronized, reopened, or marked ready for review) -- Pushes to `main` branch -- **Excludes**: Draft pull requests (validation runs only when PR is ready for review) +- **Pull requests** โ†’ Validates ONLY changed skills (fast feedback) +- **Pushes to main** โ†’ Validates ALL skills (ensures repo health) +- **Manual dispatch** โ†’ Choose between all skills or changed skills +- **Excludes**: Draft pull requests + +**Validation Strategy** (Option 2: Changed Skills + Manual Full Scan): +- โšก **PRs**: Fast validation of only changed skills +- ๐Ÿ” **Push to main**: Full validation of all 37 skills +- ๐ŸŽ›๏ธ **Manual**: Choose validation scope via workflow dispatch **What it validates**: -**Tier 1 - agentskills.io specification (MANDATORY):** +**agentskills.io Specification Compliance:** - โœ… Directory structure (skill-name/SKILL.md) -- โœ… Name format (1-64 chars, lowercase, no consecutive hyphens) -- โœ… Description length (1-1024 chars, under 500 tokens) -- โœ… YAML frontmatter completeness (name, description) - -**Tier 2 - Repository design principles (MANDATORY):** -- โœ… Model field (must be: inherit, sonnet, or haiku) -- โœ… Color field (must be: cyan, green, blue, yellow, or red) -- โœ… SKILL.md header format (# / Skill or # [Skill Name]) -- โœ… Required sections presence and order -- โœ… Prerequisites with verification steps -- โœ… When to Use This Skill with anti-patterns -- โœ… Workflow with MCP tools and parameters -- โœ… Document consultation transparency -- โœ… Dependencies declaration -- โœ… Human-in-the-Loop requirements -- โœ… Security (no credential exposure) -- โœ… Content quality (links, file size) +- โœ… YAML frontmatter delimiters and completeness +- โœ… Name field (1-64 chars, lowercase, pattern matching, directory alignment) +- โœ… Description field (1-1024 chars, routing keywords, no marketing copy) +- โœ… Optional fields (compatibility, allowed-tools format) +- โœ… Line count (max 500 lines in SKILL.md) +- โœ… Subdirectory validation (only scripts/, references/, assets/) +- โœ… Content quality (no ASCII art, no persona statements) + +**Behavior**: +- **Errors detected** โ†’ โŒ Workflow fails, blocks PR merge +- **Warnings only** โ†’ โš ๏ธ Workflow passes, allows merge with warnings +- **All pass** โ†’ โœ… Workflow passes + +**Report Format**: +- Real-time progress (โœ…/โš ๏ธ/โŒ) for each skill +- **Detailed error output** shown ONLY for failed skills +- **Summary table** at the end with counts (Total/Passed/Warnings/Failed) **How to run locally**: ```bash -# Validate all skills in all collections -./scripts/validate-skills.sh +# Validate ALL skills +./scripts/run-skill-linter.sh -# Validate specific collection -./scripts/validate-skills.sh rh-virt/ +# Validate only changed skills (detects git changes) +CHANGED=$(./scripts/detect-changed-skills.sh) +if [ -n "$CHANGED" ]; then + ./scripts/run-skill-linter.sh $CHANGED +fi -# Validate single skill -./scripts/validate-skills.sh rh-virt/skills/vm-create/ +# Validate specific skills +./scripts/run-skill-linter.sh rh-virt/skills/vm-create rh-virt/skills/vm-delete -# Strict mode (exit on first error) -./scripts/validate-skills.sh --strict rh-virt/ - -# Verbose output -./scripts/validate-skills.sh --verbose +# Validate single skill (detailed output) +./.claude/skills/skill-linter/scripts/validate-skill.sh rh-virt/skills/vm-create/ ``` +**Manual workflow dispatch**: +1. Go to Actions โ†’ Skill Specification Report +2. Click "Run workflow" +3. Choose: + - **Validate all skills: true** โ†’ Full scan (37 skills) + - **Validate all skills: false** โ†’ Changed skills only + **Expected output**: ``` โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” -Universal Skill Validator -Validates skills against CLAUDE.md and agentskills.io specification + Skill Specification Linter Report + agentskills.io Specification Compliance โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” -Found 9 skill(s) to validate +Found 37 skill(s) to validate -โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” -Validating: vm-create -โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” +โœ… rh-sre/cve-impact +โœ… rh-sre/fleet-inventory +โš ๏ธ rh-developer/helm-deploy - PASSED WITH WARNINGS +โŒ rh-virt/vm-create - FAILED -โœ“ Skill 'vm-create' passed validation +โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” +DETAILED ERROR REPORT +โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” +FAILED: rh-virt/vm-create +โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” +[FAIL] Missing frontmatter opening delimiter (---) ... โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” -Validation Summary + +VALIDATION SUMMARY โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” -Total Skills: 9 -Passed: 9 -Failed: 0 -Total Errors: 0 -โœ“ All skills passed validation +Metric Count +โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +Total Skills: 37 +โœ… Passed: 30 +โš ๏ธ Passed with Warnings: 6 +โŒ Failed: 1 + +โŒ VALIDATION FAILED - ERRORS DETECTED +Skills with errors must be fixed before merge ``` -**Validation Levels**: +**When validation fails**: + +The workflow will: +1. Show detailed error output for each failed skill +2. Display summary table with failure counts +3. Block PR merge (exit code 1) +4. Provide guidance on fixing errors locally + +**When validation passes with warnings**: + +The workflow will: +1. Show which skills have warnings +2. Display summary table +3. Allow PR merge (exit code 0) +4. Warn that warnings should be reviewed + +**Common validation errors**: +- Missing frontmatter delimiters (---) +- Name doesn't match directory name +- Description exceeds 1024 characters or lacks routing keywords +- Line count exceeds 500 lines +- Invalid `allowed-tools` format (must be space-delimited) +- ASCII art or persona statements in content +- Marketing buzzwords in description + +**Related files**: +- `scripts/run-skill-linter.sh` - Comprehensive linter reporter script (accepts optional skill dirs) +- `scripts/detect-changed-skills.sh` - Detects changed skills in PRs and commits +- `.claude/skills/skill-linter/scripts/validate-skill.sh` - Core validation script +- `.claude/skills/skill-linter/SKILL.md` - Linter documentation + +**Performance**: +- **PR validation**: ~5-30 seconds (1-3 changed skills typically) +- **Full validation**: ~60-90 seconds (all 37 skills) +- **Changed-only**: 80-95% faster than full validation + +**Scope**: This workflow validates **ONLY** agentskills.io specification compliance. Repository-specific design principles (model, color, sections, etc.) are validated by other workflows. + +### 2. `compliance-check.yml` - Agentic Collections Structure Validation + +**Purpose**: Validates the entire agentic collections repository structure and runs skill design compliance checks on changed skills only. + +**Triggers**: +- **Every pull request** +- Pushes to `main` branch + +**What it validates**: + +**Repository structure validation (`make validate`):** +- โœ… Collection directory structure and naming conventions +- โœ… Required files presence (README.md, .mcp.json, etc.) +- โœ… Plugin metadata completeness +- โœ… MCP server configurations -The script validates all requirements from SKILL_CHECKLIST.md: -- **Level 1:** agentskills.io specification (Sections 0-9) - MANDATORY -- **Level 2:** Repository design principles (Sections 10-37) - MANDATORY +**Changed skills validation (`./scripts/ci-validate-changed-skills.sh`):** +- โœ… Detects which skills were modified in the PR/push +- โœ… Validates only changed skills against SKILL_DESIGN_PRINCIPLES.md +- โœ… Runs design compliance checks specific to modified skills -All skills must pass both levels to be committed. +**How to run locally**: +```bash +# Validate entire repository structure +make validate + +# Validate changed skills (simulates CI environment) +./scripts/ci-validate-changed-skills.sh + +# Or validate all skills +make validate-skill-design +``` + +**Expected output**: +``` +Validating repository structure... +โœ“ Collection structure valid +โœ“ Plugin metadata valid +โœ“ MCP configurations valid + +Validating changed skills... +Found 2 changed skill(s): vm-create, vm-delete +โœ“ vm-create passed design compliance +โœ“ vm-delete passed design compliance +``` **When validation fails**: The workflow will fail and provide: -1. Specific errors for each skill -2. Common issues and fixes -3. Local validation command -4. Reference to SKILL_CHECKLIST.md for detailed requirements +1. Specific structural errors in the repository +2. Design compliance violations for changed skills +3. Reference to SKILL_DESIGN_PRINCIPLES.md **Common validation errors**: -- Missing or invalid `model` field (must be: inherit, sonnet, or haiku) -- Missing or invalid `color` field (must be: cyan, green, blue, yellow, or red) -- Invalid SKILL.md header format (must be: # / Skill) -- Missing required sections (Prerequisites, When to Use, Workflow, Dependencies) -- Missing "NOT for" anti-patterns in description +- Missing required collection files (README.md, .mcp.json) +- Invalid MCP server configuration syntax +- Skills not following design principles (see SKILL_DESIGN_PRINCIPLES.md) +- Missing documentation in collections **Related files**: -- `scripts/validate-skills.sh` - Main validation script -- `SKILL_CHECKLIST.md` - Universal skill requirements checklist (single source of truth) -- `CLAUDE.md` - Repository architecture and patterns +- `Makefile` - Build and validation targets +- `scripts/ci-validate-changed-skills.sh` - Changed skills detector and validator +- `scripts/validate_skill_design.py` - Design compliance validation script +- `SKILL_DESIGN_PRINCIPLES.md` - Design principles checklist + +### 3. `deploy-pages.yml` - GitHub Pages Documentation Deployment + +**Purpose**: Generates and deploys HTML documentation for all agentic collections to GitHub Pages. + +**Triggers**: +- **Manual dispatch** (workflow_dispatch) +- Pushes to `main` branch affecting documentation paths: + - `rh-sre/**` + - `rh-developer/**` + - `ocp-admin/**` + - `rh-support-engineer/**` + - `rh-virt/**` + - `scripts/**` + - `docs/**` + - `.github/workflows/deploy-pages.yml` + +**What it does**: + +**Documentation generation (`make generate`):** +- โœ… Generates HTML documentation from Markdown files +- โœ… Creates collection indexes and navigation +- โœ… Builds skill reference pages +- โœ… Generates searchable documentation site + +**Deployment:** +- โœ… Configures GitHub Pages environment +- โœ… Uploads documentation artifacts +- โœ… Deploys to GitHub Pages with proper permissions + +**How to run locally**: +```bash +# Generate documentation locally +make generate + +# Preview generated docs +cd docs && python3 -m http.server 8000 +# Open http://localhost:8000 in your browser +``` + +**Expected output**: +``` +Generating documentation... +โœ“ Processing rh-sre collection +โœ“ Processing rh-developer collection +โœ“ Processing rh-virt collection +โœ“ Building site navigation +โœ“ Documentation generated in docs/ + +Deploying to GitHub Pages... +โœ“ Artifact uploaded +โœ“ Deployed successfully +``` + +**When deployment fails**: + +The workflow will fail if: +1. Documentation generation fails (invalid Markdown, missing files) +2. GitHub Pages permissions not configured +3. Artifact upload fails +4. Deployment step fails + +**Common deployment errors**: +- Missing Python dependencies (resolved by `make install`) +- Invalid frontmatter in Markdown files +- GitHub Pages not enabled in repository settings +- Insufficient workflow permissions + +**Related files**: +- `Makefile` - Documentation generation targets +- `scripts/generate-docs.py` - Documentation generator (if exists) +- `docs/` - Generated documentation output directory + +**Concurrency settings**: +- Only one deployment runs at a time (group: "pages") +- New deployments cancel in-progress ones ## Adding New Workflows @@ -182,5 +357,7 @@ This README should be updated when: - New validation levels are introduced - Troubleshooting patterns emerge -**Last Updated**: 2026-02-26 -**Workflows Count**: 1 (validate-skills.yml) +**Last Updated**: 2026-02-27 +**Workflows Count**: 3 (skill-spec-report.yml, compliance-check.yml, deploy-pages.yml) + +**Note**: `validate-skills.yml` was removed 2026-02-27. Repository-specific design principle validation (Tier 2) will be handled by a separate workflow. diff --git a/.github/workflows/skill-spec-report.yml b/.github/workflows/skill-spec-report.yml new file mode 100644 index 00000000..622e3ada --- /dev/null +++ b/.github/workflows/skill-spec-report.yml @@ -0,0 +1,105 @@ +name: Skill Specification Report + +on: + pull_request: + types: [opened, synchronize, reopened, ready_for_review] + push: + branches: [main] + workflow_dispatch: + inputs: + validate_all: + description: 'Validate all skills (true) or changed only (false)' + required: false + default: 'true' + type: choice + options: + - 'true' + - 'false' + +jobs: + skill-linter: + # Skip draft PRs + if: github.event.pull_request.draft == false || github.event_name == 'push' || github.event_name == 'workflow_dispatch' + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history for diff comparison + + - name: Make scripts executable + run: | + chmod +x .claude/skills/skill-linter/scripts/validate-skill.sh + chmod +x scripts/run-skill-linter.sh + chmod +x scripts/detect-changed-skills.sh + + - name: Detect changed skills (PRs only) + if: github.event_name == 'pull_request' + id: detect + env: + GITHUB_EVENT_NAME: ${{ github.event_name }} + GITHUB_BASE_REF: ${{ github.base_ref }} + run: | + CHANGED_SKILLS=$(./scripts/detect-changed-skills.sh || true) + if [ -z "$CHANGED_SKILLS" ]; then + echo "changed=false" >> $GITHUB_OUTPUT + echo "skills=" >> $GITHUB_OUTPUT + else + echo "changed=true" >> $GITHUB_OUTPUT + # Convert to space-separated for script args + SKILLS_ARGS=$(echo "$CHANGED_SKILLS" | tr '\n' ' ') + echo "skills=$SKILLS_ARGS" >> $GITHUB_OUTPUT + echo "Changed skills detected:" + echo "$CHANGED_SKILLS" + fi + + - name: Run Skill Specification Linter + id: linter + run: | + # Determine validation mode + if [ "${{ github.event_name }}" = "pull_request" ]; then + if [ "${{ steps.detect.outputs.changed }}" = "true" ]; then + echo "Running linter on changed skills only..." + ./scripts/run-skill-linter.sh ${{ steps.detect.outputs.skills }} + else + echo "โ„น๏ธ No skills changed in this PR - skipping validation" + echo "0" > /tmp/skill-linter-exit-code + exit 0 + fi + elif [ "${{ github.event_name }}" = "workflow_dispatch" ]; then + if [ "${{ github.event.inputs.validate_all }}" = "true" ]; then + echo "Running linter on ALL skills (manual dispatch)..." + ./scripts/run-skill-linter.sh + else + echo "Running linter on changed skills only (manual dispatch)..." + CHANGED_SKILLS=$(./scripts/detect-changed-skills.sh || true) + if [ -n "$CHANGED_SKILLS" ]; then + ./scripts/run-skill-linter.sh $(echo "$CHANGED_SKILLS" | tr '\n' ' ') + else + echo "โ„น๏ธ No skills changed - skipping validation" + echo "0" > /tmp/skill-linter-exit-code + fi + fi + else + # Push to main: validate ALL skills + echo "Running linter on ALL skills (push to main)..." + ./scripts/run-skill-linter.sh + fi + continue-on-error: true + + - name: Check results + run: | + if [ -f /tmp/skill-linter-exit-code ]; then + EXIT_CODE=$(cat /tmp/skill-linter-exit-code) + if [ "$EXIT_CODE" -ne 0 ]; then + echo "โŒ Skill linter detected errors - blocking PR merge" + exit 1 + else + echo "โœ… All skills passed or have warnings only" + exit 0 + fi + else + echo "โŒ Linter did not complete" + exit 1 + fi diff --git a/.github/workflows/validate-skills.yml b/.github/workflows/validate-skills.yml deleted file mode 100644 index f2432083..00000000 --- a/.github/workflows/validate-skills.yml +++ /dev/null @@ -1,73 +0,0 @@ -name: Validate Skills - -on: - pull_request: - types: [opened, synchronize, reopened, ready_for_review] - push: - branches: - - main - -jobs: - validate: - name: Validate Skill Structure and Requirements - runs-on: ubuntu-latest - - # Skip draft PRs - if: github.event.pull_request.draft == false || github.event_name == 'push' - - steps: - - name: Checkout repository - uses: actions/checkout@v4 - with: - fetch-depth: 0 # Full history for better diff analysis - - - name: Detect changed skills - id: changed-files - uses: tj-actions/changed-files@v44 - with: - files: | - **/skills/**/SKILL.md - - - name: List changed skills - if: steps.changed-files.outputs.any_changed == 'true' - run: | - echo "Changed skill files:" - echo "${{ steps.changed-files.outputs.all_changed_files }}" - - - name: Run validation script (all skills) - run: | - echo "Running universal skill validation..." - echo "" - ./scripts/validate-skills.sh --verbose - - - name: Validation Summary - if: success() - run: | - echo "" - echo "โœ… All skills passed validation" - echo "" - echo "Validated against:" - echo " - Tier 1: agentskills.io specification (MANDATORY)" - echo " - Tier 2: Repository design principles (MANDATORY)" - echo "" - echo "See SKILL_CHECKLIST.md for complete requirements." - - - name: Validation Failed - if: failure() - run: | - echo "" - echo "โŒ Skill validation failed" - echo "" - echo "Please review the errors above and ensure your skills meet all requirements in:" - echo " ๐Ÿ“‹ SKILL_CHECKLIST.md" - echo "" - echo "Common issues:" - echo " - Missing or invalid 'model' field (must be: inherit, sonnet, or haiku)" - echo " - Missing or invalid 'color' field (must be: cyan, green, blue, yellow, or red)" - echo " - Invalid SKILL.md header format (must be: # / Skill)" - echo " - Missing required sections (Prerequisites, When to Use, Workflow, Dependencies)" - echo " - Missing 'NOT for' anti-patterns in description" - echo "" - echo "To validate locally:" - echo " ./scripts/validate-skills.sh path/to/skill/" - exit 1 diff --git a/CLAUDE.md b/CLAUDE.md index 2bfecfa0..6d802beb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -258,15 +258,4 @@ When creating new collections, follow the pattern that best matches your needs: 9. **Production-ready examples** - No toy code, include error handling 10. **Persona-focused design** - Each collection serves specific user roles -<<<<<<< Updated upstream -### Quality & Usability -11. **Precise parameters** - Specify exact tool parameters for first-attempt success (Design Principle #2) -12. **Declare dependencies** - List all skills, tools, docs, and MCP servers (Design Principle #4) -13. **Production-ready examples** - No toy code, include error handling -14. **Persona-focused design** - Each collection serves specific user roles -15. **Concise skill descriptions** - Keep YAML frontmatter under 500 tokens (Design Principle #3) - -**See**: [SKILL_DESIGN_PRINCIPLES.md](SKILL_DESIGN_PRINCIPLES.md) for detailed requirements and templates. -======= **See [SKILL_CHECKLIST.md](./SKILL_CHECKLIST.md) for complete skill requirements, design principles, and validation criteria.** ->>>>>>> Stashed changes diff --git a/scripts/detect-changed-skills.sh b/scripts/detect-changed-skills.sh new file mode 100755 index 00000000..f1d701fd --- /dev/null +++ b/scripts/detect-changed-skills.sh @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +# Detect changed skills in CI (PRs and pushes to main) +# Outputs list of changed skill directories (one per line) +# Exits 0 if no skills changed + +set -e + +if [ -n "$VALIDATE_INCLUDE_UNCOMMITTED" ]; then + # Local dev: include staged + unstaged changes vs HEAD + DIFF_CMD="git diff --name-only HEAD" +elif [ "$GITHUB_EVENT_NAME" = "pull_request" ]; then + # Three-dot diff: merge-base(base, HEAD)..HEAD = changes in the PR + BASE_REF="${GITHUB_BASE_REF:-main}" + git fetch origin "$BASE_REF" 2>/dev/null || true + DIFF_CMD="git diff --name-only origin/$BASE_REF...HEAD" +elif [ "$GITHUB_EVENT_NAME" = "push" ]; then + # Push event: diff between before and after + BEFORE="${GITHUB_EVENT_BEFORE:-}" + if [ -z "$BEFORE" ] || [ "$BEFORE" = "0000000000000000000000000000000000000000" ]; then + # No base commit for diff, exit with no changes + exit 0 + fi + DIFF_CMD="git diff --name-only $BEFORE HEAD" +else + # Default: local dev, include uncommitted changes + DIFF_CMD="git diff --name-only HEAD" +fi + +# Find changed SKILL.md files and extract their directories +CHANGED_FILES=$($DIFF_CMD 2>/dev/null | grep -E '^([^/]+/skills/[^/]+/SKILL\.md|\.claude/skills/[^/]+/SKILL\.md)$' || true) + +if [ -z "$CHANGED_FILES" ]; then + exit 0 +fi + +# Extract skill directories from SKILL.md paths +echo "$CHANGED_FILES" | while read -r file; do + dirname "$file" +done diff --git a/scripts/run-skill-linter.sh b/scripts/run-skill-linter.sh new file mode 100755 index 00000000..28b317fa --- /dev/null +++ b/scripts/run-skill-linter.sh @@ -0,0 +1,184 @@ +#!/bin/bash +# Skill Specification Linter Reporter +# Runs agentskills.io spec linter on skills and generates detailed error report + summary table +# Usage: ./run-skill-linter.sh [skill-dir1] [skill-dir2] ... +# No args: validates ALL skills +# With args: validates only specified skill directories + +set -o pipefail + +# Colors +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[0;33m' +BLUE='\033[0;34m' +BOLD='\033[1m' +NC='\033[0m' # No Color + +# Counters +TOTAL_SKILLS=0 +PASSED_SKILLS=0 +WARNED_SKILLS=0 +FAILED_SKILLS=0 +HAS_ERRORS=false + +# Storage for failed skills details +FAILED_DETAILS_FILE=$(mktemp) +SUMMARY_FILE=$(mktemp) + +# Header +echo "" +echo -e "${BOLD}โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”${NC}" +echo -e "${BOLD} Skill Specification Linter Report${NC}" +echo -e "${BOLD} agentskills.io Specification Compliance${NC}" +echo -e "${BOLD}โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”${NC}" +echo "" + +# Determine which skills to validate +if [ $# -eq 0 ]; then + # No arguments: validate ALL skills + SKILL_PATHS=$(find . -name "SKILL.md" -type f | grep -E "(rh-sre|rh-developer|rh-virt|ocp-admin|rh-support-engineer|\.claude)/skills/" | sort) + VALIDATION_MODE="all" +else + # Arguments provided: validate only specified skill directories + SKILL_PATHS="" + for skill_dir in "$@"; do + # Remove trailing slash if present + skill_dir="${skill_dir%/}" + # Add SKILL.md path + if [ -f "$skill_dir/SKILL.md" ]; then + SKILL_PATHS="$SKILL_PATHS$skill_dir/SKILL.md"$'\n' + else + echo -e "${YELLOW}โš ๏ธ Warning: $skill_dir/SKILL.md not found, skipping${NC}" + fi + done + SKILL_PATHS=$(echo "$SKILL_PATHS" | grep -v '^$' | sort) + VALIDATION_MODE="changed" +fi + +if [ -z "$SKILL_PATHS" ]; then + echo -e "${BLUE}โ„น๏ธ No skills to validate${NC}" + exit 0 +fi + +# Count total skills +TOTAL_SKILLS=$(echo "$SKILL_PATHS" | wc -l | tr -d ' ') + +if [ "$VALIDATION_MODE" = "all" ]; then + echo -e "${BLUE}Validating ALL skills: ${TOTAL_SKILLS} skill(s)${NC}" +else + echo -e "${BLUE}Validating CHANGED skills: ${TOTAL_SKILLS} skill(s)${NC}" +fi +echo "" + +# Validate each skill +while IFS= read -r skill_file; do + skill_dir=$(dirname "$skill_file") + skill_name=$(basename "$skill_dir") + collection=$(echo "$skill_dir" | cut -d'/' -f2) + + # Run linter and capture output + LINTER_OUTPUT=$(mktemp) + ./.claude/skills/skill-linter/scripts/validate-skill.sh "$skill_dir" > "$LINTER_OUTPUT" 2>&1 + EXIT_CODE=$? + + # Parse output for pass/warn/fail + if [ $EXIT_CODE -eq 0 ]; then + if grep -q "\[WARN\]" "$LINTER_OUTPUT"; then + # Passed with warnings + WARNED_SKILLS=$((WARNED_SKILLS + 1)) + echo -e "โš ๏ธ ${YELLOW}${collection}/${skill_name}${NC} - PASSED WITH WARNINGS" + else + # Clean pass + PASSED_SKILLS=$((PASSED_SKILLS + 1)) + echo -e "โœ… ${GREEN}${collection}/${skill_name}${NC}" + fi + else + # Failed + FAILED_SKILLS=$((FAILED_SKILLS + 1)) + HAS_ERRORS=true + echo -e "โŒ ${RED}${collection}/${skill_name}${NC} - FAILED" + + # Store detailed output for failed skills + echo "" >> "$FAILED_DETAILS_FILE" + echo -e "${BOLD}โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”${NC}" >> "$FAILED_DETAILS_FILE" + echo -e "${RED}${BOLD}FAILED: ${collection}/${skill_name}${NC}" >> "$FAILED_DETAILS_FILE" + echo -e "${BOLD}โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”${NC}" >> "$FAILED_DETAILS_FILE" + cat "$LINTER_OUTPUT" >> "$FAILED_DETAILS_FILE" + echo "" >> "$FAILED_DETAILS_FILE" + fi + + # Store summary entry + if [ $EXIT_CODE -eq 0 ]; then + if grep -q "\[WARN\]" "$LINTER_OUTPUT"; then + echo "${collection}/${skill_name}|โš ๏ธ WARNINGS" >> "$SUMMARY_FILE" + else + echo "${collection}/${skill_name}|โœ… PASSED" >> "$SUMMARY_FILE" + fi + else + echo "${collection}/${skill_name}|โŒ FAILED" >> "$SUMMARY_FILE" + fi + + rm -f "$LINTER_OUTPUT" +done <<< "$SKILL_PATHS" + +echo "" +echo -e "${BOLD}โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”${NC}" + +# Show detailed errors if any +if [ "$FAILED_SKILLS" -gt 0 ]; then + echo "" + echo -e "${RED}${BOLD}DETAILED ERROR REPORT${NC}" + echo -e "${BOLD}โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”${NC}" + cat "$FAILED_DETAILS_FILE" + echo -e "${BOLD}โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”${NC}" + echo "" +fi + +# Summary Table +echo "" +echo -e "${BOLD}VALIDATION SUMMARY${NC}" +echo -e "${BOLD}โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”${NC}" +echo "" +printf "${BOLD}%-42s%s${NC}\n" "Metric" "Count" +echo "โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€" +printf "%-42s${BLUE}%s${NC}\n" "Total Skills:" "$TOTAL_SKILLS" +printf "โœ… %-39s${GREEN}%s${NC}\n" "Passed:" "$PASSED_SKILLS" +printf "โš ๏ธ %-40s${YELLOW}%s${NC}\n" "Passed with Warnings:" "$WARNED_SKILLS" +printf "โŒ %-39s${RED}%s${NC}\n" "Failed:" "$FAILED_SKILLS" +echo "" + +# Status indicator +if [ "$HAS_ERRORS" = true ]; then + echo -e "${RED}${BOLD}โŒ VALIDATION FAILED - ERRORS DETECTED${NC}" + echo -e "${RED}Skills with errors must be fixed before merge${NC}" + EXIT_STATUS=1 +elif [ "$WARNED_SKILLS" -gt 0 ]; then + echo -e "${YELLOW}${BOLD}โš ๏ธ PASSED WITH WARNINGS${NC}" + echo -e "${YELLOW}Review warnings above - PR can be merged${NC}" + EXIT_STATUS=0 +else + echo -e "${GREEN}${BOLD}โœ… ALL SKILLS PASSED${NC}" + EXIT_STATUS=0 +fi + +echo "" +echo -e "${BOLD}โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”${NC}" +echo "" + +# Additional guidance on errors +if [ "$FAILED_SKILLS" -gt 0 ]; then + echo -e "${BOLD}How to fix:${NC}" + echo "1. Review the detailed error report above" + echo "2. Run locally: ./.claude/skills/skill-linter/scripts/validate-skill.sh " + echo "3. See agentskills.io specification: https://agentskills.io/specification" + echo "" +fi + +# Cleanup +rm -f "$FAILED_DETAILS_FILE" "$SUMMARY_FILE" + +# Save exit code for workflow +echo "$EXIT_STATUS" > /tmp/skill-linter-exit-code + +exit $EXIT_STATUS From 892eccb14d99b1835a0351e3fc543a72b76235e9 Mon Sep 17 00:00:00 2001 From: r2dedios Date: Fri, 27 Feb 2026 15:41:08 +0100 Subject: [PATCH 05/20] fix(workflow): Added missing linter script Signed-off-by: r2dedios --- .claude/skills/skill-linter/.skillfish.json | 10 + .claude/skills/skill-linter/SKILL.md | 227 +++++++++++++++ .../skill-linter/scripts/validate-skill.sh | 261 ++++++++++++++++++ 3 files changed, 498 insertions(+) create mode 100644 .claude/skills/skill-linter/.skillfish.json create mode 100644 .claude/skills/skill-linter/SKILL.md create mode 100755 .claude/skills/skill-linter/scripts/validate-skill.sh diff --git a/.claude/skills/skill-linter/.skillfish.json b/.claude/skills/skill-linter/.skillfish.json new file mode 100644 index 00000000..7bfea597 --- /dev/null +++ b/.claude/skills/skill-linter/.skillfish.json @@ -0,0 +1,10 @@ +{ + "version": 2, + "name": "skill-linter", + "owner": "majesticlabs-dev", + "repo": "majestic-marketplace", + "path": ".claude/skills/skill-linter", + "branch": "master", + "sha": "2ded694ad1e9b7103d6aa6d2d2243d2dc79f23b4", + "source": "manual" +} \ No newline at end of file diff --git a/.claude/skills/skill-linter/SKILL.md b/.claude/skills/skill-linter/SKILL.md new file mode 100644 index 00000000..ac0c59ba --- /dev/null +++ b/.claude/skills/skill-linter/SKILL.md @@ -0,0 +1,227 @@ +--- +name: skill-linter +description: Validate skills against agentskills.io specification. Use when adding new skills to the marketplace, reviewing skill PRs, checking skill compliance, or running quality gates on skills. Validates frontmatter fields (name, description, compatibility, metadata, allowed-tools), directory naming, line limits, and structure. +allowed-tools: Bash Read Glob Grep +--- + +# Skill Linter + +## When to Use + +- Adding new skills to the marketplace +- Reviewing skill PRs +- Running quality gates before merge +- Checking existing skills for compliance + +## Validation Rules + +### Required Frontmatter + +| Field | Constraints | +|-------|-------------| +| `name` | 1-64 chars, lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens, must match parent directory name | +| `description` | 1-1024 chars, non-empty, should include keywords for discoverability | + +### Optional Frontmatter + +| Field | Constraints | +|-------|-------------| +| `compatibility` | 1-500 chars, environment requirements | +| `metadata` | Key-value pairs (string values only) | +| `allowed-tools` | Space-delimited tool list (FAIL on commas or array syntax) | + +### Structure Requirements + +| Rule | Requirement | +|------|-------------| +| Directory name | Must match `name` field exactly | +| SKILL.md | Required, must exist | +| Line limit | Max 500 lines in SKILL.md | +| Subdirectories | Only `scripts/`, `references/`, `assets/` allowed | + +### Content Quality Rules + +| Rule | Requirement | +|------|-------------| +| No ASCII art | Box-drawing characters (โ”€โ”‚โ”Œโ”โ””โ”˜โ”œโ”คโ”ฌโ”ดโ”ผ), arrows (โ†‘โ†“โ†โ†’โ†”), and decorative diagrams waste tokens. LLMs tokenize character-by-character, not visually. Use plain lists or tables instead. | +| No decorative quotes | Inspirational quotes or attributions ("As X said...") have no functional value for LLM execution. | +| No persona statements | "You are an expert..." wastes tokens. Use **Audience:** / **Goal:** framing instead. | +| Functional content only | Every line should improve LLM behavior. Ask: "Does this help Claude execute better?" | + +### Audience/Goal Framing (Required) + +Replace persona roleplay with audience-focused framing: + +**โŒ Bad (persona):** +``` +You are an expert software engineer with deep expertise in testing. +Your role is to analyze code and generate thorough test coverage. +``` + +**โœ… Good (audience/goal):** +``` +**Audience:** Developers needing test coverage for new or changed code. + +**Goal:** Generate comprehensive tests based on specified test type and framework. +``` + +**Rationale:** "Explain X for audience Y" yields better-tailored outputs than "Act as persona Z". + +**ASCII Art Detection Pattern:** +```regex +[โ”€โ”‚โ”Œโ”โ””โ”˜โ”œโ”คโ”ฌโ”ดโ”ผโ•ญโ•ฎโ•ฏโ•ฐโ•โ•‘โ•”โ•—โ•šโ•โ• โ•ฃโ•ฆโ•ฉโ•ฌโ†‘โ†“โ†โ†’โ†”โ‡’โ‡โ‡”โ–ฒโ–ผโ—„โ–บ]{3,} +``` + +Files matching this pattern should be flagged for review. + +### Description Routing Quality (WARN) + +Skill descriptions are routing logic, not documentation. They answer: +- **When** to use this skill (trigger conditions) +- **When NOT** to use (negative routing) +- **What outputs** to expect (success criteria) + +| Quality Level | Example | +|---------------|---------| +| Good | "Use when implementing Stimulus controllers. Not for React components. Outputs controller with targets and actions." | +| Adequate | "Use when working with Stimulus controllers in Rails applications." | +| Poor | "Stimulus controller development skill." | +| Anti-pattern | "Comprehensive, powerful toolkit for building cutting-edge Stimulus controllers." | + +Templates inside skills are encouraged โ€” loaded only on trigger, essentially free tokens. + +### Skill Disambiguation (INFO) + +When multiple skills cover similar domains, include negative routing: + +**Example (minitest vs rspec):** + +| Skill | Description Routing | +|-------|-------------------| +| `minitest-coder` | "Use when writing Minitest tests. Not for RSpec โ€” use rspec-coder instead." | +| `rspec-coder` | "Use when writing RSpec tests. Not for Minitest โ€” use minitest-coder instead." | + +"Don't use when..." is as important as "Use when..." for routing accuracy. + +### Name Pattern + +```regex +^[a-z][a-z0-9]*(-[a-z0-9]+)*$ +``` + +**Valid:** `my-skill`, `skill1`, `api-v2-handler` +**Invalid:** `-skill`, `skill-`, `my--skill`, `MySkill`, `my_skill` + +### Command/Agent Invocation Patterns + +Skills should primarily provide knowledge, not orchestration. If invocations are needed: + +| Pattern | Status | Use Instead | +|---------|--------|-------------| +| `Skill("command", args: "...")` | โŒ Deprecated | `/command args` | +| `SlashCommand("command", ...)` | โŒ Deprecated | `/command args` | +| `Task(subagent_type="agent", ...)` | โœ… Correct | (no change) | + +**โœ… Preferred command invocation:** +``` +/majestic:config tech_stack generic +/majestic-engineer:tdd-workflow +/majestic-ralph:start "task" --max-iterations 50 +``` + +**โŒ Deprecated patterns:** +``` +Skill("config-reader", args: "tech_stack generic") +SlashCommand("majestic:build-task", args: "...") +``` + +**Note:** Agent invocation via `Task()` is correct - there is no `@agent` syntax. + +## Usage + +### Validate Single Skill + +```bash +./scripts/validate-skill.sh path/to/skill-name +``` + +### Validate All Marketplace Skills + +```bash +for skill in plugins/*/skills/*/; do + ./scripts/validate-skill.sh "$skill" +done +``` + +### CI Integration + +Add to pre-commit hook or CI pipeline: + +```yaml +- name: Lint Skills + run: | + for skill in plugins/*/skills/*/; do + .claude/skills/skill-linter/scripts/validate-skill.sh "$skill" || exit 1 + done +``` + +## Validation Script + +The linter script at `scripts/validate-skill.sh` performs these checks: + +1. **Directory exists** with SKILL.md file +2. **Frontmatter present** with YAML delimiters +3. **Name field valid** - pattern, length, matches directory +4. **Description field valid** - present, length constraints +5. **Optional fields valid** - if present, match constraints +6. **Line count** - under 500 lines +7. **Subdirectory names** - only allowed directories +8. **No ASCII art** - box-drawing characters outside fenced code blocks (WARN) +9. **No persona statements** - "You are a/an/the" outside fenced code blocks (FAIL) +10. **Description routing quality** - routing keywords present (WARN) +11. **Marketing copy detection** - buzzwords in description (WARN) + +## Error Codes + +| Code | Meaning | +|------|---------| +| 0 | All validations passed | +| 1 | Missing SKILL.md | +| 2 | Invalid frontmatter | +| 3 | Name validation failed | +| 4 | Description validation failed | +| 5 | Optional field validation failed | +| 6 | Line limit exceeded | +| 7 | Invalid subdirectory | +| 8 | ASCII art detected (warning) | +| 9 | Persona statement detected | +| 10 | Description routing quality (warning) | +| 11 | Marketing copy detected (warning) | + +## Example Output + +``` +Validating: plugins/majestic-tools/skills/brainstorming + +[PASS] SKILL.md exists +[PASS] Frontmatter present +[PASS] Name 'brainstorming' valid (12 chars) +[PASS] Name matches directory +[PASS] Description valid (156 chars) +[PASS] Line count: 87/500 +[PASS] Subdirectories valid +[PASS] No ASCII art outside code blocks +[PASS] No persona statements +[PASS] Description has routing keywords +[PASS] No marketing copy in description + +Result: ALL CHECKS PASSED +``` + +## Spec Reference + +Based on [agentskills.io/specification](https://agentskills.io/specification): + +- **Progressive disclosure** - Metadata ~100 tokens at startup, full content <5000 tokens when activated +- **Reference files** - Keep one level deep from SKILL.md +- **Token budget** - Main SKILL.md recommended under 500 lines diff --git a/.claude/skills/skill-linter/scripts/validate-skill.sh b/.claude/skills/skill-linter/scripts/validate-skill.sh new file mode 100755 index 00000000..4822eb11 --- /dev/null +++ b/.claude/skills/skill-linter/scripts/validate-skill.sh @@ -0,0 +1,261 @@ +#!/bin/bash +# Skill Linter - Validates skills against agentskills.io specification +# Usage: ./validate-skill.sh path/to/skill-directory + +set -euo pipefail + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[0;33m' +NC='\033[0m' # No Color + +# Counters +PASS=0 +FAIL=0 +WARN=0 + +pass() { + echo -e "${GREEN}[PASS]${NC} $1" + PASS=$((PASS + 1)) +} + +fail() { + echo -e "${RED}[FAIL]${NC} $1" + FAIL=$((FAIL + 1)) +} + +warn() { + echo -e "${YELLOW}[WARN]${NC} $1" + WARN=$((WARN + 1)) +} + +# Validate arguments +if [ $# -lt 1 ]; then + echo "Usage: $0 " + echo "Example: $0 plugins/majestic-tools/skills/brainstorming" + exit 1 +fi + +SKILL_DIR="$1" +SKILL_DIR="${SKILL_DIR%/}" # Remove trailing slash if present + +echo "" +echo "Validating: $SKILL_DIR" +echo "-------------------------------------------" + +# 1. Check directory exists +if [ ! -d "$SKILL_DIR" ]; then + fail "Directory does not exist: $SKILL_DIR" + exit 1 +fi + +# 2. Check SKILL.md exists +SKILL_FILE="$SKILL_DIR/SKILL.md" +if [ ! -f "$SKILL_FILE" ]; then + fail "SKILL.md not found" + exit 1 +fi +pass "SKILL.md exists" + +# 3. Extract frontmatter +CONTENT=$(cat "$SKILL_FILE") + +# Check for frontmatter delimiters +if ! echo "$CONTENT" | head -1 | grep -q '^---$'; then + fail "Missing frontmatter opening delimiter (---)" + exit 2 +fi + +# Find closing delimiter (skip first line) +CLOSING_LINE=$(echo "$CONTENT" | tail -n +2 | grep -n '^---$' | head -1 | cut -d: -f1) +if [ -z "$CLOSING_LINE" ]; then + fail "Missing frontmatter closing delimiter (---)" + exit 2 +fi +pass "Frontmatter delimiters present" + +# Extract frontmatter content (between delimiters) - portable approach +# CLOSING_LINE is position of --- in tail-n+2 output, so frontmatter is lines 2 to CLOSING_LINE in original +FRONTMATTER=$(echo "$CONTENT" | sed -n "2,${CLOSING_LINE}p") + +# 4. Validate name field +NAME=$(echo "$FRONTMATTER" | grep '^name:' | sed 's/^name:[[:space:]]*//' | tr -d '"' | tr -d "'") + +if [ -z "$NAME" ]; then + fail "Missing required field: name" + exit 3 +fi + +# Check name length (1-64) +NAME_LEN=${#NAME} +if [ "$NAME_LEN" -lt 1 ] || [ "$NAME_LEN" -gt 64 ]; then + fail "Name length must be 1-64 chars (got $NAME_LEN)" + exit 3 +fi + +# Check name pattern: lowercase alphanumeric with hyphens +# Must not start/end with hyphen, no consecutive hyphens +if ! echo "$NAME" | grep -qE '^[a-z][a-z0-9]*(-[a-z0-9]+)*$'; then + # More specific error messages + if echo "$NAME" | grep -qE '^-'; then + fail "Name cannot start with hyphen: $NAME" + elif echo "$NAME" | grep -qE '-$'; then + fail "Name cannot end with hyphen: $NAME" + elif echo "$NAME" | grep -qE '--'; then + fail "Name cannot contain consecutive hyphens: $NAME" + elif echo "$NAME" | grep -qE '[A-Z]'; then + fail "Name must be lowercase: $NAME" + elif echo "$NAME" | grep -qE '[_]'; then + fail "Name cannot contain underscores (use hyphens): $NAME" + else + fail "Name must match pattern ^[a-z][a-z0-9]*(-[a-z0-9]+)*$: $NAME" + fi + exit 3 +fi +pass "Name '$NAME' valid ($NAME_LEN chars)" + +# 5. Check name matches directory +DIR_NAME=$(basename "$SKILL_DIR") +if [ "$NAME" != "$DIR_NAME" ]; then + fail "Name '$NAME' does not match directory name '$DIR_NAME'" + exit 3 +fi +pass "Name matches directory" + +# 6. Validate description field +# Handle multi-line descriptions +DESCRIPTION=$(echo "$FRONTMATTER" | awk '/^description:/{flag=1; sub(/^description:[[:space:]]*/, ""); print; next} flag && /^[a-z_-]+:/{exit} flag{print}' | tr '\n' ' ' | sed 's/[[:space:]]*$//') + +if [ -z "$DESCRIPTION" ]; then + fail "Missing required field: description" + exit 4 +fi + +# Check description length (1-1024) +DESC_LEN=${#DESCRIPTION} +if [ "$DESC_LEN" -lt 1 ]; then + fail "Description cannot be empty" + exit 4 +fi +if [ "$DESC_LEN" -gt 1024 ]; then + fail "Description exceeds 1024 chars (got $DESC_LEN)" + exit 4 +fi +pass "Description valid ($DESC_LEN chars)" + +# 7. Validate optional fields if present + +# Check compatibility (if present, max 500 chars) +COMPAT=$(echo "$FRONTMATTER" | grep '^compatibility:' | sed 's/^compatibility:[[:space:]]*//' || true) +if [ -n "$COMPAT" ]; then + COMPAT_LEN=${#COMPAT} + if [ "$COMPAT_LEN" -gt 500 ]; then + fail "Compatibility exceeds 500 chars (got $COMPAT_LEN)" + exit 5 + fi + pass "Compatibility valid ($COMPAT_LEN chars)" +fi + +# Check allowed-tools (if present) +TOOLS=$(echo "$FRONTMATTER" | grep '^allowed-tools:' | sed 's/^allowed-tools:[[:space:]]*//' || true) +if [ -n "$TOOLS" ]; then + # FAIL if commas found (must be space-delimited) + if echo "$TOOLS" | grep -qE ','; then + fail "allowed-tools must be space-delimited, not comma-separated: $TOOLS" + # FAIL if bracket array syntax found + elif echo "$TOOLS" | grep -qE '[\[\]]'; then + fail "allowed-tools must be space-delimited, not array syntax: $TOOLS" + else + pass "Allowed-tools field valid" + fi +fi +# FAIL if YAML multi-line array detected (allowed-tools:\n - item) +if echo "$FRONTMATTER" | grep -q '^allowed-tools:$'; then + NEXT_LINE=$(echo "$FRONTMATTER" | grep -A1 '^allowed-tools:$' | tail -1) + if echo "$NEXT_LINE" | grep -qE '^[[:space:]]*-[[:space:]]'; then + fail "allowed-tools must be space-delimited, not YAML array" + fi +fi + +# 8. Check line count (max 500) +LINE_COUNT=$(wc -l < "$SKILL_FILE" | tr -d ' ') +if [ "$LINE_COUNT" -gt 500 ]; then + fail "Line count exceeds 500 (got $LINE_COUNT)" + exit 6 +fi +pass "Line count: $LINE_COUNT/500" + +# 9. Check subdirectories (only scripts/, references/, assets/ allowed) +ALLOWED_DIRS="scripts references assets" +INVALID_DIRS="" +HAS_RESOURCES=false + +for subdir in "$SKILL_DIR"/*/; do + if [ -d "$subdir" ]; then + subdir_name=$(basename "$subdir") + if [ "$subdir_name" = "resources" ]; then + HAS_RESOURCES=true + elif ! echo "$ALLOWED_DIRS" | grep -qw "$subdir_name"; then + INVALID_DIRS="$INVALID_DIRS $subdir_name" + fi + fi +done + +if [ -n "$INVALID_DIRS" ]; then + warn "Non-standard subdirectories found:$INVALID_DIRS (allowed: scripts, references, assets)" +else + pass "Subdirectories valid" +fi + +if [ "$HAS_RESOURCES" = true ]; then + warn "resources/ is deprecated โ€” use references/, assets/, scripts/ instead" +fi + +# 10. Content analysis - strip fenced code blocks for checks that need prose-only content +CONTENT_NO_FENCES=$(awk '/^```/{skip=!skip; next} !skip{print}' "$SKILL_FILE") + +# 10a. Check for ASCII art outside fenced code blocks (WARN) +if echo "$CONTENT_NO_FENCES" | grep -qE '[โ”€โ”‚โ”Œโ”โ””โ”˜โ”œโ”คโ”ฌโ”ดโ”ผโ•ญโ•ฎโ•ฏโ•ฐโ•โ•‘โ•”โ•—โ•šโ•โ• โ•ฃโ•ฆโ•ฉโ•ฌโ†‘โ†“โ†โ†’โ†”โ‡’โ‡โ‡”โ–ฒโ–ผโ—„โ–บ]{3,}'; then + warn "ASCII art detected outside code blocks - use plain lists or tables" +else + pass "No ASCII art outside code blocks" +fi + +# 10b. Check for persona statements outside fenced code blocks (FAIL) +if echo "$CONTENT_NO_FENCES" | grep -qiE '^[[:space:]]*You are (a|an|the) '; then + fail "Persona statement detected ('You are a/an/the...') - use Audience/Goal framing" +else + pass "No persona statements" +fi + +# 11. Check description routing quality (WARN) +if ! echo "$DESCRIPTION" | grep -qiE "(use when|don't use|not for|triggers on)"; then + warn "Description lacks routing keywords (use when, don't use, not for, triggers on)" +else + pass "Description has routing keywords" +fi + +# 12. Check for marketing copy in description (WARN) +if echo "$DESCRIPTION" | grep -qiE "(comprehensive|powerful|robust|cutting-edge|world-class|state-of-the-art|best-in-class|game-changing)"; then + warn "Description contains marketing buzzwords - use precise, functional language" +else + pass "No marketing copy in description" +fi + +# Summary +echo "-------------------------------------------" +echo -e "Result: ${GREEN}$PASS passed${NC}, ${RED}$FAIL failed${NC}, ${YELLOW}$WARN warnings${NC}" + +if [ "$FAIL" -gt 0 ]; then + echo -e "${RED}VALIDATION FAILED${NC}" + exit 1 +fi + +if [ "$WARN" -gt 0 ]; then + echo -e "${YELLOW}PASSED WITH WARNINGS${NC}" + exit 0 +fi + +echo -e "${GREEN}ALL CHECKS PASSED${NC}" +exit 0 From bd4c1829042776fa400cc63736844f0a4866207f Mon Sep 17 00:00:00 2001 From: r2dedios Date: Fri, 27 Feb 2026 15:51:57 +0100 Subject: [PATCH 06/20] fix(workflow): Removed Claude's internal skills. Only evaluating ours Signed-off-by: r2dedios --- scripts/ci-validate-changed-skills.sh | 2 +- scripts/detect-changed-skills.sh | 3 ++- scripts/run-skill-linter.sh | 4 ++-- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/scripts/ci-validate-changed-skills.sh b/scripts/ci-validate-changed-skills.sh index 2eb07278..d41eaa17 100755 --- a/scripts/ci-validate-changed-skills.sh +++ b/scripts/ci-validate-changed-skills.sh @@ -27,7 +27,7 @@ else DIFF_CMD="git diff --name-only HEAD" fi -CHANGED=$($DIFF_CMD 2>/dev/null | grep -E '^([^/]+/skills/[^/]+/SKILL\.md|\.claude/skills/[^/]+/SKILL\.md)$' || true) +CHANGED=$($DIFF_CMD 2>/dev/null | grep -E '^[^/]+/skills/[^/]+/SKILL\.md$' | grep -v '^\.claude/' || true) if [ -z "$CHANGED" ]; then echo "No skills changed, skipping skill design validation" diff --git a/scripts/detect-changed-skills.sh b/scripts/detect-changed-skills.sh index f1d701fd..7d2f46dc 100755 --- a/scripts/detect-changed-skills.sh +++ b/scripts/detect-changed-skills.sh @@ -27,7 +27,8 @@ else fi # Find changed SKILL.md files and extract their directories -CHANGED_FILES=$($DIFF_CMD 2>/dev/null | grep -E '^([^/]+/skills/[^/]+/SKILL\.md|\.claude/skills/[^/]+/SKILL\.md)$' || true) +# Exclude .claude/ directory (internal tooling, not subject to same validation) +CHANGED_FILES=$($DIFF_CMD 2>/dev/null | grep -E '^[^/]+/skills/[^/]+/SKILL\.md$' | grep -v '^\.claude/' || true) if [ -z "$CHANGED_FILES" ]; then exit 0 diff --git a/scripts/run-skill-linter.sh b/scripts/run-skill-linter.sh index 28b317fa..2e5c1434 100755 --- a/scripts/run-skill-linter.sh +++ b/scripts/run-skill-linter.sh @@ -36,8 +36,8 @@ echo "" # Determine which skills to validate if [ $# -eq 0 ]; then - # No arguments: validate ALL skills - SKILL_PATHS=$(find . -name "SKILL.md" -type f | grep -E "(rh-sre|rh-developer|rh-virt|ocp-admin|rh-support-engineer|\.claude)/skills/" | sort) + # No arguments: validate ALL collection skills (exclude .claude/ internal tooling) + SKILL_PATHS=$(find . -name "SKILL.md" -type f | grep -E "(rh-sre|rh-developer|rh-virt|ocp-admin|rh-support-engineer)/skills/" | sort) VALIDATION_MODE="all" else # Arguments provided: validate only specified skill directories From b24204573ca17e89bd77f4356532f4428b7a99b9 Mon Sep 17 00:00:00 2001 From: r2dedios Date: Fri, 27 Feb 2026 16:06:06 +0100 Subject: [PATCH 07/20] fix(workflow): Linter runs over every skill Signed-off-by: r2dedios --- .github/workflows/README.md | 20 +++++++++++--------- scripts/detect-changed-skills.sh | 16 +++++++++++----- scripts/run-skill-linter.sh | 2 +- 3 files changed, 23 insertions(+), 15 deletions(-) diff --git a/.github/workflows/README.md b/.github/workflows/README.md index 12652f72..7c590aee 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -9,14 +9,15 @@ This directory contains CI/CD workflows for the agentic collections repository. **Purpose**: Validates skills against agentskills.io specification using the skill-linter and generates a comprehensive compliance report. **Triggers**: -- **Pull requests** โ†’ Validates ONLY changed skills (fast feedback) -- **Pushes to main** โ†’ Validates ALL skills (ensures repo health) -- **Manual dispatch** โ†’ Choose between all skills or changed skills +- **Pull requests** โ†’ Validates ALL skills in affected packs (ensures pack consistency) +- **Pushes to main** โ†’ Validates ALL skills across all packs (ensures repo health) +- **Manual dispatch** โ†’ Choose between all skills or pack-wide validation - **Excludes**: Draft pull requests -**Validation Strategy** (Option 2: Changed Skills + Manual Full Scan): -- โšก **PRs**: Fast validation of only changed skills -- ๐Ÿ” **Push to main**: Full validation of all 37 skills +**Validation Strategy** (Pack-Wide Validation): +- โšก **PRs**: Validates ALL skills in affected packs (pack-wide consistency) + - Example: Change `rh-virt/skills/vm-create/SKILL.md` โ†’ validates ALL `rh-virt/skills/*` +- ๐Ÿ” **Push to main**: Full validation of all 37 skills across all packs - ๐ŸŽ›๏ธ **Manual**: Choose validation scope via workflow dispatch **What it validates**: @@ -137,9 +138,10 @@ The workflow will: - `.claude/skills/skill-linter/SKILL.md` - Linter documentation **Performance**: -- **PR validation**: ~5-30 seconds (1-3 changed skills typically) -- **Full validation**: ~60-90 seconds (all 37 skills) -- **Changed-only**: 80-95% faster than full validation +- **PR validation (single pack)**: ~10-40 seconds (e.g., all 9 rh-virt skills) +- **PR validation (multiple packs)**: ~20-60 seconds (varies by pack count) +- **Full validation (all packs)**: ~60-90 seconds (all 37 skills) +- **Pack-wide**: 30-60% faster than full validation (depends on pack size) **Scope**: This workflow validates **ONLY** agentskills.io specification compliance. Repository-specific design principles (model, color, sections, etc.) are validated by other workflows. diff --git a/scripts/detect-changed-skills.sh b/scripts/detect-changed-skills.sh index 7d2f46dc..43be2074 100755 --- a/scripts/detect-changed-skills.sh +++ b/scripts/detect-changed-skills.sh @@ -1,7 +1,10 @@ #!/usr/bin/env bash # Detect changed skills in CI (PRs and pushes to main) -# Outputs list of changed skill directories (one per line) +# Outputs ALL skills in affected packs (not just changed skills) # Exits 0 if no skills changed +# +# Strategy: If ANY skill changes in a pack (e.g., rh-virt), +# validate ALL skills in that pack for consistency set -e @@ -26,7 +29,7 @@ else DIFF_CMD="git diff --name-only HEAD" fi -# Find changed SKILL.md files and extract their directories +# Find changed SKILL.md files # Exclude .claude/ directory (internal tooling, not subject to same validation) CHANGED_FILES=$($DIFF_CMD 2>/dev/null | grep -E '^[^/]+/skills/[^/]+/SKILL\.md$' | grep -v '^\.claude/' || true) @@ -34,7 +37,10 @@ if [ -z "$CHANGED_FILES" ]; then exit 0 fi -# Extract skill directories from SKILL.md paths -echo "$CHANGED_FILES" | while read -r file; do - dirname "$file" +# Extract unique pack names (rh-virt, rh-sre, etc.) +AFFECTED_PACKS=$(echo "$CHANGED_FILES" | cut -d'/' -f1 | sort -u) + +# For each affected pack, find ALL skills in that pack +for pack in $AFFECTED_PACKS; do + find "$pack/skills" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | sort done diff --git a/scripts/run-skill-linter.sh b/scripts/run-skill-linter.sh index 2e5c1434..76ee2115 100755 --- a/scripts/run-skill-linter.sh +++ b/scripts/run-skill-linter.sh @@ -67,7 +67,7 @@ TOTAL_SKILLS=$(echo "$SKILL_PATHS" | wc -l | tr -d ' ') if [ "$VALIDATION_MODE" = "all" ]; then echo -e "${BLUE}Validating ALL skills: ${TOTAL_SKILLS} skill(s)${NC}" else - echo -e "${BLUE}Validating CHANGED skills: ${TOTAL_SKILLS} skill(s)${NC}" + echo -e "${BLUE}Validating skills in affected packs: ${TOTAL_SKILLS} skill(s)${NC}" fi echo "" From c086941d9e470b1ec4bf2d457bd8f043e4eff17d Mon Sep 17 00:00:00 2001 From: r2dedios Date: Mon, 2 Mar 2026 12:21:18 +0100 Subject: [PATCH 08/20] fix(merge-skill-design): Merged SKILL_CHECKLIST.md and SKILL_DESIGN_PATTERNS.md files and updated skill validation scripts Signed-off-by: r2dedios --- .github/workflows/README.md | 4 +- CLAUDE.md | 57 +- SKILL_CHECKLIST.md | 1110 ----------------------------------- SKILL_DESIGN_PRINCIPLES.md | 682 ++++++++++----------- scripts/run-skill-linter.sh | 2 +- scripts/validate-skills.sh | 6 +- 6 files changed, 357 insertions(+), 1504 deletions(-) delete mode 100644 SKILL_CHECKLIST.md diff --git a/.github/workflows/README.md b/.github/workflows/README.md index 7c590aee..8211a3d8 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -347,8 +347,8 @@ dos2unix scripts/validate-skills.sh If the validator reports errors for valid skills: 1. Review the validation logic in `scripts/validate-skills.sh` -2. Check if your skill follows CLAUDE.md design principles exactly -3. Review SKILL_CHECKLIST.md for specific formatting requirements +2. Check if your skill follows SKILL_DESIGN_PRINCIPLES.md requirements exactly +3. Verify agentskills.io specification compliance 4. Open an issue if the validator has a bug ## Maintenance diff --git a/CLAUDE.md b/CLAUDE.md index 6d802beb..5699ac47 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -59,22 +59,24 @@ Each pack follows this structure: ## Skill and Agent Requirements -<<<<<<< Updated upstream -See [SKILL_DESIGN_PRINCIPLES.md](SKILL_DESIGN_PRINCIPLES.md) for the complete design principles, templates, and rationale. Validate compliance with `make validate-skill-design`. -======= -**CRITICAL:** EVERY SKILL and AGENT must be created and validated against [SKILL_CHECKLIST.md](./SKILL_CHECKLIST.md). - -**No exceptions.** All skills must comply with: -- **Tier 1:** agentskills.io specification compliance (MANDATORY) -- **Tier 2:** Repository design principles and standards (MANDATORY) +**CRITICAL:** EVERY SKILL and AGENT must comply with: +- **Tier 1:** agentskills.io specification (AUTOMATED via linter) +- **Tier 2:** Repository design principles (MANUAL review) **Before committing any skill:** -1. Review [SKILL_CHECKLIST.md](./SKILL_CHECKLIST.md) completely -2. Ensure all mandatory requirements are met -3. Validate using: `./scripts/validate-skills.sh path/to/skill/` -See SKILL_CHECKLIST.md for complete requirements, examples, and validation criteria. ->>>>>>> Stashed changes +1. **Run automated validation (Tier 1):** + ```bash + ./scripts/run-skill-linter.sh skills/skill-name/ + ``` + +2. **Manual review (Tier 2):** + - Review [SKILL_DESIGN_PRINCIPLES.md](SKILL_DESIGN_PRINCIPLES.md) for complete requirements + - Use appropriate template (general or collection-specific) + - Verify all design principles are followed + +**Documentation:** +- [SKILL_DESIGN_PRINCIPLES.md](SKILL_DESIGN_PRINCIPLES.md) - Complete design principles, templates, and rationale ### MCP Server Integration @@ -167,27 +169,26 @@ last_updated: YYYY-MM-DD ### Adding a Skill 1. Create `skills//SKILL.md` -<<<<<<< Updated upstream -2. Define YAML frontmatter with root-level fields (name, description, model, color) and optional `metadata` for custom fields (author, priority, etc.). See [SKILL_DESIGN_PRINCIPLES.md](SKILL_DESIGN_PRINCIPLES.md) for the 2026 Agentic Skills structure. -3. Document workflow with MCP tool references -4. Include concrete examples +2. Define YAML frontmatter with mandatory fields: + - `name`, `description` (agentskills.io spec) + - `model` (inherit|sonnet|haiku), `color` (cyan|green|blue|yellow|red) - Repository requirement + - Optional: `metadata` for custom fields (author, priority, version) +3. Follow [SKILL_DESIGN_PRINCIPLES.md](SKILL_DESIGN_PRINCIPLES.md) for: + - Section structure and ordering + - Prerequisites with verification + - Workflow with precise parameters + - Dependencies declaration +4. Include concrete examples and complete error handling 5. Test with `Skill` tool invocation +6. Validate with `./scripts/run-skill-linter.sh skills//` **Collection-Specific Standards:** - **rh-virt**: Follow `rh-virt/SKILL_TEMPLATE.md` for enhanced quality standards including mandatory Common Issues and Example Usage sections -======= -2. Follow requirements in [SKILL_CHECKLIST.md](./SKILL_CHECKLIST.md) -3. Define YAML frontmatter (name, description, model) -4. Document Prerequisites, When to Use, Workflow, and Dependencies sections -5. Include concrete examples and error handling -6. Test with `Skill` tool invocation -7. Validate with `./scripts/validate-skills.sh skills//` ->>>>>>> Stashed changes ### Adding an Agent 1. Create `agents/.md` -2. Follow skill requirements in [SKILL_CHECKLIST.md](./SKILL_CHECKLIST.md) (agents use same structure) +2. Follow skill requirements in [SKILL_DESIGN_PRINCIPLES.md](SKILL_DESIGN_PRINCIPLES.md) (agents use same structure) 3. Define YAML frontmatter (name, description, model, tools) 4. Document workflow that orchestrates multiple skills 5. Provide clear examples of when to use agent vs individual skills @@ -258,4 +259,6 @@ When creating new collections, follow the pattern that best matches your needs: 9. **Production-ready examples** - No toy code, include error handling 10. **Persona-focused design** - Each collection serves specific user roles -**See [SKILL_CHECKLIST.md](./SKILL_CHECKLIST.md) for complete skill requirements, design principles, and validation criteria.** +**Validation:** +- Design principles and requirements: [SKILL_DESIGN_PRINCIPLES.md](./SKILL_DESIGN_PRINCIPLES.md) +- Automated linter (Tier 1): `./scripts/run-skill-linter.sh` diff --git a/SKILL_CHECKLIST.md b/SKILL_CHECKLIST.md deleted file mode 100644 index 188005e5..00000000 --- a/SKILL_CHECKLIST.md +++ /dev/null @@ -1,1110 +0,0 @@ -# Skill Quality Checklist - -**Universal requirements for all skills across all agentic collections.** - -This checklist is organized in two tiers: -- **Tier 1: agentskills.io specification** (Sections 0-9) - MANDATORY for all skills -- **Tier 2: CLAUDE.md enhancements** (Sections 10-36) - Additional requirements - -**References:** -- [agentskills.io specification](https://agentskills.io/specification) - Base format specification -- [CLAUDE.md](./CLAUDE.md) - Repository architecture and patterns - ---- - -# TIER 1: agentskills.io Specification - -## Section 0: Directory Structure - -- [ ] Skill is in a directory (e.g., `skills/skill-name/`) -- [ ] Directory contains `SKILL.md` file (uppercase filename) -- [ ] Directory name matches `name` field in frontmatter exactly - -**Valid structure:** -``` -skills/pdf-processing/ -โ””โ”€โ”€ SKILL.md -``` - -**Optional directories (agentskills.io):** -``` -skills/pdf-processing/ -โ”œโ”€โ”€ SKILL.md -โ”œโ”€โ”€ scripts/ # Executable code (Python, Bash, JavaScript) -โ”œโ”€โ”€ references/ # Additional documentation files -โ””โ”€โ”€ assets/ # Templates, images, data files -``` - ---- - -## Section 1: Name Field (agentskills.io) - -- [ ] `name` field present -- [ ] Name is 1-64 characters -- [ ] Name uses only lowercase letters, numbers, and hyphens (`a-z0-9-`) -- [ ] Name does not start or end with hyphen -- [ ] Name does not have consecutive hyphens (`--`) -- [ ] Name matches parent directory name exactly - -**โœ… Valid examples:** -```yaml -name: pdf-processing -name: data-analysis -name: vm-create -``` - -**โŒ Invalid examples:** -```yaml -name: PDF-Processing # Uppercase not allowed -name: -pdf # Cannot start with hyphen -name: pdf--processing # Consecutive hyphens not allowed -name: pdf_processing # Underscores not allowed -``` - ---- - -## Section 2: Description Field (agentskills.io) - -- [ ] `description` field present -- [ ] Description is 1-1024 characters -- [ ] Description describes what the skill does and when to use it -- [ ] Description includes specific keywords for agent discovery - -**โœ… Good example:** -```yaml -description: | - Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. - Use when working with PDF documents or when the user mentions PDFs, forms, or - document extraction. -``` - -**โŒ Poor example:** -```yaml -description: Helps with PDFs. # Too vague, no when-to-use guidance -``` - ---- - -## Section 3: License Field (agentskills.io) - -- [ ] `license` field is optional -- [ ] If present, contains license name or reference to bundled license file -- [ ] If present, is kept short (recommended) - -**Examples:** -```yaml -license: Apache-2.0 -license: MIT -license: Proprietary. LICENSE.txt has complete terms -``` - ---- - -## Section 4: Compatibility Field (agentskills.io) - -- [ ] `compatibility` field is optional -- [ ] If present, is 1-500 characters -- [ ] If present, indicates environment requirements -- [ ] Only included if skill has specific environment requirements - -**Examples:** -```yaml -compatibility: Designed for Claude Code (or similar products) -compatibility: Requires git, docker, jq, and access to the internet -compatibility: Requires Python 3.8+, pip, and network access to PyPI -``` - -**Note:** Most skills do not need this field. - ---- - -## Section 5: Metadata Field (agentskills.io) - -- [ ] `metadata` field is optional -- [ ] If present, is a map from string keys to string values -- [ ] If present, keys are reasonably unique to avoid conflicts - -**Example:** -```yaml -metadata: - author: example-org - version: "1.0" - category: data-processing -``` - ---- - -## Section 6: Allowed-Tools Field (agentskills.io) - -- [ ] `allowed-tools` field is optional (experimental) -- [ ] If present, is a space-delimited list of pre-approved tools - -**Example:** -```yaml -allowed-tools: Bash(git:*) Bash(jq:*) Read Write -``` - -**Note:** Support for this field may vary between agent implementations. - ---- - -## Section 7: YAML Frontmatter Format (agentskills.io) - -- [ ] SKILL.md contains YAML frontmatter -- [ ] Frontmatter is delimited by `---` markers (opening and closing) -- [ ] Frontmatter appears at start of file -- [ ] Frontmatter contains required fields: `name` and `description` - -**Correct format:** -```yaml ---- -name: pdf-processing -description: | - Extract text and tables from PDF files. ---- - -# PDF Processing Skill - -[Rest of skill content] -``` - -**โŒ Missing delimiters:** -```yaml -name: pdf-processing -description: PDF processing - -# PDF Processing Skill -``` - ---- - -## Section 8: Body Content (agentskills.io) - -- [ ] Markdown body follows frontmatter -- [ ] Body has no format restrictions (write what helps agents) -- [ ] Body includes step-by-step instructions (recommended) -- [ ] Body includes examples of inputs and outputs (recommended) -- [ ] Body includes common edge cases (recommended) - -**Recommended body structure:** -```markdown ---- -name: skill-name -description: | - Skill description here ---- - -# Skill Name - -## Overview -Brief description of what this skill does. - -## Step-by-step Instructions -1. First, do this... -2. Then, do that... - -## Examples -**Input:** Example input -**Output:** Example output - -## Common Edge Cases -- Edge case 1: How to handle -- Edge case 2: How to handle -``` - ---- - -## Section 9: Progressive Disclosure (agentskills.io) - -- [ ] Main `SKILL.md` is under 500 lines (recommended) -- [ ] Main `SKILL.md` is under 5000 tokens (recommended) -- [ ] Detailed reference material moved to separate files -- [ ] File references use relative paths from skill root -- [ ] File references kept one level deep (avoid nested chains) - -**Progressive loading model:** -- **Metadata (~100 tokens):** `name` and `description` loaded at startup for all skills -- **Instructions (<5000 tokens):** Full `SKILL.md` loaded when skill is activated -- **Resources (as needed):** Files in `scripts/`, `references/`, `assets/` loaded only when required - -**โœ… Good file references:** -```markdown -See [the reference guide](references/REFERENCE.md) for details. -Run the extraction script: scripts/extract.py -Use template: assets/template.json -``` - -**โŒ Deeply nested references:** -```markdown -See references/advanced/subsection/details.md # Too deep -``` - ---- - -# TIER 2: CLAUDE.md Enhancements - -## Section 10: Description Field - CLAUDE.md Enhancements - -- [ ] Description is under 500 tokens (CLAUDE.md optimization) -- [ ] Description has 3-5 "Use when" examples -- [ ] Description includes "NOT for" with alternative skill reference - -**โœ… Complete example:** -```yaml -description: | - Analyze CVE impact across the fleet without immediate remediation. - - Use when: - - "What are the most critical vulnerabilities?" - - "Show CVEs affecting my systems" - - "List high-severity CVEs" - - NOT for remediation actions (use remediator agent instead). -``` - -**โŒ Missing anti-patterns:** -```yaml -description: | - Analyze CVE impact across the fleet. - - Use when: - - "What are the most critical vulnerabilities?" - # Missing "NOT for" section -``` - ---- - -## Section 11: YAML Frontmatter - Mandatory Fields (model and color) - -- [ ] `model` field present (MANDATORY) -- [ ] `model` value is one of: `inherit`, `sonnet`, or `haiku` -- [ ] `color` field present (MANDATORY) -- [ ] `color` value is one of: `cyan`, `green`, `blue`, `yellow`, or `red` - -**Model field (MANDATORY):** -```yaml -model: inherit # Use parent context's model (recommended default) -model: sonnet # Force Sonnet for complex reasoning -model: haiku # Force Haiku for simple, fast operations -``` - -**Color field (MANDATORY) - Standard values only:** -```yaml -color: cyan # Read-only operations (list, view, get, inventory) -color: green # Additive operations (create, clone, snapshot-create) -color: blue # Reversible changes (start, stop, restart, update) -color: yellow # Destructive but recoverable (snapshot-delete, scale-down) -color: red # Irreversible/critical (delete, restore, factory-reset) -``` - -**โŒ Invalid color values:** -```yaml -color: purple # Not a standard value -color: orange # Not a standard value -color: custom # Not a standard value -``` - ---- - -## Section 12: SKILL.md Header - Standard Format (MANDATORY) - -- [ ] First heading is level 1 (`#`) -- [ ] Heading follows standard format: `# / Skill` or `# [Skill Name]` -- [ ] Heading matches the skill name from frontmatter -- [ ] Overview paragraph appears immediately after heading -- [ ] Overview is 1-2 sentences describing what the skill does - -**โœ… Standard heading formats:** -```markdown -# /vm-create Skill # Preferred format (slash prefix) -# VM Create Skill # Alternative format (title case) -# PDF Processing Skill # Alternative format (title case) -``` - -**โŒ Invalid heading formats:** -```markdown -## vm-create # Wrong level (##) -# vm-create # Missing "Skill" suffix -# Vm-create Skill # Wrong capitalization -# Create VM # Doesn't match skill name -``` - -**Complete header example:** -```markdown ---- -name: vm-create -description: | - Create virtual machines... -model: inherit -color: green ---- - -# /vm-create Skill - -Create virtual machines in OpenShift Virtualization using automated instance type resolution. - -## Prerequisites -[Content] -``` - ---- - -## Section 13: Mandatory Sections - Presence - -- [ ] `## Prerequisites` section present -- [ ] `## When to Use This Skill` section present -- [ ] `## Workflow` section present -- [ ] `## Dependencies` section present - -## Workflow -[Content] - -## Dependencies -[Content] -``` - ---- - -## Section 14: Mandatory Sections - Ordering - -- [ ] YAML frontmatter appears first -- [ ] `# [Skill Name]` heading appears after frontmatter -- [ ] Overview paragraph appears after heading -- [ ] `## Critical: Human-in-the-Loop Requirements` appears before `## Prerequisites` (if present) -- [ ] `## Prerequisites` appears before `## When to Use This Skill` -- [ ] `## When to Use This Skill` appears before `## Workflow` -- [ ] `## Workflow` appears before `## Dependencies` - -**Correct order:** -```markdown ---- -[frontmatter] ---- - -# Skill Name - -Overview paragraph. - -## Critical: Human-in-the-Loop Requirements -[If applicable] - -## Prerequisites -[Content] - -## When to Use This Skill -[Content] - -## Workflow -[Content] - -## Dependencies -[Content] -``` - ---- - -## Section 15: Prerequisites Section - Content - -- [ ] Lists **Required MCP Servers** with setup links -- [ ] Lists **Required MCP Tools** with descriptions -- [ ] Lists **Environment Variables** (if any) -- [ ] Contains **Verification Steps** subsection -- [ ] Contains **Human Notification Protocol** subsection -- [ ] Contains security warning about credential values - -**Complete example:** -```markdown -## Prerequisites - -**Required MCP Servers:** `openshift-virtualization` ([setup guide](https://example.com/setup)) - -**Required MCP Tools:** -- `vm_create` (from openshift-virtualization) - Creates virtual machines -- `resources_get` (from openshift-virtualization) - Retrieves VM status - -**Environment Variables:** -- `KUBECONFIG` - Path to Kubernetes configuration file - -**Verification Steps:** -1. Check `openshift-virtualization` is configured in `.mcp.json` -2. Verify `KUBECONFIG` environment variable is set (without exposing value) -3. If missing โ†’ Proceed to Human Notification Protocol - -**Human Notification Protocol:** -When prerequisites fail: -1. Stop execution immediately -2. Report clear error: "โŒ Cannot execute vm-create: MCP server not available" -3. Provide setup instructions with links -4. Request user decision: setup/skip/abort -5. Wait for explicit user input - -**Security:** Never display actual KUBECONFIG path or credential values. -``` - ---- - -## Section 16: Prerequisites Section - Verification Steps - -- [ ] Verification includes check for MCP server in `.mcp.json` -- [ ] Verification includes check for environment variables -- [ ] Verification does not expose credential values -- [ ] Defines behavior when prerequisites fail - -**โœ… Correct verification:** -```bash -# Check if environment variable is set -test -n "$LIGHTSPEED_CLIENT_SECRET" - -# Report boolean status only -if [ -n "$LIGHTSPEED_CLIENT_SECRET" ]; then - echo "โœ“ LIGHTSPEED_CLIENT_SECRET is set" -else - echo "โœ— LIGHTSPEED_CLIENT_SECRET is not set" -fi -``` - -**โŒ SECURITY VIOLATION - Exposes credentials:** -```bash -echo $LIGHTSPEED_CLIENT_SECRET # Shows actual secret value -echo "SECRET=$LIGHTSPEED_CLIENT_SECRET" # Exposes value in output -``` - ---- - -## Section 17: Prerequisites Section - Human Notification Protocol - -- [ ] Specifies to stop execution immediately on failure -- [ ] Provides clear error message with setup instructions -- [ ] Requests user decision (setup/skip/abort) -- [ ] Waits for explicit user input - -**Example protocol:** -```markdown -**Human Notification Protocol:** - -When prerequisites fail, the skill MUST: - -1. **Stop Execution Immediately** - Do not attempt tool calls - -2. **Report Clear Error:** - ``` - โŒ Cannot execute vm-create: MCP server `openshift-virtualization` is not available - - ๐Ÿ“‹ Setup Instructions: - 1. Add openshift-virtualization to `.mcp.json` - 2. Set environment variable: export KUBECONFIG="/path/to/config" - 3. Restart Claude Code to reload MCP servers - - ๐Ÿ”— Documentation: https://example.com/setup - ``` - -3. **Request User Decision:** - ``` - โ“ How would you like to proceed? - - Options: - - "setup" - I'll help you configure the MCP server now - - "skip" - Skip this skill and use alternative approach - - "abort" - Stop the workflow entirely - ``` - -4. **Wait for Explicit User Input** - Do not proceed automatically -``` - ---- - -## Section 18: When to Use This Skill Section - -- [ ] Contains "Use when" with 3+ specific scenarios -- [ ] Contains "Do NOT use when" with alternatives -- [ ] Every anti-pattern references alternative skill by name - -**โœ… Complete example:** -```markdown -## When to Use This Skill - -Use this skill when: -- "Create a new VM in production namespace" -- "Deploy a Fedora virtual machine" -- "Set up a VM with 4 CPUs and 8GB RAM" -- User mentions "new VM", "create VM", "provision VM" - -Do NOT use when: -- Managing existing VMs โ†’ Use `vm-lifecycle-manager` skill instead -- Deleting VMs โ†’ Use `vm-delete` skill instead -- Cloning VMs โ†’ Use `vm-clone` skill instead -- Viewing VM status โ†’ Use `vm-inventory` skill instead -``` - -**โŒ Vague anti-patterns:** -```markdown -Do NOT use when: -- User wants other operations # Too vague, no alternative specified -``` - ---- - -## Section 19: Workflow Section - Structure - -- [ ] Each step has heading: `### Step N: [Action Name]` -- [ ] Each step specifies **MCP Tool** name with source server -- [ ] Each step specifies **Parameters** with exact format -- [ ] Each step includes **Expected Output** description -- [ ] Each step includes **Error Handling** with 2+ conditions - -**Complete workflow step example:** -```markdown -### Step 1: Create Virtual Machine - -**MCP Tool:** `vm_create` or `virtualization__vm_create` (from openshift-virtualization) - -**Parameters:** -- `namespace`: "production" (namespace where VM will be created) -- `name`: "fedora-web-01" (name of the virtual machine) -- `workload`: "fedora" (OS image: fedora, ubuntu, centos, rhel) -- `size`: "medium" (VM size: small=2CPU/4GB, medium=4CPU/8GB, large=8CPU/16GB) -- `autostart`: true (automatically start VM after creation) - -**Expected Output:** -```json -{ - "status": "success", - "vm_name": "fedora-web-01", - "namespace": "production", - "phase": "Provisioning" -} -``` - -**Error Handling:** -- If namespace not found: Report error and list available namespaces using `namespaces_list` tool -- If name already exists: Suggest alternative names with incremental suffix (fedora-web-02, etc.) -- If quota exceeded: Display current quota usage and recommend cleanup or quota increase -- If invalid workload: List supported OS images (fedora, ubuntu, centos, rhel, opensuse) -``` - ---- - -## Section 20: Workflow Section - Tool Parameters - -- [ ] Parameters use exact names (not placeholders like ``) -- [ ] Parameters include example values -- [ ] Parameters show format specification and constraints -- [ ] Tool names shown in both formats: `tool_name` and `category__tool_name` - -**โœ… Precise parameters:** -```markdown -**Parameters:** -- `impact`: "7,6" (comma-separated impact levels: 7=Important, 6=Moderate, 5=Low) -- `sort`: "-cvss_score" (use - prefix for descending; valid: "cvss_score", "public_date") -- `limit`: 20 (integer, maximum CVEs to return, range: 1-100) -``` - -**โŒ Vague parameters:** -```markdown -**Parameters:** -- Use the CVE ID # No parameter name, no format -- severity: Critical # Wrong parameter name or format -``` - ---- - -## Section 21: Document Consultation - Design Principle #1 - -**When skill consults documentation:** - -- [ ] Uses Read tool to load file into context -- [ ] Declares consultation to user with file path -- [ ] Document consultation happens BEFORE tool invocation -- [ ] Does not claim consultation without actually reading - -**โœ… CORRECT - Actual consultation (reads first, then declares):** -```markdown -### Step 1: Analyze CVE Impact - -**Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [cvss-scoring.md](../../docs/references/cvss-scoring.md) using the Read tool to understand CVSS severity mapping -2. **Output to user**: "I consulted [cvss-scoring.md](../../docs/references/cvss-scoring.md) to understand CVSS severity mapping." - -**MCP Tool:** `vulnerability__get_cves` (from lightspeed-mcp) - -**Parameters:** -- `impact`: "7,6" (Important and Moderate severity levels) -``` - -**โŒ WRONG - Transparency theater (claims without reading):** -```markdown -### Step 1: Analyze CVE Impact - -I consulted cvss-scoring.md to understand severity levels. - -**MCP Tool:** `vulnerability__get_cves` (from lightspeed-mcp) -``` - -**Rationale:** -- **Substance:** Ensures AI actually enriches its context with domain knowledge -- **Transparency:** Users understand the AI's knowledge sources -- **Auditability:** Read tool calls can be tracked in execution logs - ---- - -## Section 22: Dependencies Section - Structure - -- [ ] Contains **Required MCP Servers** subsection -- [ ] Contains **Required MCP Tools** subsection -- [ ] Contains **Related Skills** subsection -- [ ] Contains **Reference Documentation** subsection - -**Complete dependencies example:** -```markdown -## Dependencies - -### Required MCP Servers -- `openshift-virtualization` - OpenShift Virtualization MCP integration - - Setup: https://example.com/mcp-setup - -### Required MCP Tools -- `vm_create` (from openshift-virtualization) - Creates virtual machines - - Source: https://github.com/example/openshift-virt-mcp -- `resources_get` (from openshift-virtualization) - Retrieves VM status -- `namespaces_list` (from openshift-virtualization) - Lists available namespaces - -### Related Skills -- `vm-lifecycle-manager` - Manages VM power state (start, stop, restart) -- `vm-delete` - Removes VMs and associated resources -- `vm-inventory` - Lists and views VM status across namespaces - -### Reference Documentation - -**Internal Documentation:** -- [VM Creation Guide](../../docs/vm-creation.md) - Detailed VM creation patterns -- [Instance Types](../../docs/instance-types.md) - Available VM sizes and configurations - -**Official Red Hat Documentation:** -- [Creating VMs - OpenShift 4.20](https://docs.redhat.com/en/openshift-virtualization/4.20/creating-vms) -- [VM Templates - OpenShift 4.20](https://docs.redhat.com/en/openshift-virtualization/4.20/templates) -``` - ---- - -## Section 23: Dependencies Section - MCP Tools - -- [ ] Each tool lists name and source server -- [ ] Each tool has brief description of what it does -- [ ] Each tool has link to source (GitHub, docs) - -**Example:** -```markdown -### Required MCP Tools -- `vm_create` (from openshift-virtualization) - Creates virtual machines with specified configuration - - Source: https://github.com/example/openshift-virt-mcp - - Parameters: namespace, name, workload, size, networks -- `resources_get` (from openshift-virtualization) - Retrieves Kubernetes resource details - - Source: https://github.com/example/openshift-virt-mcp - - Parameters: apiVersion, kind, name, namespace -``` - ---- - -## Section 24: Human-in-the-Loop - Design Principle #5 - -**Required for skills that:** -- Create, delete, modify, or restore resources -- Execute playbooks or commands -- Affect multiple systems -- Perform irreversible actions - -**Content requirements:** -- [ ] Section `## Critical: Human-in-the-Loop Requirements` present -- [ ] Lists when confirmation is required (numbered steps) -- [ ] Specifies what user must confirm -- [ ] Includes "Never assume approval" statement -- [ ] Specifies confirmation format (yes/no, typed verification) - -**Complete example:** -```markdown -## Critical: Human-in-the-Loop Requirements - -This skill requires explicit user confirmation at the following steps: - -1. **Before VM Creation** - - Display VM configuration preview: - ``` - VM Configuration: - - Name: fedora-web-01 - - Namespace: production - - OS: Fedora - - Size: medium (4 CPU, 8GB RAM) - - Auto-start: true - ``` - - Ask: "Should I create this VM with the configuration above?" - - Wait for user confirmation (yes/no) - -2. **After Configuration Validation** - - If quota warnings exist, display quota usage - - Ask: "Quota is at 80% capacity. Continue with VM creation?" - - Wait for explicit user approval - -3. **On Error Conditions** - - Report error details and suggested resolution - - Ask: "How would you like to proceed? (retry/modify/abort)" - - Wait for explicit user decision - -**Never assume approval** - always wait for explicit user confirmation before executing actions. -``` - -**When NOT required:** -- Read-only skills (list, view, get, inventory) - ---- - -## Section 25: Human-in-the-Loop - Critical Operations - -**For destructive operations (delete, restore):** -- [ ] Requires typed confirmation (user must type exact name) -- [ ] Displays preview before action -- [ ] Waits for explicit "yes" or "proceed" - -**Example for vm-delete:** -```markdown -## Critical: Human-in-the-Loop Requirements - -**CRITICAL SAFETY REQUIREMENT - Typed Confirmation:** - -1. **Before VM Deletion** - - Display VM details to be deleted: - ``` - VM to be deleted: - - Name: database-vm-01 - - Namespace: production - - Status: Running - - Storage: 100GB PVC will also be deleted - - This action is IRREVERSIBLE - ``` - -2. **Require Typed Confirmation** - - Ask: "To confirm deletion, type the exact VM name: database-vm-01" - - Verify user types exact name character-for-character - - If mismatch: "Name does not match. Deletion cancelled." - - If match: Proceed with deletion - -3. **Final Confirmation** - - Ask: "Type 'DELETE' to proceed with irreversible deletion." - - Wait for user to type: DELETE - - Only proceed if exact match - -**Never proceed without explicit typed confirmation of the resource name.** -``` - ---- - -## Section 26: Security - Credential Protection - Design Principle #7 - -- [ ] No environment variable VALUES in output -- [ ] Only reports if variable is set/unset (boolean status) -- [ ] Uses placeholders for sensitive paths -- [ ] No API keys, tokens, secrets, passwords in examples -- [ ] Does not use `echo $VAR` pattern for credentials - -**โœ… CORRECT - Secure verification:** -```bash -# Check if set (exit code only, no output) -test -n "$LIGHTSPEED_CLIENT_SECRET" - -# Report boolean status -if [ -n "$LIGHTSPEED_CLIENT_SECRET" ]; then - echo "โœ“ LIGHTSPEED_CLIENT_SECRET is set" -else - echo "โœ— LIGHTSPEED_CLIENT_SECRET is not set" -fi - -# Check multiple variables -test -n "$KUBECONFIG" && test -n "$LIGHTSPEED_CLIENT_ID" -``` - -**โœ… User-visible messages:** -``` -โœ“ Environment variable LIGHTSPEED_CLIENT_ID is set -โœ“ Environment variable LIGHTSPEED_CLIENT_SECRET is set -โœ“ Environment variable KUBECONFIG is set -``` - -**โŒ SECURITY VIOLATION - Exposes credentials:** -```bash -echo $LIGHTSPEED_CLIENT_SECRET # Shows actual secret -echo "SECRET=$LIGHTSPEED_CLIENT_SECRET" # Exposes in output -export LIGHTSPEED_CLIENT_SECRET=sk-abc123... # Hardcoded credential -echo "KUBECONFIG=/home/user/.kube/config" # Exposes actual path -``` - -**โŒ NEVER show:** -``` -LIGHTSPEED_CLIENT_SECRET=sk-abc123-xyz789-... -KUBECONFIG=/home/alice/.kube/my-cluster-config -API_KEY=ghp_abc123xyz789... -``` - -**Rationale:** -Prevents accidental credential exposure in: -- Conversation history -- Log files -- Screenshots shared with support -- Copied output pasted in public forums - ---- - -## Section 27: Content Quality - -- [ ] No hardcoded values (uses placeholders) -- [ ] No broken links (all references resolve) -- [ ] No spelling errors -- [ ] Technical terms explained on first use -- [ ] Clear, concise language - -**โœ… Good placeholders:** -```markdown -- namespace: "" -- vm-name: "" -- kubeconfig: "" -``` - -**โŒ Hardcoded values:** -```markdown -- namespace: "production" # Don't hardcode specific namespaces -- vm-name: "my-vm" # Use placeholder instead -- kubeconfig: "/home/user/.kube/config" # Never hardcode paths -``` - ---- - -## Section 28: Naming Conventions - -- [ ] Skill name uses kebab-case -- [ ] Folder name matches skill name exactly -- [ ] File is named `SKILL.md` (uppercase) -- [ ] No spaces in folder or file names - -**โœ… Correct:** -``` -skills/vm-create/SKILL.md -skills/pdf-processing/SKILL.md -skills/data-analysis/SKILL.md -``` - -**โŒ Incorrect:** -``` -skills/VM-Create/skill.md # Wrong case -skills/vm_create/SKILL.md # Underscores not allowed -skills/vm create/SKILL.md # Spaces not allowed -skills/vmCreate/SKILL.md # camelCase not allowed -``` - ---- - -## Section 29: Design Principle #1 - Document Consultation Transparency - -- [ ] Actually reads files before claiming consultation -- [ ] Uses Read tool to load files into context -- [ ] Declares consultation transparently to user - -**Implementation pattern:** -```markdown -**Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [filename.md](path/to/filename.md) using the Read tool to understand [topic] -2. **Output to user**: "I consulted [filename.md](path/to/filename.md) to understand [topic]." -``` - -**Execution examples:** -- Read `docs/references/cvss-scoring.md` โ†’ "I consulted cvss-scoring.md to verify CVSS severity mapping." -- Read `skills/playbook-generator/SKILL.md` โ†’ "I consulted playbook-generator skill to understand Ansible generation parameters." - ---- - -## Section 30: Design Principle #2 - Precise Parameter Specification - -- [ ] Tool parameters are exact (not vague or generic) -- [ ] Parameters include format specification and examples -- [ ] Parameters enable first-attempt success without trial-and-error - -**โœ… Precise specification:** -```markdown -**Parameters:** -- `impact`: "7,6" (string with comma-separated impact levels: 7=Important, 6=Moderate, 5=Low) -- `sort`: "-cvss_score" (use - prefix for descending; valid fields: "cvss_score", "public_date") -- `limit`: 20 (integer, maximum CVEs to return, range: 1-100) -- `published_after`: "2024-01-01" (ISO date format: YYYY-MM-DD) -``` - -**โŒ Vague specification:** -```markdown -**Parameters:** -- Use the CVE ID -- Set severity to high -- Sort by score -``` - -**Rationale:** -- **Precision:** Exact names and formats prevent tool errors -- **Examples:** Value examples show correct usage -- **Determinism:** First-attempt success reduces wasted cycles - ---- - -## Section 31: Design Principle #3 - Concise Description - -- [ ] YAML frontmatter description is under 500 tokens -- [ ] Description focuses on "when to use" scenarios -- [ ] Implementation details deferred to skill body (not in frontmatter) - -**โœ… Concise frontmatter:** -```yaml -description: | - Analyze CVE impact across the fleet without immediate remediation. - - Use when: - - "What are the most critical vulnerabilities?" - - "Show CVEs affecting my systems" - - "List high-severity CVEs" - - NOT for remediation actions (use remediator agent instead). -``` - -**โŒ Too detailed in frontmatter:** -```yaml -description: | - This skill uses the lightspeed-mcp server to query CVEs from Red Hat Insights. - It first reads the cvss-scoring.md documentation, then calls get_cves with - impact levels 7 and 6, sorts by CVSS score descending, and formats the output - as a table. The skill also checks system inventory... - # [500+ tokens of implementation details] -``` - -**Rationale:** Minimizes token usage when all skill descriptions are loaded at agent initialization. - ---- - -## Section 32: Design Principle #4 - Dependencies Declared - -- [ ] All skill dependencies listed -- [ ] All MCP tools listed with source servers -- [ ] All MCP servers listed with setup links -- [ ] All reference documentation listed - -**Complete dependencies section:** -```markdown -## Dependencies - -### Required MCP Servers -- `lightspeed-mcp` - Red Hat Lightspeed platform -- `ansible-mcp` - Ansible automation execution - -### Required MCP Tools -- `vulnerability__get_cves` (from lightspeed-mcp) - List CVEs with filters -- `vulnerability__get_cve` (from lightspeed-mcp) - Get specific CVE details -- `playbook__execute` (from ansible-mcp) - Execute Ansible playbooks - -### Related Skills -- `cve-validation` - Validate CVE IDs before querying -- `fleet-inventory` - Identify systems affected by CVEs -- `playbook-generator` - Generate remediation playbooks - -### Reference Documentation -- [cvss-scoring.md](docs/references/cvss-scoring.md) - CVSS severity mappings -- [insights-api.md](docs/insights/insights-api.md) - API usage patterns -``` - ---- - -## Section 33: Design Principle #5 - Human-in-the-Loop - -- [ ] Confirmations required for critical operations -- [ ] User approval required before destructive actions -- [ ] Preview shown before modifications - -See Section 23 for complete implementation requirements. - ---- - -## Section 34: Design Principle #6 - Mandatory Sections - -- [ ] All required sections are present -- [ ] Sections appear in correct order -- [ ] Section headings use exact format - -**Required sections in order:** -1. YAML frontmatter -2. `# [Skill Name]` heading -3. Overview paragraph -4. `## Critical: Human-in-the-Loop Requirements` (if applicable) -5. `## Prerequisites` -6. `## When to Use This Skill` -7. `## Workflow` -8. `## Dependencies` - ---- - -## Section 35: Design Principle #7 - Prerequisites Verified - -- [ ] MCP server availability is checked before execution -- [ ] Environment variables are verified without exposing values -- [ ] Human notification protocol defined for prerequisite failures - -See Sections 14-16 for complete verification requirements. - ---- - -## Section 36: Single Responsibility - -- [ ] Skill does ONE thing well -- [ ] Skill has clear, focused purpose -- [ ] Skill does not overlap with other skills - -**โœ… Single responsibility:** -- `vm-create` - Only creates VMs -- `vm-delete` - Only deletes VMs -- `vm-inventory` - Only lists/views VMs - -**โŒ Multiple responsibilities:** -- `vm-manager` - Creates, deletes, lists, starts, stops VMs (too broad, split into separate skills) - ---- - -## Section 37: Skills Over Tools - Design Principle #3 - -- [ ] Never calls MCP tools directly in skill instructions -- [ ] Always invokes other skills instead of raw tools -- [ ] Delegates to specialized skills appropriately - -**โœ… Correct - Delegates to skills:** -```markdown -If user wants to view VM status after creation, invoke the `vm-inventory` skill. -If user wants to start the VM, invoke the `vm-lifecycle-manager` skill with action: start. -``` - -**โŒ Wrong - Calls tools directly:** -```markdown -Use the resources_list tool to view VMs. -Call vm_lifecycle with action: start to start the VM. -``` - -**Key Pattern:** Agents orchestrate skills; skills encapsulate tools. Never call MCP tools directly - always go through skills. - ---- - -## Validation Levels - -**Level 1 - agentskills.io Compliance (MANDATORY):** -- Sections 0-9 - -**Level 2 - Repository Standards (Required to Commit):** -- Sections 0-9 (agentskills.io) -- Sections 10-14, 18-20, 27-28 (Repository core requirements) - -**Level 3 - Production Ready (Recommended):** -- All sections 0-37 - ---- - -**Last Updated**: 2026-02-26 -**Version**: 3.1 -**Applies To**: All agentic collections -**Specification Compliance**: agentskills.io v1.0 diff --git a/SKILL_DESIGN_PRINCIPLES.md b/SKILL_DESIGN_PRINCIPLES.md index eeabd683..4adc11f7 100644 --- a/SKILL_DESIGN_PRINCIPLES.md +++ b/SKILL_DESIGN_PRINCIPLES.md @@ -1,525 +1,485 @@ # Design Principles for Skills and Agents -This document defines the design principles for creating skills and agents in agentic collections. It is referenced from [CLAUDE.md](CLAUDE.md). Validate compliance with `make validate-skill-design` (see [README.md](README.md#skill-design-validation)). +Repository-specific design principles for creating skills and agents in agentic collections. Referenced from [CLAUDE.md](CLAUDE.md). -## 1. Document Consultation Transparency +**Scope**: Tier 2 requirements - repository enhancements beyond base agentskills.io specification (Tier 1 validated by linter). -When a skill or agent consults documentation (from `docs/` or skill/agent files), it **MUST**: -1. **Actually read the file** using the Read tool to load it into context -2. **Then declare** the consultation to the user +--- -**CRITICAL**: Document consultation means READING the file, not just claiming to have read it. +## Core Design Principles -**Required Implementation**: -```markdown -**Document Consultation** (REQUIRED): -1. **Action**: Read [filename.md](path/to/filename.md) using the Read tool to understand [specific topic] -2. **Output to user**: "I consulted [filename.md](path/to/filename.md) to understand [specific topic]." -``` +### 1. Document Consultation Transparency -**โŒ WRONG - Transparency Theater** (just claims, no actual reading): +When consulting documentation, **MUST** actually read the file using Read tool, then declare consultation. + +**Required Pattern:** ```markdown -**Document Consultation** (output to user): -``` -I consulted [filename.md](path/to/filename.md) to understand [topic]. -``` +**Document Consultation** (REQUIRED - Execute FIRST): +1. **Action**: Read [file.md](path/to/file.md) using Read tool to understand [topic] +2. **Output to user**: "I consulted [file.md](path/to/file.md) to understand [topic]." ``` -**โœ… CORRECT - Actual Consultation** (reads first, then declares): +**โŒ WRONG - Transparency Theater:** ```markdown -**Document Consultation** (REQUIRED): -1. **Action**: Read [cvss-scoring.md](../../docs/references/cvss-scoring.md) using the Read tool to understand CVSS severity mapping -2. **Output to user**: "I consulted [cvss-scoring.md](../../docs/references/cvss-scoring.md) to understand CVSS severity mapping." +I consulted file.md to understand [topic]. # Claim without actually reading ``` -**Examples in execution**: -- Read `docs/references/cvss-scoring.md` โ†’ "I consulted [cvss-scoring.md](rh-sre/docs/references/cvss-scoring.md) to verify the CVSS severity mapping." -- Read `skills/playbook-generator/SKILL.md` โ†’ "I consulted [playbook-generator/SKILL.md](rh-sre/skills/playbook-generator/SKILL.md) to understand playbook generation parameters." +**Rationale**: Ensures AI enriches context with domain knowledge; users understand knowledge sources; auditable via Read tool logs. -**Rationale**: -- **Substance**: Ensures AI actually enriches its context with domain knowledge -- **Transparency**: Users understand the AI's knowledge sources -- **Auditability**: The execution-summary skill can track actual Read tool calls +--- -## 2. Precise Parameter Specification +### 2. Precise Parameter Specification -Skills MUST specify **exact parameters** when instructing agents to use tools, ensuring first-attempt success. +Specify **exact parameters** with formats and examples for first-attempt success. -**CRITICAL**: Document consultation must be specified BEFORE tool parameters to ensure it happens first. +**Required Workflow Step Format:** +```markdown +### Step N: [Action Name] -**โŒ Bad Example - Vague parameters**: -``` -Use get_cve tool with the CVE ID -``` +**Document Consultation** (if applicable): [See Principle #1] + +**MCP Tool**: `tool_name` or `category__tool_name` (from server-name) + +**Parameters**: +- `param`: "value" (type, constraints, format details) + +**Expected Output**: [Description] -**โŒ Bad Example - Wrong parameters**: +**Error Handling**: +- If [condition]: [resolution] ``` -**MCP Tool**: get_cves +**โœ… Good Example:** +```markdown **Parameters**: -- severity: ["Critical", "Important"] -- sort_by: "cvss_score" +- `impact`: "7,6" (comma-separated: 7=Important, 6=Moderate, 5=Low) +- `sort`: "-cvss_score" (use - for descending) +- `limit`: 20 (integer, range: 1-100) ``` -(Actual tool uses `impact: "7,6"` and `sort: "-cvss_score"`) -**โœ… Good Example - Correct structure with document consultation first**: +**โŒ Bad Example:** +```markdown +**Parameters**: +- Use the CVE ID +- Set severity to high ``` -**CRITICAL**: Document consultation MUST happen BEFORE tool invocation. -**Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [vulnerability-logic.md](../../docs/insights/vulnerability-logic.md) using the Read tool -2. **Output to user**: "I consulted [vulnerability-logic.md]..." +**Rationale**: Exact names/formats prevent errors; first-attempt success reduces wasted cycles. -**MCP Tool**: `get_cves` or `vulnerability__get_cves` (from lightspeed-mcp) +--- -**Parameters**: -- impact: "7,6" (string with comma-separated impact levels: 7=Important, 6=Moderate, 5=Low) -- sort: "-cvss_score" (use - prefix for descending; valid fields: "cvss_score", "public_date") -- limit: 20 (maximum number of CVEs to return) -``` +### 3. Skill Precedence and Conciseness + +**A. Skills Over Tools** -**Rationale**: -- **Ordering**: Document consultation before parameters ensures it's executed first -- **Precision**: Exact parameter names and formats prevent tool errors -- **Examples**: Value examples (e.g., "7,6") show correct format -- **Determinism**: First-attempt success reduces wasted cycles +Delegate to skills, not raw MCP tools. -## 3. Skill Precedence and Conciseness +**โœ… CORRECT:** `invoke the vm-inventory skill` +**โŒ WRONG:** `use the resources_list tool` -**Precedence Rule**: Skills > Tools (always invoke skills, not raw MCP tools) +**B. Concise Descriptions** -**Conciseness Requirement**: Skill descriptions (loaded at agent start time) must be: -- **Under 500 tokens** for the YAML frontmatter description field -- **Focus on "when to use"** with 3-5 concrete examples -- **Defer implementation details** to the skill body (not frontmatter) +- Under 500 tokens in frontmatter `description` +- 3-5 "Use when" examples +- "NOT for" anti-patterns with alternatives +- Defer implementation to skill body -**Example**: +**โœ… Complete Example:** ```yaml ---- -name: cve-impact description: | - Analyze CVE impact across the fleet without immediate remediation. + Analyze CVE impact without remediation. Use when: - - "What are the most critical vulnerabilities?" - - "Show CVEs affecting my systems" - - "List high-severity CVEs" + - "What are critical vulnerabilities?" + - "Show CVEs affecting systems" + - User mentions "CVEs", "vulnerabilities" - NOT for remediation actions (use remediator agent instead). - model: inherit # Root: Runtime configuration required before skill execution - color: blue # Root: UX - IDE sidebar/terminal theme ---- + NOT for remediation (use remediator agent instead). ``` -**Rationale**: Minimizes token usage at agent initialization while maintaining clarity. +**Rationale**: Minimizes token usage at initialization; prevents skill misuse. -### Root-Level Frontmatter (2026 Agentic Skills Standard) - -Primary UI and runtime configuration fields belong at the **root level** of YAML frontmatter so the IDE or Agent Host can parse them without traversing nested blocks. - -| Field Type | Location | Examples | -|------------|----------|----------| -| Runtime | Root | `model`, `allowed-tools` | -| UX/UI | Root | `color`, `icon`, `version` | -| Custom | `metadata` | `author`, `priority`, `compliance` | - -**Standard Color Values** (Cursor, Claude Code): - -| Color | Use Case | -|-------|----------| -| blue, cyan | Analysis, read-only | -| green | Success, deployment | -| yellow | Caution, validation | -| red | Critical, security, remediation | -| magenta | Creative, generation | +--- -## 4. Dependencies Declaration +### 4. Dependencies Declaration -Every skill MUST include a **Dependencies** section listing: -- **Skills**: Other skills this skill may invoke -- **MCP Tools**: Specific tools from MCP servers -- **MCP Servers**: Required MCP server names -- **Documentation**: Reference docs for context +Every skill MUST include complete Dependencies section. -**Required Format**: +**Required Structure:** ```markdown ## Dependencies ### Required MCP Servers -- `lightspeed-mcp` - Red Hat Lightspeed platform access +- `server-name` - Description ([setup guide](link)) ### Required MCP Tools -- `vulnerability__get_cves` (from lightspeed-mcp) - List CVEs -- `vulnerability__get_cve` (from lightspeed-mcp) - Get CVE details +- `tool_name` (from server-name) - What it does + - Parameters: param1, param2 ### Related Skills -- `cve-validation` - Validate CVEs before impact analysis -- `fleet-inventory` - Identify affected systems +- `skill-name` - When to use instead ### Reference Documentation -- [cvss-scoring.md](docs/references/cvss-scoring.md) - CVSS severity mappings -- [insights-api.md](docs/insights/insights-api.md) - API usage patterns +**Internal:** [doc.md](path) - Purpose +**Official:** [Title - Product](https://docs.redhat.com/...) ``` -**Rationale**: Makes dependencies explicit for debugging and ensures proper error handling. +**Rationale**: Makes dependencies explicit for debugging and troubleshooting. -## 5. Human-in-the-Loop Requirements +--- -Skills performing **critical operations** MUST include this section: +### 5. Human-in-the-Loop Requirements -**Required Section**: -```markdown -## Critical: Human-in-the-Loop Requirements +Skills performing critical operations MUST require explicit confirmation. -This skill requires explicit user confirmation at the following steps: +**When Required:** Create, delete, modify, restore, execute commands, affect multiple systems +**NOT Required:** Read-only operations (list, view, get) -1. **Before Tool Invocation** [if applicable] - - Ask: "Should I proceed with [specific action]?" - - Wait for user confirmation - -2. **Before Destructive Actions** [if applicable] - - Display preview of changes - - Ask: "Review the changes above. Should I execute this?" - - Wait for explicit "yes" or "proceed" +**Required Section:** +```markdown +## Critical: Human-in-the-Loop Requirements -3. **After Each Major Step** [if applicable] - - Report results - - Ask: "Continue to next step?" +1. **Before [Action]** + - Display preview: [what will happen] + - Ask: "Should I [action]?" + - Wait for confirmation (yes/no) -**Never assume approval** - always wait for explicit user confirmation. +**Never assume approval** - always wait for explicit confirmation. ``` -**When to Use**: -- Playbook execution (ansible-mcp-server) -- System modifications (package updates, config changes) -- Multi-system operations (batch remediation) -- Data deletion or irreversible actions +**For Destructive Operations - Add Typed Confirmation:** +```markdown +2. **Typed Confirmation** + - Ask: "Type exact resource name to confirm: " + - Verify exact match, cancel if mismatch + - Ask: "Type 'DELETE' to proceed" + - Only proceed on exact match +``` -**Rationale**: Prevents unintended automation; maintains user control over critical operations. +**Rationale**: Prevents unintended automation; maintains user control; reduces accidental data loss. -## 6. Mandatory Skill Sections +--- -Every skill MUST include these sections in order: +### 6. Mandatory Skill Sections -### Template Structure: +**Required Section Order:** +1. YAML frontmatter +2. `# [Skill Name]` heading + overview (1-2 sentences) +3. `## Critical: Human-in-the-Loop Requirements` (if applicable) +4. `## Prerequisites` +5. `## When to Use This Skill` +6. `## Workflow` +7. `## Dependencies` +8. `## Example Usage` (recommended) -```markdown +**A. Mandatory Frontmatter Fields:** +```yaml --- -name: skill-name -description: | - [Concise when-to-use with 3-5 examples] -model: inherit|sonnet|haiku -color: red|blue|green|yellow|cyan|magenta -version: 1.0.0 -metadata: - author: "team-name" - priority: "high" +name: skill-name # MANDATORY - kebab-case, matches directory +description: | # MANDATORY - <500 tokens, includes use cases + [With "Use when" and "NOT for"] +model: inherit # MANDATORY - inherit | sonnet | haiku +color: green # MANDATORY - cyan|green|blue|yellow|red --- +``` -# [Skill Name] - -## Prerequisites - -**Required MCP Servers**: `server-name` ([setup guide](link)) -**Required MCP Tools**: `tool_name` (from server-name) -**Environment Variables**: `VAR_NAME` (if applicable) - -**Verification**: -Before executing, verify MCP server availability: -1. Check `server-name` is configured in `.mcp.json` -2. Verify environment variables are set -3. If missing: Report to user with setup instructions - -**Human Notification on Failure**: -If prerequisites are not met: -- โŒ "Cannot proceed: MCP server `server-name` is not available" -- ๐Ÿ“‹ "Setup required: [link to setup guide]" -- โ“ "How would you like to proceed? (setup now / skip / abort)" -- โธ๏ธ Wait for user decision +**Model Values:** +- `inherit` - Use parent context (recommended) +- `sonnet` - Complex reasoning +- `haiku` - Simple, fast operations + +**Color Values (Risk-Based):** +- `cyan` - Read-only (list, view, get) +- `green` - Additive (create, clone) +- `blue` - Reversible (start, stop, restart) +- `yellow` - Destructive but recoverable (snapshot-delete) +- `red` - Irreversible (delete, restore) + +**B. Prerequisites Section Must Include:** +- Required MCP Servers with setup links +- Required MCP Tools with descriptions +- Environment Variables (if any) +- Verification Steps +- Human Notification Protocol +- Security warning + +See Principle #7 for details. + +**C. When to Use Section Must Include:** +- 3+ specific scenarios +- "Do NOT use when" with alternatives + +**D. Workflow Section Steps Must Include:** +- `### Step N: [Action]` heading +- Document consultation (if applicable) +- MCP Tool with server +- Parameters with exact format +- Expected output +- Error handling (2+ conditions) -## When to Use This Skill +--- -Use this skill when: -- [Specific scenario 1] -- [Specific scenario 2] -- [Specific scenario 3] +### 7. MCP Server Availability Verification -Do NOT use when: -- [Anti-pattern 1] โ†’ Use [alternative] instead -- [Anti-pattern 2] โ†’ Use [alternative] instead +Prerequisites MUST include verification and human notification protocol. -## Workflow +**CRITICAL SECURITY - NEVER expose credential values:** -### Step 1: [Action Name] +**โŒ WRONG:** +```bash +echo $API_SECRET # Exposes value +echo "SECRET=$API_SECRET" # Exposes value +``` -**CRITICAL**: Document consultation MUST happen BEFORE tool invocation. +**โœ… CORRECT:** +```bash +# Report boolean only +test -n "$API_SECRET" && echo "โœ“ API_SECRET is set" || echo "โœ— Not set" +``` -**Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [doc.md](../../docs/category/doc.md) using the Read tool to understand [specific topic] -2. **Output to user**: "I consulted [doc.md](../../docs/category/doc.md) to understand [specific topic]." +**Required Prerequisites Pattern:** +```markdown +## Prerequisites -**MCP Tool**: `tool_name` or `toolset__tool_name` (from server-name) +**Required MCP Servers:** `server-name` ([setup](link)) -**Parameters**: -- `param1`: [exact specification with example - see Design Principle #2] - - Example: `"CVE-2024-1234"` -- `param2`: [exact specification with example] - - Example: `true` (description of what this does) +**Required MCP Tools:** `tool_name` - Description -**Expected Output**: [describe what the tool returns] +**Environment Variables:** `VAR` - What it controls -**Error Handling**: -- If [error condition]: [how to handle] +**Verification Steps:** +1. Check `server-name` in `.mcp.json` +2. Verify `VAR` is set (without exposing value) +3. If missing โ†’ Human Notification Protocol -### Step 2: [Next Action] +**Human Notification Protocol:** -[Continue pattern...] +When prerequisites fail: +1. **Stop immediately** - No tool calls +2. **Report error:** + ``` + โŒ Cannot execute skill: MCP server `name` unavailable + ๐Ÿ“‹ Setup: [instructions + link] + ``` +3. **Request decision:** "How to proceed? (setup/skip/abort)" +4. **Wait for user input** -## Dependencies +**Security:** Never display credential values. +``` -[As specified in principle #4] +**Rationale**: Graceful degradation; clear guidance; prevents credential exposure. -## Critical: Human-in-the-Loop Requirements +--- -[As specified in principle #5, if applicable] +## Additional Quality Standards -## Example Usage +### 8. Single Responsibility -[Concrete example with user query and skill response] -``` +One clear purpose per skill. -**Rationale**: Standardizes skill structure for consistency and completeness. +**โœ… Good:** `vm-create`, `vm-delete`, `vm-inventory` (separate skills) +**โŒ Bad:** `vm-manager` (creates, deletes, lists - too broad) -## 7. MCP Server Availability Verification +--- -The **Prerequisites** section MUST include verification logic: +### 9. Naming Conventions -**CRITICAL SECURITY CONSTRAINT**: -- **NEVER print environment variable values in user-visible output** -- When checking if env vars are set, only report presence/absence -- Do NOT use `echo $VAR_NAME` or display actual credential values -- Protect sensitive data like API keys, tokens, secrets, passwords +- kebab-case only +- Folder matches `name` field exactly +- File named `SKILL.md` (uppercase) +- Name: 1-64 chars, `a-z0-9-`, no consecutive `--`, no leading/trailing `-` -**โŒ WRONG - Exposes credentials**: -```bash -echo $LIGHTSPEED_CLIENT_SECRET # Shows actual secret value -``` +**โœ… Correct:** `skills/vm-create/SKILL.md` +**โŒ Wrong:** `skills/VM-Create/skill.md`, `skills/vm_create/SKILL.md` -**โœ… CORRECT - Check without exposing**: -```bash -# Check if set (exit code only, no output) -test -n "$LIGHTSPEED_CLIENT_SECRET" - -# Or check and report boolean result -if [ -n "$LIGHTSPEED_CLIENT_SECRET" ]; then - echo "โœ“ LIGHTSPEED_CLIENT_SECRET is set" -else - echo "โœ— LIGHTSPEED_CLIENT_SECRET is not set" -fi -``` +--- -**In User-Visible Messages**: -``` -โœ“ Environment variable LIGHTSPEED_CLIENT_ID is set -โœ“ Environment variable LIGHTSPEED_CLIENT_SECRET is set -``` +### 10. Content Quality -**NEVER show**: -``` -LIGHTSPEED_CLIENT_SECRET=sk-abc123-xyz789-... โŒ SECURITY VIOLATION -``` +**Required:** +- No hardcoded values (use ``, ``) +- No broken links +- Production-ready examples +- Complete error handling -**Rationale**: Prevents accidental credential exposure in conversation history, logs, or screenshots. +**โœ… Good:** `namespace: ""` +**โŒ Bad:** `namespace: "production"` --- -**Required Pattern**: -```markdown -## Prerequisites +## Root-Level Frontmatter (2026 Standard) -**Required MCP Servers**: `lightspeed-mcp` ([setup guide](https://console.redhat.com/)) -**Required MCP Tools**: -- `vulnerability__get_cves` -- `vulnerability__get_cve` - -**Verification Steps**: -1. **Check MCP Server Configuration** - - Verify `lightspeed-mcp` exists in `.mcp.json` - - If missing โ†’ Proceed to Human Notification - -2. **Check Environment Variables** - - Verify `LIGHTSPEED_CLIENT_ID` is set - - Verify `LIGHTSPEED_CLIENT_SECRET` is set - - If missing โ†’ Proceed to Human Notification - -3. **Test MCP Server Connection** (optional, for critical skills) - - Attempt simple tool call (e.g., `get_mcp_version`) - - If fails โ†’ Proceed to Human Notification - -**Human Notification Protocol**: - -When prerequisites fail, the skill MUST: - -1. **Stop Execution Immediately** - Do not attempt tool calls -2. **Report Clear Error**: - ``` - โŒ Cannot execute [skill-name]: MCP server `lightspeed-mcp` is not available - - ๐Ÿ“‹ Setup Instructions: - 1. Add lightspeed-mcp to `.mcp.json` (see: [setup guide]) - 2. Set environment variables: - export LIGHTSPEED_CLIENT_ID="your-id" - export LIGHTSPEED_CLIENT_SECRET="your-secret" - 3. Restart Claude Code to reload MCP servers - - ๐Ÿ”— Documentation: [link to MCP server docs] - ``` - -3. **Request User Decision**: - ``` - โ“ How would you like to proceed? - - Options: - - "setup" - I'll help you configure the MCP server now - - "skip" - Skip this skill and continue with alternative approach - - "abort" - Stop the workflow entirely - - Please respond with your choice. - ``` - -4. **Wait for Explicit User Input** - Do not proceed automatically - -**Error Message Templates**: - -- Missing MCP Server: - ``` - โŒ MCP server `{server_name}` not configured in .mcp.json - ๐Ÿ“‹ Add server configuration: [setup guide link] - ``` - -- Missing Environment Variable: - ``` - โŒ Environment variable `{VAR_NAME}` not set - ๐Ÿ“‹ Set variable: export {VAR_NAME}="your-value" - - โš ๏ธ SECURITY: Never expose actual values in output or logs - ``` - -- Connection Failure: - ``` - โŒ Cannot connect to `{server_name}` MCP server - ๐Ÿ“‹ Possible causes: - - Container not running (run: podman ps) - - Network issues (check: podman logs) - - Invalid credentials (verify env vars) - ``` -``` +UI/runtime fields at root; custom fields in `metadata`. -**Rationale**: Provides graceful degradation and clear user guidance when dependencies are missing. +| Field Type | Location | Examples | +|------------|----------|----------| +| Runtime | Root | `model`, `allowed-tools` | +| UX/UI | Root | `color`, `version` | +| Custom | `metadata` | `author`, `priority` | -## Skill File Format +--- -Skills MUST follow the structure defined in **Design Principle #6** above. Here's a minimal template: +## Skill Template ```yaml --- name: skill-name description: | - [Concise when-to-use with 3-5 examples - under 500 tokens] -model: inherit|sonnet|haiku -color: red|blue|green|yellow|cyan|magenta -version: 1.0.0 +[Description] + +Use when: +- "Example query 1" +- "Example query 2" +- User mentions "keyword" + +NOT for [use case] (use [skill] instead). +model: inherit +color: green metadata: - author: "team-name" - priority: "high" +author: "team" +version: "1.0" --- -# [Skill Name] +# /skill-name Skill + +[Overview - 1-2 sentences] + +## Critical: Human-in-the-Loop Requirements +[See Principle #5 - if applicable] ## Prerequisites -[As defined in Design Principle #7 - with verification and human notification] + +**Required MCP Servers:** `server` ([setup](link)) +**Required MCP Tools:** `tool` (from server) - Description +**Environment Variables:** `VAR` - Description + +**Verification Steps:** +[See Principle #7] + +**Human Notification Protocol:** +[See Principle #7] + +**Security:** Never display credential values. ## When to Use This Skill -[Clear use cases and anti-patterns] + +Use when: +- [Scenario 1] +- [Scenario 2] + +Do NOT use when: +- [Anti-pattern] โ†’ Use `skill` instead ## Workflow + ### Step 1: [Action] -**CRITICAL**: Document consultation MUST happen BEFORE tool invocation. +**Document Consultation** (if needed): +1. **Action**: Read [doc.md](path) using Read tool +2. **Output**: "I consulted [doc.md](path)..." -**Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [doc.md](path/to/doc.md) using the Read tool to understand [topic] -2. **Output to user**: "I consulted [doc.md](path/to/doc.md) to understand [topic]." +**MCP Tool:** `tool_name` (from server) -**MCP Tool**: `tool_name` or `toolset__tool_name` (from server-name) +**Parameters:** +- `param`: "value" (format details) -**Parameters**: -- param1: "value" (exact format with example - Design Principle #2) -- param2: true (description of what this does) +**Expected Output:** +```json +{"status": "success"} +``` -[Implementation details] +**Error Handling:** +- If [condition]: [resolution] ## Dependencies -[As defined in Design Principle #4] -## Critical: Human-in-the-Loop Requirements -[If applicable - Design Principle #5] -``` +### Required MCP Servers +- `server` - Description ([setup](link)) + +### Required MCP Tools +- `tool` (from server) - What it does -**Important**: See this document for complete requirements and rationale. +### Related Skills +- `skill` - When to use -## Agent File Format +### Reference Documentation +**Internal:** [doc.md](path) +**Official:** [Title](link) -Agents MUST follow similar principles as skills, with focus on skill orchestration: +## Example Usage +[User query + skill response] +``` + +--- + +## Agent Template ```yaml --- name: agent-name description: | - When to use this agent vs skills - [Concise with 3-5 examples - under 500 tokens] +Multi-step workflow orchestrating skills. + +Use when: +- [Complex workflow] + +NOT for single ops (use skills). model: inherit color: red -version: 1.0.0 metadata: - author: "team-name" +author: "team" tools: ["All"] --- # [Agent Name] +[Overview] + ## Prerequisites -[MCP servers and skills this agent depends on - Design Principle #7] +[MCP servers and skills - see Principle #7] ## When to Use This Agent -[Multi-step workflows requiring orchestration] +[Multi-step workflows vs individual skills] ## Workflow -### 1. Step Name -**Invoke the skill-name skill**: +### Step 1: [Action] + +**Invoke skill:** ``` Skill: skill-name -Args: [Precise parameters - Design Principle #2] +Args: [precise parameters] ``` -**Document Consultation** (if needed): -I consulted [filename.md](path/to/filename.md) to understand [topic]. -[Design Principle #1] - **Human Confirmation** (if critical): -Ask: "Should I proceed with [action]?" -Wait for confirmation. -[Design Principle #5] - -### 2. Next Step -[Continue orchestration pattern...] +Ask: "Proceed?" Wait for confirmation. ## Dependencies -[Skills, tools, docs this agent uses - Design Principle #4] +[Skills, tools, docs - see Principle #4] ## Critical: Human-in-the-Loop Requirements -[For agents performing critical operations - Design Principle #5] +[If applicable - see Principle #5] ``` -**Important**: Agents inherit the same design principles as skills. See this document for complete requirements. +--- + +## Summary + +**Core Principles:** +1. **Document Consultation Transparency** - Read files, then declare +2. **Precise Parameter Specification** - Exact formats with examples +3. **Skill Precedence and Conciseness** - Skills over tools; <500 tokens +4. **Dependencies Declaration** - Explicit dependencies +5. **Human-in-the-Loop** - Confirmations for critical ops +6. **Mandatory Sections** - Standard structure +7. **MCP Verification** - Prerequisites with security +8. **Single Responsibility** - One purpose per skill +9. **Naming Conventions** - kebab-case +10. **Content Quality** - Production-ready examples + +--- + +**Last Updated**: 2026-03-02 +**Version**: 5.0 +**Applies To**: All agentic collections +**Specification Compliance**: agentskills.io v1.0 diff --git a/scripts/run-skill-linter.sh b/scripts/run-skill-linter.sh index 76ee2115..a9742c37 100755 --- a/scripts/run-skill-linter.sh +++ b/scripts/run-skill-linter.sh @@ -144,7 +144,7 @@ printf "${BOLD}%-42s%s${NC}\n" "Metric" "Count" echo "โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€" printf "%-42s${BLUE}%s${NC}\n" "Total Skills:" "$TOTAL_SKILLS" printf "โœ… %-39s${GREEN}%s${NC}\n" "Passed:" "$PASSED_SKILLS" -printf "โš ๏ธ %-40s${YELLOW}%s${NC}\n" "Passed with Warnings:" "$WARNED_SKILLS" +printf "โš ๏ธ %-40s${YELLOW}%s${NC}\n" "Passed with Warnings:" "$WARNED_SKILLS" printf "โŒ %-39s${RED}%s${NC}\n" "Failed:" "$FAILED_SKILLS" echo "" diff --git a/scripts/validate-skills.sh b/scripts/validate-skills.sh index 51ad6e5c..a70b862a 100755 --- a/scripts/validate-skills.sh +++ b/scripts/validate-skills.sh @@ -4,8 +4,8 @@ # Universal skill validation for all agentic collections # # Validates skills against: -# - SKILL_CHECKLIST.md (Tier 1: agentskills.io specification) -# - SKILL_CHECKLIST.md (Tier 2: Repository design principles) +# - Tier 1: agentskills.io specification (via run-skill-linter.sh) +# - Tier 2: Repository design principles (SKILL_DESIGN_PRINCIPLES.md) # # Usage: # ./scripts/validate-skills.sh [path] # Validate specific skill or collection @@ -649,7 +649,7 @@ main() { echo "โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”" echo -e "${BLUE}Universal Skill Validator${NC}" - echo "Validates skills against SKILL_CHECKLIST.md" + echo "Validates skills against SKILL_DESIGN_PRINCIPLES.md" echo "โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”" # Determine target paths From dcd7161fe4ffc1dc1dc633164eb429392f24f8a3 Mon Sep 17 00:00:00 2001 From: Daniele Martinoli Date: Mon, 2 Mar 2026 17:56:21 +0100 Subject: [PATCH 09/20] reviewed remediation solution --- .claude-plugin/marketplace.json | 2 +- CLAUDE.md | 32 +- SKILL_DESIGN_PRINCIPLES.md | 70 +- docs/plugins.json | 2 +- ocp-admin/.claude-plugin/plugin.json | 2 +- rh-sre/DEMO.md | 2 +- rh-sre/README.md | 84 +- rh-sre/agents/remediator.md | 346 -------- rh-sre/docs/INDEX.md | 7 + rh-sre/docs/ansible/aap-job-execution.md | 2 +- .../references/lightspeed-mcp-parameters.md | 87 ++ .../lightspeed-mcp-tool-failures.md | 55 ++ rh-sre/docs/references/skill-invocation.md | 35 + .../testing/aap-integration-test-guide.md | 6 +- rh-sre/skills/cve-impact/SKILL.md | 254 ++++-- .../cve-impact/flows/01-account-cves.md | 92 +++ .../cve-impact/flows/02-system-all-cves.md | 89 +++ .../flows/03-system-remediatable-cves.md | 96 +++ .../references/01-cve-response-parser.py | 225 ++++++ .../references/02-cve-parsing-guide.md | 147 ++++ rh-sre/skills/cve-validation/SKILL.md | 106 ++- .../references/01-remediation-indicators.md | 66 ++ rh-sre/skills/execution-summary/SKILL.md | 30 +- rh-sre/skills/fleet-inventory/SKILL.md | 44 +- rh-sre/skills/job-template-creator/SKILL.md | 21 +- .../SKILL.md | 70 +- rh-sre/skills/mcp-aap-validator/SKILL.md | 553 +------------ .../skills/mcp-lightspeed-validator/SKILL.md | 532 +----------- rh-sre/skills/playbook-executor/SKILL.md | 754 ++++-------------- .../01-execution-report-templates.md | 168 ++++ .../references/02-error-handling-guide.md | 108 +++ .../references/03-workflow-examples.md | 119 +++ .../04-dry-run-display-templates.md | 93 +++ .../references/05-git-flow-prompts.md | 97 +++ rh-sre/skills/playbook-generator/SKILL.md | 329 ++------ rh-sre/skills/remediation-verifier/SKILL.md | 8 +- rh-sre/skills/remediation/SKILL.md | 277 +++++++ .../01-remediation-plan-template.md | 85 ++ rh-sre/skills/system-context/SKILL.md | 8 +- scripts/generate_pack_data.py | 20 +- scripts/validate_skill_design.py | 2 +- 41 files changed, 2613 insertions(+), 2512 deletions(-) delete mode 100644 rh-sre/agents/remediator.md create mode 100644 rh-sre/docs/references/lightspeed-mcp-parameters.md create mode 100644 rh-sre/docs/references/lightspeed-mcp-tool-failures.md create mode 100644 rh-sre/docs/references/skill-invocation.md create mode 100644 rh-sre/skills/cve-impact/flows/01-account-cves.md create mode 100644 rh-sre/skills/cve-impact/flows/02-system-all-cves.md create mode 100644 rh-sre/skills/cve-impact/flows/03-system-remediatable-cves.md create mode 100644 rh-sre/skills/cve-impact/references/01-cve-response-parser.py create mode 100644 rh-sre/skills/cve-impact/references/02-cve-parsing-guide.md create mode 100644 rh-sre/skills/cve-validation/references/01-remediation-indicators.md create mode 100644 rh-sre/skills/playbook-executor/references/01-execution-report-templates.md create mode 100644 rh-sre/skills/playbook-executor/references/02-error-handling-guide.md create mode 100644 rh-sre/skills/playbook-executor/references/03-workflow-examples.md create mode 100644 rh-sre/skills/playbook-executor/references/04-dry-run-display-templates.md create mode 100644 rh-sre/skills/playbook-executor/references/05-git-flow-prompts.md create mode 100644 rh-sre/skills/remediation/SKILL.md create mode 100644 rh-sre/skills/remediation/references/01-remediation-plan-template.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index b801f2b6..40145fea 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -18,7 +18,7 @@ }, "source": "./rh-sre", "category": "sre", - "agents": "./agents/remediator.md", + "agents": [], "skills": "./skills" }, { diff --git a/CLAUDE.md b/CLAUDE.md index 5699ac47..756f2e1f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -26,9 +26,7 @@ Each pack follows this structure: โ”œโ”€โ”€ .claude-plugin/ # Claude Code plugin metadata โ”‚ โ””โ”€โ”€ plugin.json # Name, version, description, author, license โ”œโ”€โ”€ .mcp.json # MCP server configurations (uses env vars for credentials) -โ”œโ”€โ”€ agents/ # Multi-step workflow orchestrators -โ”‚ โ””โ”€โ”€ .md # Agent definition with YAML frontmatter -โ”œโ”€โ”€ skills/ # Specialized task executors +โ”œโ”€โ”€ skills/ # Specialized task executors (including orchestration skills) โ”‚ โ””โ”€โ”€ / โ”‚ โ””โ”€โ”€ SKILL.md # Skill definition with YAML frontmatter โ””โ”€โ”€ docs/ # AI-optimized knowledge base (rh-sre only currently) @@ -39,7 +37,7 @@ Each pack follows this structure: ## Working with Agentic Collections -### Skills vs Agents +### Skills **Skills** (`skills//SKILL.md`): - Single-purpose task executors @@ -48,14 +46,7 @@ Each pack follows this structure: - Structure: YAML frontmatter + implementation guide - Example: `cve-impact` (CVE risk assessment), `playbook-generator` (Ansible generation) -**Agents** (`agents/.md`): -- Multi-step workflow orchestrators -- Delegate to multiple skills in sequence -- Invoked via the `Task` tool with `subagent_type` -- Structure: YAML frontmatter + workflow definition -- Example: `remediator` (orchestrates 5 skills for end-to-end CVE remediation) - -**Key Pattern**: Agents orchestrate skills; skills encapsulate tools. Never call MCP tools directly - always go through skills. +**Key Pattern**: Skills encapsulate tools; orchestration skills invoke other skills. Never call MCP tools directly - always go through skills. For end-to-end CVE remediation, use the `/remediation` skill which orchestrates 6 specialized skills. ## Skill and Agent Requirements @@ -151,7 +142,6 @@ last_updated: YYYY-MM-DD ### Files - Skills: `skills//SKILL.md` (uppercase SKILL.md) -- Agents: `agents/.md` (lowercase, no folder) - Docs: Lowercase with dashes, categorized by directory ## Development Workflow @@ -163,8 +153,7 @@ last_updated: YYYY-MM-DD 3. Create `skills/` directory 4. Optional: Add `.claude-plugin/plugin.json` for Claude Code 5. Optional: Add `.mcp.json` for MCP server integrations -6. Optional: Add `agents/` for multi-step workflows -7. Update main `README.md` table with link +6. Update main `README.md` table with link ### Adding a Skill @@ -185,15 +174,6 @@ last_updated: YYYY-MM-DD **Collection-Specific Standards:** - **rh-virt**: Follow `rh-virt/SKILL_TEMPLATE.md` for enhanced quality standards including mandatory Common Issues and Example Usage sections -### Adding an Agent - -1. Create `agents/.md` -2. Follow skill requirements in [SKILL_DESIGN_PRINCIPLES.md](SKILL_DESIGN_PRINCIPLES.md) (agents use same structure) -3. Define YAML frontmatter (name, description, model, tools) -4. Document workflow that orchestrates multiple skills -5. Provide clear examples of when to use agent vs individual skills -6. Test with `Task` tool invocation - ### Adding Documentation (rh-sre pattern) 1. Create doc in appropriate category: `docs/{rhel,ansible,openshift,insights,references}/` @@ -221,7 +201,7 @@ last_updated: YYYY-MM-DD The `rh-sre` pack is the most complete implementation, demonstrating: - Full skill orchestration (10 skills) -- Agent-based workflows (remediator agent) +- Orchestration skills (remediation skill orchestrates 6 skills) - AI-optimized documentation system - MCP server integration - Red Hat Lightspeed platform integration @@ -245,7 +225,7 @@ When creating new collections, follow the pattern that best matches your needs: ### Core Architecture 1. **Skills encapsulate tools** - Never call MCP tools directly; always invoke skills -2. **Agents orchestrate skills** - Complex workflows delegate to specialized skills +2. **Orchestration skills invoke other skills** - Complex workflows delegate to specialized skills 3. **agentskills.io compliance** - All skills follow the official specification 4. **Progressive disclosure** - Load docs incrementally based on task needs diff --git a/SKILL_DESIGN_PRINCIPLES.md b/SKILL_DESIGN_PRINCIPLES.md index 4adc11f7..1615a2bc 100644 --- a/SKILL_DESIGN_PRINCIPLES.md +++ b/SKILL_DESIGN_PRINCIPLES.md @@ -86,6 +86,7 @@ Delegate to skills, not raw MCP tools. **โœ… Complete Example:** ```yaml +--- description: | Analyze CVE impact without remediation. @@ -94,7 +95,10 @@ description: | - "Show CVEs affecting systems" - User mentions "CVEs", "vulnerabilities" - NOT for remediation (use remediator agent instead). + NOT for remediation actions (use remediation skill instead). +model: inherit # Root: Runtime configuration required before skill execution +color: blue # Root: UX - IDE sidebar/terminal theme +--- ``` **Rationale**: Minimizes token usage at initialization; prevents skill misuse. @@ -105,7 +109,53 @@ description: | Every skill MUST include complete Dependencies section. -**Required Structure:** +**Standard Color Values** (Cursor, Claude Code): + +| Color | Use Case | +|-------|----------| +| blue, cyan | Analysis, read-only | +| green | Success, deployment | +| yellow | Caution, validation | +| red | Critical, security, remediation | +| magenta | Creative, generation | + +## 4. Skill-to-Skill Invocation Standard + +**Standard format**: Use the slash format `/skill-name` when one skill or agent invokes another. + +```markdown +**How to invoke**: Execute the `/mcp-lightspeed-validator` skill +**Action**: Execute the `/mcp-aap-validator` skill +``` + +**โŒ Avoid** - Skill tool format (inconsistent): +```markdown +Use the Skill tool: + skill: "mcp-lightspeed-validator" +``` + +**โœ… Use** - Slash format (consistent across rh-sre): +```markdown +Execute the `/mcp-lightspeed-validator` skill +Invoke the `/playbook-executor` skill +``` + +**Applies to**: +- Skill โ†’ skill (remediation invokes `/cve-validation`, `/playbook-generator`, etc.) +- Skill โ†’ skill prerequisites (cve-validation invokes `/mcp-lightspeed-validator`) +- Skill โ†’ skill delegation (playbook-generator delegates to `/playbook-executor`) + +**Rationale**: Single format across agent and skill invocations improves consistency and reduces confusion. + +## 5. Dependencies Declaration + +Every skill MUST include a **Dependencies** section listing: +- **Skills**: Other skills this skill may invoke +- **MCP Tools**: Specific tools from MCP servers +- **MCP Servers**: Required MCP server names +- **Documentation**: Reference docs for context + +**Required Format**: ```markdown ## Dependencies @@ -126,9 +176,7 @@ Every skill MUST include complete Dependencies section. **Rationale**: Makes dependencies explicit for debugging and troubleshooting. ---- - -### 5. Human-in-the-Loop Requirements +## 6. Human-in-the-Loop Requirements Skills performing critical operations MUST require explicit confirmation. @@ -158,9 +206,15 @@ Skills performing critical operations MUST require explicit confirmation. **Rationale**: Prevents unintended automation; maintains user control; reduces accidental data loss. ---- +**When to Use**: +- Playbook execution (ansible-mcp-server) +- System modifications (package updates, config changes) +- Multi-system operations (batch remediation) +- Data deletion or irreversible actions + +## 7. Mandatory Skill Sections -### 6. Mandatory Skill Sections +Every skill MUST include these sections in order: **Required Section Order:** 1. YAML frontmatter @@ -219,7 +273,7 @@ See Principle #7 for details. --- -### 7. MCP Server Availability Verification +## 8. MCP Server Availability Verification Prerequisites MUST include verification and human notification protocol. diff --git a/docs/plugins.json b/docs/plugins.json index 4d89311a..34c5ebc4 100644 --- a/docs/plugins.json +++ b/docs/plugins.json @@ -8,7 +8,7 @@ "rh-developer": { "title": "Red Hat Developer Agentic Skills Collection" }, - "rh-ocp-admin": { + "ocp-admin": { "title": "Red Hat OpenShift Administration Agentic Skills Collection" }, "rh-support-engineer": { diff --git a/ocp-admin/.claude-plugin/plugin.json b/ocp-admin/.claude-plugin/plugin.json index d71ca0fe..0c57acf1 100644 --- a/ocp-admin/.claude-plugin/plugin.json +++ b/ocp-admin/.claude-plugin/plugin.json @@ -1,5 +1,5 @@ { - "name": "rh-ocp-admin", + "name": "ocp-admin", "version": "1.0.0", "description": "Automation capabilities for OpenShift Container Platform cluster management, workload orchestration, security policies, and operational tasks.", "author": { diff --git a/rh-sre/DEMO.md b/rh-sre/DEMO.md index be5aeda9..5b322d52 100644 --- a/rh-sre/DEMO.md +++ b/rh-sre/DEMO.md @@ -37,7 +37,7 @@ Tools: , ,... Docs: , , ... **** EXECUTION SUMMARY END **** """ -Agent, skills and tools names must include the plugin name, as in remediation-agent:remediator. +Agent, skills and tools names must include the plugin name, as in sre-agents:remediation. Doc names must include only the folder and the document name, omit everything before the docs/ folder. Example: docs/ansible/cve-remediation-templates.md ``` diff --git a/rh-sre/README.md b/rh-sre/README.md index e1f89419..f593604e 100644 --- a/rh-sre/README.md +++ b/rh-sre/README.md @@ -68,9 +68,9 @@ While you could use the underlying MCP servers (`lightspeed-mcp`, AAP MCP server **Workflow Abstraction** - Complex multi-tool workflows wrapped in single skill invocations -- Agent orchestration sequences skills automatically (validation โ†’ context โ†’ remediation โ†’ verification) +- Orchestration skills sequence other skills automatically (validation โ†’ context โ†’ remediation โ†’ verification) - Eliminates cognitive load of remembering workflow steps -- Example: `remediator` agent coordinates 5 skills across 6 steps instead of requiring 15+ individual MCP tool calls +- Example: `remediation` skill coordinates 6 skills across 6 steps instead of requiring 15+ individual MCP tool calls **Progressive Documentation Loading** - Skills load Red Hat documentation on-demand based on task requirements @@ -120,7 +120,7 @@ While you could use the underlying MCP servers (`lightspeed-mcp`, AAP MCP server --- -**Bottom Line**: The agentic collection transforms raw MCP tools into a reliable, safe, and user-friendly SRE automation platform. Skills provide guardrails, encode expertise, and eliminate common pitfalls, while agents orchestrate complex workflows that would otherwise require dozens of manual tool invocations. +**Bottom Line**: The agentic collection transforms raw MCP tools into a reliable, safe, and user-friendly SRE automation platform. Skills provide guardrails, encode expertise, and eliminate common pitfalls, while orchestration skills coordinate complex workflows that would otherwise require dozens of manual tool invocations. ## Quick Start @@ -162,9 +162,23 @@ claude plugin list --json | jq '[.[] | select(.id | contains("redhat"))]' ## Skills -The pack provides 12 specialized skills for common SRE operations: +The pack provides 13 skills for common SRE operations, including one orchestration skill for end-to-end remediation: -### 1. **fleet-inventory** - System Discovery and Fleet Management +### 1. **remediation** - End-to-End CVE Remediation (Orchestration) +Orchestrates 6 specialized skills for complete CVE remediation workflows. + +**Use when:** +- "Remediate CVE-2024-1234 on production systems" +- "Create and execute a remediation playbook for CVE-X" +- "Patch these CVEs on all web servers" + +**What it does:** +- Validates CVE and gathers system context +- Generates Ansible playbook +- Executes via AAP (with user confirmation) +- Verifies remediation success + +### 2. **fleet-inventory** - System Discovery and Fleet Management Query and display Red Hat Lightspeed managed system inventory. **Use when:** @@ -178,7 +192,7 @@ Query and display Red Hat Lightspeed managed system inventory. - Shows system health and check-in status - Identifies stale systems -### 2. **cve-impact** - CVE Discovery and Risk Assessment +### 3. **cve-impact** - CVE Discovery and Risk Assessment Analyze CVE impact across the fleet without immediate remediation. **Use when:** @@ -192,7 +206,7 @@ Analyze CVE impact across the fleet without immediate remediation. - Shows affected system counts - Provides priority recommendations -### 3. **cve-validation** - CVE Verification +### 4. **cve-validation** - CVE Verification Validate CVE existence and remediation availability. **Use when:** @@ -205,7 +219,7 @@ Validate CVE existence and remediation availability. - Checks remediation availability - Returns CVE metadata and severity -### 4. **system-context** - System Information Gathering +### 5. **system-context** - System Information Gathering Collect detailed system information from Red Hat Lightspeed. **Use when:** @@ -219,7 +233,7 @@ Collect detailed system information from Red Hat Lightspeed. - Displays configuration data - Maps CVE-to-system relationships -### 5. **playbook-generator** - Ansible Playbook Creation +### 6. **playbook-generator** - Ansible Playbook Creation Generate Ansible remediation playbooks following Red Hat best practices. **Use when:** @@ -232,7 +246,7 @@ Generate Ansible remediation playbooks following Red Hat best practices. - Includes error handling and rollback steps - Follows Red Hat standards -### 6. **playbook-executor** - AAP Playbook Execution +### 7. **playbook-executor** - AAP Playbook Execution Execute Ansible playbooks via AAP (Ansible Automation Platform) with dry-run capabilities, real-time monitoring, and comprehensive reporting. **Use when:** @@ -247,7 +261,7 @@ Execute Ansible playbooks via AAP (Ansible Automation Platform) with dry-run cap **Note**: This skill requires separate configuration (not included by default in this collection). For AAP-based playbook execution, use the `job-template-creator` skill to create job templates in AAP instead. -### 7. **remediation-verifier** - Remediation Verification +### 8. **remediation-verifier** - Remediation Verification Verify that CVE remediations were successfully applied. **Use when:** @@ -259,7 +273,7 @@ Verify that CVE remediations were successfully applied. - Verifies package updates - Confirms remediation success -### 8. **mcp-lightspeed-validator** - Lightspeed MCP Server Validation +### 9. **mcp-lightspeed-validator** - Lightspeed MCP Server Validation Validate Red Hat Lightspeed MCP server configuration and connectivity. **Use when:** @@ -274,7 +288,7 @@ Validate Red Hat Lightspeed MCP server configuration and connectivity. - Tests server connectivity and tool availability - Reports validation status (PASSED/PARTIAL/FAILED) -### 9. **mcp-aap-validator** - AAP MCP Server Validation +### 10. **mcp-aap-validator** - AAP MCP Server Validation Validate AAP (Ansible Automation Platform) MCP server configuration and connectivity. **Use when:** @@ -289,7 +303,7 @@ Validate AAP (Ansible Automation Platform) MCP server configuration and connecti - Tests server connectivity and authentication - Reports validation status (PASSED/PARTIAL/FAILED) -### 10. **execution-summary** - Workflow Execution Report +### 11. **execution-summary** - Workflow Execution Report Generate concise execution reports for audit and learning purposes. **Use when:** @@ -304,7 +318,7 @@ Generate concise execution reports for audit and learning purposes. - Formats in machine-readable format - Provides audit trail for workflows -### 11. **job-template-creator** - AAP Job Template Creation +### 12. **job-template-creator** - AAP Job Template Creation Create AAP job templates for executing Ansible playbooks through Ansible Automation Platform. **Use when:** @@ -318,7 +332,7 @@ Create AAP job templates for executing Ansible playbooks through Ansible Automat - Verifies template creation - Prepares for AAP-based playbook execution -### 12. **job-template-remediation-validator** - AAP Job Template Remediation Validation +### 13. **job-template-remediation-validator** - AAP Job Template Remediation Validation Verify an AAP job template meets requirements for executing CVE remediation playbooks. **Use when:** @@ -332,11 +346,11 @@ Verify an AAP job template meets requirements for executing CVE remediation play - Verifies project and inventory exist - Reports PASSED / PASSED WITH WARNINGS / FAILED -## Agent +## Orchestration Skill -### **remediator** - End-to-End CVE Remediation Orchestration +### **remediation** - End-to-End CVE Remediation -The remediator agent orchestrates the CVE-related skills to provide complete CVE remediation workflows. +The remediation skill orchestrates 6 specialized skills to provide complete CVE remediation workflows. **Use when:** - "Remediate CVE-2024-1234 on system abc-123" @@ -344,11 +358,12 @@ The remediator agent orchestrates the CVE-related skills to provide complete CVE - "Patch these 5 CVEs on all production servers" **Workflow:** -1. **Validate** (cve-validation skill) -2. **Gather Context** (system-context skill) -3. **Generate Playbook** (playbook-generator skill) -4. **Execute** (playbook-executor skill) -5. **Verify** (remediation-verifier skill) +1. **Impact** (cve-impact skill, if needed) +2. **Validate** (cve-validation skill) +3. **Gather Context** (system-context skill) +4. **Generate Playbook** (playbook-generator skill) +5. **Execute** (playbook-executor skill, with user confirmation) +6. **Verify** (remediation-verifier skill) **Capabilities:** - Single CVE on single system @@ -357,7 +372,7 @@ The remediator agent orchestrates the CVE-related skills to provide complete CVE - Automated job tracking and reporting - Partial failure handling -## Skills vs Agent Decision Guide +## Skills Decision Guide | User Request | Tool to Use | Reason | |--------------|-------------|--------| @@ -369,11 +384,11 @@ The remediator agent orchestrates the CVE-related skills to provide complete CVE | "Create job template" | **job-template-creator skill** | AAP template setup | | "Validate template for remediation" | **job-template-remediation-validator skill** | Template compatibility check | | "Generate execution summary" | **execution-summary skill** | Audit trail reporting | -| "Remediate CVE-2024-1234" | **remediator agent** | Multi-step workflow | -| "Create playbook for CVE-X" | **remediator agent** | Orchestration needed | +| "Remediate CVE-2024-1234" | **remediation skill** | Multi-step workflow | +| "Create playbook for CVE-X" | **remediation skill** | Orchestration needed | | "Was CVE-Y patched?" | **remediation-verifier skill** | Standalone check | -**General Rule**: Skills for information gathering and validation, agent for remediation actions. +**General Rule**: Use individual skills for information gathering and validation; use the remediation skill for end-to-end remediation actions. ## Documentation @@ -435,7 +450,7 @@ User: "What are the critical CVEs affecting these systems?" โ†’ cve-impact skill analyzes vulnerabilities User: "Remediate CVE-2024-1234 on all RHEL 8 production systems" -โ†’ remediator agent orchestrates end-to-end remediation +โ†’ remediation skill orchestrates end-to-end remediation ``` ### Workflow 2: Emergency CVE Patching @@ -443,7 +458,7 @@ User: "Remediate CVE-2024-1234 on all RHEL 8 production systems" ``` User: "URGENT: CVE-2024-CRITICAL has CVSS 9.8 - create emergency remediation playbooks for all production systems" -โ†’ remediator agent: +โ†’ remediation skill: 1. Validates CVE (cve-validation skill) 2. Lists production systems (system-context skill) 3. Generates playbook (playbook-generator skill) @@ -456,7 +471,7 @@ User: "URGENT: CVE-2024-CRITICAL has CVSS 9.8 - create emergency ``` User: "Create and execute remediation playbooks for CVE-X, CVE-Y, CVE-Z on systems server-01, server-02, server-03" -โ†’ remediator agent: +โ†’ remediation skill: 1. Validates all CVEs 2. Gathers system context 3. Generates consolidated playbook @@ -587,9 +602,8 @@ rh-sre/ โ”œโ”€โ”€ .claude-plugin/ โ”‚ โ””โ”€โ”€ plugin.json # Plugin metadata โ”œโ”€โ”€ .mcp.json # MCP server configurations -โ”œโ”€โ”€ agents/ -โ”‚ โ””โ”€โ”€ remediator.md # Orchestration agent โ”œโ”€โ”€ skills/ +โ”‚ โ”œโ”€โ”€ remediation/SKILL.md # Orchestration skill (end-to-end CVE remediation) โ”‚ โ”œโ”€โ”€ fleet-inventory/SKILL.md โ”‚ โ”œโ”€โ”€ cve-impact/SKILL.md โ”‚ โ”œโ”€โ”€ cve-validation/SKILL.md @@ -610,7 +624,7 @@ rh-sre/ ### Key Patterns - **Skills encapsulate tools** - Never call MCP tools directly -- **Agents orchestrate skills** - Complex workflows delegate to skills +- **Orchestration skills invoke other skills** - Complex workflows delegate to specialized skills - **Progressive disclosure** - Load docs incrementally - **Environment-based secrets** - No hardcoded credentials @@ -618,7 +632,7 @@ rh-sre/ See main repository [CLAUDE.md](../CLAUDE.md) for: - Adding new skills -- Creating agents +- Creating orchestration skills - Integrating MCP servers - Documentation best practices diff --git a/rh-sre/agents/remediator.md b/rh-sre/agents/remediator.md deleted file mode 100644 index 6f23806c..00000000 --- a/rh-sre/agents/remediator.md +++ /dev/null @@ -1,346 +0,0 @@ ---- -name: remediator -description: | - Comprehensive remediation planning and execution agent. Use this agent when users request: - - CVE remediation playbooks or security patch deployment - - Multi-step remediation workflows (validation โ†’ context โ†’ playbook โ†’ execution) - - Batch remediation across multiple systems or CVEs - - End-to-end CVE management (analysis + remediation + verification) - - Prioritizing and remediating CVEs (not just listing them) - - Emergency security response with immediate remediation plans - - System hardening with actionable remediation steps - - DO NOT use this agent for simple queries like: - - "List critical CVEs" or "Show me vulnerabilities" (use cve-impact skill instead) - - "What's the CVSS score for CVE-X?" (use cve-impact or cve-validation skills) - - Standalone impact analysis without remediation (use cve-impact skill) - - This agent orchestrates 5 specialized skills (cve-impact, cve-validation, system-context, playbook-generator, remediation-verifier) to provide complete remediation workflows. Use this agent when the user needs remediation ACTION, not just information. - - Examples: - - - Context: SRE needs to understand CVE impact before taking action - user: "What's the impact of CVE-2024-1234 and which systems are affected?" - assistant: "I'll use the remediator agent to analyze CVE-2024-1234, identify affected systems, and assess the risk." - - This is a CVE analysis request. The remediator agent handles impact analysis as part of its validation and context-gathering workflow, then offers remediation options based on risk level. - - - - - Context: SRE needs to patch a critical CVE on production systems - user: "Create a remediation playbook for CVE-2024-1234 on system abc-123" - assistant: "I'll use the remediator agent to help you create the remediation playbook for CVE-2024-1234." - - The user is requesting CVE remediation, which is the core responsibility of this agent. The agent will validate the CVE, gather system information, generate the playbook, and provide execution instructions. - - - - - Context: SRE needs to remediate multiple CVEs across a fleet - user: "Remediate CVE-2024-1234, CVE-2024-5678, and CVE-2024-9012 on all web servers in production" - assistant: "I'll use the remediator agent to create a batch remediation playbook for these three CVEs across your production web servers." - - This is a batch remediation request - multiple CVEs on multiple systems. The agent is optimized for this scenario and will handle it efficiently. - - - - - Context: SRE needs to prioritize CVE remediation efforts AND create remediation plan - user: "Compare CVE-2024-1234 and CVE-2024-5678, tell me which to fix first, and create the remediation playbook" - assistant: "I'll use the remediator agent to analyze both CVEs, compare their risk levels, recommend prioritization, and generate the remediation playbook for the higher-priority CVE." - - This is a risk assessment + remediation request. The remediator agent will retrieve CVE details, assess CVSS scores, check affected systems, provide a prioritized remediation plan, AND generate playbooks. - - - - - Context: SRE wants to see critical vulnerabilities (NO remediation requested) - user: "What are the most critical vulnerabilities on my account?" - assistant: "I'll use the cve-impact skill to analyze critical CVEs affecting your systems." - - This is a simple discovery/listing request with NO remediation action. Use the cve-impact skill directly, NOT the remediator agent. The skill will list CVEs, assess risk, and offer to create remediation plans if needed. - - - - - Context: SRE asks about a specific CVE (NO remediation requested yet) - user: "What's the impact of CVE-2024-1234?" - assistant: "I'll use the cve-impact skill to analyze CVE-2024-1234 and assess its impact on your systems." - - This is standalone impact analysis. Use cve-impact skill directly. If the user then asks "create a remediation playbook," invoke the remediator agent at that point. - - - -model: inherit -color: red -tools: ["All"] ---- - -You are a Red Hat remediation specialist helping SREs analyze, prioritize, and remediate CVE vulnerabilities on RHEL systems. - -## ๐Ÿšจ CRITICAL: You MUST Use Skills via Tool Calls - -**MANDATORY REQUIREMENT**: You MUST invoke skills using the Skill tool, NOT by generating text responses. - -โŒ **WRONG** - Generating text pretending to use a skill: -``` -I'll invoke the cve-impact skill to analyze the CVE... -[then generating text without actually calling the tool] -``` - -โœ… **CORRECT** - Actually invoking skills using slash command format: -``` -Execute the `/cve-impact` skill: -"Analyze CVE-2026-23116 and assess its impact on the fleet" -``` - -**Verification**: After EVERY workflow step, check your tool use count. If you have "0 tool uses", you are doing it WRONG and must start over using actual tool calls. - -**Skill Reference Format**: Use the slash command format (e.g., `/cve-impact`, `/playbook-generator`) to invoke skills, matching the pattern used in the rh-developer collection. - -## Your Core Responsibilities - -1. **Impact Analysis** - Assess CVE severity, affected systems, and business risk -2. **CVE Validation** - Verify CVEs exist and have available remediations -3. **Risk Prioritization** - Help users prioritize remediation based on CVSS scores and system criticality -4. **Context Gathering** - Collect system information and cluster deployment details -5. **Playbook Generation** - Create Ansible remediation playbooks -6. **Execution Guidance** - Provide clear instructions for playbook execution -7. **Verification** - Help validate remediation success - -**Important**: You handle both CVE analysis AND remediation. When users ask about CVE impact, affected systems, or risk assessment, you perform the analysis as part of your workflow before offering remediation options. - -**Skill Orchestration Architecture**: You orchestrate specialized skills to implement complex remediation workflows. Each skill encapsulates specific domain expertise and tool access. You coordinate high-level workflow by delegating to these skills: - -- **cve-impact**: CVE risk assessment and impact analysis (`skills/cve-impact/`) -- **cve-validation**: CVE metadata validation and remediation availability (`skills/cve-validation/`) -- **system-context**: System inventory and deployment context analysis (`skills/system-context/`) -- **playbook-generator**: Ansible playbook generation with Red Hat best practices (`skills/playbook-generator/`) -- **playbook-executor**: Ansible playbook execution and job status tracking (`skills/playbook-executor/`) -- **remediation-verifier**: Post-remediation verification and compliance checking (`skills/remediation-verifier/`) - -**Important**: Always use the Skill tool to invoke these specialized skills. Do NOT call MCP tools directly - skills handle all tool interactions and documentation consultation. - -## Your Workflow - -When a user requests CVE analysis or remediation, orchestrate skills in this workflow: - -### 1. Impact Analysis (If Requested or Needed) - -**๐Ÿ”ง ACTION REQUIRED: Execute the `/cve-impact` skill** - -Invoke the `/cve-impact` skill with the instruction: -``` -"Analyze CVE-XXXX-YYYY and assess its impact on affected systems" -``` - -**Expected behavior**: The skill will: -- Consult `docs/insights/vulnerability-logic.md` for Red Hat Lightspeed CVE assessment methodology -- Consult `docs/references/cvss-scoring.md` for CVSS interpretation guidelines -- Use `get_cve` (lightspeed-mcp vulnerability toolset) to retrieve CVE metadata -- Use `get_cve_systems` (lightspeed-mcp vulnerability toolset) to identify affected systems -- Assess CVSS score, severity, attack vector, and exploitability -- Determine risk level (Critical/High/Medium/Low) based on Red Hat guidelines -- Provide structured risk assessment, affected systems list, and business impact analysis - -**Your role**: Integrate the skill's output into your remediation planning. If the user only requested impact analysis, provide their comprehensive risk assessment and offer remediation options. If proceeding to remediation, use the risk assessment to inform next steps. - -### 2. Validate CVE - -**๐Ÿ”ง ACTION REQUIRED: Execute the `/cve-validation` skill** - -Invoke the `/cve-validation` skill with the instruction: -``` -"Validate CVE-XXXX-YYYY format, existence, and remediation availability" -``` - -**Expected behavior**: The skill will: -- Validate CVE format (CVE-YYYY-NNNNN) -- Check CVE exists in Red Hat Lightspeed database -- Verify CVSS score, severity, and affected packages -- Confirm remediation is available -- Return validation status with metadata - -**Your role**: If CVE is invalid or has no remediation, explain clearly to the user and suggest alternatives (e.g., manual patching steps, package update commands). If valid, proceed to context gathering. - -### 3. Gather Context - -**๐Ÿ”ง ACTION REQUIRED: Execute the `/system-context` skill** - -Invoke the `/system-context` skill with the instruction: -``` -"Gather system context for CVE-XXXX-YYYY: identify affected systems, RHEL versions, and deployment environments" -``` - -**Expected behavior**: The skill will: -- Identify affected systems using `get_cve_systems` (lightspeed-mcp vulnerability toolset) -- Gather detailed system information using `get_host_details` (lightspeed-mcp inventory toolset) -- Analyze RHEL versions, environments (dev/staging/prod), and system criticality -- Determine optimal remediation strategy (batch vs individual, rolling update, maintenance windows) -- Return comprehensive context summary with recommended approach - -**Your role**: Use the context summary to inform playbook generation and execution planning. Incorporate strategy recommendations into your remediation plan. - -### 4. Generate Playbook - -**๐Ÿ”ง ACTION REQUIRED: Execute the `/playbook-generator` skill** - -**CRITICAL**: This is where most agents fail. You MUST actually invoke the `/playbook-generator` skill, NOT generate playbook text yourself. - -Invoke the `/playbook-generator` skill with the instruction: -``` -"Generate an Ansible remediation playbook for CVE-XXXX-YYYY targeting systems [list of system UUIDs]. Apply Red Hat best practices and RHEL-specific patterns from documentation." -``` - -**Expected behavior**: The skill will: -- Consult documentation (cve-remediation-templates.md, package-management.md) -- Detect CVE type (kernel, service, SELinux, batch) automatically -- Generate playbook using `create_vulnerability_playbook` (lightspeed-mcp remediations toolset) -- Apply Red Hat best practices and documentation patterns -- Validate playbook YAML syntax and completeness -- Return production-ready Ansible playbook - -**Your role**: Present the generated playbook to the user. - -**๐Ÿšจ CRITICAL**: The playbook-generator skill **ONLY GENERATES** playbooks. It does **NOT EXECUTE** them. After generation, you MUST proceed to Step 5 to invoke the playbook-executor skill for execution. - -### 5. Execute Playbook (With User Confirmation) - -**๐Ÿšจ CRITICAL HANDOFF**: The playbook-generator skill **GENERATED** the playbook. Now you MUST invoke the playbook-executor skill to **EXECUTE** it via AAP MCP. - -**โŒ DO NOT**: -- Run `ansible-playbook` command via Shell tool -- Execute playbooks using local Ansible CLI -- Attempt any direct playbook execution - -**โœ… ALWAYS**: -- Invoke `/playbook-executor` skill for all playbook execution -- Use AAP MCP tools (not ansible-playbook CLI) -- Let playbook-executor handle job monitoring and status - -**User Confirmation Flow**: - -1. **Show playbook preview** - Display key tasks and explain what will happen -2. **Offer dry-run** - Ask: "Run dry-run first via AAP? (recommended)" -3. **If dry-run approved** - Invoke playbook-executor with dry-run mode -4. **Show dry-run results** - Display simulated changes from AAP -5. **If execution approved** - Invoke playbook-executor for actual execution -6. **Monitor progress** - playbook-executor streams AAP job events in real-time -7. **Generate report** - playbook-executor provides comprehensive execution summary - -**๐Ÿ”ง ACTION REQUIRED: Execute the `/playbook-executor` skill** - -Invoke the `/playbook-executor` skill with the instruction. Pass playbook metadata so the skill can derive the playbook path and match templates: -``` -"Execute the generated playbook for CVE-XXXX-YYYY. Playbook file: [filename from playbook-generator]. Content: [in context from playbook-generator output]. Target systems: [list of system UUIDs from system-context]. Start with dry-run (check mode) if user requested it. Monitor job status until completion and report results." -``` - -**Important**: Ensure playbook content and filename are in context when invoking. The playbook-executor derives the path as `playbooks/remediation/` and uses it to match job templates. - -**Expected behavior**: The skill will: -- Validate AAP MCP server availability (via mcp-aap-validator) -- Match templates by playbook path (exact match, different path with override, or invoke job-template-creator if none found) -- Add playbook to AAP project via git when override chosen (with commit/push confirmation) -- Offer dry-run execution (job_type="check") -- If approved, launch actual execution (job_type="run") -- Poll job status with `jobs_retrieve` -- Stream progress from `jobs_job_events_list` -- Generate comprehensive report with: - - Per-host statistics (`jobs_job_host_summaries_list`) - - Full console output (`jobs_stdout_retrieve`) - - Task timeline - - AAP URL for detailed view -- Handle errors with specific troubleshooting - -**Your role**: After execution completes successfully, suggest verification with remediation-verifier skill. If execution fails, present the skill's error report and offer to relaunch for failed hosts only. - -### 6. Verify Deployment (Optional) - -**๐Ÿ”ง ACTION REQUIRED: Execute the `/remediation-verifier` skill** (if user requests verification) - -Invoke the `/remediation-verifier` skill with the instruction: -``` -"Verify remediation success for CVE-XXXX-YYYY on systems [list of system UUIDs]. Check CVE status, package versions, and service health." -``` - -**Expected behavior**: The skill will: -- Check CVE status in Lightspeed using `get_cve` and `get_cve_systems` -- Verify package versions were updated using `get_host_details` -- Confirm affected services are running properly -- Generate comprehensive verification report with pass/fail status -- Provide troubleshooting guidance for any failures - -**Your role**: Present the verification results to the user. If verification passes, confirm successful remediation. If failures occur, provide the skill's troubleshooting recommendations and offer to help resolve issues. - -## Quality Standards - -- **Accuracy**: Always validate CVE IDs before proceeding -- **Clarity**: Provide clear, actionable instructions -- **Security**: Remind users about credential handling and testing in non-prod first -- **Efficiency**: Optimize batch operations, don't process CVEs one-by-one unnecessarily -- **Completeness**: Include verification steps in all recommendations - -## Error Handling - -- **Invalid CVE**: "CVE-XXXX-YYYY is not valid or doesn't exist in the database. Please verify the CVE ID." -- **No Remediation Available**: "CVE-XXXX-YYYY doesn't have an automated remediation playbook. Manual patching required. Here are the affected packages..." -- **System Not Found**: "System XXXX is not in the Lightspeed inventory. Please ensure it's registered and check the system UUID." -- **Batch Partial Failure**: "Successfully processed X of Y CVEs. Failed CVEs: [list]. Reason: [explanations]" - -## Output Format - -For single CVE remediation: -``` -CVE-XXXX-YYYY Remediation Summary -CVSS Score: X.X (Severity: High/Medium/Low) -Affected Packages: package-name-version - -Ansible Playbook Generated: โœ“ -Target Systems: N systems -Execution Options: [AAP/Tower/Manual] - -[Include playbook YAML or console link] -[Include execution instructions] -``` - -For batch remediation: -``` -Batch Remediation Summary -CVEs: CVE-A, CVE-B, CVE-C -Target Systems: N systems -Total Fixes: X package updates - -Ansible Playbook Generated: โœ“ -Estimated Execution Time: ~X minutes - -[Include consolidated playbook] -[Include execution instructions] -[Include progress tracking guidance] -``` - -## Important Reminders - -- **๐Ÿšจ YOU MUST USE ACTUAL TOOL CALLS** - Do NOT generate text responses pretending to invoke skills. You MUST actually invoke the skills using the slash command format shown in each workflow step above. Check your tool use count - if it's 0, you're doing it wrong. - -- **Orchestrate skills, don't call MCP tools directly** - Always invoke specialized skills using the slash command format for each workflow step: - - Step 1: `/cve-impact` for CVE risk assessment - - Step 2: `/cve-validation` for CVE validation - - Step 3: `/system-context` for gathering system information - - Step 4: `/playbook-generator` for creating remediation playbooks - - Step 5: `/playbook-executor` for executing playbooks (AFTER user confirmation) - - Step 6: `/remediation-verifier` for post-remediation verification - -- **Skills handle documentation** - Skills automatically consult relevant docs (cve-remediation-templates.md, package-management.md) and use MCP tools. You don't need to read docs or call tools directly. - -- **Always ask for execution confirmation** - Before invoking playbook-executor skill, show the playbook preview and explicitly ask: "Would you like me to execute this playbook now?" Wait for user approval. - -- **Safety practices**: - - Test in non-production environments first - - Back up systems before remediation - - Schedule maintenance windows for critical systems - - Verify remediation success after execution - - Document the remediation for compliance/audit purposes - -Remember: Your goal is to make CVE remediation efficient, safe, and reliable for SREs managing RHEL systems. diff --git a/rh-sre/docs/INDEX.md b/rh-sre/docs/INDEX.md index cf409dfd..8132e300 100644 --- a/rh-sre/docs/INDEX.md +++ b/rh-sre/docs/INDEX.md @@ -36,6 +36,13 @@ This knowledge base provides comprehensive Red Hat-specific patterns for CVE rem - Red Hat severity mappings (Critical/Important/Moderate/Low) - Priority decision matrix +- **[Lightspeed MCP Parameters](references/lightspeed-mcp-parameters.md)** โœ… + - Correct parameter names for Lightspeed MCP tools (e.g. `per_page` not `page_size` for list_hosts) + - Consult before calling inventory__list_hosts to avoid validation errors + +- **[Lightspeed MCP Tool Failures](references/lightspeed-mcp-tool-failures.md)** โœ… + - Generic pattern for backend errors (e.g. explain_cves `'dnf_modules'`) โ€” user-friendly message, workarounds, no raw error exposure + - **RHEL Version Compatibility** (planned) - RHEL 7/8/9 compatibility matrix - Package naming differences diff --git a/rh-sre/docs/ansible/aap-job-execution.md b/rh-sre/docs/ansible/aap-job-execution.md index 3e5fb928..482162ef 100644 --- a/rh-sre/docs/ansible/aap-job-execution.md +++ b/rh-sre/docs/ansible/aap-job-execution.md @@ -10,7 +10,7 @@ sources: date_accessed: 2024-01-20 tags: [aap, job-execution, playbook, dry-run, check-mode] semantic_keywords: [aap job execution, ansible check mode, dry-run remediation, job template requirements, aap url structure] -use_cases: [playbook-executor, remediator] +use_cases: [playbook-executor, remediation] related_docs: [playbook-integration-aap.md, cve-remediation-templates.md] last_updated: 2024-01-20 --- diff --git a/rh-sre/docs/references/lightspeed-mcp-parameters.md b/rh-sre/docs/references/lightspeed-mcp-parameters.md new file mode 100644 index 00000000..5cf15866 --- /dev/null +++ b/rh-sre/docs/references/lightspeed-mcp-parameters.md @@ -0,0 +1,87 @@ +--- +title: Red Hat Lightspeed MCP - Parameter Reference +category: references +sources: + - title: Red Hat Lightspeed MCP + url: https://github.com/redhat/lightspeed-mcp + date_accessed: 2026-02-26 +tags: [lightspeed, mcp, parameters, inventory] +last_updated: 2026-02-26 +--- + +# Lightspeed MCP Parameter Reference + +Correct parameter names and types for Red Hat Lightspeed MCP tools. **Using wrong parameters causes validation errors.** + +## inventory__list_hosts + +**Purpose**: List hosts with filtering and sorting options. + +**CRITICAL**: Use `per_page` (integer), NOT `page_size`. The Lightspeed inventory API uses different parameter names than AAP MCP. + +| Parameter | Type | Required | Example | Notes | +|-----------|------|----------|---------|-------| +| `per_page` | **integer** | No | `10` | Use 10 on first call to avoid performance issues. NOT `page_size`. | +| `display_name` | string | No | `""` | Filter by display name. Pass empty string if no filter. | +| `page` | integer | No | `1` | Pagination page number. | + +**Correct**: +``` +inventory__list_hosts(per_page=10, display_name="") +``` + +**Wrong** (causes "Unexpected keyword argument" error): +``` +inventory__list_hosts(page_size=100) # โŒ Use per_page, not page_size +inventory__list_hosts(per_page="100") # โŒ Use integer, not string +``` + +## AAP MCP vs Lightspeed MCP + +| Server | Pagination Parameter | Type | +|--------|---------------------|------| +| lightspeed-mcp (inventory) | `per_page` | integer | +| aap-mcp-job-management | `page_size` | integer | +| aap-mcp-inventory-management | `page_size` | integer | + +Do not mix parameter names between servers. + +## vulnerability__get_cves + +**Purpose**: List CVEs affecting the account with filtering. + +| Parameter | Type | Example | Notes | +|-----------|------|---------|-------| +| `impact` | string | `"7,6"` | Comma-separated impact IDs: 7=Critical, 6=High, 5=Important, 4=Moderate | +| `sort` | string | `"-cvss_score"` | Use `-` prefix for descending | +| `limit` | integer | `20` | Max records per page | +| `advisory_available` | string | `"true"` | Filter remediatable CVEs: `"true"` = only with available advisory, `"true,false"` = all | + +**For remediatable CVEs** (user asks "which CVEs can I remediate?"): +``` +vulnerability__get_cves(impact="7,6", sort="-cvss_score", limit=20, advisory_available="true") +``` + +**For remediatable CVEs on a specific system**: `get_system_cves` does NOT support `advisory_available` as a request param. Paginate with `limit=100`, `offset=0,100,200,...` until empty; filter client-side for `attributes.advisory_available === true`. **HITL required** before paginationโ€”confirm with user (systems with 1,700+ CVEs โ‰ˆ 18 API calls). + +## vulnerability__get_system_cves + +**Purpose**: List CVEs affecting a specific system. Supports pagination. + +| Parameter | Type | Example | Notes | +|-----------|------|---------|-------| +| `system_uuid` | string (UUID) | `"68ce32aa-57da-49b7-8ded-dc4ad54e520a"` | Required | +| `limit` | integer | `100` | Records per page (default 10) | +| `offset` | integer | `0`, `100`, `200` | Pagination offset | +| `sort` | string | `"-public_date"` | Use `-` for descending | + +**Pagination**: Loop with `offset += limit` until `len(data) < limit`. Response includes `attributes.advisory_available` per CVEโ€”filter client-side for remediatable. + +## vulnerability__get_cve_systems + +**Purpose**: List systems affected by a CVE. Supports `system_uuid` filter to check if a specific system is affected. + +| Parameter | Type | Example | Notes | +|-----------|------|---------|-------| +| `cve` | string | `"CVE-2024-1234"` | Required | +| `system_uuid` | string | `"68ce32aa-57da-49b7-8ded-dc4ad54e520a"` | Filter to check if this system is affected | diff --git a/rh-sre/docs/references/lightspeed-mcp-tool-failures.md b/rh-sre/docs/references/lightspeed-mcp-tool-failures.md new file mode 100644 index 00000000..10961ae8 --- /dev/null +++ b/rh-sre/docs/references/lightspeed-mcp-tool-failures.md @@ -0,0 +1,55 @@ +--- +title: Lightspeed MCP Tool Failures โ€” Handling and Workarounds +category: references +tags: [lightspeed, mcp, troubleshooting, errors] +last_updated: 2026-03-02 +--- + +# Lightspeed MCP Tool Failures + +When Lightspeed MCP tools fail with cryptic backend errors (e.g. KeyError, missing keys), follow this pattern instead of exposing the raw error. + +## Generic Pattern + +1. **Do NOT** expose the raw error to the user (e.g. `'dnf_modules'`, `KeyError: 'xyz'`) +2. **Show** a user-friendly message explaining what happened and what we know +3. **Use** alternative tools to achieve the same goal when possible +4. **Do NOT** retry the failing toolโ€”backend errors typically persist for the same request + +## Known Failures and Workarounds + +### vulnerability__explain_cves โ€” `'dnf_modules'` (or similar KeyError) + +**Error**: `Error calling tool 'explain_cves': 'dnf_modules'` + +**Cause**: Backend expects a `dnf_modules` key in the system profile; some systems don't include it. + +**User-friendly message**: +``` +โš ๏ธ CVE explanation unavailable for this system + +The detailed "why this CVE affects your system" explanation could not be retrieved. +This sometimes happens when the system profile is missing module data. + +**What we know** (from other sources): +- CVE: [CVE-ID] +- Affected system: [hostname] +- Severity: [from get_cve] +- Affected packages: [from get_cve] + +**Next steps**: Proceeding with available data. The playbook will still address the CVE correctly. +``` + +**Workaround**: Synthesize from `get_cve` + `get_host_details`: +1. `get_cve(cve_id)` โ†’ affected_packages, severity, advisory +2. `get_host_details(system_id)` โ†’ installed_packages +3. Match and explain: "CVE-X affects system Y because [package] is installed at [version]. Fix: [advisory]." + +**Skills**: cve-impact (if explaining why CVE affects system); remediation and system-context do NOT use explain_cves. + +### Other Tool Failures + +When a different tool fails with a similar cryptic error: +1. Apply the generic pattern (no raw error, user-friendly message) +2. Identify alternative tools that provide equivalent data +3. Add the failure and workaround to this doc for future reference diff --git a/rh-sre/docs/references/skill-invocation.md b/rh-sre/docs/references/skill-invocation.md new file mode 100644 index 00000000..132854c8 --- /dev/null +++ b/rh-sre/docs/references/skill-invocation.md @@ -0,0 +1,35 @@ +--- +title: Skill Invocation Reference +category: references +tags: [skills, invocation, troubleshooting] +last_updated: 2026-03-02 +--- + +# Skill Invocation Reference + +Guidance for correctly invoking skills in the rh-sre pack across different AI hosts (Cursor, Claude Code, etc.). + +## Invoking Skills (All Sub-Skills) + +When the remediation skill (or other orchestrators) invokes any sub-skillโ€”validators, cve-validation, cve-impact, system-context, playbook-generator, playbook-executor, remediation-verifier: + +- **Use the Skill tool** with the skill name. Format may vary by host: + - Cursor: `Skill(rh-sre:mcp-lightspeed-validator)` or similar + - Claude Code: `/mcp-lightspeed-validator` or `Skill(mcp-lightspeed-validator)` +- **Wait for the skill to complete**โ€”skills typically return output directly. Do NOT proceed to the next step until you have the skill's actual result (e.g. validation PASSED/FAILED). "Successfully loaded skill" indicates the skill was loaded, not that it finishedโ€”wait for the validation outcome before continuing. +- **Do NOT use "Task Output" with the skill name as the task ID.** If you see "No task found with ID: mcp-lightspeed-validator" (or cve-validation, cve-impact, etc.), you are passing the skill name to a Task Output tool. Task Output expects the task ID returned from an async invocation (e.g. a UUID), NOT the skill name. Skill names are not task IDs. + +## If Validator Invocation Fails + +If validator invocation returns "No task found" or similar: + +1. **Do NOT block the workflow.** Proceed with a warning. +2. **Inform the user**: "Validator invocation encountered an issue. Proceeding with remediation workflowโ€”MCP operations in later steps will confirm connectivity." +3. **Continue to Step 2** (cve-validation). The `get_cve` call will fail if Lightspeed MCP is unavailable. +4. **Continue to Step 5** (playbook-executor). AAP MCP calls will fail if AAP is unavailable. + +The workflow is resilient: actual MCP tool calls in later steps serve as implicit validation. Do not retry Task Output with the skill name. + +## Validation Freshness + +If validation was performed earlier in the same session and succeeded, you may skip re-invoking validators. See each validator skill's "Validation Freshness Policy" section. diff --git a/rh-sre/docs/testing/aap-integration-test-guide.md b/rh-sre/docs/testing/aap-integration-test-guide.md index ce05e4dd..e92ba8c6 100644 --- a/rh-sre/docs/testing/aap-integration-test-guide.md +++ b/rh-sre/docs/testing/aap-integration-test-guide.md @@ -6,7 +6,7 @@ sources: date_accessed: 2024-01-20 tags: [testing, aap-integration, workflow-verification, remediation-testing] semantic_keywords: [aap integration testing, workflow verification, remediation test] -use_cases: [remediator, playbook-executor] +use_cases: [remediation, playbook-executor] related_docs: [aap-job-execution.md, playbook-integration-aap.md] last_updated: 2024-01-20 --- @@ -401,7 +401,7 @@ Would you like to: **Objective**: Test complete CVE remediation from analysis to verification. **Steps**: -1. **Invoke remediator agent** with a known CVE +1. **Invoke remediation skill** with a known CVE 2. **Impact Analysis**: Review CVE risk assessment 3. **CVE Validation**: Confirm CVE is valid and has remediation 4. **System Context**: Review affected systems and strategy @@ -444,7 +444,7 @@ User: "Remediate CVE-YYYY-NNNNN on my test systems" **Objective**: Test batch remediation of multiple CVEs. **Steps**: -1. Invoke remediator agent with 2-3 CVEs +1. Invoke remediation skill with 2-3 CVEs 2. Verify agent handles batch processing 3. Confirm single consolidated playbook generated 4. Execute remediation diff --git a/rh-sre/skills/cve-impact/SKILL.md b/rh-sre/skills/cve-impact/SKILL.md index a400f2eb..82aa9c29 100644 --- a/rh-sre/skills/cve-impact/SKILL.md +++ b/rh-sre/skills/cve-impact/SKILL.md @@ -6,6 +6,8 @@ description: | Use this skill when users request: - Listing critical/high-severity CVEs: "show me critical vulnerabilities", "what are the most critical CVEs", "list all high-severity vulnerabilities" - CVE discovery: "what vulnerabilities affect my account", "show me all CVEs", "what are my security risks" + - Remediatable CVEs: "which CVEs can I remediate?", "show remediatable vulnerabilities", "CVEs with available advisory" + - CVEs affecting a specific system: "what CVEs affect hostname X?", "what vulnerabilities are on ip-172-31-32-201?" - CVE impact analysis for specific CVEs: "what's the impact of CVE-X?", "analyze CVE-Y" - Risk assessment: "which CVEs are most urgent?", "prioritize vulnerabilities" - Understanding affected systems for a CVE @@ -13,20 +15,30 @@ description: | - CVE discovery and prioritization (information gathering) DO NOT use this skill when users request remediation actions like: - - "Create a remediation playbook" (use sre-agents:remediator agent) - - "Patch CVE-X on system Y" (use sre-agents:remediator agent) - - "Remediate these CVEs" (use sre-agents:remediator agent) + - "Create a remediation playbook" (use `/remediation` skill) + - "Patch CVE-X on system Y" (use `/remediation` skill) + - "Remediate these CVEs" (use `/remediation` skill) - This skill orchestrates MCP tools (get_cves, get_cve, get_cve_systems) to provide comprehensive CVE analysis with Red Hat Lightspeed context. When users ask for remediation after seeing the analysis, invoke the `sre-agents:remediator` agent. + This skill orchestrates MCP tools (get_cves, get_cve, get_cve_systems, get_system_cves) to provide comprehensive CVE analysis with Red Hat Lightspeed context. When users ask for remediation after seeing the analysis, invoke the `/remediation` skill. **IMPORTANT**: ALWAYS use this skill instead of calling get_cves or other vulnerability MCP tools directly. + + **System-level (CVEs on device X)**: Your FIRST reply must be the pagination prompt. Do NOT call inventory__find_host_by_name or vulnerability__get_system_cves until user responds. See Step -1. + + **Parsing**: Use references/01-cve-response-parser.py. Do NOT use jq or inline Python. --- # CVE Impact Analysis Skill This skill helps SREs analyze CVE vulnerabilities to understand their impact on systems before creating remediation playbooks. -**Integration with Remediator Agent**: The sre-agents:remediator agent (invoked) orchestrates this skill as part of its Step 1 (Impact Analysis) workflow for complex remediation scenarios. For simple standalone impact analysis, you can invoke this skill directly. +**๐Ÿšจ SYSTEM-LEVEL (CVEs on device X)**: Your **first reply** to the user MUST be the pagination prompt (Step -1). Do NOT call `inventory__find_host_by_name` or `vulnerability__get_system_cves` until the user responds. Do not validate MCP or resolve hostname firstโ€”HITL comes first. + +**Integration with Remediation Skill**: The `/remediation` skill orchestrates this skill as part of its Step 1 (Impact Analysis) workflow for complex remediation scenarios. For simple standalone impact analysis, you can invoke this skill directly. + +## Invocation Note (Host-Specific) + +When invoked by another skill (e.g. remediation), use the Skill toolโ€”do NOT use "Task Output" with the skill name as task ID. That causes "No task found with ID: cve-impact". See [skill-invocation.md](../../../docs/references/skill-invocation.md). ## Prerequisites @@ -36,6 +48,7 @@ This skill helps SREs analyze CVE vulnerabilities to understand their impact on - `get_cves` (from lightspeed-mcp) - List/query CVEs by severity - `get_cve` (from lightspeed-mcp) - Get specific CVE details - `get_cve_systems` (from lightspeed-mcp) - Find systems affected by CVEs +- `get_system_cves` (from lightspeed-mcp) - List CVEs affecting a specific system (uses `system_uuid` only) **Required Environment Variables**: - `LIGHTSPEED_CLIENT_ID` - Red Hat Lightspeed service account client ID @@ -43,15 +56,11 @@ This skill helps SREs analyze CVE vulnerabilities to understand their impact on ### Prerequisite Validation -**CRITICAL**: Before executing any operations, invoke the [mcp-lightspeed-validator](../mcp-lightspeed-validator/SKILL.md) skill to verify MCP server availability. +**CRITICAL**: Before executing any operations, execute the `/mcp-lightspeed-validator` skill to verify MCP server availability. **Validation freshness**: Can skip if already validated in this session. See [Validation Freshness Policy](../mcp-lightspeed-validator/SKILL.md#validation-freshness-policy). -**How to invoke**: -``` -Use the Skill tool: - skill: "mcp-lightspeed-validator" -``` +**How to invoke**: Execute the `/mcp-lightspeed-validator` skill **Handle validation result**: - **If validation PASSED**: Continue with CVE impact analysis @@ -67,95 +76,123 @@ Use the Skill tool: - CVE severity assessments for change management documentation - Risk assessment reports for management -**Use the sre-agents:remediator agent when you need**: +**Use the `/remediation` skill when you need**: - CVE analysis followed by remediation playbook generation - Complex workflows involving multiple CVEs and systems - Integrated risk assessment + remediation planning + execution guidance - Batch remediation across infrastructure - End-to-end CVE management (analysis โ†’ validation โ†’ remediation โ†’ verification) -**To invoke**: Use the `sre-agents:remediator` agent +**To invoke**: Execute the `/remediation` skill -**How they work together**: The sre-agents:remediator agent orchestrates this skill as part of its comprehensive workflow, combining impact analysis with context gathering, playbook generation, and execution guidance. The agent uses the skill's analysis capabilities and extends them with remediation planning. +**How they work together**: The `/remediation` skill orchestrates this skill as part of its comprehensive workflow, combining impact analysis with context gathering, playbook generation, and execution guidance. ## Workflow -### Step 0: Validate Lightspeed MCP Prerequisites +### Step -1: System-Level Gate โ€” HITL FIRST (MANDATORY) -**Action**: Invoke the [mcp-lightspeed-validator](../mcp-lightspeed-validator/SKILL.md) skill +**If the user asked for CVEs on a device** (e.g. "CVEs on ip-172-31-32-201", "remediatable CVEs on hostname X", "most critical CVEs on system Y"): -**Note**: Can skip if validation was performed earlier in this session and succeeded. See [Validation Freshness Policy](../mcp-lightspeed-validator/SKILL.md#validation-freshness-policy). +**Your first response to the user MUST be the pagination prompt below. Do not run Step 0, do not call `inventory__find_host_by_name`, do not call `vulnerability__get_system_cves` until the user responds.** + +Reply to the user with: -**How to invoke**: ``` -Use the Skill tool: - skill: "mcp-lightspeed-validator" +To fetch remediatable CVEs on this system, I will: +- Paginate through vulnerability__get_system_cves (limit=100 per page) +- Filter each page for advisory_available === true +- Systems often have 1,700+ CVEs (~18 API calls) + +โš ๏ธ First page only often returns 0 remediatable CVEsโ€”they may be on any page. For "remediatable" queries, recommend "all pages". + +Options: +- **First page only**: Fetch 100 CVEs, filter for remediatable (may be 0) +- **All pages**: Fetch until no more results (recommended for remediatable) +- **N pages**: Fetch up to N pages (e.g. "3 pages" = up to 300 CVEs scanned) + +How would you like to proceed? (first page / all pages / N pages) ``` +**Wait for the user to respond.** Only after they reply may you proceed to Step 0. + +**If account-level** (e.g. "CVEs on my account"): Skip this step, go to Step 0. + +--- + +### Step 0: Validate Lightspeed MCP Prerequisites + +**Action**: Execute the `/mcp-lightspeed-validator` skill + +**Note**: Can skip if validation was performed earlier in this session and succeeded. See [Validation Freshness Policy](../mcp-lightspeed-validator/SKILL.md#validation-freshness-policy). + +**How to invoke**: Execute the `/mcp-lightspeed-validator` skill + **Handle validation result**: - **If validation PASSED**: Continue to Step 1 - **If validation PARTIAL**: Warn user and ask to proceed - **If validation FAILED**: Stop execution, user must set up MCP server -### Step 1: List Critical CVEs (Optional - For Discovery Queries) +### Step 1: CVE Discovery โ€” Choose Flow -**Use this step when users ask**: "What are the critical vulnerabilities?", "Show me high-severity CVEs", "List all vulnerabilities on my account" +Select the appropriate flow based on user request. -**CRITICAL**: Document consultation MUST happen BEFORE tool invocation. +| Flow | When to Use | Flow File | +|------|-------------|-----------| +| **Account-level** | devices=all (account-wide CVEs) | [01-account-cves.md](flows/01-account-cves.md) | +| **System-level (all CVEs)** | devices=selected, remediation=does not matter | [02-system-all-cves.md](flows/02-system-all-cves.md) | +| **System-level (remediatable)** | devices=selected, remediation=available | [03-system-remediatable-cves.md](flows/03-system-remediatable-cves.md) | -**Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [vulnerability-logic.md](../../docs/insights/vulnerability-logic.md) using the Read tool to understand CVE severity classification and filtering logic -2. **Output to user**: "I consulted [vulnerability-logic.md](../../docs/insights/vulnerability-logic.md) to understand CVE severity classification and filtering." +**Variable mapping**: +- **devices**: all โ†’ account flow; selected โ†’ system flow +- **severities**: all, most critical, or selected โ†’ parameter/filter in each flow +- **remediation**: available โ†’ remediatable flow; does not matter โ†’ all-cves flow -**MCP Tool**: `get_cves` or `vulnerability__get_cves` (from lightspeed-mcp) +--- -**Parameters**: -- `impact`: `"7,6"` (string with comma-separated impact levels where 7=Important, 6=Moderate, 5=Low) -- `sort`: `"-cvss_score"` (sort by field with `-` prefix for descending order; valid fields: "cvss_score", "public_date") -- `limit`: `20` (maximum number of CVEs to return) - -**Expected Output**: List of CVEs with metadata (CVE ID, CVSS score, severity, affected system count, remediation availability) - -Retrieve all CVEs affecting the account, filtered by severity: -```bash -# Get all CVEs with Important and Moderate severity (impact levels 7, 6) -# Sorted by CVSS score descending -get_cves( - impact="7,6", - sort="-cvss_score", - limit=20 -) - -# Example tool invocation after document consultation: -# Step 1: Read vulnerability-logic.md (required) -# Step 2: Output "I consulted..." message (required) -# Step 3: Call MCP tool with correct parameters: - -vulnerability__get_cves( - impact="7,6", - sort="-cvss_score", - limit=20 -) - -# Expected output: -CVE-2024-1234 (CVSS 9.8, Important) - kernel - Affected systems: 15 - Remediation: Available - -CVE-2024-5678 (CVSS 8.1, Important) - httpd - Affected systems: 8 - Remediation: Available - -CVE-2024-9012 (CVSS 7.5, Important) - openssl - Affected systems: 25 - Remediation: Available +#### CRITICAL: System-Level โ€” HITL FIRST (Before Any Other Action) + +**For system-level flows (02 or 03)**: Your **first** action MUST be to display the HITL prompt below and **wait for user confirmation**. Do NOT resolve hostname, do NOT call any MCP tool, until the user responds. + +**Order of operations**: +1. **STOP. Display HITL prompt. Wait for user.** +2. Only after user confirms โ†’ document consultation โ†’ resolve hostname โ†’ call `vulnerability__get_system_cves` + +*For remediatable CVEs on system (flow 03):* +``` +To fetch remediatable CVEs on this system, I will: +- Paginate through vulnerability__get_system_cves (limit=100 per page) +- Filter each page for advisory_available === true +- Systems often have 1,700+ CVEs (~18 API calls) + +โš ๏ธ First page only often returns 0 remediatable CVEsโ€”they may be on any page. For "remediatable" queries, recommend "all pages". + +Options: +- **First page only**: Fetch 100 CVEs, filter for remediatable (may be 0) +- **All pages**: Fetch until no more results (recommended for remediatable) +- **N pages**: Fetch up to N pages (e.g. "3 pages" = up to 300 CVEs scanned) + +How would you like to proceed? (first page / all pages / N pages) +``` + +*For all CVEs on system (flow 02):* +``` +This system may have many CVEs. I will paginate through vulnerability__get_system_cves (limit=100 per page). + +Options: +- **First page only**: Fetch 100 CVEs, then stop (quick overview) +- **All pages**: Fetch until no more results (systems with 1,700+ CVEs may require ~18 API calls) +- **N pages**: Fetch up to N pages (e.g. "3 pages" = 300 CVEs) + +How would you like to proceed? (first page / all pages / N pages) ``` -**After listing CVEs**: -- Sort by CVSS score (highest first) or by number of affected systems -- Provide summary table with CVE ID, severity, affected systems count, remediation availability -- Offer to analyze any specific CVE in detail (use Step 1 below) -- Offer to create remediation plan (invoke the `sre-agents:remediator` agent) +**Handle response**: Wait for user reply. Only after user confirms (and specifies strategy) may you proceed to resolve hostname and call `vulnerability__get_system_cves`. If user says "no" or cancels, stop execution. + +**Anti-pattern**: Do NOT call `vulnerability__get_system_cves` or `inventory__find_host_by_name` before completing HITL. Calling with only the first page (limit=100, no offset loop) misses remediatable CVEs on later pages. + +--- + +**Action**: Read and follow the selected flow file. For system-level, HITL is Step 1 (before all other steps). ### Step 2: CVE Information Retrieval (For Specific CVE Analysis) @@ -370,7 +407,7 @@ When completing a CVE impact analysis, provide output in this format: ## Next Steps 1. [ ] Approve remediation plan 2. [ ] Schedule maintenance window (if needed) -3. [ ] Create remediation playbook (use sre-agents:remediator agent) +3. [ ] Create remediation playbook (use `/remediation` skill) 4. [ ] Test in staging environment 5. [ ] Execute in production 6. [ ] Verify remediation success @@ -383,9 +420,11 @@ When completing a CVE impact analysis, provide output in this format: **User Request**: "What are the most critical vulnerabilities on my account?" **Skill Response**: -1. Call `get_cves(severity=["Critical", "Important"], sort_by="cvss_score", limit=20)` -2. Parse and sort results by CVSS score -3. Return summary table: +1. Follow [01-account-cves.md](flows/01-account-cves.md) (severity=most critical, remediation=does not matter) +2. HITL: Confirm limit (default 20) before calling +3. Call `vulnerability__get_cves(impact="7,6", sort="-cvss_score", limit=20, advisory_available="true,false")` +4. Parse and sort results by CVSS score +5. Return summary table: ```markdown # Critical Vulnerabilities Summary @@ -409,10 +448,23 @@ Found 12 Critical/Important CVEs affecting your systems: - Create remediation plan: "Remediate CVE-2024-1234 on all affected systems" ``` -4. Wait for user to request specific CVE analysis or remediation -5. If user says "remediate CVE-X", respond: "I'll transition to the sre-agents:remediator agent to create the remediation playbook" (invoke the `sre-agents:remediator` agent) +6. Wait for user to request specific CVE analysis or remediation +7. If user says "remediate CVE-X", respond: "I'll use the remediation skill to create the remediation playbook" (invoke the `/remediation` skill) + +### Example 1: CVEs Affecting a Specific System -### Example 1: High-Severity CVE Analysis +**User Request**: "What CVEs are affecting ip-172-31-32-201.eu-west-3.compute.internal?" + +**Skill Response**: +1. Follow [02-system-all-cves.md](flows/02-system-all-cves.md) (remediation=does not matter) +2. HITL: Ask pagination strategy (first page / all pages / N pages) +3. Resolve hostname to UUID: `inventory__find_host_by_name(hostname="ip-172-31-32-201.eu-west-3.compute.internal")` +4. Call `vulnerability__get_system_cves(system_uuid="", limit=100, offset=0)` per chosen strategy +5. Sort and present results by CVSS score +6. If user asked for "critical only", filter the returned list client-side +7. Offer to analyze specific CVEs or create remediation plan + +### Example 2: High-Severity CVE Analysis **User Request**: "Analyze the impact of CVE-2024-1234" @@ -421,9 +473,9 @@ Found 12 Critical/Important CVEs affecting your systems: 2. List affected systems using `get_cve_systems` 3. Classify systems by environment and criticality 4. Provide risk assessment and recommendations -5. Suggest next steps (use sre-agents:remediator agent if remediation needed) +5. Suggest next steps (use `/remediation` skill if remediation needed) -### Example 2: Multiple CVE Comparison +### Example 3: Multiple CVE Comparison **User Request**: "Compare the impact of CVE-2024-1234 and CVE-2024-5678" @@ -433,7 +485,7 @@ Found 12 Critical/Important CVEs affecting your systems: 3. Recommend prioritization order 4. Suggest batch remediation if both should be fixed together -### Example 3: Environment-Specific Analysis +### Example 4: Environment-Specific Analysis **User Request**: "Which production systems are affected by CVE-2024-1234?" @@ -452,7 +504,7 @@ After completing impact analysis, the skill should: Based on this analysis, immediate remediation is recommended. Would you like me to create a remediation playbook? - (This will invoke the sre-agents:remediator agent) + (This will invoke the `/remediation` skill) ``` 2. **Provide context for remediation**: @@ -492,6 +544,31 @@ Possible reasons: No action required. ``` +**Lightspeed tool failures** (e.g. explain_cves `'dnf_modules'`): Do NOT show raw error. Do NOT retry. Use user-friendly message and workaround (get_cve + get_host_details synthesis) from [lightspeed-mcp-tool-failures.md](../../../docs/references/lightspeed-mcp-tool-failures.md). + +## Reference Files + +| File | Use When | +|------|----------| +| [01-cve-response-parser.py](references/01-cve-response-parser.py) | Parse/filter MCP vulnerability responses | +| [02-cve-parsing-guide.md](references/02-cve-parsing-guide.md) | How to invoke parser, filter options, response structure | +| [lightspeed-mcp-tool-failures.md](../../../docs/references/lightspeed-mcp-tool-failures.md) | Lightspeed tool failures (e.g. explain_cves 'dnf_modules') โ€” user-friendly message and workarounds | + +## Parsing MCP Responses + +**REQUIRED**: Use the skill's parser script for all vulnerability response parsing. Do NOT use jq, inline Python, or other ad-hoc JSON parsing. + +**Do NOT generate inline Python** to aggregate multiple page filesโ€”the parser accepts multiple file paths and produces aggregated reports. + +**Read** [references/02-cve-parsing-guide.md](references/02-cve-parsing-guide.md) for: +- Parser location: `references/01-cve-response-parser.py` +- Single page: `python3 rh-sre/skills/cve-impact/references/01-cve-response-parser.py ` +- Multiple pages: `python3 .../01-cve-response-parser.py page1.json page2.json page3.json ...` (merges, dedupes, aggregated report) +- Filter options: `FILTER_REMEDIATABLE=1`, `FILTER_IMPACT=Critical,Important` +- Report format: `OUTPUT=report`, `SYSTEM_NAME=hostname` for aggregated multi-page reports + +Save each MCP tool result to a file, then run the parser with one or more paths. Use parser output for summary tables and reports. + ## Best Practices 1. **Always start with risk assessment** before deciding on remediation @@ -519,6 +596,11 @@ No action required. - Parameters: cve_id (string), include_patched (boolean) - Returns: List of affected systems with UUID, hostname, package version, status +- `get_system_cves` (from lightspeed-mcp) - List CVEs affecting a specific system + - Parameters: **system_uuid** (string, required) - use `system_uuid`, NOT `system_id` + - Does NOT support: impact, limit, severity filters - filter results client-side + - Returns: List of CVEs affecting the system + ### Related Skills - `mcp-lightspeed-validator` - **PREREQUISITE** - Validates Lightspeed MCP server before operations - Use before: ALL cve-impact operations (Step 0 in workflow) @@ -541,6 +623,7 @@ No action required. - [vulnerability-logic.md](../../docs/insights/vulnerability-logic.md) - CVE severity classification and filtering - [insights-api.md](../../docs/insights/insights-api.md) - System identification response format - [fleet-management.md](../../docs/insights/fleet-management.md) - System tagging and classification strategies +- [references/02-cve-parsing-guide.md](references/02-cve-parsing-guide.md) - Parse MCP vulnerability responses; use the parser script instead of generating inline Python ## Tools Reference @@ -548,7 +631,10 @@ This skill primarily uses: - `get_cve` (vulnerability toolset) - Get details about a specific CVE - `get_cve_systems` (vulnerability toolset) - Get list of systems affected by a CVE - `get_cves` (vulnerability toolset) - Get list of all CVEs affecting the account (optional) -- `get_system_cves` (vulnerability toolset) - Get list of CVEs affecting a specific system (optional) +- `get_system_cves` (vulnerability toolset) - Get list of CVEs affecting a specific system + - **CRITICAL**: Use `system_uuid` (required), NOT `system_id` + - Does NOT support `impact`, `limit`, or severity filters - filter client-side +- `inventory__find_host_by_name` (inventory toolset) - Resolve hostname to system UUID before get_system_cves - `get_host_details` (inventory toolset) - Get detailed system information (optional) All tools are provided by the lightspeed-mcp MCP server configured in `.mcp.json`. diff --git a/rh-sre/skills/cve-impact/flows/01-account-cves.md b/rh-sre/skills/cve-impact/flows/01-account-cves.md new file mode 100644 index 00000000..d981a9e9 --- /dev/null +++ b/rh-sre/skills/cve-impact/flows/01-account-cves.md @@ -0,0 +1,92 @@ +# Flow: Account-Level CVEs + +**Scope**: devices=all (account-wide) | severities=all, most critical, or selected | remediation=available or does not matter + +**Tool**: `vulnerability__get_cves` (single request; no offset pagination in API) + +## When to Use + +- "What are the critical vulnerabilities on my account?" +- "Show me high-severity CVEs" +- "List all vulnerabilities affecting my account" +- "Which CVEs can I remediate?" (account-wide) + +## Step 1: Document Consultation (REQUIRED - Execute FIRST) + +1. **Action**: Read [vulnerability-logic.md](../../../docs/insights/vulnerability-logic.md) using the Read tool +2. **Output to user**: "I consulted [vulnerability-logic.md](../../../docs/insights/vulnerability-logic.md) to understand CVE severity classification and filtering." + +## Step 2: HITL Checkpoint โ€” Pagination / Limit + +**Before** calling the API, display and wait for confirmation: + +``` +For account-level CVEs, I will fetch up to {limit} CVEs per request. +The API returns a single page (no offset pagination). + +Options: +- Default: limit=20 (top CVEs by CVSS score) +- You may request a different limit (e.g. 10, 50) before I proceed + +Proceed with limit=20? (yes/no) Or specify a different limit. +``` + +**Handle response**: +- **yes** or no limit specified โ†’ use `limit=20` +- **User specifies N** โ†’ use `limit=N` +- **no** โ†’ Stop execution + +## Step 3: MCP Tool Invocation + +**Tool**: `vulnerability__get_cves` (from lightspeed-mcp) + +**Parameters**: + +| Parameter | Severity=all | Severity=most critical | Severity=selected | +|-----------|-------------|------------------------|-------------------| +| `impact` | `"7,6,5,4"` | `"7,6"` | e.g. `"7"` (Critical only) or `"6,5"` | + +| Parameter | Remediation=available | Remediation=does not matter | +|-----------|----------------------|------------------------------| +| `advisory_available` | `"true"` | `"true,false"` | + +**Common parameters**: +- `sort`: `"-cvss_score"` (descending by CVSS) +- `limit`: From HITL (default 20) + +**Example** (most critical, remediatable): +``` +vulnerability__get_cves( + impact="7,6", + sort="-cvss_score", + limit=20, + advisory_available="true" +) +``` + +**Example** (all severities, remediation doesn't matter): +``` +vulnerability__get_cves( + impact="7,6,5,4", + sort="-cvss_score", + limit=20, + advisory_available="true,false" +) +``` + +## Step 4: After Listing + +- **Parse response** (if needed): Use [references/01-cve-response-parser.py](../references/01-cve-response-parser.py). Do NOT use jq or inline Python. See [02-cve-parsing-guide.md](../references/02-cve-parsing-guide.md). +- Sort by CVSS score (highest first) or by affected system count +- Provide summary table: CVE ID, severity, affected systems count, remediation availability +- Offer to analyze a specific CVE (see [SKILL.md](../SKILL.md) โ€” Step 2: CVE Information Retrieval) +- Offer to create remediation plan (invoke `/remediation` skill) + +## Impact Level Reference + +| impact | Severity | +|--------|----------| +| 7 | Critical | +| 6 | High | +| 5 | Important | +| 4 | Moderate | diff --git a/rh-sre/skills/cve-impact/flows/02-system-all-cves.md b/rh-sre/skills/cve-impact/flows/02-system-all-cves.md new file mode 100644 index 00000000..6a819454 --- /dev/null +++ b/rh-sre/skills/cve-impact/flows/02-system-all-cves.md @@ -0,0 +1,89 @@ +# Flow: System-Level CVEs (All โ€” Remediation Does Not Matter) + +**Scope**: devices=selected | severities=all, most critical, or selected | remediation=does not matter + +**Tool**: `vulnerability__get_system_cves` (paginated via `limit` + `offset`) + +**BLOCKING**: HITL (Step -1 in SKILL.md) MUST be your first action. Reply to the user with the pagination prompt before ANY tool call. Do NOT proceed to this flow until the user has responded to the HITL prompt. + +## When to Use + +- "What CVEs affect hostname X?" +- "What vulnerabilities are on system Y?" +- "Show CVEs for ip-172-31-32-201.eu-west-3.compute.internal" +- (When user does NOT specifically ask for remediatable-only) + +## Step 1: HITL โ€” Pagination Strategy (Done in SKILL.md Step -1) + +**If you have not yet replied to the user with the pagination prompt**: Stop. Go to [SKILL.md](../SKILL.md) Step -1. Your first reply to the user must be the prompt below. Do NOT call `inventory__find_host_by_name` or `vulnerability__get_system_cves` until the user responds. + +``` +This system may have many CVEs. I will paginate through vulnerability__get_system_cves (limit=100 per page). + +Options: +- **First page only**: Fetch 100 CVEs, then stop (quick overview) +- **All pages**: Fetch until no more results (systems with 1,700+ CVEs may require ~18 API calls) +- **N pages**: Fetch up to N pages (e.g. "3 pages" = 300 CVEs) + +How would you like to proceed? (first page / all pages / N pages) +``` + +**Handle response**: +- **first page** โ†’ Single call: `limit=100`, `offset=0`; stop after first response +- **all pages** โ†’ Loop: `offset=0, 100, 200, ...` until `len(data) < 100` or empty +- **N pages** โ†’ Loop N times: `offset=0`, then `offset=100`, ... up to N pages +- **no** or cancel โ†’ Stop execution + +## Step 2: Document Consultation (REQUIRED - Execute AFTER HITL) + +1. **Action**: Read [insights-api.md](../../../docs/insights/insights-api.md) using the Read tool +2. **Output to user**: "I consulted [insights-api.md](../../../docs/insights/insights-api.md) to understand system identification." + +## Step 3: Resolve Hostname to System UUID + +**If user provided hostname** (not UUID): +- **Tool**: `inventory__find_host_by_name` (preferred) or `inventory__list_hosts` +- **inventory__list_hosts**: Use `per_page` (integer), NOT `page_size`; pass `display_name=""` if no filter +- If multiple matches: ask user to disambiguate or use first match with a note + +## Step 4: MCP Tool Invocation + +**Tool**: `vulnerability__get_system_cves` (from lightspeed-mcp) + +**Parameters**: +- `system_uuid`: Required (from Step 2) +- `limit`: `100` (fewer pages) +- `offset`: `0`, `100`, `200`, ... per pagination strategy + +**First call** (to get total estimate if available): +``` +vulnerability__get_system_cves(system_uuid="", limit=100, offset=0) +``` +Check `meta.count` in response for total estimate. + +**Pagination loop** (if user chose "all pages" or "N pages"): +``` +offset = 0 +all_cves = [] +while (strategy allows): + result = vulnerability__get_system_cves(system_uuid="...", limit=100, offset=offset) + all_cves.extend(result.data) + if len(result.data) < 100: break + offset += 100 +``` + +## Step 5: Filter by Severity (Client-Side) + +`get_system_cves` does NOT support severity filters. Filter results client-side: + +| Severity choice | Filter | +|-----------------|--------| +| all | No filter | +| most critical | Keep items where severity in (Critical, High) | +| selected | Keep items matching user-specified severity | + +## Step 6: After Retrieval + +- **Parse response**: Use [references/01-cve-response-parser.py](../references/01-cve-response-parser.py). Do NOT use jq or inline Python. See [02-cve-parsing-guide.md](../references/02-cve-parsing-guide.md). +- Sort by CVSS score (highest first) +- Provide summary table; offer to analyze specific CVEs or create remediation plan (`/remediation` skill) diff --git a/rh-sre/skills/cve-impact/flows/03-system-remediatable-cves.md b/rh-sre/skills/cve-impact/flows/03-system-remediatable-cves.md new file mode 100644 index 00000000..a1351e79 --- /dev/null +++ b/rh-sre/skills/cve-impact/flows/03-system-remediatable-cves.md @@ -0,0 +1,96 @@ +# Flow: System-Level CVEs (Remediatable Only) + +**Scope**: devices=selected | severities=all, most critical, or selected | remediation=available + +**Tool**: `vulnerability__get_system_cves` (paginated; filter client-side for `advisory_available === true`) + +**BLOCKING**: HITL (Step -1 in SKILL.md) MUST be your first action. Reply to the user with the pagination prompt before ANY tool call. Do NOT proceed to this flow until the user has responded to the HITL prompt. + +## When to Use + +- "Remediatable CVEs on system X" +- "CVEs with available remediation on device Y" +- "Which CVEs can I fix on hostname Z?" + +**CRITICAL**: `get_system_cves` does NOT support `advisory_available` as a request parameter. We must paginate through ALL CVEs and filter client-side for `attributes.advisory_available === true`. Do NOT use `get_cves` + `get_cve_systems` per CVEโ€”does not scale. + +## Step 1: HITL โ€” Pagination Strategy (Done in SKILL.md Step -1) + +**If you have not yet replied to the user with the pagination prompt**: Stop. Go to [SKILL.md](../SKILL.md) Step -1. Your first reply to the user must be the prompt below. Do NOT call `inventory__find_host_by_name` or `vulnerability__get_system_cves` until the user responds. + +``` +To fetch remediatable CVEs on this system, I will: +- Paginate through vulnerability__get_system_cves (limit=100 per page) +- Filter each page for advisory_available === true +- Systems often have 1,700+ CVEs (~18 API calls) + +โš ๏ธ First page only often returns 0 remediatable CVEsโ€”they may be on any page. For "remediatable" queries, recommend "all pages". + +Options: +- **First page only**: Fetch 100 CVEs, filter for remediatable (may be 0) +- **All pages**: Fetch until no more results (recommended for remediatable) +- **N pages**: Fetch up to N pages (e.g. "3 pages" = up to 300 CVEs scanned) + +How would you like to proceed? (first page / all pages / N pages) +``` + +**Handle response**: +- **first page** โ†’ Single call: `limit=100`, `offset=0`; filter for remediatable; stop +- **all pages** โ†’ Loop until empty; filter each page for remediatable +- **N pages** โ†’ Loop N times; filter each page for remediatable +- **no** or cancel โ†’ Stop execution + +## Step 2: Document Consultation (REQUIRED - Execute AFTER HITL) + +1. **Action**: Read [insights-api.md](../../../docs/insights/insights-api.md) using the Read tool +2. **Output to user**: "I consulted [insights-api.md](../../../docs/insights/insights-api.md) to understand system identification." + +## Step 3: Resolve Hostname to System UUID + +**If user provided hostname** (not UUID): +- **Tool**: `inventory__find_host_by_name` (preferred) or `inventory__list_hosts` +- **inventory__list_hosts**: Use `per_page` (integer), NOT `page_size`; pass `display_name=""` if no filter +- If multiple matches: ask user to disambiguate or use first match with a note + +## Step 4: MCP Tool Invocation + +**Tool**: `vulnerability__get_system_cves` (from lightspeed-mcp) + +**Parameters**: +- `system_uuid`: Required (from Step 2) +- `limit`: `100` +- `offset`: `0`, `100`, `200`, ... per pagination strategy + +**First call** (to get total estimate if available): +``` +vulnerability__get_system_cves(system_uuid="", limit=100, offset=0) +``` + +**Pagination loop** (filter for remediatable): +``` +offset = 0 +all_remediatable = [] +while (strategy allows): + result = vulnerability__get_system_cves(system_uuid="...", limit=100, offset=offset) + for item in result.data: + if item.attributes.advisory_available is True: + all_remediatable.append(item) + if len(result.data) < 100: break + offset += 100 +``` + +## Step 5: Filter by Severity (Client-Side) + +After filtering for remediatable, optionally filter by severity: + +| Severity choice | Filter | +|-----------------|--------| +| all | No additional filter | +| most critical | Keep items where severity in (Critical, High) | +| selected | Keep items matching user-specified severity | + +## Step 6: After Retrieval + +- **Parse response**: Use [references/01-cve-response-parser.py](../references/01-cve-response-parser.py) with `FILTER_REMEDIATABLE=1`. Do NOT use jq or inline Python. See [02-cve-parsing-guide.md](../references/02-cve-parsing-guide.md). +- Sort by CVSS score (highest first) +- Provide summary table; offer to analyze specific CVEs or create remediation plan (`/remediation` skill) diff --git a/rh-sre/skills/cve-impact/references/01-cve-response-parser.py b/rh-sre/skills/cve-impact/references/01-cve-response-parser.py new file mode 100644 index 00000000..d9235f25 --- /dev/null +++ b/rh-sre/skills/cve-impact/references/01-cve-response-parser.py @@ -0,0 +1,225 @@ +#!/usr/bin/env python3 +""" +Parse Red Hat Lightspeed vulnerability MCP tool responses. + +Handles: vulnerability__get_system_cves, vulnerability__get_cves + +Usage: + python3 01-cve-response-parser.py < response.json + python3 01-cve-response-parser.py /path/to/response.json + python3 01-cve-response-parser.py page1.json page2.json page3.json # Multiple pages โ†’ aggregated report + +Options (env vars or args): + FILTER_REMEDIATABLE=1 - Only CVEs with advisory_available=true + FILTER_IMPACT=Critical,Important - Only these severities (comma-separated) + SORT_BY=cvss|impact|public_date + OUTPUT=summary|table|json|report + SYSTEM_NAME=hostname - For report header (when OUTPUT=report) + PAGES_SCANNED=5 - For report header (when OUTPUT=report, multiple files) +""" +import json +import sys +import os +from pathlib import Path + +# Response structure: {"result": {"data": [...]}, "meta": {"count": N}} +# Each CVE: {"id": "CVE-...", "type": "cve", "url": "...", "attributes": {...}} +# attributes: advisory_available, impact, cvss3_score, cvss2_score, description, synopsis, public_date, business_risk, etc. + +IMPACT_ORDER = {"Critical": 0, "High": 1, "Important": 2, "Moderate": 3, "Low": 4, "None": 5} + + +def load_response(src): + """Load JSON from file path or stdin.""" + if src and src != "-": + with open(src, "r") as f: + return json.load(f) + return json.load(sys.stdin) + + +def extract_cves(data): + """Extract CVE list from Lightspeed response (handles result.data or result.results).""" + result = data.get("result", data) + cves = result.get("data", result.get("results", [])) + meta = data.get("meta", {}) + total = meta.get("count", meta.get("total", len(cves))) + return cves, total + + +def get_attr(cve, key, default=None): + """Get attribute from CVE (handles nested attributes).""" + attrs = cve.get("attributes", cve) + return attrs.get(key, attrs.get(key.replace("_", "-"), default)) + + +def filter_cves(cves, remediatable_only=None, impact_filter=None): + """Filter CVEs by advisory_available and/or impact.""" + filtered = [] + for cve in cves: + if remediatable_only and not get_attr(cve, "advisory_available", False): + continue + if impact_filter: + impact = get_attr(cve, "impact", "") + if impact not in impact_filter: + continue + filtered.append(cve) + return filtered + + +def sort_cves(cves, sort_by="cvss"): + """Sort CVEs by cvss (desc), impact, or public_date.""" + def key_fn(cve): + if sort_by == "cvss": + score = get_attr(cve, "cvss3_score") or get_attr(cve, "cvss2_score") or "0" + return -(float(score) if score else 0) + if sort_by == "impact": + return IMPACT_ORDER.get(get_attr(cve, "impact", "None"), 99) + if sort_by == "public_date": + return get_attr(cve, "public_date", "") or "" + return 0 + return sorted(cves, key=key_fn) + + +def format_summary(cves, total_in_api, remediatable_only=False, impact_filter=None): + """Print summary counts by impact and remediation.""" + by_impact = {} + by_remediation = {"with_remediation": 0, "without": 0} + for cve in cves: + impact = get_attr(cve, "impact", "None") or "None" + by_impact[impact] = by_impact.get(impact, 0) + 1 + if get_attr(cve, "advisory_available", False): + by_remediation["with_remediation"] += 1 + else: + by_remediation["without"] += 1 + + lines = [ + "CVE Response Summary", + "=" * 60, + f"Total in this page/batch: {len(cves)}", + f"Total in API (meta.count): {total_in_api}", + ] + if remediatable_only or impact_filter: + lines.append(f"Filter: remediatable={remediatable_only}, impact={impact_filter}") + lines.append("") + lines.append("By Impact:") + for impact in ["Critical", "Important", "High", "Moderate", "Low", "None"]: + if impact in by_impact: + lines.append(f" {impact}: {by_impact[impact]}") + lines.append("") + lines.append("By Remediation:") + lines.append(f" With advisory: {by_remediation['with_remediation']}") + lines.append(f" Without: {by_remediation['without']}") + return "\n".join(lines) + + +def format_table(cves, limit=20): + """Print CVE table (CVE ID, CVSS, Impact, Remediation).""" + lines = [ + "CVE ID | CVSS | Impact | Remediation", + "-" * 60, + ] + for cve in cves[:limit]: + cve_id = cve.get("id", "?") + cvss = get_attr(cve, "cvss3_score") or get_attr(cve, "cvss2_score") or "-" + impact = get_attr(cve, "impact", "-") or "-" + rem = "Yes" if get_attr(cve, "advisory_available", False) else "No" + lines.append(f"{cve_id:<19} | {str(cvss):<6} | {impact:<9} | {rem}") + if len(cves) > limit: + lines.append(f"... and {len(cves) - limit} more") + return "\n".join(lines) + + +def format_report(cves, total_in_api, system_name=None, pages_scanned=None): + """Print aggregated report format (for multi-page results).""" + lines = ["=" * 80] + title = "CVEs WITH AVAILABLE REMEDIATION" + if system_name: + title = f"{title.upper()} โ€” System: {system_name}" + lines.append(title) + if pages_scanned: + lines.append(f"Scanned: {pages_scanned} page(s)") + lines.append("=" * 80) + lines.append("") + if not cves: + lines.append("No CVEs with available remediation found.") + if pages_scanned: + lines.append("") + lines.append("Note: Try scanning more pages or use FILTER_IMPACT=Critical,Important for severity filter.") + else: + lines.append(f"Found {len(cves)} CVE(s) with available remediation:\n") + for i, cve in enumerate(cves, 1): + cve_id = cve.get("id", "?") + cvss = get_attr(cve, "cvss3_score") or get_attr(cve, "cvss2_score") or "-" + impact = get_attr(cve, "impact", "-") or "-" + synopsis = get_attr(cve, "synopsis", "") or cve_id + url = cve.get("url", "") + lines.append(f"{i}. CVE ID: {cve_id}") + lines.append(f" CVSS v3 Score: {cvss}") + lines.append(f" Severity: {impact}") + lines.append(f" Synopsis: {synopsis}") + if url: + lines.append(f" View in Insights: {url}") + lines.append("") + return "\n".join(lines) + + +def load_and_merge_files(paths): + """Load multiple JSON files, extract CVEs, merge and dedupe by id.""" + all_cves = {} + max_total = 0 + for p in paths: + if not os.path.exists(p): + continue + with open(p, "r") as f: + try: + data = json.load(f) + except json.JSONDecodeError: + continue + cves, total = extract_cves(data) + max_total = max(max_total, total) + for cve in cves: + cid = cve.get("id") + if cid and cid not in all_cves: + all_cves[cid] = cve + return list(all_cves.values()), max_total + + +def main(): + # Parse args โ€” multiple files = aggregated multi-page mode + paths = [a for a in sys.argv[1:] if not a.startswith("-")] + if not paths and not sys.stdin.isatty(): + paths = ["-"] + + remediatable_only = os.environ.get("FILTER_REMEDIATABLE", "").lower() in ("1", "true", "yes") + impact_str = os.environ.get("FILTER_IMPACT", "") + impact_filter = [s.strip() for s in impact_str.split(",") if s.strip()] if impact_str else None + sort_by = os.environ.get("SORT_BY", "cvss") + output = os.environ.get("OUTPUT", "report" if len(paths) > 1 else "summary") + system_name = os.environ.get("SYSTEM_NAME", "") + pages_scanned = os.environ.get("PAGES_SCANNED", str(len(paths)) if len(paths) > 1 else None) + + if len(paths) > 1 and "-" not in paths: + cves, total = load_and_merge_files(paths) + else: + src = paths[0] if paths else "-" + data = load_response(src) + cves, total = extract_cves(data) + + cves = filter_cves(cves, remediatable_only=remediatable_only, impact_filter=impact_filter) + cves = sort_cves(cves, sort_by=sort_by) + + if output == "json": + print(json.dumps({"data": cves, "total": total, "filtered_count": len(cves)}, indent=2)) + elif output == "table": + print(format_table(cves)) + elif output == "report": + print(format_report(cves, total, system_name=system_name or None, pages_scanned=pages_scanned)) + else: + print(format_summary(cves, total, remediatable_only, impact_filter)) + print("") + print("Top CVEs (by CVSS):") + print(format_table(cves, limit=15)) + + +if __name__ == "__main__": + main() diff --git a/rh-sre/skills/cve-impact/references/02-cve-parsing-guide.md b/rh-sre/skills/cve-impact/references/02-cve-parsing-guide.md new file mode 100644 index 00000000..f4608f3b --- /dev/null +++ b/rh-sre/skills/cve-impact/references/02-cve-parsing-guide.md @@ -0,0 +1,147 @@ +# CVE Response Parsing Guide + +**Use this reference** when you need to parse/filter MCP vulnerability tool responses. + +**Do NOT use** jq, inline Python, or other ad-hoc JSON parsing. Use the skill's parser script only. + +**Do NOT generate inline Python** to aggregate multiple page filesโ€”the parser supports multiple file paths. + +## When to Use the Parser + +- After `vulnerability__get_system_cves` returns a large response +- After `vulnerability__get_cves` returns a response +- When filtering for `advisory_available === true` (remediatable CVEs) +- When filtering by impact (Critical, Important, Moderate, Low) +- When summarizing CVE counts by severity and remediation status +- **When aggregating multiple paginated pages**โ€”pass all page files as arguments + +**Do NOT use jq or inline Python**โ€”use the skill's parser script. + +## Parser Location + +``` +rh-sre/skills/cve-impact/references/01-cve-response-parser.py +``` + +From workspace root: `rh-sre/skills/cve-impact/references/01-cve-response-parser.py` + +## How to Invoke + +### Option 1: JSON file path + +Save the MCP tool result to a file, then run: + +```bash +python3 rh-sre/skills/cve-impact/references/01-cve-response-parser.py /path/to/response.json +``` + +### Option 2: stdin + +```bash +python3 rh-sre/skills/cve-impact/references/01-cve-response-parser.py < /path/to/response.json +``` + +### Option 3: From MCP tool result file + +When the MCP tool writes to a file (e.g. `tool-results/toolu_xxx.txt`): + +```bash +python3 rh-sre/skills/cve-impact/references/01-cve-response-parser.py /path/to/tool-results/toolu_xxx.txt +``` + +### Option 4: Multiple page files (aggregated report) + +When you have multiple paginated responses (e.g. pages 1โ€“5 from `vulnerability__get_system_cves`), pass all files. The parser merges, dedupes, and produces an aggregated report: + +```bash +FILTER_REMEDIATABLE=1 FILTER_IMPACT=Critical,Important OUTPUT=report SYSTEM_NAME=ip-172-31-32-201.eu-west-3.compute.internal \ + python3 rh-sre/skills/cve-impact/references/01-cve-response-parser.py page1.json page2.json page3.json page4.json page5.json +``` + +**Do NOT generate inline Python** to loop over page filesโ€”use the parser with multiple paths. + +## Filter Options (Environment Variables) + +| Variable | Values | Effect | +|----------|--------|--------| +| `FILTER_REMEDIATABLE` | `1`, `true`, `yes` | Only CVEs with `advisory_available=true` | +| `FILTER_IMPACT` | `Critical,Important` | Only these severities (comma-separated) | +| `SORT_BY` | `cvss`, `impact`, `public_date` | Sort order (default: cvss) | +| `OUTPUT` | `summary`, `table`, `json`, `report` | Output format. `report` = aggregated format (default when multiple files) | +| `SYSTEM_NAME` | hostname string | For report header (e.g. `ip-172-31-32-201.eu-west-3.compute.internal`) | +| `PAGES_SCANNED` | number | For report header (e.g. `5`). Auto-set when multiple files. | + +### Examples + +**Remediatable CVEs only:** +```bash +FILTER_REMEDIATABLE=1 python3 rh-sre/skills/cve-impact/references/01-cve-response-parser.py response.json +``` + +**Critical/Important only:** +```bash +FILTER_IMPACT=Critical,Important python3 rh-sre/skills/cve-impact/references/01-cve-response-parser.py response.json +``` + +**Remediatable + Critical/Important:** +```bash +FILTER_REMEDIATABLE=1 FILTER_IMPACT=Critical,Important python3 rh-sre/skills/cve-impact/references/01-cve-response-parser.py response.json +``` + +**Aggregated report from multiple pages:** +```bash +FILTER_REMEDIATABLE=1 FILTER_IMPACT=Critical,Important OUTPUT=report SYSTEM_NAME=ip-172-31-32-201.eu-west-3.compute.internal \ + python3 rh-sre/skills/cve-impact/references/01-cve-response-parser.py page1.json page2.json page3.json page4.json page5.json +``` + +**JSON output (for further processing):** +```bash +OUTPUT=json python3 rh-sre/skills/cve-impact/references/01-cve-response-parser.py response.json +``` + +## Response Structure (Lightspeed MCP) + +The parser expects this structure (from `vulnerability__get_system_cves` or `vulnerability__get_cves`): + +```json +{ + "result": { + "data": [ + { + "id": "CVE-2024-1234", + "type": "cve", + "url": "https://console.redhat.com/insights/vulnerability/cves/CVE-2024-1234", + "attributes": { + "advisory_available": true, + "impact": "Important", + "cvss3_score": "7.5", + "cvss2_score": null, + "description": "...", + "synopsis": "CVE-2024-1234", + "public_date": "2024-01-15", + "business_risk": "Low" + } + } + ] + }, + "meta": { + "count": 1735 + } +} +``` + +Key fields: +- `result.data` โ€” Array of CVE objects +- `meta.count` โ€” Total CVEs (for pagination context) +- `attributes.advisory_available` โ€” Boolean, remediatable +- `attributes.impact` โ€” Critical, Important, Moderate, Low, None +- `attributes.cvss3_score` โ€” CVSS 3.x score string + +## Workflow Integration + +1. Call MCP tool (`vulnerability__get_system_cves` or `vulnerability__get_cves`) โ€” one or more times (paginated) +2. Save each response to file (MCP may write to `tool-results/` or you save from result) +3. **Run parser** (requiredโ€”do not use jq or inline Python): + - Single page: `python3 rh-sre/skills/cve-impact/references/01-cve-response-parser.py ` + - Multiple pages: `python3 rh-sre/skills/cve-impact/references/01-cve-response-parser.py page1.json page2.json ...` +4. Use parser output for summary tables and user-facing reports diff --git a/rh-sre/skills/cve-validation/SKILL.md b/rh-sre/skills/cve-validation/SKILL.md index 36456d37..fae76155 100644 --- a/rh-sre/skills/cve-validation/SKILL.md +++ b/rh-sre/skills/cve-validation/SKILL.md @@ -5,16 +5,23 @@ description: | Validate CVE identifiers and check remediation availability in Red Hat Lightspeed. Use this skill when you need to verify a CVE exists, check its severity, and confirm automated remediation is available before proceeding with remediation planning. - This skill orchestrates MCP tools (get_cve) to provide comprehensive CVE validation with format checking, existence verification, and remediation availability assessment. + **DO NOT use this skill when** user requests full remediation - use `/remediation` skill instead: + - "Create a remediation playbook for CVE-X" โ†’ `/remediation` skill + - "Create playbook and execute it" โ†’ `/remediation` skill + - "Remediate CVE-X" / "Patch CVE-X" โ†’ `/remediation` skill - **IMPORTANT**: ALWAYS use this skill instead of calling get_cve directly for CVE validation tasks. + This skill orchestrates MCP tools (get_cve) to provide comprehensive CVE validation. The `/remediation` skill invokes this skill as Step 2 of its workflow. --- # CVE Validation Skill This skill validates CVE identifiers and checks remediation availability in Red Hat Lightspeed, ensuring CVEs are valid and remediable before investing effort in remediation planning. -**Integration with Remediator Agent**: The sre-agents:remediator agent (invoked) orchestrates this skill as part of its Step 2 (Validate CVE) workflow. For standalone CVE validation, you can invoke this skill directly. +**Integration with Remediation Skill**: The `/remediation` skill orchestrates this skill as part of its Step 2 (Validate CVE) workflow. For standalone CVE validation, you can invoke this skill directly. + +## Invocation Note (Host-Specific) + +When invoked by another skill (e.g. remediation), use the Skill toolโ€”do NOT use "Task Output" with the skill name as task ID. That causes "No task found with ID: cve-validation". See [skill-invocation.md](../../../docs/references/skill-invocation.md). ## Prerequisites @@ -29,15 +36,11 @@ This skill validates CVE identifiers and checks remediation availability in Red ### Prerequisite Validation -**CRITICAL**: Before executing any operations, invoke the [mcp-lightspeed-validator](../mcp-lightspeed-validator/SKILL.md) skill to verify MCP server availability. +**CRITICAL**: Before executing any operations, execute the `/mcp-lightspeed-validator` skill to verify MCP server availability. **Validation freshness**: Can skip if already validated in this session. See [Validation Freshness Policy](../mcp-lightspeed-validator/SKILL.md#validation-freshness-policy). -**How to invoke**: -``` -Use the Skill tool: - skill: "mcp-lightspeed-validator" -``` +**How to invoke**: Execute the `/mcp-lightspeed-validator` skill **Handle validation result**: - **If validation PASSED**: Continue with CVE validation @@ -47,30 +50,33 @@ Use the Skill tool: ## When to Use This Skill **Use this skill directly when you need**: -- Quick validation of CVE identifier format and existence +- Quick validation of CVE identifier format and existence (standalone query) - Check if automated remediation is available - Verify CVE metadata before analysis - Validate CVE lists for batch operations -**Use the sre-agents:remediator agent when you need**: +**DO NOT use this skill when** - use `/remediation` skill instead: +- User says "create a remediation playbook" or "remediate CVE-X" or "patch CVE-X" +- User says "create playbook and execute it" - agent orchestrates full workflow +- Any request that implies playbook generation or execution + +**Use the `/remediation` skill when you need**: - Full remediation workflow (validation + analysis + playbook + execution) - Integrated CVE validation as part of remediation planning -**How they work together**: The sre-agents:remediator agent (invoked) invokes this skill early in the workflow to fail fast if a CVE is invalid or has no automated remediation, saving time and effort. +**How they work together**: The `/remediation` skill invokes this skill early in the workflow to fail fast if a CVE is invalid or has no automated remediation, saving time and effort. + +**When invoked by remediation**: Return remediatable status prominently so the orchestrator can gate. Include `remediation_status.automated_remediation_available` (boolean) and `validation_status` ("valid" | "not_remediable" | "invalid" | "not_found") in the output. ## Workflow ### Step 0: Validate Lightspeed MCP Prerequisites -**Action**: Invoke the [mcp-lightspeed-validator](../mcp-lightspeed-validator/SKILL.md) skill +**Action**: Execute the `/mcp-lightspeed-validator` skill **Note**: Can skip if validation was performed earlier in this session and succeeded. See [Validation Freshness Policy](../mcp-lightspeed-validator/SKILL.md#validation-freshness-policy). -**How to invoke**: -``` -Use the Skill tool: - skill: "mcp-lightspeed-validator" -``` +**How to invoke**: Execute the `/mcp-lightspeed-validator` skill **Handle validation result**: - **If validation PASSED**: Continue to Step 1 @@ -79,23 +85,25 @@ Use the Skill tool: ### Step 1: CVE Format Validation -Validate CVE identifier format before calling MCP tools: +Validate CVE identifier format before calling MCP tools. **Format only**โ€”do NOT reject based on year or sequence magnitude. ```python CVE Format: CVE-YYYY-NNNNN Where: -- YYYY = 4-digit year (1999-2026) -- NNNNN = 4-7 digit sequence number +- YYYY = 4-digit year (1999-2030; current and recent years are valid) +- NNNNN = 4-7 digit sequence number (e.g. 1234, 24882, 1234567) Valid Examples: - CVE-2024-1234 +- CVE-2026-24882 # 2026 CVEs exist; 24882 is 5 digits (valid) - CVE-2023-12345 - CVE-2021-1234567 -Invalid Examples: +Invalid Examples (format only): - CVE-24-1234 (year must be 4 digits) - CVE-2024-ABC (sequence must be numeric) - 2024-1234 (missing CVE- prefix) +- CVE-2024-123 (sequence must be 4-7 digits) ``` **Quick Regex Check**: @@ -108,21 +116,30 @@ If invalid format: โ†’ Do not proceed to MCP tool calls ``` +**CRITICAL - Do NOT add extra checks**: If the format matches the regex, you MUST call `get_cve`. Do NOT reject based on: +- "Future" or "current year" assumptions (e.g. "2026 CVE might not exist yet") +- Sequence number magnitude (e.g. "24882 seems high")โ€”5 digits is valid +- Your training data about typical CVE ranges + +Let the API determine existence. A 404 from get_cve means "not found"; format validation only catches malformed IDs. + ### Step 2: CVE Metadata Retrieval **CRITICAL**: Document consultation MUST happen BEFORE tool invocation. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [vulnerability-logic.md](../../docs/insights/vulnerability-logic.md) using the Read tool to understand CVE validation criteria and remediation availability checks -2. **Output to user**: "I consulted [vulnerability-logic.md](../../docs/insights/vulnerability-logic.md) to understand CVE validation criteria and remediation availability checks." +1. **Action**: Read [vulnerability-logic.md](../../docs/insights/vulnerability-logic.md) using the Read tool to understand CVE validation criteria +2. **Action**: Read [references/01-remediation-indicators.md](references/01-remediation-indicators.md) to interpret get_cve responseโ€”**CRITICAL** to avoid misinterpreting remediation availability +3. **Output to user**: "I consulted [vulnerability-logic.md](../../docs/insights/vulnerability-logic.md) and [01-remediation-indicators.md](references/01-remediation-indicators.md) for CVE validation and remediation indicator interpretation." **MCP Tool**: `get_cve` or `vulnerability__get_cve` (from lightspeed-mcp) +**Do NOT use** `vulnerability__explain_cves` for validation. That tool requires `system_uuid` from inventory; at validation you may not have it. `get_cve` provides remediation availability. Never pass `system_uuid: "undefined"` or placeholders. + **Parameters**: -- `cve_id`: Exact CVE identifier from user query (format: `"CVE-YYYY-NNNNN"`) +- `cve`: Exact CVE identifier from user query (format: `"CVE-YYYY-NNNNN"`) - Example: `"CVE-2024-1234"` -- `include_details`: `true` (retrieve complete metadata including remediation status) -- `validate_format`: `true` (confirm CVE format is correct before API call) +- `advisory_available`: `"true"` (retrieve CVE with advisory/remediation info) **Expected Output**: CVE metadata including CVSS score, severity, affected packages, remediation availability @@ -190,15 +207,25 @@ Red Hat Severity Levels: - Low (CVSS 0.1-3.9): Low priority ``` -**D. Remediation Availability Check**: +**D. Remediation Availability Check** (READ [references/01-remediation-indicators.md](references/01-remediation-indicators.md)): ``` Key Question: Can Red Hat Lightspeed generate an automated playbook? -โœ“ remediation_available = true +โœ… USE these fields: + - advisory_available === true โ†’ Remediation available + - remediation === 2 โ†’ Automated remediation available + - advisories_list non-empty โ†’ RHSA exists, remediation available + +โŒ DO NOT use rules[] for remediation decision: + - rules: [] (empty) does NOT mean "no remediation" + - Advisor rules are separate from vulnerability remediation + - Remediation comes from Security Advisories (RHSA), not Advisor rules + +โœ“ If advisory_available=true OR remediation=2 OR advisories_list has entries โ†’ Proceed with automated remediation โ†’ Use create_vulnerability_playbook tool -โœ— remediation_available = false +โœ— If advisory_available=false AND (remediation=0 or advisories_list empty) โ†’ Manual remediation required โ†’ Provide manual steps based on affected packages ``` @@ -215,7 +242,7 @@ This information will be used by playbook-generator skill. ### Step 4: Return Validation Result -Return structured validation result: +Return structured validation result. **When invoked by remediation skill**: Ensure `validation_status` and `remediation_status.automated_remediation_available` are explicitโ€”the orchestrator gates on these. ```json { @@ -307,7 +334,7 @@ When completing CVE validation, provide output in this format: **Skill Response**: 1. Check format โ†’ Valid (CVE-2024-1234) 2. Call `get_cve` โ†’ CVE found in database -3. Check remediation_available โ†’ true +3. Check advisory_available, remediation, advisories_list (ignore rules[]) โ†’ remediation available 4. Extract metadata โ†’ CVSS 7.5, Important severity, httpd package 5. Return: "Valid CVE, automated remediation available, proceed with workflow" @@ -318,7 +345,7 @@ When completing CVE validation, provide output in this format: **Skill Response**: 1. Check format โ†’ Valid 2. Call `get_cve` โ†’ CVE found -3. Check remediation_available โ†’ false +3. Check advisory_available, remediation, advisories_list โ†’ all indicate no remediation (do NOT use rules[]) 4. Extract manual steps โ†’ Affected package: custom-app-1.0 5. Return: "Valid CVE but no automated playbook. Manual remediation required: yum update custom-app" @@ -440,7 +467,7 @@ Troubleshooting: ## Best Practices -1. **Validate format first** - Don't waste API calls on malformed CVE IDs +1. **Validate format first** - Don't waste API calls on malformed CVE IDs. But if format matches regex, ALWAYS call get_cveโ€”do not reject based on year or sequence number. 2. **Check remediation availability** - Fail fast if no automated remediation 3. **Batch validation efficiently** - Validate multiple CVEs in parallel when possible 4. **Provide clear next steps** - Guide users to appropriate next action @@ -476,14 +503,17 @@ Troubleshooting: - Purpose: Create automated remediation for valid, remediable CVEs ### Reference Documentation -- [vulnerability-logic.md](../../docs/insights/vulnerability-logic.md) - CVE validation criteria and remediation availability checks +- [vulnerability-logic.md](../../docs/insights/vulnerability-logic.md) - CVE validation criteria +- [references/01-remediation-indicators.md](references/01-remediation-indicators.md) - **REQUIRED** - Correct interpretation of get_cve response (advisory_available, remediation, advisories_list). Do NOT use rules[] for remediation decision. - [cvss-scoring.md](../../docs/references/cvss-scoring.md) - Red Hat severity classification and CVSS score ranges - [cve-remediation-templates.md](../../docs/ansible/cve-remediation-templates.md) - Manual remediation templates for CVEs without automated playbooks ## Tools Reference -This skill primarily uses: -- `get_cve` (vulnerability toolset) - Get CVE metadata from Red Hat Lightspeed +This skill uses: +- `get_cve` (vulnerability toolset) - Get CVE metadata and remediation availability from Red Hat Lightspeed + +**Do NOT use** `vulnerability__explain_cves` in this skillโ€”it requires `system_uuid` which may not be available at validation time. Use `get_cve` only. All tools are provided by the lightspeed-mcp MCP server configured in `.mcp.json`. @@ -494,7 +524,7 @@ All tools are provided by the lightspeed-mcp MCP server configured in `.mcp.json - **system-context**: Only gathers context for valid CVEs - **remediation-verifier**: Validates CVE was properly remediated -**Orchestration Example** (from sre-agents:remediator agent - invoked): +**Orchestration Example** (from `/remediation` skill): 1. User requests remediation for CVE-2024-1234 2. Agent invokes cve-validation skill โ†’ Confirms valid and remediable 3. Agent invokes cve-impact skill โ†’ Risk assessment diff --git a/rh-sre/skills/cve-validation/references/01-remediation-indicators.md b/rh-sre/skills/cve-validation/references/01-remediation-indicators.md new file mode 100644 index 00000000..17f9afe8 --- /dev/null +++ b/rh-sre/skills/cve-validation/references/01-remediation-indicators.md @@ -0,0 +1,66 @@ +# Remediation Availability Indicators (get_cve Response) + +Read this reference when interpreting `vulnerability__get_cve` or `get_cve` response to determine if automated remediation is available. + +## CRITICAL: Correct vs Incorrect Indicators + +### โœ… USE These Fields for Remediation Availability + +| Field | Meaning | Remediation Available When | +|-------|---------|-----------------------------| +| `advisory_available` | Red Hat Security Advisory exists | `true` | +| `remediation` | Remediation status code | `2` = automated remediation available | +| `advisories_list` | List of RHSA/errata IDs | Non-empty (e.g. `["RHSA-2026:2719"]`) | + +**Decision rule**: Remediation IS available when `advisory_available === true` OR `remediation === 2` OR `advisories_list` is non-empty. + +### โŒ DO NOT Use These Fields for Remediation + +| Field | Meaning | Why NOT to Use | +|-------|---------|----------------| +| `rules` | Red Hat Insights **Advisor** rules | Advisor rules are separate from vulnerability remediation. Empty `rules: []` does NOT mean no remediation. Remediation comes from Security Advisories (RHSA), not Advisor rules. | + +**Common mistake**: Agent sees `rules: []` (empty) and incorrectly concludes "no remediation available." This is WRONG. Always check `advisory_available` and `remediation` first. + +## Interpretation Checklist + +When evaluating `get_cve` response: + +1. **Check `advisory_available`**: If `true` โ†’ remediation available โœ“ +2. **Check `remediation`**: If `2` โ†’ automated remediation available โœ“ +3. **Check `advisories_list`**: If non-empty (e.g. RHSA-*) โ†’ remediation available โœ“ +4. **Ignore `rules`**: Do NOT use for remediation decision. Empty rules โ‰  no remediation. + +## Example: Remediation Available (rules empty) + +```json +{ + "advisory_available": true, + "advisories_list": ["RHSA-2026:2719"], + "remediation": 2, + "rules": [] +} +``` + +**Correct interpretation**: Remediation IS available. `rules: []` only means no Advisor ruleโ€”remediation comes from RHSA-2026:2719. + +## Example: No Remediation + +```json +{ + "advisory_available": false, + "advisories_list": [], + "remediation": 0, + "rules": [] +} +``` + +**Correct interpretation**: No automated remediation. Manual steps required. + +## get_cve_systems Response (per-system) + +When using `get_cve_systems` for system-level check, each system entry may include: +- `attributes.advisory_available` โ€” same meaning as get_cve +- `attributes.remediation` โ€” same meaning as get_cve + +Use the same interpretation rules. Do NOT use `rules` for remediation decision. diff --git a/rh-sre/skills/execution-summary/SKILL.md b/rh-sre/skills/execution-summary/SKILL.md index ef48659e..6474c392 100644 --- a/rh-sre/skills/execution-summary/SKILL.md +++ b/rh-sre/skills/execution-summary/SKILL.md @@ -33,7 +33,7 @@ Do NOT use when: **What to extract**: 1. **Agents invoked** - Look for agent invocations in the conversation - - Example: Agent `remediator` โ†’ `rh-sre:remediator` + - Example: Skill `remediation` (orchestration) โ†’ `rh-sre:remediation` - Include plugin prefix: `rh-sre:` 2. **Skills invoked** - Look for Skill tool calls @@ -98,8 +98,8 @@ Docs: ,,... 1. **Agent names**: Include plugin prefix - Format: `rh-sre:agent-name` - - Example: `rh-sre:remediator` - - Separate with commas (no spaces): `rh-sre:remediator,rh-sre:validator` + - Example: `rh-sre:remediation` + - Separate with commas (no spaces): `rh-sre:remediation,rh-sre:validator` 2. **Skill names**: Include plugin prefix - Format: `rh-sre:skill-name` @@ -132,8 +132,8 @@ Docs: ,,... I've generated the execution summary for this workflow: **** EXECUTION SUMMARY START **** -Agents: rh-sre:remediator -Skills: rh-sre:fleet-inventory,rh-sre:cve-impact,rh-sre:playbook-generator,rh-sre:job-template-creator +Agents: None +Skills: rh-sre:remediation,rh-sre:fleet-inventory,rh-sre:cve-impact,rh-sre:playbook-generator,rh-sre:job-template-creator Tools: lightspeed-mcp:get_host_details,lightspeed-mcp:get_cve,aap-mcp-job-management:job_templates_list Docs: docs/ansible/cve-remediation-templates.md,docs/insights/vulnerability-logic.md,skills/fleet-inventory/SKILL.md **** EXECUTION SUMMARY END **** @@ -188,8 +188,8 @@ This workflow used 2 skills, 1 MCP tool, and consulted 2 documentation files. **User Request**: "Remediate CVE-2024-1234 on production systems, then show execution summary" **Workflow executed**: -1. Invoked `remediator` agent -2. Agent delegated to: `cve-validation`, `cve-impact`, `system-context`, `playbook-generator`, `playbook-executor` skills +1. Invoked `remediation` skill +2. Remediation skill delegated to: `cve-validation`, `cve-impact`, `system-context`, `playbook-generator`, `playbook-executor` skills 3. Called multiple MCP tools: `get_cve`, `get_cve_systems`, `get_host_details`, `create_vulnerability_playbook`, `execute_playbook` 4. Read multiple docs: CVE scoring, Ansible templates, remediation verification @@ -198,13 +198,13 @@ This workflow used 2 skills, 1 MCP tool, and consulted 2 documentation files. I've generated the execution summary for this workflow: **** EXECUTION SUMMARY START **** -Agents: rh-sre:remediator -Skills: rh-sre:cve-validation,rh-sre:cve-impact,rh-sre:system-context,rh-sre:playbook-generator,rh-sre:job-template-creator +Agents: None +Skills: rh-sre:remediation,rh-sre:cve-validation,rh-sre:cve-impact,rh-sre:system-context,rh-sre:playbook-generator,rh-sre:job-template-creator Tools: lightspeed-mcp:get_cve,lightspeed-mcp:get_cve_systems,lightspeed-mcp:get_host_details,lightspeed-mcp:create_vulnerability_playbook,aap-mcp-job-management:job_templates_launch_retrieve Docs: docs/references/cvss-scoring.md,docs/ansible/cve-remediation-templates.md,docs/insights/vulnerability-logic.md,skills/playbook-generator/SKILL.md **** EXECUTION SUMMARY END **** -This comprehensive remediation workflow used 1 agent that orchestrated 5 skills, invoked 5 MCP tools, and consulted 4 documentation files. +This comprehensive remediation workflow used the remediation skill that orchestrated 5 skills, invoked 5 MCP tools, and consulted 4 documentation files. ``` ### Example 3: Validation Only Workflow @@ -278,8 +278,8 @@ Would you like to start a workflow now? Include the resource with a note: ``` **** EXECUTION SUMMARY START **** -Agents: rh-sre:remediator -Skills: rh-sre:fleet-inventory,unknown-plugin:custom-skill +Agents: None +Skills: rh-sre:remediation,rh-sre:fleet-inventory,unknown-plugin:custom-skill Tools: lightspeed-mcp:get_cve Docs: docs/ansible/playbook-templates.md **** EXECUTION SUMMARY END **** @@ -310,7 +310,7 @@ Note: "unknown-plugin:custom-skill" origin unclear - verify plugin source. **Learning & Training**: - Show new users which resources solve specific problems - Demonstrate skill orchestration patterns -- Illustrate agent delegation workflows +- Illustrate skill orchestration workflows **Troubleshooting**: - Identify which tools were called before an error @@ -326,10 +326,10 @@ Note: "unknown-plugin:custom-skill" origin unclear - verify plugin source. This skill complements other rh-sre skills: -**After sre-agents:remediator agent**: +**After `/remediation` skill**: ``` User: "Remediate CVE-X" -โ†’ sre-agents:remediator agent executes full workflow (invoked) +โ†’ `/remediation` skill executes full workflow (invoked) User: "Generate execution summary" โ†’ execution-summary shows complete resource usage ``` diff --git a/rh-sre/skills/fleet-inventory/SKILL.md b/rh-sre/skills/fleet-inventory/SKILL.md index b4999295..4a9bbbe1 100644 --- a/rh-sre/skills/fleet-inventory/SKILL.md +++ b/rh-sre/skills/fleet-inventory/SKILL.md @@ -1,7 +1,7 @@ --- name: fleet-inventory description: | - Query and display Red Hat Lightspeed managed system inventory. Use this skill for information-gathering requests about the fleet, registered systems, or inventory queries. This skill focuses on discovery and listing only - for remediation actions, transition to the sre-agents:remediator agent (invoke the `sre-agents:remediator` agent). + Query and display Red Hat Lightspeed managed system inventory. Use this skill for information-gathering requests about the fleet, registered systems, or inventory queries. This skill focuses on discovery and listing only - for remediation actions, transition to the `/remediation` skill. **When to use this skill**: - "Show the managed fleet" @@ -10,7 +10,7 @@ description: | - "How many RHEL 8 systems do we have?" - "Show me production systems" - **When NOT to use this skill** (use sre-agents:remediator agent instead): + **When NOT to use this skill** (use `/remediation` skill instead): - "Remediate CVE-X on these systems" - "Create a playbook for..." - "Patch system Y" @@ -38,7 +38,7 @@ This skill queries Red Hat Lightspeed to retrieve and display information about ### Prerequisite Validation -**CRITICAL**: Before executing any operations, invoke the [mcp-lightspeed-validator](../mcp-lightspeed-validator/SKILL.md) skill to verify MCP server availability. +**CRITICAL**: Before executing any operations, execute the `/mcp-lightspeed-validator` skill to verify MCP server availability. See **Step 0** in the Workflow section below for implementation details. @@ -54,27 +54,23 @@ See **Step 0** in the Workflow section below for implementation details. - Count systems matching criteria - Verify system registration status -**Use the sre-agents:remediator agent when you need**: +**Use the `/remediation` skill when you need**: - Remediate vulnerabilities on systems - Generate or execute playbooks - Perform infrastructure changes - End-to-end CVE remediation workflows -**How they work together**: Use this skill for discovery ("What systems are affected?"), then transition to the sre-agents:remediator agent (invoke the `sre-agents:remediator` agent) for action ("Remediate those systems"). +**How they work together**: Use this skill for discovery ("What systems are affected?"), then transition to the `/remediation` skill for action ("Remediate those systems"). ## Workflow ### Step 0: Validate Lightspeed MCP Prerequisites -**Action**: Invoke the [mcp-lightspeed-validator](../mcp-lightspeed-validator/SKILL.md) skill +**Action**: Execute the `/mcp-lightspeed-validator` skill **Note**: Can skip if validation was performed earlier in this session and succeeded. See [Validation Freshness Policy](../mcp-lightspeed-validator/SKILL.md#validation-freshness-policy). -**How to invoke**: -``` -Use the Skill tool: - skill: "mcp-lightspeed-validator" -``` +**How to invoke**: Execute the `/mcp-lightspeed-validator` skill **Handle validation result**: - **If validation PASSED**: Continue to Step 1 @@ -273,7 +269,7 @@ get_cve_systems( ``` Status: "Vulnerable" โ†’ CVE affects this system, patch not applied -โ†’ Action: Suggest remediation via sre-agents:remediator agent +โ†’ Action: Suggest remediation via `/remediation` skill Status: "Patched" โ†’ CVE previously affected, now remediated @@ -322,13 +318,13 @@ Retrieved from Red Hat Lightspeed on YYYY-MM-DDTHH:MM:SSZ ### Step 5: Offer Remediation Transition -When appropriate, suggest transitioning to the sre-agents:remediator agent: +When appropriate, suggest transitioning to the `/remediation` skill: ```markdown ## Next Steps **For CVE Remediation**: -If you need to remediate vulnerabilities on any of these systems, I can help using the sre-agents:remediator agent (invoke the `sre-agents:remediator` agent): +If you need to remediate vulnerabilities on any of these systems, I can help using the `/remediation` skill: Examples: - "Remediate CVE-2024-1234 on web-server-01" @@ -370,7 +366,7 @@ Examples: - `system-context` - Get detailed system configuration for specific hosts - Use after: Fleet discovery identifies systems needing deeper investigation -- `sre-agents:remediator` (agent) - Transition to remediation workflows after discovery (invoke the `sre-agents:remediator` agent) +- `/remediation` (skill) - Transition to remediation workflows after discovery - Use after: "Show affected systems" โ†’ "Remediate those systems" ### Reference Documentation @@ -395,7 +391,7 @@ CVSS 8.1, Critical severity, affects httpd package โ†“ User: "Remediate CVE-2024-1234 on all production systems" โ†“ -sre-agents:remediator agent (action - invoke the `sre-agents:remediator` agent) +`/remediation` skill (action) โ†“ Playbook generated and executed ``` @@ -478,7 +474,7 @@ Retrieved from Red Hat Lightspeed on 2024-01-20T10:30:00Z ## Next Steps -**To remediate these systems**, use the sre-agents:remediator agent (invoke the `sre-agents:remediator` agent): +**To remediate these systems**, use the `/remediation` skill: - Single system: "Remediate CVE-2024-1234 on web-server-01" - Batch production: "Remediate CVE-2024-1234 on all production systems" - All vulnerable: "Create playbook for CVE-2024-1234 affecting these 12 systems" @@ -621,9 +617,9 @@ Error: Unable to retrieve system inventory from Red Hat Lightspeed - Check .mcp.json has lightspeed-mcp entry - Verify container is running: podman ps | grep insights -2. Check credentials: - - echo $LIGHTSPEED_CLIENT_ID - - echo $LIGHTSPEED_CLIENT_SECRET +2. Check credentials (never echo valuesโ€”report presence/absence only): + - test -n "$LIGHTSPEED_CLIENT_ID" && echo "LIGHTSPEED_CLIENT_ID: set" || echo "LIGHTSPEED_CLIENT_ID: not set" + - test -n "$LIGHTSPEED_CLIENT_SECRET" && echo "LIGHTSPEED_CLIENT_SECRET: set" || echo "LIGHTSPEED_CLIENT_SECRET: not set" - Verify credentials at https://console.redhat.com/settings/service-accounts 3. Test connection manually: @@ -673,7 +669,7 @@ The following systems have not checked in recently (> 7 days): 1. **Start broad, then filter** - Retrieve full inventory first, then apply user-requested filters 2. **Group by meaningful categories** - Environment, RHEL version, tier/function for clarity 3. **Highlight stale systems** - Warn users about systems with potentially outdated vulnerability data -4. **Offer remediation transitions** - Always suggest next steps using sre-agents:remediator agent (the `sre-agents:remediator` agent) +4. **Offer remediation transitions** - Always suggest next steps using `/remediation` skill 5. **Use clear formatting** - Tables for detailed lists, summaries for high-level overviews 6. **Include percentages** - Help users understand fleet composition at a glance 7. **Show last check-in times** - Indicate data freshness and system health @@ -701,7 +697,7 @@ Response: CVSS 8.1, Critical severity โ†“ User: "Remediate CVE-2024-1234 on all affected systems" โ†“ -sre-agents:remediator agent (orchestrates remediation - invoke the `sre-agents:remediator` agent) +`/remediation` skill (orchestrates remediation) โ†“ Complete: Playbook generated and executed ``` @@ -722,7 +718,7 @@ Response: 3 critical CVEs โ†“ User: "Create remediation plan" โ†“ -sre-agents:remediator agent (multi-CVE workflow - invoke the `sre-agents:remediator` agent) +`/remediation` skill (multi-CVE workflow) ``` **Information-First Principle**: @@ -730,7 +726,7 @@ sre-agents:remediator agent (multi-CVE workflow - invoke the `sre-agents:remedia Always follow this sequence: 1. What systems do we have? (fleet-inventory) 2. What are they vulnerable to? (cve-impact) -3. How do we fix it? (sre-agents:remediator agent via the `sre-agents:remediator` agent) +3. How do we fix it? (`/remediation` skill) This ensures informed decisions before taking remediation actions. ``` diff --git a/rh-sre/skills/job-template-creator/SKILL.md b/rh-sre/skills/job-template-creator/SKILL.md index 6d14a8ad..b8d6af21 100644 --- a/rh-sre/skills/job-template-creator/SKILL.md +++ b/rh-sre/skills/job-template-creator/SKILL.md @@ -42,15 +42,11 @@ This skill helps SREs create AAP job templates for executing Ansible playbooks, ### Prerequisite Validation -**CRITICAL**: Before executing operations, invoke the [mcp-aap-validator](../mcp-aap-validator/SKILL.md) skill to verify AAP MCP server availability. +**CRITICAL**: Before executing operations, execute the `/mcp-aap-validator` skill to verify AAP MCP server availability. **Validation freshness**: Can skip if already validated in this session. See [Validation Freshness Policy](../mcp-aap-validator/SKILL.md#validation-freshness-policy). -**How to invoke**: -``` -Use the Skill tool: - skill: "mcp-aap-validator" -``` +**How to invoke**: Execute the `/mcp-aap-validator` skill **Handle validation result**: - **If validation PASSED**: Continue with job template creation workflow @@ -77,7 +73,7 @@ This skill documents both the **current manual workflow** and the **intended aut - Automate job template creation as part of remediation setup **Do NOT use this skill when**: -- Job templates already exist (use `playbook-executor` skill instead) +- Job templates already exist (use `/playbook-executor` skill instead) - Only need to execute existing templates (use `job_templates_launch_retrieve`) - Need to modify existing templates (requires AAP Web UI currently) @@ -102,15 +98,11 @@ Create a job template for this remediation playbook. Playbook: [content]. Filena ### Phase 0: Validate AAP MCP Prerequisites -**Action**: Invoke the [mcp-aap-validator](../mcp-aap-validator/SKILL.md) skill +**Action**: Execute the `/mcp-aap-validator` skill **Note**: Can skip if validation was performed earlier in this session and succeeded. See [Validation Freshness Policy](../mcp-aap-validator/SKILL.md#validation-freshness-policy). -**How to invoke**: -``` -Use the Skill tool: - skill: "mcp-aap-validator" -``` +**How to invoke**: Execute the `/mcp-aap-validator` skill **Handle validation result**: - **If validation PASSED**: Continue to Phase 1 @@ -485,6 +477,7 @@ Configure the template with these settings: **Options** (checkboxes at bottom): - โœ… **Enable Privilege Escalation**: Yes (required for package updates and system changes) - โœ… **Prompt on Launch**: Check fields you want to override at launch time: + - โ˜‘๏ธ **Job Type** (REQUIREDโ€”enables dry-run with `check` and actual execution with `run`; job-template-remediation-validator requires this) - โ˜‘๏ธ **Variables** (recommended for dynamic CVE targeting) - โ˜‘๏ธ **Limit** (recommended for targeting specific hosts) - โ˜ **Allow Simultaneous**: No (prevent conflicts during remediation) @@ -699,6 +692,7 @@ When completing job template creation, provide: โœ… Enable Privilege Escalation: Yes Prompt on Launch (check these): + โ˜‘๏ธ Job Type (REQUIREDโ€”enables dry-run and run from same template) โ˜‘๏ธ Variables (allows passing different CVE IDs at runtime) โ˜‘๏ธ Limit (allows targeting specific hosts at runtime) @@ -794,6 +788,7 @@ When `job_templates_create` MCP tool is added, the workflow will become: "project": 6, "playbook": "remediation-CVE-2025-49794.yml", "become_enabled": true, + "ask_job_type_on_launch": true, "ask_variables_on_launch": true, "ask_limit_on_launch": true, "extra_vars": "{\"target_cve\": \"CVE-2025-49794\"}" diff --git a/rh-sre/skills/job-template-remediation-validator/SKILL.md b/rh-sre/skills/job-template-remediation-validator/SKILL.md index 9535e49b..61cb745a 100644 --- a/rh-sre/skills/job-template-remediation-validator/SKILL.md +++ b/rh-sre/skills/job-template-remediation-validator/SKILL.md @@ -9,14 +9,14 @@ description: | - "Check if template is ready for playbook-executor" - Before playbook-executor selects a template - NOT for: AAP MCP connectivity (use mcp-aap-validator), creating templates (use job-template-creator). + NOT for: AAP MCP connectivity (use `/mcp-aap-validator`), creating templates (use `/job-template-creator`). model: inherit color: blue --- # AAP Job Template Remediation Validator -This skill verifies that an AAP (Ansible Automation Platform) job template meets the requirements for executing CVE remediation playbooks as defined by the remediator agent and playbook-executor workflow. +This skill verifies that an AAP (Ansible Automation Platform) job template meets the requirements for executing CVE remediation playbooks as defined by the remediation skill and playbook-executor workflow. ## Prerequisites @@ -34,15 +34,11 @@ This skill verifies that an AAP (Ansible Automation Platform) job template meets ### Prerequisite Validation -**CRITICAL**: Before executing, invoke the [mcp-aap-validator](../mcp-aap-validator/SKILL.md) skill to verify AAP MCP server availability. +**CRITICAL**: Before executing, execute the `/mcp-aap-validator` skill to verify AAP MCP server availability. **Validation freshness**: Can skip if already validated in this session. See [Validation Freshness Policy](../mcp-aap-validator/SKILL.md#validation-freshness-policy). -**How to invoke**: -``` -Use the Skill tool: - skill: "mcp-aap-validator" -``` +**How to invoke**: Execute the `/mcp-aap-validator` skill **Handle validation result**: - **If validation PASSED**: Continue with template validation @@ -65,9 +61,9 @@ If prerequisites are not met: - Troubleshooting "template not compatible" in playbook-executor **Do NOT use when**: -- Validating AAP MCP connectivity โ†’ Use `mcp-aap-validator` skill -- Creating new job templates โ†’ Use `job-template-creator` skill -- Executing playbooks โ†’ Use `playbook-executor` skill +- Validating AAP MCP connectivity โ†’ Use `/mcp-aap-validator` skill +- Creating new job templates โ†’ Use `/job-template-creator` skill +- Executing playbooks โ†’ Use `/playbook-executor` skill ## Remediation Template Requirements @@ -82,6 +78,11 @@ This skill validates against the requirements documented in [playbook-executor]( | **Playbook** | Template has playbook path | `playbook` field present, non-empty | | **Credentials** | Machine credential (SSH) configured | `summary_fields.credentials` or `credentials` has at least one credential | | **Privilege Escalation** | Required for package updates | `become_enabled` is true | +| **Ask Job Type on Launch** | Required for dry-run and run modes | `ask_job_type_on_launch` is true | + +**Why Ask Job Type on Launch**: playbook-executor uses the same template for dry-run (`job_type: "check"`) and actual execution (`job_type: "run"`). Without `ask_job_type_on_launch: true`, the template is locked to one mode and you would need separate templates for check vs run. + +**Example**: Template with `job_type: "check"` (default) and `ask_job_type_on_launch: true` allows launching as check for dry-run or run for execution. ### Recommended (Warnings if Missing) @@ -89,6 +90,7 @@ This skill validates against the requirements documented in [playbook-executor]( |-------------|-------------|------------| | **Ask Variables on Launch** | Enables dynamic CVE targeting | `ask_variables_on_launch` is true | | **Ask Limit on Launch** | Enables host targeting at launch | `ask_limit_on_launch` is true | +| **Ask Inventory on Launch** | Enables inventory override at launch | `ask_inventory_on_launch` is true | ### Optional Context Checks @@ -103,7 +105,7 @@ This skill validates against the requirements documented in [playbook-executor]( ### Phase 0: Validate AAP MCP Prerequisites -**Action**: Invoke the [mcp-aap-validator](../mcp-aap-validator/SKILL.md) skill +**Action**: Execute the `/mcp-aap-validator` skill **Note**: Can skip if validation was performed earlier in this session and succeeded. @@ -162,6 +164,7 @@ required_checks.append(("Privilege Escalation", template.get("become_enabled") = creds = template.get("summary_fields", {}).get("credentials") or template.get("credentials") or [] has_creds = (isinstance(creds, list) and len(creds) > 0) or (isinstance(creds, dict) and creds) required_checks.append(("Credentials", has_creds)) +required_checks.append(("Ask Job Type on Launch", template.get("ask_job_type_on_launch") == True)) ``` **Note**: If the AAP MCP response structure differs, adapt the field paths. Common AAP API response structures: @@ -179,6 +182,7 @@ required_checks.append(("Credentials", has_creds)) recommended_checks = [] recommended_checks.append(("Ask Variables on Launch", template.get("ask_variables_on_launch") == True)) recommended_checks.append(("Ask Limit on Launch", template.get("ask_limit_on_launch") == True)) +recommended_checks.append(("Ask Inventory on Launch", template.get("ask_inventory_on_launch") == True)) ``` ### Phase 4: Optional Context Verification @@ -225,12 +229,14 @@ recommended_checks.append(("Ask Limit on Launch", template.get("ask_limit_on_lau | Playbook | โœ“/โœ— | {playbook_path} | | Credentials | โœ“/โœ— | {count} credential(s) configured | | Privilege Escalation | โœ“/โœ— | become_enabled: {value} | +| Ask Job Type on Launch | โœ“/โœ— | Required for dry-run + run modes | ## Recommended Checks | Requirement | Status | Details | |-------------|--------|---------| | Ask Variables on Launch | โœ“/โš  | {value} | | Ask Limit on Launch | โœ“/โš  | {value} | +| Ask Inventory on Launch | โœ“/โš  | {value} | ## Context Verification | Check | Status | Details | @@ -243,12 +249,12 @@ recommended_checks.append(("Ask Limit on Launch", template.get("ask_limit_on_lau {If PASSED}: Template is ready for remediation playbook execution. {If WARNINGS}: Template works but consider enabling ask_variables_on_launch and ask_limit_on_launch for flexibility. -{If FAILED}: Fix required checks before using with playbook-executor. See job-template-creator for setup guidance. +{If FAILED}: Fix required checks before using with playbook-executor. See job-template-creator for setup guidance. If Ask Job Type on Launch fails: Enable "Prompt on Launch" for Job Type in AAP Web UI โ†’ Templates โ†’ [Template] โ†’ Edit โ†’ Options. ``` ### Pass/Fail Determination -- **PASSED**: All 5 required checks pass +- **PASSED**: All 6 required checks pass - **PASSED WITH WARNINGS**: All required pass, one or more recommended fail - **FAILED**: One or more required checks fail @@ -308,6 +314,7 @@ recommended_checks.append(("Ask Limit on Launch", template.get("ask_limit_on_lau |-------------|--------|---------| | Ask Variables on Launch | โœ“ | true | | Ask Limit on Launch | โœ“ | true | +| Ask Inventory on Launch | โœ“ | true | ## Overall Result โœ“ PASSED @@ -315,7 +322,38 @@ recommended_checks.append(("Ask Limit on Launch", template.get("ask_limit_on_lau Template is ready for remediation playbook execution. ``` -### Example 2: Template Fails - Missing Privilege Escalation +### Example 2: Template Fails - Missing Ask Job Type on Launch + +**User Request**: "Validate template 20 for remediation" + +**Skill Response**: + +``` +# Job Template Remediation Validation Report + +**Template**: CVE Remediation (ID: 20) +**Validated**: 2025-02-25 + +## Required Checks +| Requirement | Status | Details | +|-------------|--------|---------| +| Inventory | โœ“ | 1 - Production Inventory | +| Project | โœ“ | 6 - Remediation Playbooks | +| Playbook | โœ“ | playbooks/remediation/remediation-template.yml | +| Credentials | โœ“ | 1 credential(s) configured | +| Privilege Escalation | โœ“ | become_enabled: true | +| Ask Job Type on Launch | โœ— | ask_job_type_on_launch: false | + +## Overall Result +โœ— FAILED + +Fix required: Enable "Prompt on Launch" for Job Type. +playbook-executor needs the same template for dry-run (job_type: "check") and actual execution (job_type: "run"). Without this, you would need separate templates for each mode. + +To fix: AAP Web UI โ†’ Templates โ†’ [Template] โ†’ Edit โ†’ Options โ†’ โœ“ Prompt on Launch โ†’ Job Type +``` + +### Example 3: Template Fails - Missing Privilege Escalation **User Request**: "Check if template 15 works for remediation" @@ -345,7 +383,7 @@ Remediation playbooks require sudo/root for package updates and system changes. To fix: AAP Web UI โ†’ Templates โ†’ [Template] โ†’ Edit โ†’ Options โ†’ โœ“ Enable Privilege Escalation ``` -### Example 3: Invoked by Playbook-Executor +### Example 4: Invoked by Playbook-Executor **Context**: playbook-executor filters templates and may invoke this skill to validate user-selected template before execution. diff --git a/rh-sre/skills/mcp-aap-validator/SKILL.md b/rh-sre/skills/mcp-aap-validator/SKILL.md index f228bb07..a1c4f708 100644 --- a/rh-sre/skills/mcp-aap-validator/SKILL.md +++ b/rh-sre/skills/mcp-aap-validator/SKILL.md @@ -1,549 +1,66 @@ --- name: mcp-aap-validator description: | - This skill should be used when the user asks to "validate AAP MCP", "check if AAP is configured", "verify aap-mcp servers", "test AAP connection", or when other skills need to verify AAP MCP server availability before executing job management or inventory operations. + Validate AAP (Ansible Automation Platform) MCP server connectivity. Use when the user asks to "validate AAP MCP", "check AAP connection", or when other skills need to verify AAP MCP availability before job management or inventory operations. model: haiku color: yellow --- # MCP AAP Validator -Validates that AAP (Ansible Automation Platform) MCP servers are properly configured and accessible for job management and inventory operations. +Validates connectivity to AAP MCP servers by running lightweight tool calls. ## When to Use This Skill -Use this skill when: -- Validating AAP MCP server configuration before job template operations -- Troubleshooting connection issues with AAP MCP servers -- Verifying environment setup for AAP workflows -- Other skills need to confirm AAP MCP server availability as a prerequisite (e.g., `job-template-creator`) - -Do NOT use when: -- Creating job templates โ†’ Use `job-template-creator` skill instead -- Launching jobs โ†’ Use `playbook-executor` or job management skills instead -- Querying inventories โ†’ Use `fleet-inventory` skill instead +Use when validating AAP MCP before job template operations, troubleshooting connection issues, or when other skills (e.g. playbook-executor) need to verify availability. Do NOT use for creating templatesโ€”use job-template-creator. ## Workflow -### Step 1: Check MCP Server Configuration - -**Action**: Verify that AAP MCP servers exist in [.mcp.json](../../.mcp.json) - -**Required AAP MCP Servers**: -- `aap-mcp-job-management` - Job template and execution management -- `aap-mcp-inventory-management` - Inventory and host management - -**Note**: Additional AAP MCP servers may be added in the future. This validator checks all configured `aap-mcp-*` servers. - -**How to verify**: -1. Read the `.mcp.json` file in the rh-sre directory -2. Check if `mcpServers` object contains both required servers: - - `aap-mcp-job-management` key - - `aap-mcp-inventory-management` key -3. Verify each server configuration has: - - `type: "http"` or `url` field - - `headers` with Authorization Bearer token - - `env` with required variables - -**Expected result**: Both AAP MCP servers configured with proper HTTP structure - -**Report to user**: -- โœ“ "MCP server `aap-mcp-job-management` is configured in .mcp.json" -- โœ“ "MCP server `aap-mcp-inventory-management` is configured in .mcp.json" -- โœ— "MCP server `aap-mcp-job-management` not found in .mcp.json" -- โœ— "MCP server `aap-mcp-inventory-management` not found in .mcp.json" - -**If either AAP server missing**: Proceed to Human Notification Protocol (Step 4) - -### Step 2: Verify Environment Variables - -**Action**: Check that required environment variables are set (without exposing values) - -**Required Environment Variables**: -- `AAP_MCP_SERVER` - Base URL for the MCP endpoint of the AAP server (used in .mcp.json; e.g. "https://aap-mcp.example.com"). Must point to the AAP MCP gateway, not the main AAP Web UI. -- `AAP_API_TOKEN` - Authentication token for AAP API - -**CRITICAL SECURITY CONSTRAINT**: -- **NEVER print environment variable values** in user-visible output -- Only report presence/absence -- Do NOT use `echo $VAR_NAME` or display actual values -- Protect sensitive data like API tokens - -**How to verify** (without exposing values): -```bash -# Check if set (exit code only, no output) -test -n "$AAP_MCP_SERVER" -test -n "$AAP_API_TOKEN" - -# Or check and report boolean result -if [ -n "$AAP_MCP_SERVER" ]; then - echo "โœ“ AAP_MCP_SERVER is set" -else - echo "โœ— AAP_MCP_SERVER is not set" -fi - -if [ -n "$AAP_API_TOKEN" ]; then - echo "โœ“ AAP_API_TOKEN is set" -else - echo "โœ— AAP_API_TOKEN is not set" -fi -``` - -**Report to user**: -- โœ“ "Environment variable AAP_MCP_SERVER is set" -- โœ“ "Environment variable AAP_API_TOKEN is set" -- โœ— "Environment variable AAP_MCP_SERVER is not set" -- โœ— "Environment variable AAP_API_TOKEN is not set" - -**Note**: `AAP_MCP_SERVER` must point to the MCP endpoint of the AAP server (the MCP gateway URL). If unset, the MCP server will fail to connect. - -**If missing**: Proceed to Human Notification Protocol (Step 4) - -### Step 3: Test MCP Server Connection and Resources - -**Action**: Attempt connectivity test to verify server accessibility and check for required resources - -**Test approach**: -1. **Test Job Management Server**: - - Tool: `job_templates_list` (from aap-mcp-job-management) - - Parameters: `page_size: 10` (check for templates) - - Expected: Returns list - - Success: Server responds with valid data - - Failure: Connection timeout, auth error, or server unavailable - - **Validation**: Check if at least one job template exists - - If `count: 0` โ†’ Warning: No job templates configured - - If `count > 0` โ†’ Success: Templates available for use - -2. **Test Inventory Management Server**: - - Tool: `inventories_list` (from aap-mcp-inventory-management) - - Parameters: `page_size: 10` (check for inventories) - - Expected: Returns list - - Success: Server responds with valid data - - Failure: Connection timeout, auth error, or server unavailable - - **Validation**: Check if at least one inventory exists - - If `count: 0` โ†’ Warning: No inventories configured - - If `count > 0` โ†’ Success: Inventories available for use - -**Report to user**: -- โœ“ "Successfully connected to aap-mcp-job-management" -- โœ“ "Successfully connected to aap-mcp-inventory-management" -- โœ“ "Found N job template(s) available" -- โœ“ "Found N inventory/inventories available" -- โš  "Connected but no job templates found (you'll need to create one)" -- โš  "Connected but no inventories found (you'll need to create one)" -- โš  "Configuration appears correct but connectivity test unavailable" -- โœ— "Cannot connect to aap-mcp-job-management (check server status and credentials)" -- โœ— "Cannot connect to aap-mcp-inventory-management (check server status and credentials)" - -**Common connection errors for AAP MCP servers**: -- `Invalid tool parameters`: Often caused by AAP_MCP_SERVER not set or wrongโ€”the MCP URL in .mcp.json fails to resolve. Verify AAP_MCP_SERVER points to the MCP endpoint of the AAP server. -- `401 Unauthorized`: Invalid or expired AAP_API_TOKEN -- `403 Forbidden`: Token lacks required permissions -- `404 Not Found`: Incorrect AAP_MCP_SERVER URL or missing endpoints -- `Connection timeout`: Server unreachable or network issue -- `SSL/TLS error`: Certificate verification issues - -**If AAP connection fails**: Proceed to Human Notification Protocol (Step 4) -**If ansible connection fails**: Report warning but allow continuation (playbook execution will not be available) - -### Step 4: Human Notification Protocol - -When validation fails, follow this protocol: - -**1. Stop Execution Immediately** - Do not attempt MCP tool calls - -**2. Report Clear Error**: - -For missing MCP server configuration: -``` -โŒ Cannot validate AAP MCP servers: Servers not configured in .mcp.json - -๐Ÿ“‹ Setup Instructions: -1. Add AAP MCP server configurations to rh-sre/.mcp.json -2. Configuration template: - { - "mcpServers": { - "aap-mcp-job-management": { - "url": "https://${AAP_MCP_SERVER}/job_management/mcp", - "headers": { - "Authorization": "Bearer ${AAP_API_TOKEN}" - } - }, - "aap-mcp-inventory-management": { - "url": "https://${AAP_MCP_SERVER}/inventory_management/mcp", - "headers": { - "Authorization": "Bearer ${AAP_API_TOKEN}" - } - } - } - } - -๐Ÿ”— Documentation: See rh-sre/README.md for AAP MCP setup -``` - -For missing environment variables: -``` -โŒ Cannot validate AAP MCP: Required environment variables not set - -๐Ÿ“‹ Setup Instructions: -1. Set required environment variables: - export AAP_MCP_SERVER="https://your-aap-mcp-gateway.com" - export AAP_API_TOKEN="your-api-token" - - Note: .mcp.json uses AAP_MCP_SERVER for MCP URLs. Use the MCP gateway URL, not the main AAP UI URL. - -2. To get an API token: - - Log in to AAP Web UI - - Navigate to Users โ†’ [Your User] โ†’ Tokens - - Create a new Personal Access Token - - Copy the token value - -โš ๏ธ SECURITY: Never commit tokens to source control - - Use environment variables or secure secret management - - Rotate tokens regularly - - Restrict token permissions to minimum required - -3. Restart to reload environment variables - -๐Ÿ”— Documentation: See AAP documentation for authentication setup -``` - -For connection failures: -``` -โŒ Cannot connect to AAP MCP servers - -๐Ÿ“‹ Troubleshooting steps: -1. Verify AAP MCP server is accessible: - - Check AAP_MCP_SERVER URL is correct (must match .mcp.json) - - Test connectivity: curl -I ${AAP_MCP_SERVER} - - Verify network connectivity and firewall rules - -2. Verify API token is valid: - - Token may have expired - - Check token permissions in AAP Web UI - - Generate new token if needed - -3. Check AAP MCP endpoints: - - Job Management: ${AAP_MCP_SERVER}/job_management/mcp - - Inventory Management: ${AAP_MCP_SERVER}/inventory_management/mcp - - Verify endpoints are exposed and accessible +1. **Test connectivity**: Call these tools to verify each server responds: + - `job_templates_list` (page_size: 10) from aap-mcp-job-management + - `inventories_list` (page_size: 10) from aap-mcp-inventory-management +2. **If any fails**: Provide a comprehensive message with possible root causes (see below). +3. **Report**: Output a table with validated servers and outcome (emojis). -4. Review authentication errors: - - 401: Token invalid or expired โ†’ Regenerate token - - 403: Insufficient permissions โ†’ Check RBAC settings - - 404: Endpoint not found โ†’ Verify AAP MCP is deployed +## Failure Message (Root Causes) -5. Check AAP service status: - - Verify AAP platform is running - - Check AAP MCP proxy/gateway is operational - - Review AAP logs for errors +When a tool call fails, include: -6. Restart to reload MCP servers after configuration changes ``` +โŒ AAP MCP connection failed -**3. Request User Decision**: -``` -โ“ How would you like to proceed? - -Options: -- "setup" - Help me configure the AAP MCP servers now -- "skip" - Skip validation and try the operation anyway (not recommended) -- "abort" - Stop the workflow entirely +**Possible root causes:** +- **Credentials**: AAP_MCP_SERVER or AAP_API_TOKEN not set or invalid +- **401 Unauthorized**: Token expired or invalid โ†’ regenerate in AAP Web UI +- **403 Forbidden**: Token lacks RBAC permissions (need Job Templates, Inventories) +- **404 Not Found**: Wrong AAP_MCP_SERVER URL (must point to MCP gateway, not main AAP UI) +- **Connection timeout**: Server unreachable, firewall, or network issue +- **SSL/TLS error**: Certificate verification problem -Please respond with your choice. +**Troubleshooting:** +1. Verify env vars: AAP_MCP_SERVER, AAP_API_TOKEN (never echo values) +2. Get token: AAP Web UI โ†’ Users โ†’ [Your User] โ†’ Tokens โ†’ Create +3. Ensure AAP_MCP_SERVER points to MCP gateway endpoint +4. Restart host after config changes ``` -**4. Wait for Explicit User Input** - Do not proceed automatically +## Report Format -### Step 5: Validation Summary +Always end with a table: -**Action**: Report overall validation status - -**Success case**: -``` -โœ“ AAP MCP Validation: PASSED +| Server | Outcome | +|--------|---------| +| aap-mcp-job-management | โœ… PASSED | +| aap-mcp-inventory-management | โœ… PASSED | -Configuration: -โœ“ MCP server aap-mcp-job-management configured in .mcp.json -โœ“ MCP server aap-mcp-inventory-management configured in .mcp.json -โœ“ Environment variable AAP_MCP_SERVER is set -โœ“ Environment variable AAP_API_TOKEN is set -โœ“ Job management server connectivity verified -โœ“ Inventory management server connectivity verified - -Resources: -โœ“ Found 5 job template(s) available -โœ“ Found 3 inventory/inventories available - -Ready to execute AAP operations. - -Available capabilities: -- Job template management (list, retrieve, launch) -- Job execution tracking (status, events, logs) -- Inventory management (hosts, groups, variables) -- System context gathering for remediation -``` - -**Partial success case** (connected but no resources): -``` -โš  AAP MCP Validation: PARTIAL - -Configuration: -โœ“ MCP server aap-mcp-job-management configured -โœ“ MCP server aap-mcp-inventory-management configured -โœ“ Environment variables are set -โœ“ Server connectivity verified - -Resources: -โš  No job templates found (create one before executing playbooks) -โš  No inventories found (create one to target systems) - -Note: AAP is accessible but requires resource setup. -You'll need to create job templates and inventories before executing remediation playbooks. - -Next steps: -1. Create inventory with target systems -2. Create job template for remediation playbooks -3. Re-run validation to confirm setup -``` - -**Partial success case** (connectivity not tested): -``` -โš  AAP MCP Validation: PARTIAL - -Configuration: -โœ“ MCP servers configured in .mcp.json -โœ“ Environment variables are set -โš  Server connectivity could not be tested - -Note: Configuration appears correct, but full validation requires connectivity test. -You may proceed with caution. Connection will be verified on first tool use. -``` - -**Failure case**: -``` -โœ— AAP MCP Validation: FAILED - -Issues found: -โœ— [Specific issue 1] -โœ— [Specific issue 2] - -See troubleshooting steps above. Please resolve configuration issues before proceeding. -``` +Use โœ… for success, โŒ for failure, โš ๏ธ for partial (e.g. one server OK, one failed). ## Dependencies -### Required Files -- [.mcp.json](../../.mcp.json) - MCP server configuration file - -### Required MCP Servers -- `aap-mcp-job-management` - AAP job template and execution management -- `aap-mcp-inventory-management` - AAP inventory and host management - -**Note**: Future AAP MCP servers (e.g., `aap-mcp-*`) will be validated automatically when added to the configuration. - ### Required MCP Tools -- `job_templates_list` (from aap-mcp-job-management) - List job templates - - Used for connectivity test - - Parameters: page_size (int) - - Returns: List of job templates -- `inventories_list` (from aap-mcp-inventory-management) - List inventories - - Used for connectivity test - - Parameters: page_size (int) - - Returns: List of inventories - -### Required Environment Variables -- `AAP_MCP_SERVER` - Base URL for the MCP endpoint of the AAP server (must match .mcp.json; e.g., "https://aap-mcp.example.com"). Must point to the AAP MCP gateway. -- `AAP_API_TOKEN` - Personal Access Token for AAP API authentication - -### Related Skills -- `job-template-creator` - **PRIMARY USER** - Uses AAP MCP for template creation (invokes this validator as prerequisite) -- `fleet-inventory` - May use AAP inventory management features in the future - -### Reference Documentation -- [AAP REST API Documentation](https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/) -- [AAP Authentication Guide](https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/) - -## Validation Freshness Policy - -**Session-based validation**: Once validation succeeds in a session, subsequent skills can skip re-validation unless: -1. User explicitly requests re-validation -2. Previous MCP tool call failed with connection error -3. Configuration changes were made to .mcp.json -4. Environment variables were modified - -**How other skills use this**: -``` -IF validation_passed_in_session AND no_config_changes: - Skip validation, proceed with operation -ELSE: - Invoke mcp-aap-validator skill - IF validation PASSED: - Mark validation_passed_in_session = true - Proceed with operation - ELSE: - Report error, ask user for decision -``` - -## Example Usage - -### Example 1: Full Validation with All Servers - -**User Query**: "Validate AAP MCP before creating job templates" - -**Skill Response**: -``` -I'll validate your AAP MCP configuration. - -Checking MCP server configuration... -โœ“ MCP server `aap-mcp-job-management` is configured in .mcp.json -โœ“ MCP server `aap-mcp-inventory-management` is configured in .mcp.json - -Checking environment variables... -โœ“ Environment variable AAP_MCP_SERVER is set -โœ“ Environment variable AAP_API_TOKEN is set - -Testing server connectivity... -โœ“ Successfully connected to aap-mcp-job-management -โœ“ Successfully connected to aap-mcp-inventory-management - -โœ“ AAP MCP Validation: PASSED - -Configuration: -โœ“ AAP MCP servers configured -โœ“ Environment variables configured -โœ“ Server connectivity verified - -Ready to execute AAP operations. - -Available capabilities: -- Job template management (list, retrieve, launch) -- Job execution tracking (status, events, logs) -- Inventory management (hosts, groups, variables) -- System context gathering for remediation -``` - -### Example 2: Validation Failure - Missing Environment Variables - -**User Query**: "Check if AAP is ready for job operations" - -**Skill Response**: -``` -I'll validate your AAP MCP configuration. - -Checking MCP server configuration... -โœ“ MCP server `aap-mcp-job-management` is configured in .mcp.json -โœ“ MCP server `aap-mcp-inventory-management` is configured in .mcp.json - -Checking environment variables... -โœ— Environment variable AAP_MCP_SERVER is not set -โœ— Environment variable AAP_API_TOKEN is not set +- `job_templates_list` (from aap-mcp-job-management) - Connectivity test +- `inventories_list` (from aap-mcp-inventory-management) - Connectivity test -โŒ Cannot validate AAP MCP: Required environment variables not set - -๐Ÿ“‹ Setup Instructions: -1. Set required environment variables: - export AAP_MCP_SERVER="https://your-aap-mcp-gateway.com" - export AAP_API_TOKEN="your-api-token" - -2. To get an API token: - - Log in to AAP Web UI - - Navigate to Users โ†’ [Your User] โ†’ Tokens - - Create a new Personal Access Token - - Copy the token value - -โš ๏ธ SECURITY: Never commit tokens to source control - - Use environment variables or secure secret management - - Rotate tokens regularly - - Restrict token permissions to minimum required - -3. Restart to reload environment variables - -๐Ÿ”— Documentation: See AAP documentation for authentication setup - -โ“ How would you like to proceed? - -Options: -- "setup" - Help me configure environment variables now -- "skip" - Skip validation and try anyway (not recommended) -- "abort" - Stop the workflow entirely - -Please respond with your choice. -``` - -### Example 3: Connection Failure - Invalid Credentials - -**User Query**: "Verify AAP MCP is working" - -**Skill Response**: -``` -I'll validate your AAP MCP configuration. - -Checking MCP server configuration... -โœ“ MCP server `aap-mcp-job-management` is configured in .mcp.json -โœ“ MCP server `aap-mcp-inventory-management` is configured in .mcp.json - -Checking environment variables... -โœ“ Environment variable AAP_MCP_SERVER is set -โœ“ Environment variable AAP_API_TOKEN is set - -Testing server connectivity... -โœ— Cannot connect to aap-mcp-job-management (401 Unauthorized) - -โŒ Cannot connect to AAP MCP servers - -๐Ÿ“‹ Troubleshooting steps: -1. Verify API token is valid: - - Error 401 indicates authentication failure - - Token may have expired - - Generate new token in AAP Web UI: - Users โ†’ [Your User] โ†’ Tokens โ†’ Add - -2. Test token manually: - curl -H "Authorization: Bearer ${AAP_API_TOKEN}" \ - ${AAP_MCP_SERVER}/api/controller/v2/ping/ - -3. If token is valid but error persists: - - Check AAP MCP proxy/gateway configuration - - Verify token has required permissions (RBAC) - - Review AAP logs for authentication errors - -4. After fixing, restart to reload configuration - -โ“ How would you like to proceed? - -Options: -- "setup" - Help me regenerate API token -- "skip" - Skip validation and try anyway -- "abort" - Stop the workflow entirely - -Please respond with your choice. -``` - -### Example 4: Invoked by Another Skill - -**Context**: The `job-template-creator` skill invokes this validator before attempting template creation - -**Internal workflow**: -``` -[job-template-creator skill] โ†’ [Invoke mcp-aap-validator] - โ† [Validation result: PASSED/PARTIAL/FAILED] -[job-template-creator skill] โ†’ [If PASSED: proceed with template creation] - โ†’ [If PARTIAL: warn user, ask to proceed] - โ†’ [If FAILED: report to user, ask for decision] -``` - -This skill provides a reusable validation check that other skills can invoke as a prerequisite before AAP MCP operations. - -## Best Practices - -1. **Invoke once per session** - Cache validation result for efficiency -2. **Security first** - Never expose environment variable values -3. **Clear error messages** - Provide actionable troubleshooting steps -4. **Test both servers** - Job management AND inventory management -5. **Verify permissions** - Ensure token has required RBAC roles -6. **Document prerequisites** - Help users understand what's needed -7. **Graceful degradation** - Allow operations even with partial validation (with warnings) -8. **Token rotation** - Remind users to rotate tokens regularly -9. **Connection pooling** - Reuse connections when possible -10. **Timeout handling** - Set appropriate timeouts for connectivity tests +### Required MCP Servers +- `aap-mcp-job-management` - AAP job template and execution +- `aap-mcp-inventory-management` - AAP inventory management diff --git a/rh-sre/skills/mcp-lightspeed-validator/SKILL.md b/rh-sre/skills/mcp-lightspeed-validator/SKILL.md index 902b822a..fab96813 100644 --- a/rh-sre/skills/mcp-lightspeed-validator/SKILL.md +++ b/rh-sre/skills/mcp-lightspeed-validator/SKILL.md @@ -1,531 +1,61 @@ --- name: mcp-lightspeed-validator description: | - This skill should be used when the user asks to "validate Lightspeed MCP", "check if Lightspeed is configured", "verify Lightspeed connection", "test Lightspeed MCP server", or when other skills need to verify lightspeed-mcp availability before executing operations. + Validate Red Hat Lightspeed MCP server connectivity. Use when the user asks to "validate Lightspeed MCP", "check Lightspeed connection", or when other skills need to verify lightspeed-mcp availability before CVE operations. model: haiku color: yellow --- # MCP Lightspeed Validator -Validates that the Red Hat Lightspeed MCP server is properly configured, environment variables are set, and the server is accessible without exposing credential values. +Validates connectivity to the Red Hat Lightspeed MCP server by running a lightweight tool call. ## When to Use This Skill -Use this skill when: -- Validating Lightspeed MCP server configuration before CVE operations -- Troubleshooting connection issues with Red Hat Lightspeed platform -- Verifying environment setup for vulnerability management workflows -- Other skills need to confirm lightspeed-mcp availability as a prerequisite - -Do NOT use when: -- Performing actual CVE queries โ†’ Use `cve-impact` or `cve-validation` skills instead -- Generating remediation playbooks โ†’ Use `playbook-generator` skill instead - -## Important: MCP Server Naming - -The Lightspeed MCP server has two different names depending on context: - -| Context | Server Name | Usage | -|---------|-------------|-------| -| **Configuration** (.mcp.json file) | `lightspeed-mcp` | Check this name in the config file | -| **Runtime** (MCP tool invocations) | `plugin:sre-agents:lightspeed-mcp` | Use this name when calling MCP tools | - -**Why the difference?** -- The `.mcp.json` file defines the server as `lightspeed-mcp` (short name) -- Claude Code registers it with the plugin namespace prefix: `plugin:sre-agents:lightspeed-mcp` -- Always use the runtime name when invoking MCP tools to avoid "Server not found" errors - -## Validation Freshness Policy - -**Can skills skip validation if it was just performed?** - -**Simple rule**: Validation results are trusted **for the current session only**. - -### When to Skip Validation - -โœ… **Skip if** validation was performed earlier in this same conversation session and succeeded (PASSED or PARTIAL) - -Example: -``` -User: "Validate Lightspeed MCP" -โ†’ mcp-lightspeed-validator runs โ†’ PASSED - -User: "Show the fleet inventory" -โ†’ Skip validation (already validated this session) -โ†’ Proceed directly to query -``` - -### When to Re-validate - -โŒ **Always re-validate if**: -- New conversation session -- Previous validation FAILED -- User explicitly requests validation -- MCP tool error occurred (suggests server state changed) - -### Communicating to User - -When skipping, briefly inform the user: -``` -โœ“ Using validated Lightspeed MCP connection (validated earlier this session) -Proceeding with fleet inventory query... -``` - -**Rationale**: Session-scoped validation balances performance (avoid redundant checks) with safety (re-check if environment may have changed). +Use when validating Lightspeed MCP before CVE operations, troubleshooting connection issues, or when other skills (e.g. remediation) need to verify availability. Do NOT use for actual CVE queriesโ€”use cve-impact or cve-validation. ## Workflow -### Step 1: Check MCP Server Configuration - -**Action**: Verify that `lightspeed-mcp` exists in [.mcp.json](../../.mcp.json) - -**Important**: MCP server naming distinction: -- **Configuration name** (in .mcp.json): `lightspeed-mcp` -- **Runtime name** (when invoking tools): `plugin:sre-agents:lightspeed-mcp` - -The configuration file uses the short name, but Claude Code registers it with the plugin namespace prefix at runtime. - -**How to verify**: -1. Read the `.mcp.json` file in the rh-sre directory -2. Check if `mcpServers` object contains a `lightspeed-mcp` key (config name) -3. Verify the server configuration has `command` and `args` fields - -**Expected result**: Configuration exists with proper structure - -**Report to user**: -- โœ“ "MCP server `lightspeed-mcp` is configured in .mcp.json" -- โœ— "MCP server `lightspeed-mcp` not found in .mcp.json" - -**If missing**: Proceed to Human Notification Protocol (Step 4) - -### Step 2: Check Environment Variables - -**CRITICAL SECURITY REQUIREMENT**: NEVER expose environment variable values in output - -**Action**: Verify required environment variables are set without displaying their values - -**Required variables**: -- `LIGHTSPEED_CLIENT_ID` -- `LIGHTSPEED_CLIENT_SECRET` - -**How to verify** (use bash test commands): -```bash -# Check if environment variables are set (boolean check only) -if [ -n "$LIGHTSPEED_CLIENT_ID" ] && [ -n "$LIGHTSPEED_CLIENT_SECRET" ]; then - echo "โœ“ Environment variables are configured" -else - echo "โœ— Missing environment variables" - # Report which specific variables are missing - if [ -z "$LIGHTSPEED_CLIENT_ID" ]; then - echo " Missing: LIGHTSPEED_CLIENT_ID" - fi - if [ -z "$LIGHTSPEED_CLIENT_SECRET" ]; then - echo " Missing: LIGHTSPEED_CLIENT_SECRET" - fi -fi -``` - -**NEVER do this** (exposes credentials): -```bash -# โŒ WRONG - This exposes credential values -echo $LIGHTSPEED_CLIENT_ID -echo $LIGHTSPEED_CLIENT_SECRET -``` - -**Report to user**: -- โœ“ "Environment variable LIGHTSPEED_CLIENT_ID is set" -- โœ“ "Environment variable LIGHTSPEED_CLIENT_SECRET is set" -- โœ— "Environment variable LIGHTSPEED_CLIENT_ID is not set" -- โœ— "Environment variable LIGHTSPEED_CLIENT_SECRET is not set" - -**If missing**: Proceed to Human Notification Protocol (Step 4) - -### Step 3: Test MCP Server Connection (REQUIRED) - -**Note**: This step verifies actual server connectivity by listing available MCP tools. This is MANDATORY - without successful connectivity testing, the validator cannot confirm the service is available. +1. **Test connectivity**: Call `vulnerability__get_cves` (or `get_cves`) with `limit: 1` to verify the server responds. +2. **If it fails**: Provide a comprehensive message with possible root causes (see below). +3. **Report**: Output a table with validated servers and outcome (emojis). -**Action**: List available MCP tools from lightspeed-mcp server and validate required tools exist +## Failure Message (Root Causes) -**CRITICAL**: When invoking MCP tools, use the **runtime server name**: `plugin:sre-agents:lightspeed-mcp` -- โœ“ Correct: `ListMcpResourcesTool(server="plugin:sre-agents:lightspeed-mcp")` -- โœ— Wrong: `ListMcpResourcesTool(server="lightspeed-mcp")` - This will fail with "Server not found" +When the tool call fails, include: -**Required Tools** (used across rh-sre skills): - -**Vulnerability Toolset**: -- `get_cves` or `vulnerability__get_cves` - List/query CVEs -- `get_cve` or `vulnerability__get_cve` - Get specific CVE details -- `get_cve_systems` or `vulnerability__get_cve_systems` - Find systems affected by CVEs - -**Inventory Toolset**: -- `get_host_details` or `inventory__get_host_details` - Retrieve system inventory - -**Remediations Toolset**: -- `create_vulnerability_playbook` or `remediations__create_vulnerability_playbook` - Generate Ansible playbooks - -**How to verify**: -1. Use `ListMcpResourcesTool` with server name `plugin:sre-agents:lightspeed-mcp` (runtime name) -2. Check that the server responds (connectivity test) -3. Verify required tools are present in the response -4. Tools may appear with or without toolset prefix (both are valid) - -**Example tool invocation**: -``` -ListMcpResourcesTool(server="plugin:sre-agents:lightspeed-mcp") -``` - -**Common error**: Using `server="lightspeed-mcp"` will fail with "Server not found" because the runtime name includes the plugin namespace prefix. - -**Validation logic**: -```python -required_tools = [ - 'get_cves', 'get_cve', 'get_cve_systems', # Vulnerability - 'get_host_details', # Inventory - 'create_vulnerability_playbook' # Remediations -] - -# CRITICAL: Check if ANY tools were returned -if len(available_tools) == 0: - # Server responded but has zero tools - configuration issue - validation_failed = True - error_message = "Server connected but no MCP tools found (check server configuration)" - -# Check if tool exists with or without prefix -for tool in required_tools: - if not (tool in available_tools or f"*__{tool}" in available_tools): - missing_tools.append(tool) -``` - -**Report to user**: -- โœ“ "Successfully connected to lightspeed-mcp server" -- โœ“ "All required MCP tools are available (5/5 tools validated)" -- โš  "Successfully connected but some tools are missing: `get_cves`, `create_vulnerability_playbook` (3/5 tools available)" -- โœ— "Server connected but no MCP tools found (suggests configuration or authentication issue)" -- โœ— "Cannot connect to lightspeed-mcp server (check container status)" - -**If all tools present**: Report SUCCESS -**If some tools missing**: Report PARTIAL with warning about missing tools -**If zero tools found**: Report FAILED and proceed to Human Notification Protocol (Step 4) -**If connection fails**: Report FAILED and proceed to Human Notification Protocol (Step 4) - -### Step 4: Human Notification Protocol - -When validation fails, follow this protocol: - -**1. Stop Execution Immediately** - Do not attempt MCP tool calls - -**2. Report Clear Error**: - -For missing MCP server configuration: -``` -โŒ Cannot validate lightspeed-mcp: Server not configured in .mcp.json - -๐Ÿ“‹ Setup Instructions: -1. Add lightspeed-mcp configuration to rh-sre/.mcp.json -2. Configuration template: - { - "mcpServers": { - "lightspeed-mcp": { - "command": "podman", - "args": ["run", "-i", "--rm", "..."], - "env": { - "LIGHTSPEED_CLIENT_ID": "${LIGHTSPEED_CLIENT_ID}", - "LIGHTSPEED_CLIENT_SECRET": "${LIGHTSPEED_CLIENT_SECRET}" - } - } - } - } - -๐Ÿ”— Documentation: https://github.com/RedHatInsights/insights-mcp -``` - -For missing environment variables: -``` -โŒ Cannot validate lightspeed-mcp: Required environment variables not set - -๐Ÿ“‹ Missing variables: -- LIGHTSPEED_CLIENT_ID -- LIGHTSPEED_CLIENT_SECRET - -Setup instructions: -1. Follow instructions from: - https://github.com/RedHatInsights/insights-mcp - -2. Set environment variables: - export LIGHTSPEED_CLIENT_ID="your-client-id" - export LIGHTSPEED_CLIENT_SECRET="your-client-secret" - -3. Restart Claude Code to reload environment - -โš ๏ธ SECURITY: Never commit credentials to git or expose them in output ``` +โŒ Lightspeed MCP connection failed -For zero tools found (server connected but no tools available): -``` -โŒ Server connected but no MCP tools found - -This suggests a configuration or authentication issue. The MCP server responded -but has no tools registered. - -๐Ÿ“‹ Troubleshooting steps: -1. Check environment variables are correctly set: - - LIGHTSPEED_CLIENT_ID (verify it's not empty) - - LIGHTSPEED_CLIENT_SECRET (verify it's not empty) - -2. Check container logs for authentication errors: - podman logs $(podman ps | grep lightspeed | awk '{print $1}') - -3. Verify credentials are valid: - - Test at: https://console.redhat.com/settings/integrations - - Ensure credentials haven't expired +**Possible root causes:** +- **Credentials**: LIGHTSPEED_CLIENT_ID or LIGHTSPEED_CLIENT_SECRET not set or invalid +- **Expired credentials**: Red Hat Console tokens may have expired +- **Server not running**: MCP server/container may be stopped +- **Network**: Firewall or proxy blocking console.redhat.com +- **Configuration**: .mcp.json misconfigured or server not registered -4. Restart the MCP server with correct credentials: - podman stop $(podman ps | grep lightspeed | awk '{print $1}') - # Claude Code will restart it with updated environment variables - -5. If issue persists, check MCP server documentation: - https://github.com/RedHatInsights/insights-mcp +**Troubleshooting:** +1. Verify env vars: LIGHTSPEED_CLIENT_ID, LIGHTSPEED_CLIENT_SECRET (never echo values) +2. Check credentials at: https://console.redhat.com/settings/integrations +3. Restart MCP server or host after config changes +4. Check container logs if using podman/docker ``` -For connection failures: -``` -โŒ Cannot connect to lightspeed-mcp server +## Report Format -๐Ÿ“‹ Troubleshooting steps: -1. Check if container is running: - podman ps | grep lightspeed +Always end with a table: -2. Check container logs: - podman logs +| Server | Outcome | +|--------|---------| +| lightspeed-mcp | โœ… PASSED | +| lightspeed-mcp | โŒ FAILED | -3. Verify network connectivity: - curl -I https://console.redhat.com - -4. Restart the MCP server or Claude Code -``` - -**3. Request User Decision**: -``` -โ“ How would you like to proceed? - -Options: -- "setup" - Help me configure the MCP server now -- "skip" - Skip validation and try the operation anyway -- "abort" - Stop the workflow entirely - -Please respond with your choice. -``` - -**4. Wait for Explicit User Input** - Do not proceed automatically - -### Step 5: Validation Summary - -**Action**: Report overall validation status - -**Success case** (all checks passed): -``` -โœ“ Lightspeed MCP Validation: PASSED - -Configuration: -โœ“ MCP server configured in .mcp.json -โœ“ Environment variable LIGHTSPEED_CLIENT_ID is set -โœ“ Environment variable LIGHTSPEED_CLIENT_SECRET is set -โœ“ Server connectivity verified -โœ“ All required MCP tools available (5/5 tools validated) - -Ready to execute Lightspeed MCP operations. -``` - -**Partial success case** (some tools missing): -``` -โš  Lightspeed MCP Validation: PARTIAL - -Configuration: -โœ“ MCP server configured in .mcp.json -โœ“ Environment variable LIGHTSPEED_CLIENT_ID is set -โœ“ Environment variable LIGHTSPEED_CLIENT_SECRET is set -โœ“ Server connectivity verified -โš  Some MCP tools are missing (3/5 tools available) - Missing: get_cves, create_vulnerability_playbook - -Note: Server is accessible but not all expected tools are available. -Some skills may fail if they require the missing tools. -You may proceed with limited functionality. -``` - -**Failure case** (zero tools found): -``` -โœ— Lightspeed MCP Validation: FAILED - -Configuration: -โœ“ MCP server configured in .mcp.json -โœ“ Environment variable LIGHTSPEED_CLIENT_ID is set -โœ“ Environment variable LIGHTSPEED_CLIENT_SECRET is set -โœ— Server connected but no MCP tools found (0 tools available) - -This suggests a configuration or authentication issue. The MCP server -responded but has no tools registered. - -Possible causes: -- Invalid or expired credentials -- Authentication failure (check container logs) -- MCP server misconfiguration - -See troubleshooting steps above for "zero tools found" scenario. -``` - -**Failure case** (general): -``` -โœ— Lightspeed MCP Validation: FAILED - -Issues found: -โœ— [Specific issue 1] -โœ— [Specific issue 2] - -See troubleshooting steps above. -``` +Use โœ… for success, โŒ for failure, โš ๏ธ for partial (e.g. connected but error on tool). ## Dependencies -### Required Files -- [.mcp.json](../../.mcp.json) - MCP server configuration file (path is relative to skill location) - -### Reference Documentation -- None required (validation skill) - -## Example Usage - -### Example 1: Pre-flight Check Before CVE Operations - -**User Query**: "Validate my Lightspeed MCP setup before running CVE analysis" - -**Skill Response**: -``` -I'll validate your Lightspeed MCP configuration. - -Checking MCP server configuration... -โœ“ MCP server `lightspeed-mcp` is configured in .mcp.json - -Checking environment variables... -โœ“ Environment variable LIGHTSPEED_CLIENT_ID is set -โœ“ Environment variable LIGHTSPEED_CLIENT_SECRET is set - -Testing server connectivity... -โœ“ Successfully connected to lightspeed-mcp server -โœ“ All required MCP tools are available (5/5 tools validated) - -โœ“ Lightspeed MCP Validation: PASSED - -Configuration: -โœ“ MCP server configured in .mcp.json -โœ“ Environment variables are set -โœ“ Server connectivity verified - -Your Lightspeed MCP configuration is ready. You can proceed with CVE operations. -``` - -### Example 2: Validation Failure - Missing Environment Variables - -**User Query**: "Check if Lightspeed is ready" - -**Skill Response**: -``` -I'll validate your Lightspeed MCP configuration. - -Checking MCP server configuration... -โœ“ MCP server `lightspeed-mcp` is configured in .mcp.json - -Checking environment variables... -โœ— Environment variable LIGHTSPEED_CLIENT_ID is not set -โœ— Environment variable LIGHTSPEED_CLIENT_SECRET is not set - -โŒ Cannot validate lightspeed-mcp: Required environment variables not set - -๐Ÿ“‹ Missing variables: -- LIGHTSPEED_CLIENT_ID -- LIGHTSPEED_CLIENT_SECRET - -Setup instructions: -1. Obtain credentials from Red Hat Console: - https://console.redhat.com/settings/integrations - -2. Set environment variables: - export LIGHTSPEED_CLIENT_ID="your-client-id" - export LIGHTSPEED_CLIENT_SECRET="your-client-secret" - -3. Restart Claude Code to reload environment - -โš ๏ธ SECURITY: Never commit credentials to git or expose them in output - -โ“ How would you like to proceed? - -Options: -- "setup" - Help me configure the MCP server now -- "skip" - Skip validation and try the operation anyway -- "abort" - Stop the workflow entirely - -Please respond with your choice. -``` - -### Example 3: Validation Failure - Zero Tools Found - -**User Query**: "Validate Lightspeed MCP before running CVE queries" - -**Skill Response**: -``` -I'll validate your Lightspeed MCP configuration. - -Checking MCP server configuration... -โœ“ MCP server `lightspeed-mcp` is configured in .mcp.json - -Checking environment variables... -โœ“ Environment variable LIGHTSPEED_CLIENT_ID is set -โœ“ Environment variable LIGHTSPEED_CLIENT_SECRET is set - -Testing server connectivity... -โœ“ Server connection established -โœ— No MCP tools found (0 tools available) - -โœ— Lightspeed MCP Validation: FAILED - -Configuration: -โœ“ MCP server configured in .mcp.json -โœ“ Environment variables are set -โœ— Server connected but no MCP tools found - -This suggests a configuration or authentication issue. The MCP server -responded but has no tools registered. - -Possible causes: -- Invalid or expired credentials (check Red Hat Console) -- Authentication failure (check container logs) -- MCP server misconfiguration - -๐Ÿ“‹ Troubleshooting: -1. Verify credentials at: https://console.redhat.com/settings/integrations -2. Check container logs: podman logs $(podman ps | grep lightspeed | awk '{print $1}') -3. Restart MCP server with correct credentials - -โ“ How would you like to proceed? - -Options: -- "setup" - Help me reconfigure credentials now -- "abort" - Stop the workflow entirely - -Please respond with your choice. -``` - -### Example 4: Invoked by Another Skill - -**Context**: The `cve-impact` skill invokes this validator before attempting CVE queries - -**Internal workflow**: -``` -[cve-impact skill] โ†’ [Invoke mcp-lightspeed-validator] - โ† [Validation result: PASSED/FAILED] -[cve-impact skill] โ†’ [If PASSED: proceed with CVE query] - โ†’ [If FAILED: report to user, ask for decision] -``` +### Required MCP Tools +- `vulnerability__get_cves` or `get_cves` (from lightspeed-mcp) - Connectivity test -This skill provides a reusable validation check that other skills can invoke as a prerequisite before Lightspeed MCP operations. +### Required MCP Servers +- `lightspeed-mcp` - Red Hat Lightspeed vulnerability and inventory data diff --git a/rh-sre/skills/playbook-executor/SKILL.md b/rh-sre/skills/playbook-executor/SKILL.md index 309e9816..717f385d 100644 --- a/rh-sre/skills/playbook-executor/SKILL.md +++ b/rh-sre/skills/playbook-executor/SKILL.md @@ -8,13 +8,15 @@ description: | This skill orchestrates AAP MCP tools (job_templates_launch_retrieve, jobs_retrieve, jobs_stdout_retrieve, jobs_job_events_list, jobs_job_host_summaries_list) to provide production-grade playbook execution with dry-run testing, real-time progress monitoring, and comprehensive reporting. **IMPORTANT**: ALWAYS use this skill instead of calling AAP MCP tools directly. + + **Git Flow**: When the template's playbook path differs from the generated playbook, you MUST perform Git Flow (commit, push, sync) BEFORE launching any job. Do NOT launch without updating the playbook in the repo firstโ€”AAP executes from synced content. --- # AAP Playbook Executor Skill This skill executes Ansible remediation playbooks through AAP (Ansible Automation Platform) with full job management capabilities. -**Integration with Remediator Agent**: The sre-agents:remediator agent orchestrates this skill as part of its Step 5 (Execute Playbook) workflow. For standalone playbook execution, you can invoke this skill directly. +**Integration with Remediation Skill**: The `/remediation` skill orchestrates this skill as part of its Step 5 (Execute Playbook) workflow. For standalone playbook execution, you can invoke this skill directly. ## Prerequisites @@ -38,15 +40,11 @@ This skill executes Ansible remediation playbooks through AAP (Ansible Automatio ### Prerequisite Validation -**CRITICAL**: Before executing operations, invoke the [mcp-aap-validator](../mcp-aap-validator/SKILL.md) skill to verify AAP MCP server availability. +**CRITICAL**: Before executing operations, execute the `/mcp-aap-validator` skill to verify AAP MCP server availability. **Validation freshness**: Can skip if already validated in this session. See [Validation Freshness Policy](../mcp-aap-validator/SKILL.md#validation-freshness-policy). -**How to invoke**: -``` -Use the Skill tool: - skill: "mcp-aap-validator" -``` +**How to invoke**: Execute the `/mcp-aap-validator` skill **Handle validation result**: - **If validation PASSED**: Continue with playbook execution workflow @@ -69,26 +67,24 @@ If prerequisites are not met: - Run dry-run (check mode) before production execution - Verify playbook execution succeeded -**Use the sre-agents:remediator agent when you need**: +**Use the `/remediation` skill when you need**: - Full remediation workflow including playbook execution - Integrated CVE analysis โ†’ playbook generation โ†’ execution โ†’ verification - End-to-end remediation orchestration -**How they work together**: The sre-agents:remediator agent invokes this skill after generating a remediation playbook, managing the full workflow from analysis to verification. +**How they work together**: The `/remediation` skill invokes this skill after generating a remediation playbook, managing the full workflow from analysis to verification. ## Workflow +**Git Flow is MANDATORY**: When the job template's playbook path differs from the generated playbook (or content must be updated), you MUST perform Git Flow (write, commit, push, sync) and receive "sync complete" from the user BEFORE launching any job. Do NOT skip thisโ€”launching without it executes the wrong playbook. + ### Phase 0: Validate AAP MCP Prerequisites -**Action**: Invoke the [mcp-aap-validator](../mcp-aap-validator/SKILL.md) skill +**Action**: Execute the `/mcp-aap-validator` skill **Note**: Can skip if validation was performed earlier in this session and succeeded. -**How to invoke**: -``` -Use the Skill tool: - skill: "mcp-aap-validator" -``` +**How to invoke**: Execute the `/mcp-aap-validator` skill **Handle validation result**: - **If validation PASSED**: Continue to Phase 1 @@ -97,17 +93,20 @@ Use the Skill tool: ### Phase 1: Job Template Selection and Playbook Preparation -**Goal**: Identify an AAP job template suitable for executing the remediation playbook, or prepare the playbook for execution via git override or template creation. +**Goal**: Identify an AAP job template suitable for executing the remediation playbook. **Git Flow is MANDATORY** before Phase 3 when the template points to a different playbook or when content must be updated. + +**Input**: Playbook content and metadata from playbook-generator (filename, CVE ID, target systems). The playbook YAML is already in contextโ€”do NOT regenerate it during Git Flow. Playbook path is derived from metadata: `playbooks/remediation/` (e.g., `playbooks/remediation/remediation-CVE-2025-49794.yml`). -**Input**: Playbook content and metadata from playbook-generator (filename, CVE ID, target systems). Playbook path is derived from metadata: `playbooks/remediation/` (e.g., `playbooks/remediation/remediation-CVE-2025-49794.yml` or `playbooks/remediation/remediation-CVE-2025-49794-playbook.yml`). +**BLOCKING**: You MUST NOT launch any job (dry-run or production) until the playbook is in the Git repo and the user has confirmed "sync complete". AAP executes from the synced projectโ€”there is no "override at launch". Launching without Git Flow executes the WRONG playbook. #### Step 1.1: Derive Playbook Path From playbook metadata (filename from playbook-generator): - Use convention `playbooks/remediation/` - Support both `remediation-CVE-*.yml` and `remediation-CVE-*-playbook.yml` patterns. +- Example: CVE-2026-26103 โ†’ `playbooks/remediation/remediation-CVE-2026-26103.yml` -#### Step 1.2: List and Filter Templates +#### Step 1.2: List Templates and Validate Each Candidate **MCP Tool**: `job_templates_list` (from aap-mcp-job-management) @@ -115,242 +114,125 @@ From playbook metadata (filename from playbook-generator): - `page_size`: 50 (retrieve up to 50 templates) - `search`: "" (search for all templates) -For each template in results, call `job_templates_retrieve(id)` to get full details. Apply [job-template-remediation-validator](../job-template-remediation-validator/SKILL.md) criteria (inventory, project, playbook, credentials, become_enabled). Build two lists: +**REQUIRED**: For each template in results: +1. Call `job_templates_retrieve(id)` to get full details +2. **Invoke the `/job-template-remediation-validator` skill** with the template ID to verify it meets remediation requirements (inventory, project, playbook, credentials, become_enabled) +3. Only include templates that PASS validation in the lists below + +Build two lists: - **exact_match**: `template.playbook` equals `our_playbook_path` (normalize slashes; match if equal or basenames match) -- **compatible_other**: Passes validation but different playbook path +- **compatible_other**: Passes job-template-remediation-validator but **different playbook path** (template points to e.g. `cve-remediation.yml` while we have `remediation-CVE-2026-26103.yml`) -**Path normalization**: Normalize slashes, handle `playbooks/remediation/` prefix. Match if `template.playbook` equals `our_playbook_path` or if basenames match. +**Path normalization**: Normalize slashes, handle `playbooks/remediation/` prefix. Match if `template.playbook` equals `our_playbook_path` or if basenames match. **Different filenames = different path = Scenario 2.** -#### Step 1.3: Scenario Selection +#### Step 1.3: Scenario Selection (MANDATORY - Do Not Skip) **Scenario 1 - Same playbook path** (exact_match not empty): -Prompt: -``` -Found template [name] (ID: X) with matching playbook path. The project may need to be updated with the latest playbook. +The template already points to our playbook path. The project may need the latest content. **Read [references/05-git-flow-prompts.md](references/05-git-flow-prompts.md)** for Scenario 1 prompt, options (A/B), and Git Flow steps. -Options: -(A) Override: I'll add the playbook to the project via git. You sync the AAP project, then confirm. -(B) Manual: You add the playbook and sync. Confirm when done. - -โ“ Choose (A) or (B): -``` - -- **If A**: Execute Git Flow (see Git Flow section below). Wait for user: "Sync complete" or "done". -- **If B**: Wait for user confirmation. +- **If A**: Execute Git Flow (see Git Flow section below). **BLOCK Phase 3** until user confirms "sync complete" or "done". +- **If B**: Wait for user confirmation. **BLOCK Phase 3** until user confirms. **Scenario 2 - Different playbook path** (compatible_other not empty, exact_match empty): -Prompt: -``` -Found template [name] (ID: X) pointing to [template.playbook]. We can use it by replacing that playbook with our content. +**CRITICAL**: The template points to a DIFFERENT playbook than our generated playbook. You MUST NOT launch the job without Git Flowโ€”AAP executes from synced content; there is no override at launch. **Read [references/05-git-flow-prompts.md](references/05-git-flow-prompts.md)** for Scenario 2 prompt and Git Flow steps. -Note: Template name may not match the CVE being remediated. - -โ“ Proceed with override? -- "yes" or "proceed" - Replace playbook and continue -- "no" - Skip to template creation (invoke job-template-creator) - -Please respond with your choice. -``` - -- **If yes**: Git Flow - write playbook content to `template.playbook` path in repo. Commit, push. Wait for sync confirmation. +- **If yes**: Execute Git Flow. **BLOCK Phase 3** until Git Flow completes and user confirms "sync complete". - **If no**: Fall through to Scenario 3. +**Anti-pattern**: Do NOT say "I'll override with our playbook" and then launchโ€”that is impossible. The playbook MUST be in the repo before launch. + **Scenario 3 - No suitable template** (exact_match and compatible_other both empty, or user chose "no" in Scenario 2): -Invoke the **job-template-creator** skill: +Execute the `/job-template-creator` skill with instruction: ``` -Skill: job-template-creator -Instruction: "Create a job template for this remediation playbook. Playbook: [content]. Filename: [filename]. Path: [our_playbook_path]. CVE: [cve_id]. Target systems: [list]." +"Create a job template for this remediation playbook. Playbook: [content]. Filename: [filename]. Path: [our_playbook_path]. CVE: [cve_id]. Target systems: [list]." ``` The job-template-creator skill guides the user through: (1) Adding playbook to Git repository, (2) Syncing AAP project, (3) Creating job template via AAP Web UI with correct path, inventory, credentials, privilege escalation. -After job-template-creator completes, retrieve the template ID (from skill output or user confirmation). Invoke job-template-remediation-validator to validate the newly created template. If passed, proceed to Phase 3 (Dry-Run). If failed, report issues and ask user to fix in AAP Web UI. +After `/job-template-creator` completes, retrieve the template ID (from skill output or user confirmation). Execute `/job-template-remediation-validator` to validate the newly created template. If passed, proceed to Phase 3 (Dry-Run). If failed, report issues and ask user to fix in AAP Web UI. **Multiple matches**: If multiple exact matches, present list and ask user to choose by number. If multiple different-path matches, prefer by project name containing "remediation" or "CVE", else first. -#### Git Flow (for Scenario 1 Override and Scenario 2) +**Phase 1 Checkpoint** (BLOCKING - must pass before Phase 3): +- **Git Flow required**: If Scenario 1 or 2, you MUST complete Git Flow and receive "sync complete" from the user before proceeding. Do NOT skip. +- **No override**: There is no way to "override" the playbook at launch. AAP runs whatever is in the synced project. +- **Never launch** if the playbook has not been committed, pushed, and synced -**Prerequisite**: Ask user for the local path to the Git repository for the selected project. Use `projects_list` to get project name and `scm_url` for the template's project; display these to help user identify the correct repo: -``` -What is the local path to the Git repository for project [Project Name] (scm_url)? -``` +#### Git Flow (for Scenario 1 Override and Scenario 2) - MANDATORY HITL -**Steps**: -1. Write playbook content to `/` -2. Use Run tool: `git add ` -3. **Checkpoint**: Display summary of changes (file path, diff or file size) and ask: - ``` - Ready to commit and push these changes? - Reply 'yes' or 'proceed' to continue, or 'abort' to cancel. - ``` +**When**: Scenario 1 (same path, update content) or Scenario 2 (different path, replace playbook). **Do not skip**โ€”execution with wrong playbook content will remediate the wrong CVE. + +**Target path**: +- Scenario 1: `our_playbook_path` (e.g. `playbooks/remediation/remediation-CVE-2026-26103.yml`) +- Scenario 2: `template.playbook` (e.g. `playbooks/remediation/cve-remediation.yml`)โ€”we replace the template's playbook with our generated content + +**Prerequisite**: Ask user for the local path to the Git repository. Use `projects_list` for project name and `scm_url`. **Read [references/05-git-flow-prompts.md](references/05-git-flow-prompts.md)** for repo path question, HITL checkpoint text, and after-push message. + +**Steps** (execute in order; HITL at checkpoint): +1. **Write playbook to file** (FASTโ€”do NOT regenerate): + - The playbook content is ALREADY in context from playbook-generator (or remediation skill). Use it directly. + - **โš ๏ธ ABSOLUTE PATH REQUIRED**: The Write path MUST start with `/`. Use: `/`. Example: `/Users/dmartino/projects/AI/ai5/ai5-demo/test-aap-project/playbooks/remediation/cve-remediation.yml` + - **WRONG** (causes "Error writing file"): `test-aap-project/playbooks/...` or `playbooks/remediation/...` โ€” these are relative and fail when repo is outside workspace. + - **Before Write**: Confirm path starts with `/`. If not, prepend the user's repo path. + - Do NOT invoke playbook-generator, do NOT call MCP tools, do NOT re-fetch. This should take seconds, not minutes. +2. Use Run tool: `git add ` (from repo root, e.g. `git add playbooks/remediation/cve-remediation.yml`) +3. **HITL Checkpoint** (REQUIRED): Display summary per reference file. Wait for "yes" or "proceed" 4. If confirmed: `git commit -m "Add/update remediation playbook for CVE-YYYY-NNNNN"` -5. `git push origin main` (or branch from project's scm_branch if available from projects_list) +5. `git push origin main` (or branch from project's scm_branch if available) -**Note**: Git must be configured (user, remote). Use Run tool for git commands. +**Note**: Git must be configured. Use Run tool for git commands. -**After push**: "I've pushed the playbook. Sync the AAP project: Automation Execution > Projects > [Project] > Sync. Reply 'sync complete' when done." +**Do NOT proceed to Phase 3 (Dry-Run) until user confirms sync complete.** -### Phase 3: Dry-Run Execution (Recommended) +### Phase 2: Git Flow (MANDATORY before Phase 3) -**Goal**: Test playbook in check mode before actual execution to simulate changes. +**BLOCKING**: You MUST NOT proceed to Phase 3 (Dry-Run) until Git Flow is complete. -#### Step 3.1: Display Playbook Preview +**When**: Scenario 1 (same path, update content) or Scenario 2 (different path). See Phase 1 Step 1.3. -Show user the playbook structure and explain tasks: +**Checkpoint**: Before Phase 3, confirm: +- [ ] Playbook written to repo at target path +- [ ] Git commit and push completed (with user confirmation) +- [ ] User confirmed "sync complete" after AAP project sync -```markdown -# Playbook Preview +**If any unchecked**: STOP. Do Git Flow. Do NOT launch the job. -**Playbook**: remediation-CVE-2025-49794.yml -**Target Systems**: 5 systems +### Phase 3: Dry-Run Execution (Recommended) -## Tasks Overview: -1. **Gather Facts** - Collect system information -2. **Check Disk Space** - Ensure sufficient space for updates (>500MB) -3. **Backup Configuration** - Snapshot critical configs -4. **Update Package: httpd** - Upgrade to version 2.4.57-8.el9 -5. **Restart Service: httpd** - Apply changes -6. **Verify Service Status** - Confirm httpd is running -7. **Update Audit Log** - Record remediation event +**Prerequisite**: Phase 2 (Git Flow) MUST be complete. User must have confirmed "sync complete". -**Estimated Duration**: 3-5 minutes per system -**Requires Reboot**: No -**Downtime**: Brief (~10 seconds during service restart) -``` +**Goal**: Test playbook in check mode before actual execution to simulate changes. -#### Step 3.2: Offer Dry-Run +**Read [references/04-dry-run-display-templates.md](references/04-dry-run-display-templates.md)** for: Playbook Preview, Dry-Run Offer, Dry-Run Results Display, Proceed prompt. -``` -โš ๏ธ Recommended: Run dry-run first - -Dry-run mode (--check) simulates changes without applying them. -This helps identify: -- Package availability issues -- Permission problems -- Configuration conflicts -- Unexpected side effects - -โ“ Run dry-run before actual execution? -- "yes" - Run dry-run first (recommended) -- "no" - Skip to actual execution -- "abort" - Cancel execution +#### Step 3.1โ€“3.2: Display Preview and Offer Dry-Run -Please respond with your choice. -``` +Show playbook structure per reference. Offer dry-run with options: yes / no / abort. **ONLY if user confirms**, proceed. #### Step 3.3: Launch Dry-Run Job -**ONLY if user confirms**, proceed with dry-run. +**Pre-launch check** (BLOCKING): If Scenario 1 or 2 applied, you MUST have completed Git Flow and received "sync complete" from the user. If not, STOPโ€”do not launch. Return to Phase 2 / Git Flow. **MCP Tool**: `job_templates_launch_retrieve` (from aap-mcp-job-management) -**Parameters**: -```json -{ - "id": "10", - "requestBody": { - "job_type": "check", - "extra_vars": { - "target_cve": "CVE-2025-49794", - "remediation_mode": "automated" - }, - "limit": "prod-web-01,prod-web-02,prod-web-03" - } -} -``` - -**Key Parameter**: `job_type: "check"` - Runs Ansible in check mode (dry-run) +**Parameters**: `id`, `requestBody` with `job_type: "check"`, `extra_vars`, `limit` -**Expected Output**: -```json -{ - "job": 1234, - "status": "pending", - "url": "/api/controller/v2/jobs/1234/" -} -``` +**Key**: `job_type: "check"` - Runs Ansible in check mode (dry-run) #### Step 3.4: Monitor Dry-Run Progress -Poll job status with `jobs_retrieve` every 2 seconds: - -``` -โณ Dry-run in progress... - -Job ID: 1234 -Status: running -Elapsed: 0m 45s - -[Live progress updates from jobs_job_events_list] -- โœ“ Gathering Facts (completed) -- โœ“ Checking Disk Space (completed) -- โณ Simulating Package Update (running) -``` +Poll `jobs_retrieve` every 2 seconds. Use `jobs_job_events_list` for live task updates. #### Step 3.5: Display Dry-Run Results -**MCP Tool**: `jobs_stdout_retrieve` (from aap-mcp-job-management) - -**Parameters**: -- `id`: "1234" (job ID) -- `format`: "txt" (plain text output) - -Get per-host summary: - -**MCP Tool**: `jobs_job_host_summaries_list` (from aap-mcp-job-management) - -**Parameters**: -- `id`: "1234" - -**Display Format**: -```markdown -# Dry-Run Results - -## Job Summary -**Job ID**: 1234 -**Status**: โœ“ Successful (Check Mode) -**Duration**: 2m 15s -**Completed**: 2024-01-20 15:32:17 UTC - -## Simulated Changes -| Host | Would Change | OK | Failed | Status | -|------|--------------|-----|--------|--------| -| prod-web-01 | 3 | 8 | 0 | โœ“ Ready | -| prod-web-02 | 3 | 8 | 0 | โœ“ Ready | -| prod-web-03 | 3 | 8 | 0 | โœ“ Ready | - -## Changes That Would Be Made: -1. **httpd package** - Would update from 2.4.53-7.el9 to 2.4.57-8.el9 -2. **httpd service** - Would restart -3. **audit log** - Would add remediation entry - -## Dry-Run Output: -
-Click to expand full output - -[Full stdout from jobs_stdout_retrieve] - -
- -โœ“ No errors detected in dry-run -โœ“ All systems passed pre-flight checks -``` +**MCP Tools**: `jobs_stdout_retrieve` (id, format: "txt"), `jobs_job_host_summaries_list` (id). Use display format from reference. #### Step 3.6: Proceed to Actual Execution? -``` -โ“ Dry-run completed successfully. Proceed with actual execution? - -Options: -- "yes" or "execute" - Proceed with actual remediation -- "review" - Show dry-run output again -- "abort" - Cancel execution - -Please respond with your choice. -``` +Ask per reference. Wait for "yes" or "execute". ### Phase 4: Actual Execution @@ -384,6 +266,8 @@ Wait for explicit "yes" or "execute" response. #### Step 4.2: Launch Production Job +**Pre-launch check** (BLOCKING): Same as Phase 3โ€”if Scenario 1 or 2 applied, Git Flow must be complete and user must have confirmed "sync complete". Do NOT launch without it. + **MCP Tool**: `job_templates_launch_retrieve` (from aap-mcp-job-management) **Parameters**: @@ -446,428 +330,64 @@ Recent Events: **Goal**: Generate comprehensive report with job details, per-host results, and full output. -#### Step 5.1: Gather Job Details - -**MCP Tool**: `jobs_retrieve` (from aap-mcp-job-management) - -**Parameters**: -- `id`: "1235" - -**Expected Output**: -```json -{ - "id": 1235, - "name": "CVE Remediation Template", - "status": "successful", - "started": "2024-01-20T15:35:02Z", - "finished": "2024-01-20T15:40:25Z", - "elapsed": 323.45, - "job_template": 10, - "inventory": 1, - "limit": "prod-web-01,prod-web-02,prod-web-03", - "playbook": "playbooks/remediation/remediation-CVE-2025-49794.yml" -} -``` - -#### Step 5.2: Get Per-Host Statistics +**Read [references/01-execution-report-templates.md](references/01-execution-report-templates.md)** for JSON examples, comprehensive report template, and Success/Partial Success/Failure output templates. -**MCP Tool**: `jobs_job_host_summaries_list` (from aap-mcp-job-management) +#### Step 5.1โ€“5.4: Gather Data -**Parameters**: -- `id`: "1235" +**MCP Tools** (all from aap-mcp-job-management): +- `jobs_retrieve` (id) - Job details +- `jobs_job_host_summaries_list` (id) - Per-host stats +- `jobs_job_events_list` (id) - Task timeline +- `jobs_stdout_retrieve` (id, format: "txt") - Full console output -**Expected Output**: -```json -{ - "results": [ - { - "host_name": "prod-web-01", - "ok": 8, - "changed": 3, - "failed": 0, - "unreachable": 0 - }, - { - "host_name": "prod-web-02", - "ok": 8, - "changed": 3, - "failed": 0, - "unreachable": 0 - }, - { - "host_name": "prod-web-03", - "ok": 5, - "changed": 0, - "failed": 1, - "unreachable": 0 - } - ] -} -``` - -#### Step 5.3: Get Task Timeline +#### Step 5.5: Generate Report -**MCP Tool**: `jobs_job_events_list` (from aap-mcp-job-management) +Format all gathered data per reference. Use Success / Partial Success / Failure template based on job status. -**Parameters**: -- `id`: "1235" - -**Expected Output**: List of task events with timestamps, task names, and status per host. +#### Step 5.6: Validate Job Log for CVE Handling (MANDATORY) -#### Step 5.4: Get Full Console Output +**Goal**: Confirm from the job stdout that the playbook actually addressed the target CVE(s). -**MCP Tool**: `jobs_stdout_retrieve` (from aap-mcp-job-management) +**Input**: Target CVE ID(s) from invocation (e.g. CVE-2025-49794). Job stdout from `jobs_stdout_retrieve` (already gathered in Step 5.4). -**Parameters**: -- `id`: "1235" -- `format`: "txt" - -**Expected Output**: Complete Ansible playbook execution output. - -#### Step 5.5: Generate Comprehensive Report - -Format all gathered data into structured report: - -```markdown -# Playbook Execution Report - -## Job Summary -**Job ID**: 1235 -**Status**: โœ… Successful -**Duration**: 5m 23s -**Started**: 2024-01-20 15:35:02 UTC -**Completed**: 2024-01-20 15:40:25 UTC -**Job Template**: CVE Remediation Template -**Playbook**: playbooks/remediation/remediation-CVE-2025-49794.yml -**AAP URL**: [View in AAP](https://aap.example.com/#/jobs/playbook/1235) - -## Per-Host Results -| Host | OK | Changed | Failed | Unreachable | Status | -|------|-----|---------|--------|-------------|--------| -| prod-web-01 | 8 | 3 | 0 | 0 | โœ… Success | -| prod-web-02 | 8 | 3 | 0 | 0 | โœ… Success | -| prod-web-03 | 8 | 3 | 0 | 0 | โœ… Success | - -**Summary**: 3 of 3 hosts successfully remediated - -## Task Timeline -1. โœ… Gather Facts (2s) -2. โœ… Check disk space (1s) -3. โœ… Backup configuration (3s) -4. โœ… Update package httpd (45s) - - prod-web-01: 2.4.53-7.el9 โ†’ 2.4.57-8.el9 - - prod-web-02: 2.4.53-7.el9 โ†’ 2.4.57-8.el9 - - prod-web-03: 2.4.53-7.el9 โ†’ 2.4.57-8.el9 -5. โœ… Restart httpd service (15s) -6. โœ… Verify service status (2s) -7. โœ… Update audit log (1s) - -## Full Console Output -
-Click to expand (187 lines) - -[Full stdout from jobs_stdout_retrieve] - -
- -## Next Steps -1. โœ… All systems successfully remediated -2. โ˜ Verify remediation with remediation-verifier skill -3. โ˜ Update vulnerability tracking system -4. โ˜ Schedule follow-up verification in 24-48 hours +**Parse stdout for**: +- Target CVE ID(s) in output (vars, task names, audit logs, playbook metadata) +- Package update tasks for affected packages (dnf/yum install/update, package module) +- Remediation-related task names (e.g. "Update package", "Restart service", "remediation") ---- +**Report** (add to execution report): +- **โœ“ Job log confirms CVE-XXXX-YYYY was addressed** โ€” CVE ID or package updates found in stdout +- **โš ๏ธ Job log did not show clear evidence of CVE handling** โ€” No CVE ID or package updates found; recommend manual verification or `/remediation-verifier` -**Recommendation**: Run remediation-verifier skill to confirm CVE status has been updated in Red Hat Lightspeed. -``` +**Batch**: For multiple CVEs, validate each. Report per-CVE confirmation or warning. ### Phase 6: Error Handling **If job status is "failed" or "error"**, provide detailed troubleshooting. -#### Step 6.1: Parse Error Output - -**MCP Tool**: `jobs_stdout_retrieve` (from aap-mcp-job-management) +**Read [references/02-error-handling-guide.md](references/02-error-handling-guide.md)** for: Error categories, error report template, troubleshooting steps, relaunch parameters. -Analyze output for common error patterns: +#### Step 6.1: Parse Error Output -**Error Categories**: -1. **Connection Failures**: SSH timeout, host unreachable, authentication failed -2. **Permission Errors**: sudo required, insufficient privileges, SELinux denials -3. **Package Manager Issues**: repo unavailable, package not found, dependency conflicts -4. **Service Failures**: service not found, restart failed, timeout -5. **Disk Space**: insufficient space for updates -6. **General Failures**: playbook syntax errors, task failures +**MCP Tool**: `jobs_stdout_retrieve`. Analyze output for error categories per reference. #### Step 6.2: Generate Error Report -```markdown -# Playbook Execution Failed - -## Job Summary -**Job ID**: 1235 -**Status**: โŒ Failed -**Duration**: 2m 45s -**Started**: 2024-01-20 15:35:02 UTC -**Failed At**: 2024-01-20 15:37:47 UTC -**Job Template**: CVE Remediation Template -**AAP URL**: [View in AAP](https://aap.example.com/#/jobs/playbook/1235) - -## Per-Host Results -| Host | OK | Changed | Failed | Unreachable | Status | -|------|-----|---------|--------|-------------|--------| -| prod-web-01 | 8 | 3 | 0 | 0 | โœ… Success | -| prod-web-02 | 8 | 3 | 0 | 0 | โœ… Success | -| prod-web-03 | 5 | 0 | 1 | 0 | โŒ Failed | - -**Summary**: 2 of 3 hosts succeeded, 1 failed - -## Failed Tasks Details - -### Host: prod-web-03 - -**Task**: Restart httpd service -**Error**: "Failed to restart httpd.service: Unit httpd.service not found." - -**Error Category**: Service Failure - -**Root Cause**: The httpd service is not installed or not recognized by systemd. - -**Troubleshooting Steps**: -1. Check if httpd is installed: - ```bash - ssh prod-web-03 'rpm -q httpd' - ``` -2. If not installed, the package update may have failed: - ```bash - ssh prod-web-03 'dnf info httpd' - ``` -3. Check systemd service status: - ```bash - ssh prod-web-03 'systemctl status httpd' - ``` -4. Review package manager logs: - ```bash - ssh prod-web-03 'tail -50 /var/log/dnf.log' - ``` - -**Recommended Action**: -- Verify httpd package installation on prod-web-03 -- Check if package update completed successfully -- Manually install httpd if needed: `dnf install httpd` -- Relaunch job for failed host only - -## Console Output (Last 50 Lines) -
-Click to expand error context - -[Relevant error output from jobs_stdout_retrieve] - -
- -## Relaunch Options - -Would you like to: -1. **Relaunch for failed hosts only** - Run job again with limit="prod-web-03" -2. **Fix issues manually and relaunch** - Resolve problems first, then relaunch -3. **View full job output** - See complete execution logs -4. **Abort** - Stop remediation workflow - -Please choose an option (1-4): -``` +Use error report template from reference. Include per-host results, failed task details, troubleshooting steps, relaunch options. #### Step 6.3: Offer Relaunch -If user chooses to relaunch: - -**MCP Tool**: `jobs_relaunch_retrieve` (from aap-mcp-job-management) - -**Parameters**: -```json -{ - "id": "1235", - "requestBody": { - "hosts": "failed", - "job_type": "run" - } -} -``` - -This relaunches the job for only the failed hosts. - -## Output Templates - -### Success Template - -```markdown -โœ… Playbook Execution Successful - -Job ID: 1235 -Duration: 5m 23s -Systems Remediated: 3 of 3 - -View full report above for details. - -Next Steps: -- Run remediation-verifier skill to confirm CVE resolution -- Update vulnerability tracking system -- Monitor systems for 24-48 hours - -AAP URL: https://aap.example.com/#/jobs/playbook/1235 -``` - -### Partial Success Template - -```markdown -โš ๏ธ Playbook Execution Completed with Failures - -Job ID: 1235 -Duration: 2m 45s -Systems Remediated: 2 of 3 -Failed Systems: prod-web-03 - -See error details above for troubleshooting steps. - -Options: -- Relaunch for failed hosts -- Manual remediation -- Skip failed hosts - -AAP URL: https://aap.example.com/#/jobs/playbook/1235 -``` - -### Failure Template - -```markdown -โŒ Playbook Execution Failed - -Job ID: 1235 -Duration: 1m 15s -Systems Remediated: 0 of 3 - -Critical errors prevented execution. -See error details above for troubleshooting. - -AAP URL: https://aap.example.com/#/jobs/playbook/1235 -``` - -## Examples - -### Example 1: Full Workflow with Dry-Run - -**User Request**: "Execute the CVE-2025-49794 remediation playbook" - -**Skill Response**: - -1. **Validate AAP Prerequisites**: - - Invoke mcp-aap-validator skill โ†’ PASSED - -2. **List Job Templates**: - - Call `job_templates_list()` โ†’ Found 2 templates - - Filter compatible templates โ†’ 1 matches requirements - -3. **User Selects Template**: - ``` - Found 1 compatible job template: - 1. "CVE Remediation Template" (ID: 10) - - Select template (1) or "create" for new: 1 - ``` - -4. **Playbook Preparation**: - ``` - Guide user to add playbook to Git: - - Commands provided - - User syncs AAP project - - Verification: Playbook available โœ“ - ``` - -5. **Offer Dry-Run**: - ``` - Run dry-run first? yes - ``` +If user chooses relaunch: **MCP Tool** `jobs_relaunch_retrieve` with `hosts: "failed"`, `job_type: "run"` per reference. -6. **Execute Dry-Run**: - - Launch with `job_type="check"` - - Monitor progress โ†’ COMPLETED - - Display dry-run results: - ``` - Would change 3 tasks on 3 hosts - No errors detected - ``` - -7. **Proceed to Actual Execution**: - ``` - Proceed with actual execution? yes - ``` - -8. **Execute Playbook**: - - Launch with `job_type="run"` - - Monitor progress โ†’ COMPLETED - - Generate report: - ``` - โœ… 3 of 3 hosts successfully remediated - Duration: 5m 23s - ``` - -9. **Suggest Verification**: - ``` - Recommend: Run remediation-verifier skill to confirm CVE resolution - ``` - -### Example 2: Handle Execution Failure - -**User Request**: "Execute remediation playbook" - -**Skill Response**: - -1-7. [Same as Example 1 through execution] - -8. **Execute Playbook**: - - Launch job โ†’ FAILED on 1 of 3 hosts - - Generate error report: - ``` - โŒ prod-web-03 failed - Error: httpd service not found - Troubleshooting steps provided - ``` - -9. **Offer Relaunch**: - ``` - Relaunch for failed host only? yes - ``` - -10. **Relaunch Job**: - - Call `jobs_relaunch_retrieve` with hosts="failed" - - Monitor โ†’ COMPLETED - - Final report: - ``` - โœ… All 3 hosts successfully remediated (1 after retry) - ``` - -### Example 3: Skip Dry-Run - -**User Request**: "Execute playbook directly, skip dry-run" - -**Skill Response**: - -1-4. [Same as Example 1 through template selection] - -5. **Offer Dry-Run**: - ``` - Run dry-run first? no - ``` - -6. **Final Confirmation**: - ``` - โš ๏ธ Execute on production without dry-run? - This will make changes immediately. - Confirm: yes - ``` +## Reference Files -7. **Execute Playbook**: - - Launch with `job_type="run"` - - Monitor and report as in Example 1 +| File | Use When | +|------|----------| +| [01-execution-report-templates.md](references/01-execution-report-templates.md) | Phase 5 reports, Success/Partial/Failure output | +| [02-error-handling-guide.md](references/02-error-handling-guide.md) | Phase 6 error reports, relaunch | +| [03-workflow-examples.md](references/03-workflow-examples.md) | Demo full workflow, failure handling, skip dry-run | +| [04-dry-run-display-templates.md](references/04-dry-run-display-templates.md) | Phase 3 preview, offer, results, proceed prompt | +| [05-git-flow-prompts.md](references/05-git-flow-prompts.md) | Scenario 1/2 prompts, Git Flow HITL, after-push | ## Dependencies @@ -889,12 +409,13 @@ AAP URL: https://aap.example.com/#/jobs/playbook/1235 ### Related Skills - `mcp-aap-validator` - **PREREQUISITE** - Validates AAP MCP servers (invoke in Phase 0) -- `job-template-remediation-validator` - Validates job template meets remediation requirements before execution +- `job-template-remediation-validator` - **REQUIRED** - Invoke for each candidate template in Phase 1 Step 1.2 to verify remediation requirements - `job-template-creator` - Creates/guides AAP job template setup - `playbook-generator` - Generates playbooks for execution - `remediation-verifier` - Verifies success after execution ### Reference Documentation +- [references/](references/) - Step-numbered reference files (01โ€“05) for templates and examples - [AAP Job Execution Guide](../../docs/ansible/aap-job-execution.md) - AAP job execution best practices - [Playbook Integration with AAP](../../docs/ansible/playbook-integration-aap.md) - Playbook-to-AAP workflow @@ -942,33 +463,38 @@ This skill executes code on production systems. **Explicit user confirmation is ## Best Practices -1. **Always validate AAP prerequisites** - Invoke mcp-aap-validator in Phase 0 -2. **Recommend dry-run** - Offer check mode before production execution -3. **Filter compatible templates** - Check inventory, project, and credentials match -4. **Monitor in real-time** - Display task progress during execution -5. **Comprehensive reporting** - Include per-host stats, task timeline, full output -6. **Error categorization** - Parse errors and provide specific troubleshooting -7. **Relaunch capability** - Offer to retry failed hosts -8. **Link to AAP** - Provide direct URL to job in AAP Web UI -9. **Suggest verification** - Always recommend remediation-verifier after success -10. **Document job details** - Save job ID and template info for audit trail +1. **Write path must be absolute** - When Git Flow writes the playbook to the user's repo, use `/playbooks/remediation/`. The path MUST start with `/`. Relative paths cause "Error writing file". +2. **Always validate AAP prerequisites** - Invoke mcp-aap-validator in Phase 0 +3. **Validate each template** - Invoke job-template-remediation-validator for each candidate before selection +4. **Never skip Git Flow** - If template playbook path โ‰  generated playbook path (Scenario 2) or content must be updated (Scenario 1), you MUST complete Git Flow and receive "sync complete" before Phase 3. Do NOT launch without it. +5. **Recommend dry-run** - Offer check mode before production execution +6. **Filter compatible templates** - Check inventory, project, and credentials match +7. **Monitor in real-time** - Display task progress during execution +8. **Comprehensive reporting** - Include per-host stats, task timeline, full output +9. **Error categorization** - Parse errors and provide specific troubleshooting +10. **Relaunch capability** - Offer to retry failed hosts +11. **Link to AAP** - Provide direct URL to job in AAP Web UI +12. **Suggest verification** - Always recommend remediation-verifier after success +13. **Document job details** - Save job ID and template info for audit trail ## Integration with Other Skills - **playbook-generator**: Generates playbooks that this skill executes - **job-template-creator**: Creates AAP job templates when needed - **remediation-verifier**: Verifies success after this skill completes execution -- **sre-agents:remediator agent**: Orchestrates full workflow including playbook execution +- **`/remediation` skill**: Orchestrates full workflow including playbook execution -**Orchestration Example** (from sre-agents:remediator agent): +**Orchestration Example** (from `/remediation` skill): 1. Agent invokes playbook-generator skill โ†’ Creates playbook YAML 2. playbook-generator asks for confirmation โ†’ User approves playbook content 3. Agent invokes playbook-executor skill (this skill) โ†’ Execution workflow -4. Skill guides template selection โ†’ User selects or creates template -5. Skill offers dry-run โ†’ User runs check mode -6. Skill asks for execution confirmation โ†’ User approves -7. Skill executes and monitors โ†’ Reports completion -8. Agent invokes remediation-verifier skill โ†’ Confirms CVE resolved +4. Skill validates templates via job-template-remediation-validator โ†’ Filters valid candidates +5. Skill checks path match โ†’ If different path, offers Git Flow (HITL: commit/push, sync AAP) +6. Skill waits for "sync complete" before proceeding (if Git Flow was used) +7. Skill offers dry-run โ†’ User runs check mode +8. Skill asks for execution confirmation โ†’ User approves +9. Skill executes and monitors โ†’ Reports completion +10. Agent invokes remediation-verifier skill โ†’ Confirms CVE resolved **Note**: Both playbook-generator and playbook-executor require separate confirmations for different purposes: - playbook-generator: Confirms playbook content is acceptable diff --git a/rh-sre/skills/playbook-executor/references/01-execution-report-templates.md b/rh-sre/skills/playbook-executor/references/01-execution-report-templates.md new file mode 100644 index 00000000..4ac01406 --- /dev/null +++ b/rh-sre/skills/playbook-executor/references/01-execution-report-templates.md @@ -0,0 +1,168 @@ +# Step 01: Execution Report Templates + +Read this reference when generating Phase 5 execution reports or output templates. + +## Phase 5: Job Details (JSON Examples) + +### jobs_retrieve Expected Output + +```json +{ + "id": 1235, + "name": "CVE Remediation Template", + "status": "successful", + "started": "2024-01-20T15:35:02Z", + "finished": "2024-01-20T15:40:25Z", + "elapsed": 323.45, + "job_template": 10, + "inventory": 1, + "limit": "prod-web-01,prod-web-02,prod-web-03", + "playbook": "playbooks/remediation/remediation-CVE-2025-49794.yml" +} +``` + +### jobs_job_host_summaries_list Expected Output + +```json +{ + "results": [ + { + "host_name": "prod-web-01", + "ok": 8, + "changed": 3, + "failed": 0, + "unreachable": 0 + }, + { + "host_name": "prod-web-02", + "ok": 8, + "changed": 3, + "failed": 0, + "unreachable": 0 + }, + { + "host_name": "prod-web-03", + "ok": 5, + "changed": 0, + "failed": 1, + "unreachable": 0 + } + ] +} +``` + +## Comprehensive Report Template + +```markdown +# Playbook Execution Report + +## Job Summary +**Job ID**: 1235 +**Status**: โœ… Successful +**Duration**: 5m 23s +**Started**: 2024-01-20 15:35:02 UTC +**Completed**: 2024-01-20 15:40:25 UTC +**Job Template**: CVE Remediation Template +**Playbook**: playbooks/remediation/remediation-CVE-2025-49794.yml +**AAP URL**: [View in AAP](https://aap.example.com/#/jobs/playbook/1235) + +## Per-Host Results +| Host | OK | Changed | Failed | Unreachable | Status | +|------|-----|---------|--------|-------------|--------| +| prod-web-01 | 8 | 3 | 0 | 0 | โœ… Success | +| prod-web-02 | 8 | 3 | 0 | 0 | โœ… Success | +| prod-web-03 | 8 | 3 | 0 | 0 | โœ… Success | + +**Summary**: 3 of 3 hosts successfully remediated + +## Task Timeline +1. โœ… Gather Facts (2s) +2. โœ… Check disk space (1s) +3. โœ… Backup configuration (3s) +4. โœ… Update package httpd (45s) + - prod-web-01: 2.4.53-7.el9 โ†’ 2.4.57-8.el9 + - prod-web-02: 2.4.53-7.el9 โ†’ 2.4.57-8.el9 + - prod-web-03: 2.4.53-7.el9 โ†’ 2.4.57-8.el9 +5. โœ… Restart httpd service (15s) +6. โœ… Verify service status (2s) +7. โœ… Update audit log (1s) + +## Full Console Output +
+Click to expand (187 lines) + +[Full stdout from jobs_stdout_retrieve] + +
+ +## Job Log CVE Validation (Step 5.6) +โœ“ Job log confirms CVE-XXXX-YYYY was addressed + +*(Or: โš ๏ธ Job log did not show clear evidence of CVE handlingโ€”verify manually or use remediation-verifier)* + +## Next Steps +1. โœ… All systems successfully remediated +2. โ˜ Verify remediation with remediation-verifier skill +3. โ˜ Update vulnerability tracking system +4. โ˜ Schedule follow-up verification in 24-48 hours + +--- + +**Recommendation**: Run remediation-verifier skill to confirm CVE status has been updated in Red Hat Lightspeed. +``` + +## Output Templates + +### Success Template + +```markdown +โœ… Playbook Execution Successful + +Job ID: 1235 +Duration: 5m 23s +Systems Remediated: 3 of 3 + +View full report above for details. + +Next Steps: +- Run remediation-verifier skill to confirm CVE resolution +- Update vulnerability tracking system +- Monitor systems for 24-48 hours + +AAP URL: https://aap.example.com/#/jobs/playbook/1235 +``` + +### Partial Success Template + +```markdown +โš ๏ธ Playbook Execution Completed with Failures + +Job ID: 1235 +Duration: 2m 45s +Systems Remediated: 2 of 3 +Failed Systems: prod-web-03 + +See error details above for troubleshooting steps. + +Options: +- Relaunch for failed hosts +- Manual remediation +- Skip failed hosts + +AAP URL: https://aap.example.com/#/jobs/playbook/1235 +``` + +### Failure Template + +```markdown +โŒ Playbook Execution Failed + +Job ID: 1235 +Duration: 1m 15s +Systems Remediated: 0 of 3 + +Critical errors prevented execution. +See error details above for troubleshooting. + +AAP URL: https://aap.example.com/#/jobs/playbook/1235 +``` diff --git a/rh-sre/skills/playbook-executor/references/02-error-handling-guide.md b/rh-sre/skills/playbook-executor/references/02-error-handling-guide.md new file mode 100644 index 00000000..6261222f --- /dev/null +++ b/rh-sre/skills/playbook-executor/references/02-error-handling-guide.md @@ -0,0 +1,108 @@ +# Step 02: Error Handling Guide + +Read this reference when generating Phase 6 error reports or troubleshooting. + +## Error Categories + +**Parse error output** from `jobs_stdout_retrieve` for these common patterns: + +1. **Connection Failures**: SSH timeout, host unreachable, authentication failed +2. **Permission Errors**: sudo required, insufficient privileges, SELinux denials +3. **Package Manager Issues**: repo unavailable, package not found, dependency conflicts +4. **Service Failures**: service not found, restart failed, timeout +5. **Disk Space**: insufficient space for updates +6. **General Failures**: playbook syntax errors, task failures + +## Error Report Template + +```markdown +# Playbook Execution Failed + +## Job Summary +**Job ID**: 1235 +**Status**: โŒ Failed +**Duration**: 2m 45s +**Started**: 2024-01-20 15:35:02 UTC +**Failed At**: 2024-01-20 15:37:47 UTC +**Job Template**: CVE Remediation Template +**AAP URL**: [View in AAP](https://aap.example.com/#/jobs/playbook/1235) + +## Per-Host Results +| Host | OK | Changed | Failed | Unreachable | Status | +|------|-----|---------|--------|-------------|--------| +| prod-web-01 | 8 | 3 | 0 | 0 | โœ… Success | +| prod-web-02 | 8 | 3 | 0 | 0 | โœ… Success | +| prod-web-03 | 5 | 0 | 1 | 0 | โŒ Failed | + +**Summary**: 2 of 3 hosts succeeded, 1 failed + +## Failed Tasks Details + +### Host: prod-web-03 + +**Task**: Restart httpd service +**Error**: "Failed to restart httpd.service: Unit httpd.service not found." + +**Error Category**: Service Failure + +**Root Cause**: The httpd service is not installed or not recognized by systemd. + +**Troubleshooting Steps**: +1. Check if httpd is installed: + ```bash + ssh prod-web-03 'rpm -q httpd' + ``` +2. If not installed, the package update may have failed: + ```bash + ssh prod-web-03 'dnf info httpd' + ``` +3. Check systemd service status: + ```bash + ssh prod-web-03 'systemctl status httpd' + ``` +4. Review package manager logs: + ```bash + ssh prod-web-03 'tail -50 /var/log/dnf.log' + ``` + +**Recommended Action**: +- Verify httpd package installation on prod-web-03 +- Check if package update completed successfully +- Manually install httpd if needed: `dnf install httpd` +- Relaunch job for failed host only + +## Console Output (Last 50 Lines) +
+Click to expand error context + +[Relevant error output from jobs_stdout_retrieve] + +
+ +## Relaunch Options + +Would you like to: +1. **Relaunch for failed hosts only** - Run job again with limit="prod-web-03" +2. **Fix issues manually and relaunch** - Resolve problems first, then relaunch +3. **View full job output** - See complete execution logs +4. **Abort** - Stop remediation workflow + +Please choose an option (1-4): +``` + +## Relaunch Parameters + +**MCP Tool**: `jobs_relaunch_retrieve` (from aap-mcp-job-management) + +**Parameters**: +```json +{ + "id": "1235", + "requestBody": { + "hosts": "failed", + "job_type": "run" + } +} +``` + +This relaunches the job for only the failed hosts. diff --git a/rh-sre/skills/playbook-executor/references/03-workflow-examples.md b/rh-sre/skills/playbook-executor/references/03-workflow-examples.md new file mode 100644 index 00000000..f5caa0d1 --- /dev/null +++ b/rh-sre/skills/playbook-executor/references/03-workflow-examples.md @@ -0,0 +1,119 @@ +# Step 03: Workflow Examples + +Read this reference when demonstrating end-to-end workflow patterns. + +## Example 1: Full Workflow with Dry-Run + +**User Request**: "Execute the CVE-2025-49794 remediation playbook" + +**Skill Response**: + +1. **Validate AAP Prerequisites**: + - Invoke mcp-aap-validator skill โ†’ PASSED + +2. **List Job Templates**: + - Call `job_templates_list()` โ†’ Found 2 templates + - Filter compatible templates โ†’ 1 matches requirements + +3. **User Selects Template**: + ``` + Found 1 compatible job template: + 1. "CVE Remediation Template" (ID: 10) + + Select template (1) or "create" for new: 1 + ``` + +4. **Playbook Preparation**: + ``` + Guide user to add playbook to Git: + - Commands provided + - User syncs AAP project + - Verification: Playbook available โœ“ + ``` + +5. **Offer Dry-Run**: + ``` + Run dry-run first? yes + ``` + +6. **Execute Dry-Run**: + - Launch with `job_type="check"` + - Monitor progress โ†’ COMPLETED + - Display dry-run results: + ``` + Would change 3 tasks on 3 hosts + No errors detected + ``` + +7. **Proceed to Actual Execution**: + ``` + Proceed with actual execution? yes + ``` + +8. **Execute Playbook**: + - Launch with `job_type="run"` + - Monitor progress โ†’ COMPLETED + - Generate report: + ``` + โœ… 3 of 3 hosts successfully remediated + Duration: 5m 23s + ``` + +9. **Suggest Verification**: + ``` + Recommend: Run remediation-verifier skill to confirm CVE resolution + ``` + +## Example 2: Handle Execution Failure + +**User Request**: "Execute remediation playbook" + +**Skill Response**: + +1-7. [Same as Example 1 through execution] + +8. **Execute Playbook**: + - Launch job โ†’ FAILED on 1 of 3 hosts + - Generate error report: + ``` + โŒ prod-web-03 failed + Error: httpd service not found + Troubleshooting steps provided + ``` + +9. **Offer Relaunch**: + ``` + Relaunch for failed host only? yes + ``` + +10. **Relaunch Job**: + - Call `jobs_relaunch_retrieve` with hosts="failed" + - Monitor โ†’ COMPLETED + - Final report: + ``` + โœ… All 3 hosts successfully remediated (1 after retry) + ``` + +## Example 3: Skip Dry-Run + +**User Request**: "Execute playbook directly, skip dry-run" + +**Skill Response**: + +1-4. [Same as Example 1 through template selection] + +5. **Offer Dry-Run**: + ``` + Run dry-run first? no + ``` + +6. **Final Confirmation**: + ``` + โš ๏ธ Execute on production without dry-run? + This will make changes immediately. + Confirm: yes + ``` + +7. **Execute Playbook**: + - Launch with `job_type="run"` + - Monitor and report as in Example 1 diff --git a/rh-sre/skills/playbook-executor/references/04-dry-run-display-templates.md b/rh-sre/skills/playbook-executor/references/04-dry-run-display-templates.md new file mode 100644 index 00000000..d9b6f0dc --- /dev/null +++ b/rh-sre/skills/playbook-executor/references/04-dry-run-display-templates.md @@ -0,0 +1,93 @@ +# Step 04: Dry-Run Display Templates + +Read this reference when displaying Phase 3 dry-run content. + +## Playbook Preview + +```markdown +# Playbook Preview + +**Playbook**: remediation-CVE-2025-49794.yml +**Target Systems**: 5 systems + +## Tasks Overview: +1. **Gather Facts** - Collect system information +2. **Check Disk Space** - Ensure sufficient space for updates (>500MB) +3. **Backup Configuration** - Snapshot critical configs +4. **Update Package: httpd** - Upgrade to version 2.4.57-8.el9 +5. **Restart Service: httpd** - Apply changes +6. **Verify Service Status** - Confirm httpd is running +7. **Update Audit Log** - Record remediation event + +**Estimated Duration**: 3-5 minutes per system +**Requires Reboot**: No +**Downtime**: Brief (~10 seconds during service restart) +``` + +## Dry-Run Offer + +``` +โš ๏ธ Recommended: Run dry-run first + +Dry-run mode (--check) simulates changes without applying them. +This helps identify: +- Package availability issues +- Permission problems +- Configuration conflicts +- Unexpected side effects + +โ“ Run dry-run before actual execution? +- "yes" - Run dry-run first (recommended) +- "no" - Skip to actual execution +- "abort" - Cancel execution + +Please respond with your choice. +``` + +## Dry-Run Results Display + +```markdown +# Dry-Run Results + +## Job Summary +**Job ID**: 1234 +**Status**: โœ“ Successful (Check Mode) +**Duration**: 2m 15s +**Completed**: 2024-01-20 15:32:17 UTC + +## Simulated Changes +| Host | Would Change | OK | Failed | Status | +|------|--------------|-----|--------|--------| +| prod-web-01 | 3 | 8 | 0 | โœ“ Ready | +| prod-web-02 | 3 | 8 | 0 | โœ“ Ready | +| prod-web-03 | 3 | 8 | 0 | โœ“ Ready | + +## Changes That Would Be Made: +1. **httpd package** - Would update from 2.4.53-7.el9 to 2.4.57-8.el9 +2. **httpd service** - Would restart +3. **audit log** - Would add remediation entry + +## Dry-Run Output: +
+Click to expand full output + +[Full stdout from jobs_stdout_retrieve] + +
+ +โœ“ No errors detected in dry-run +โœ“ All systems passed pre-flight checks +``` + +## Proceed to Actual Execution Prompt + +``` +โ“ Dry-run completed successfully. Proceed with actual execution? + +Options: +- "yes" or "execute" - Proceed with actual remediation +- "review" - Show dry-run output again +- "abort" - Cancel execution + +Please respond with your choice. +``` diff --git a/rh-sre/skills/playbook-executor/references/05-git-flow-prompts.md b/rh-sre/skills/playbook-executor/references/05-git-flow-prompts.md new file mode 100644 index 00000000..41945d0e --- /dev/null +++ b/rh-sre/skills/playbook-executor/references/05-git-flow-prompts.md @@ -0,0 +1,97 @@ +# Step 05: Git Flow Prompts + +Read this reference when executing Git Flow (Scenario 1 Override or Scenario 2). + +## Scenario 1 Prompt (Same path) + +The template already points to our playbook path. The project may need the latest content. + +``` +Found template [name] (ID: X) with matching playbook path. The project may need to be updated with the latest playbook. + +Options: +(A) Override: I'll add/update the playbook in the project via git. You sync the AAP project, then confirm. +(B) Manual: You add the playbook and sync. Confirm when done. + +โ“ Choose (A) or (B): +``` + +- **If A**: Execute Git Flow (see Git Flow section below). Wait for user: "Sync complete" or "done". +- **If B**: Wait for user confirmation. + +## Scenario 2 Prompt (Different path) + +**CRITICAL**: The template points to a DIFFERENT playbook than our generated playbook. You MUST NOT launch the job without Git Flow. AAP executes from synced project contentโ€”there is no "override at launch". The playbook MUST be in the repo before any job launch. + +``` +Found template [name] (ID: X) pointing to [template.playbook]. Our generated playbook is [our_playbook_path]. + +โš ๏ธ The template's playbook path does NOT match. We must update the playbook in the project before execution. + +Options: +- "yes" or "proceed" - I'll add our playbook to the project via git (you'll confirm commit/push, then sync AAP) +- "no" - Create a new template via `/job-template-creator` skill + +โ“ Proceed with playbook update (git flow)? +``` + +- **If yes**: Execute Git Flow. **Do NOT proceed to Phase 3 until Git Flow completes.** +- **If no**: Fall through to Scenario 3 (job-template-creator). + +## Repo Path Question + +``` +What is the local path to the Git repository for project [Project Name] (scm_url)? +``` + +Use `projects_list` to get project name and `scm_url`; display to help user identify the repo. + +**Path format**: Ask for the **absolute path** (e.g. `/Users/dmartino/projects/AI/ai5/ai5-demo/test-aap-project`). When writing the playbook, the Write tool path MUST be `/playbooks/remediation/` โ€” the full absolute path. Do NOT use a relative path like `test-aap-project/playbooks/...`; that causes "Error writing file". + +## Git Flow: Write Step (FAST) + +**CRITICAL**: The playbook is ALREADY generated. During Git Flow you must WRITE the existing content to diskโ€”nothing more. + +- **DO**: Single file write of the playbook content already in context (from playbook-generator or remediation) +- **DO NOT**: Invoke playbook-generator again, call create_vulnerability_playbook, re-fetch from MCP, or validate/transform the content +- **Expected duration**: Seconds. If it takes minutes, you are doing unnecessary work. + +### Write Path (ABSOLUTE REQUIRED) + +**โš ๏ธ WRITE PATH MUST START WITH `/`** โ€” The Write tool path MUST be an absolute path. Relative paths cause "Error writing file" because the repo is often outside the workspace. + +**Formula**: `write_path = user_provided_path + "/" + target_path` + +- `user_provided_path` = exactly what the user typed (e.g. `/Users/dmartino/projects/AI/ai5/ai5-demo/test-aap-project`) +- `target_path` = e.g. `playbooks/remediation/cve-remediation.yml` + +**Correct**: `/Users/dmartino/projects/AI/ai5/ai5-demo/test-aap-project/playbooks/remediation/cve-remediation.yml` + +**WRONG** (will fail): +- `test-aap-project/playbooks/remediation/cve-remediation.yml` +- `playbooks/remediation/cve-remediation.yml` + +**Before calling Write**: Verify the path starts with `/`. If it does not, prepend the user's repo path. + +## Git Flow HITL Checkpoint + +**REQUIRED** before commit/push: + +``` +Ready to commit and push these changes? +- File: [target_path] +- CVE: [cve_id] +- This will update the playbook in the AAP project. + +Reply 'yes' or 'proceed' to continue, or 'abort' to cancel. +``` + +**Wait for user confirmation.** If "yes" or "proceed": `git commit -m "Add/update remediation playbook for CVE-YYYY-NNNNN"` then `git push origin main`. + +## After Push Message + +``` +I've pushed the playbook. Sync the AAP project: Automation Execution > Projects > [Project] > Sync. Reply 'sync complete' when done. +``` + +**Do NOT proceed to Phase 3 (Dry-Run) until user confirms sync complete.** diff --git a/rh-sre/skills/playbook-generator/SKILL.md b/rh-sre/skills/playbook-generator/SKILL.md index ecd8e173..a9234cdd 100644 --- a/rh-sre/skills/playbook-generator/SKILL.md +++ b/rh-sre/skills/playbook-generator/SKILL.md @@ -5,7 +5,7 @@ description: | Generate production-ready Ansible remediation playbooks for CVE vulnerabilities with Red Hat best practices, error handling, and Kubernetes safety patterns. Use this skill when you need to create remediation playbooks that follow Red Hat Lightspeed patterns and incorporate RHEL-specific considerations. - This skill orchestrates MCP tools (create_vulnerability_playbook) while consulting documentation (cve-remediation-templates.md, package-management.md) to enhance playbooks with Red Hat best practices and RHEL-specific patterns. + This skill calls the MCP tool (remediations__create_vuln_playbook) and returns the playbook **AS IS**. Do NOT modify, enhance, or add to the generated playbook. Any change requires explicit user validation first. **IMPORTANT**: - ALWAYS use this skill instead of calling create_vulnerability_playbook directly @@ -17,7 +17,7 @@ description: | This skill generates Ansible remediation playbooks for CVE vulnerabilities, applying Red Hat best practices, RHEL-specific patterns, and Kubernetes safety considerations. -**Integration with Remediator Agent**: The sre-agents:remediator agent (invoked) orchestrates this skill as part of its Step 4 (Generate Playbook) workflow. For standalone playbook generation, you can invoke this skill directly. +**Integration with Remediation Skill**: The `/remediation` skill orchestrates this skill as part of its Step 4 (Generate Playbook) workflow. For standalone playbook generation, you can invoke this skill directly. ## When to Use This Skill @@ -26,219 +26,113 @@ This skill generates Ansible remediation playbooks for CVE vulnerabilities, appl **Use this skill directly when you need**: - Generate a remediation playbook for a specific CVE - Create batch remediation playbooks for multiple CVEs -- Apply Red Hat best practices to playbook generation +- Get a remediation playbook from Red Hat Lightspeed (returned unmodified) - Standalone playbook generation without full remediation workflow **Do NOT use this skill when you need**: +- "Create playbook and execute it" โ†’ Use `/remediation` skill (orchestrates this skill + playbook-executor) +- "Remediate CVE-X" (full workflow) โ†’ Use `/remediation` skill - Execute playbooks โ†’ Use `/playbook-executor` skill instead - Run ansible-playbook CLI โ†’ Use `/playbook-executor` skill via AAP MCP - Monitor job execution โ†’ Use `/playbook-executor` skill instead -**Use the sre-agents:remediator agent when you need**: +**Use the `/remediation` skill when you need**: - End-to-end CVE remediation (analysis โ†’ validation โ†’ playbook โ†’ execution โ†’ verification) - Integrated impact analysis before playbook generation - System context gathering and remediation strategy determination - Execution guidance and verification workflows **How they work together**: -1. The sre-agents:remediator agent (invoked) orchestrates this skill after gathering system context +1. The `/remediation` skill orchestrates this skill after gathering system context 2. This skill generates the optimized playbook -3. The agent then invokes `/playbook-executor` skill for execution via AAP MCP -4. Finally, `/remediation-verifier` skill confirms success +3. The remediation skill then invokes `/playbook-executor` for execution via AAP MCP +4. Finally, `/remediation-verifier` confirms success ## Workflow -### 1. Documentation Consultation +**๐Ÿšจ Tool Failure Rule**: If `create_vulnerability_playbook` (or `create_vuln_playbook`) fails, STOP. Present options (retry / generate from knowledge with user confirmation / exit). Never auto-generate from your knowledge. -**CRITICAL**: Document consultation MUST happen BEFORE playbook generation. +### 1. Playbook Generation (MCP Tool) -**Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [cve-remediation-templates.md](../../docs/ansible/cve-remediation-templates.md) using the Read tool to understand playbook patterns for this CVE type: - - Template 1: Package Update (user-space packages) - - Template 2: Service Restart (configuration changes) - - Template 3: Configuration File Update (system configs) - - Template 4: Kernel Update with Reboot (kernel CVEs) - - Template 5: SELinux Context Update (SELinux issues) - - Template 6: Batch Remediation (multiple CVEs) - -2. **Action**: Read [package-management.md](../../docs/rhel/package-management.md) using the Read tool for RHEL-specific update considerations: - - DNF vs YUM (RHEL 7 vs 8/9) - - Reboot detection patterns (`needs-restarting`) - - Service restart after package updates - - Repository and subscription management - -3. **Output to user**: "I consulted [cve-remediation-templates.md](../../docs/ansible/cve-remediation-templates.md) and [package-management.md](../../docs/rhel/package-management.md) to understand playbook patterns and RHEL-specific best practices." +**MCP Tool**: `create_vulnerability_playbook` or `remediations__create_vulnerability_playbook` (from lightspeed-mcp) +**Parameters** (tool may use `cve_ids`/`cves` and `system_ids`/`uuids`โ€”check tool schema): +- `cves` or `cve_ids`: Array of CVE identifiers + - Example: `["CVE-2024-1234"]` + - Format: CVE-YYYY-NNNNN strings +- `uuids` or `system_ids`: Array of system UUIDs from Red Hat Lightspeed inventory + - Example: `["uuid-1", "uuid-2"]` + - Format: UUID strings (get from system-context skill) +- `playbook_name`: Name for the playbook (if required by tool) -### 2. CVE Type Detection +**Expected Output**: Ansible playbook YAML from Red Hat Lightspeed. -Analyze CVE metadata to determine the appropriate playbook template: +**CRITICAL โ€” Return AS IS**: You MUST return the playbook exactly as the MCP tool provides it. Do NOT add pre-flight checks, backups, service restarts, audit logging, or any other modifications. The MCP tool description states: "Don't process the playbook. You MUST return the YAML as is." Any enhancement requires explicit user approvalโ€”offer modifications only after user requests them. -``` -CVE Type Detection Logic: -- Kernel CVE: Check if affected packages include "kernel", "vmlinuz", "grub" - โ†’ Use Template 4 (Kernel Update with Reboot) +#### When MCP Tool Fails (REQUIRED Error Handling) -- Service Configuration: Check if CVE affects config files (sshd_config, httpd.conf) - โ†’ Use Template 2 (Service Restart) or Template 3 (Config Update) +**๐Ÿšจ CRITICAL**: When `create_vulnerability_playbook` (or `remediations__create_vulnerability_playbook`) returns an error, you MUST NOT generate a playbook from your own knowledge. Stop and present options to the user. -- SELinux Issue: Check if CVE description mentions SELinux, restorecon, semanage - โ†’ Use Template 5 (SELinux Context Update) +**If the tool returns error** (e.g., "Unhandled error", timeout, 500, connection failure): -- Multiple CVEs: If remediating 3+ CVEs simultaneously - โ†’ Use Template 6 (Batch Remediation) +1. **Report the failure** to the user with the error message +2. **Present these options** and wait for explicit user choice: -- Default: User-space package update - โ†’ Use Template 1 (Package Update) ``` +โŒ Red Hat Lightspeed playbook generation failed: [error message] -### 3. System Context Analysis +**Next steps** (choose one): -Analyze target systems to determine remediation patterns: +(A) **Retry** - Try the MCP tool again (may succeed if transient) +(B) **Generate from knowledge** - Create a playbook using documentation templates (โš ๏ธ NOT from Red Hat Lightspeed; requires your explicit approval) +(C) **Exit** - Stop playbook generation; user can retry later or use manual remediation +โ“ Reply with A, B, or C: ``` -System Context Checks: -- RHEL Version: Detect RHEL 7 (use yum) vs RHEL 8/9 (use dnf) -- Kubernetes Deployment: Check if systems are K8s nodes โ†’ add pod eviction -- Environment: Production vs staging โ†’ adjust rollback/testing requirements -- Number of Systems: Single vs batch โ†’ optimize for parallelism -- Reboot Required: Kernel updates โ†’ add reboot orchestration -``` - -### 4. Playbook Generation - -**CRITICAL**: Document consultation MUST happen BEFORE tool invocation (see Step 1). - -**MCP Tool**: `create_vulnerability_playbook` or `remediations__create_vulnerability_playbook` (from lightspeed-mcp) - -**Parameters**: -- `cve_ids`: Array of CVE identifiers - - Example: `["CVE-2024-1234"]` - - Format: CVE-YYYY-NNNNN strings -- `system_ids`: Array of system UUIDs from Red Hat Lightspeed inventory - - Example: `["uuid-1", "uuid-2"]` - - Format: UUID strings (get from system-context skill) -- `auto_reboot`: Boolean controlling automatic reboot behavior - - Example: `false` (we handle reboots explicitly in playbook) - - Recommended: `false` to maintain control over reboot timing - -**Expected Output**: Base Ansible playbook YAML that will be enhanced with patterns from documentation - -### 5. Playbook Enhancement -Apply Red Hat best practices from documentation to the generated playbook: +3. **Execute based on user choice**: + - **A (Retry)**: Call the MCP tool again. If it fails again, present options again (limit retries to 2; after 2 failures, present B and C only) + - **B (Generate from knowledge)**: ONLY proceed if user explicitly chose B. Use documentation (cve-remediation-templates.md, package-management.md) to build a playbook. Add disclaimer: "Generated from documentation templatesโ€”Red Hat Lightspeed API was unavailable. Review carefully before execution." + - **C (Exit)**: Stop. Do not generate any playbook. Suggest: "You can retry later when Lightspeed MCP is available, or create a manual remediation playbook." -**A. Pre-flight Checks** (from `package-management.md`): -```yaml -pre_tasks: - - name: Verify system is RHEL - assert: - that: - - ansible_distribution == "RedHat" - - ansible_distribution_major_version in ["7", "8", "9"] - fail_msg: "This playbook is for RHEL systems only" - - - name: Check system is registered to Red Hat - command: subscription-manager status - register: subscription_status - failed_when: "'Overall Status: Current' not in subscription_status.stdout" - changed_when: false -``` - -**B. Backup and Snapshot** (from `cve-remediation-templates.md`): -```yaml - - name: Create backup point (RHEL 8/9) - command: > - snapshot create pre-{{ cve_id }}-{{ ansible_date_time.epoch }} - when: ansible_distribution_major_version in ["8", "9"] - ignore_errors: true -``` +**NEVER** auto-generate a playbook from your knowledge when the tool fails without explicit user confirmation for option B. -**C. Package Update** (from `package-management.md`): -```yaml -tasks: - - name: Update vulnerable packages (RHEL 8/9) - dnf: - name: "{{ vulnerable_packages }}" - state: latest - update_cache: true - when: ansible_distribution_major_version in ["8", "9"] - register: package_update - - - name: Update vulnerable packages (RHEL 7) - yum: - name: "{{ vulnerable_packages }}" - state: latest - update_cache: true - when: ansible_distribution_major_version == "7" - register: package_update -``` +### 5. Return Playbook AS IS (No Modifications) -**E. Reboot Detection** (from `package-management.md`): -```yaml - - name: Check if reboot required (RHEL 8/9) - command: needs-restarting -r - register: reboot_required - failed_when: false - changed_when: reboot_required.rc == 1 - when: ansible_distribution_major_version in ["8", "9"] - - - name: Check if reboot required (RHEL 7) - stat: - path: /var/run/reboot-required - register: reboot_required_file - when: ansible_distribution_major_version == "7" -``` +**CRITICAL**: Return the playbook exactly as the MCP tool provides it. Do NOT add, remove, or modify any content. -**F. Service Restart** (if no reboot needed): -```yaml - - name: Restart affected services - systemd: - name: "{{ item }}" - state: restarted - loop: "{{ affected_services | default([]) }}" - when: - - not (reboot_required.changed | default(false)) - - affected_services is defined -``` +**Do NOT**: +- Add pre-flight checks (RHEL validation, subscription check) +- Add backup/snapshot creation +- Add service restart logic +- Add audit logging +- Add Kubernetes pod eviction +- Replace or wrap the MCP output with documentation templates -**G. Audit Logging** (from `cve-remediation-templates.md`): -```yaml - - name: Log remediation success - lineinfile: - path: /var/log/cve-remediation.log - line: "{{ ansible_date_time.iso8601 }} - {{ cve_id }} remediated - {{ package_update.results | length }} packages updated" - create: true - - - name: Notify if reboot required - debug: - msg: "REBOOT REQUIRED - Schedule maintenance window for {{ inventory_hostname }}" - when: reboot_required.changed | default(false) -``` +**If the user requests enhancements** (e.g. "add pre-flight checks", "add backup step"): +1. Show the original playbook first +2. Ask: "The playbook above is from Red Hat Lightspeed. You requested [enhancement]. Should I create a modified version with these additions? (yes/no)" +3. Only if user confirms "yes", create a modified version and show the diff +4. Require explicit approval before any modified playbook is used -### 6. Playbook Validation +### 6. Playbook Validation (Minimal) -Validate the generated playbook: +Before returning, verify only: +- YAML is returned (the MCP tool output) +- No modifications were applied -``` -Validation Checks: -โœ“ YAML syntax is valid (use ansible-playbook --syntax-check) -โœ“ All variable references are defined -โœ“ Pre-flight checks included (OS validation, subscription check) -โœ“ Backup/snapshot step present -โœ“ Package manager matches RHEL version (dnf for 8/9, yum for 7) -โœ“ Reboot detection logic present -โœ“ Service restart conditional on reboot status -โœ“ If K8s: Pod eviction before remediation -โœ“ If K8s: Node uncordon after remediation -โœ“ Audit logging included -โœ“ Error handling present (failed_when, ignore_errors where appropriate) -``` +Do NOT validate for "best practices" or add missing elementsโ€”return AS IS. ## Critical: Human-in-the-Loop Requirements This skill generates code that will execute on production systems. **Explicit user confirmation is REQUIRED** before returning the playbook. +**When MCP Tool Fails** (REQUIRED): +- Do NOT generate a playbook from your own knowledge without explicit user confirmation +- Present options: (A) Retry, (B) Generate from knowledge (requires user approval), (C) Exit +- Wait for user to choose A, B, or C before proceeding +- If user chooses B: Add disclaimer that playbook was generated from documentation, not Red Hat Lightspeed + **Before Playbook Return** (REQUIRED): 1. **Display Playbook Preview**: Show complete playbook YAML to user 2. **Display Metadata**: Show CVE IDs, target systems, reboot requirements, Kubernetes considerations @@ -340,14 +234,7 @@ When completing playbook generation, provide output in this format: **Kubernetes Safe**: Yes/No ## Playbook Features -โœ“ Pre-flight checks (OS validation, subscription check) -โœ“ Backup/snapshot creation -โœ“ RHEL version-specific package management (dnf/yum) -โœ“ Reboot detection and handling -โœ“ Service restart logic -โœ“ Kubernetes pod eviction (if applicable) -โœ“ Error handling and rollback -โœ“ Audit logging +โœ“ Generated by Red Hat Lightspeed (returned AS IS, no modifications) ## Playbook File: remediation-CVE-YYYY-NNNNN.yml @@ -382,63 +269,29 @@ Options: 3. **remediation-verifier skill** โ†’ Verifies success after execution **Safety Notes**: -- Playbook includes rollback capability via snapshots (RHEL 8/9) -- Kubernetes pod eviction ensures zero-downtime updates -- Service restarts are conditional on reboot status -- All actions logged to /var/log/cve-remediation.log +- Playbook is from Red Hat Lightspeedโ€”review before execution +- No modifications were applied; user may request enhancements separately ``` ## Examples -### Example 1: Simple Package CVE - -**User Request**: "Generate playbook for CVE-2024-1234 affecting httpd package on 5 RHEL 8 systems" - -**Skill Response**: -1. Consult `docs/ansible/cve-remediation-templates.md` (Template 1: Package Update) -2. Check `docs/rhel/package-management.md` (DNF workflows for RHEL 8) -3. Call `create_vulnerability_playbook` with CVE and system IDs -4. Enhance playbook with: - - Pre-flight checks (OS validation) - - Backup creation - - DNF package update - - Service restart (httpd) - - Audit logging -5. Return production-ready playbook - -### Example 2: Kernel CVE +### Example 1: Simple CVE -**User Request**: "Generate playbook for kernel CVE on 10 RHEL nodes" +**User Request**: "Generate playbook for CVE-2024-1234 on 5 RHEL 8 systems" **Skill Response**: -1. Detect kernel CVE โ†’ Use Template 4 (Kernel Update with Reboot) -2. Consult `docs/rhel/package-management.md` for kernel update patterns -3. Call `create_vulnerability_playbook` -4. Enhance playbook with: - - Pre-flight checks - - Kernel package update - - Reboot detection - - Reboot execution (if needed) - - Audit logging -5. Return production-ready kernel update playbook +1. Call `remediations__create_vuln_playbook` with cves, uuids, playbook_name +2. Return the playbook **exactly as received**โ€”no modifications +3. Ask for user confirmation before handoff to playbook-executor -### Example 3: Batch Remediation +### Example 2: Batch CVEs -**User Request**: "Generate playbook for CVE-2024-1234, CVE-2024-5678, CVE-2024-9012 on 20 web servers" +**User Request**: "Generate playbook for CVE-2024-1234, CVE-2024-5678 on 20 systems" **Skill Response**: -1. Detect multiple CVEs โ†’ Use Template 6 (Batch Remediation) -2. Consult `docs/ansible/cve-remediation-templates.md` for batch patterns -3. Check `docs/rhel/package-management.md` for batch update considerations -4. Call `create_vulnerability_playbook` with multiple CVE IDs -5. Enhance playbook with: - - Pre-flight checks - - Batch package update (all affected packages) - - Consolidated reboot detection - - Service restart logic - - Progress tracking - - Audit logging with batch details -6. Return optimized batch playbook +1. Call `remediations__create_vuln_playbook` with multiple CVE IDs and system UUIDs +2. Return the playbook **exactly as received**โ€”no modifications +3. Ask for user confirmation before handoff to playbook-executor ## Error Handling @@ -481,9 +334,9 @@ Proceeding with standard playbook (without pod eviction). Add pod eviction manua - `lightspeed-mcp` - Red Hat Lightspeed platform access ### Required MCP Tools -- `create_vulnerability_playbook` or `remediations__create_vulnerability_playbook` (from lightspeed-mcp) - Generate base remediation playbook from Red Hat Lightspeed - - Parameters: cve_ids (array of strings), system_ids (array of UUID strings), auto_reboot (boolean) - - Returns: Base Ansible playbook YAML for remediation +- `remediations__create_vuln_playbook` (from lightspeed-mcp) - Generate remediation playbook from Red Hat Lightspeed + - Parameters: playbook_name, cves (array), uuids (array of system UUIDs) + - Returns: Ansible playbook YAMLโ€”**return AS IS**, do not modify ### Related Skills - `cve-impact` - Provides CVE severity and risk assessment to inform playbook complexity @@ -498,27 +351,17 @@ Proceeding with standard playbook (without pod eviction). Add pod eviction manua ## Best Practices 1. **๐Ÿšจ NEVER EXECUTE PLAYBOOKS** - This skill generates only. Always delegate execution to `/playbook-executor` skill -2. **Always consult documentation first** - Read [cve-remediation-templates.md] and [package-management.md] BEFORE calling MCP tools -3. **Detect CVE type** - Use appropriate template for kernel vs package vs service CVEs -4. **Check Kubernetes context** - Add pod eviction for K8s-deployed systems -5. **RHEL version awareness** - Use dnf for RHEL 8/9, yum for RHEL 7 -6. **Include pre-flight checks** - Validate OS, subscription status before proceeding -7. **Add rollback capability** - Use snapshots, backups for safety -8. **Audit everything** - Log all actions to /var/log/cve-remediation.log -9. **Require user approval** - ALWAYS get explicit confirmation before providing playbooks -10. **Test first** - Always recommend testing in staging before production -11. **Clear handoff** - After generation, explicitly tell user to invoke `/playbook-executor` for execution +2. **๐Ÿšจ RETURN AS IS** - Do NOT modify the MCP-generated playbook. No enhancements without explicit user request and approval +3. **๐Ÿšจ NEVER auto-generate on tool failure** - When the MCP tool fails, present options (retry / generate from knowledge with user confirmation / exit). Do NOT silently generate from your own knowledge +4. **Require user approval** - ALWAYS get explicit confirmation before providing playbooks for execution +5. **Clear handoff** - After generation, explicitly tell user to invoke `/playbook-executor` for execution ## Tools Reference -This skill primarily uses: -- `create_vulnerability_playbook` (remediations toolset) - Generate base playbook from Red Hat Lightspeed -- Read tool - Access documentation for best practices - - `docs/ansible/cve-remediation-templates.md` - Playbook templates - - `docs/rhel/package-management.md` - RHEL-specific patterns +This skill uses: +- `remediations__create_vuln_playbook` (from lightspeed-mcp) - Generate playbook from Red Hat Lightspeed. Returns YAML **as is**โ€”do not modify. All MCP tools are provided by the lightspeed-mcp server configured in `.mcp.json`. -All documentation is available in the `docs/` directory. ## Integration with Other Skills @@ -526,7 +369,7 @@ All documentation is available in the `docs/` directory. - **system-context**: Provides system inventory and deployment context for playbook targeting - **remediation-verifier**: Verifies playbook execution success after deployment -**Orchestration Example** (from sre-agents:remediator agent - invoked): +**Orchestration Example** (from `/remediation` skill): 1. Agent invokes cve-impact skill โ†’ Gets risk assessment 2. Agent gathers context โ†’ Determines deployment requirements 3. Agent invokes playbook-generator skill โ†’ Generates production-ready playbook diff --git a/rh-sre/skills/remediation-verifier/SKILL.md b/rh-sre/skills/remediation-verifier/SKILL.md index 29f770c2..e393f5ba 100644 --- a/rh-sre/skills/remediation-verifier/SKILL.md +++ b/rh-sre/skills/remediation-verifier/SKILL.md @@ -14,7 +14,7 @@ description: | This skill verifies CVE remediation success by validating that vulnerabilities have been properly fixed on target systems. -**Integration with Remediator Agent**: The sre-agents:remediator agent (invoked) orchestrates this skill as part of its Step 6 (Verify Deployment) workflow. For standalone verification after manual remediation, you can invoke this skill directly. +**Integration with Remediation Skill**: The `/remediation` skill orchestrates this skill as part of its Step 6 (Verify Deployment) workflow. For standalone verification after manual remediation, you can invoke this skill directly. ## When to Use This Skill @@ -25,11 +25,11 @@ This skill verifies CVE remediation success by validating that vulnerabilities h - Validate Kubernetes pod recovery after node updates - Generate verification reports for compliance -**Use the sre-agents:remediator agent when you need**: +**Use the `/remediation` skill when you need**: - Full remediation workflow including verification - Integrated remediation โ†’ execution โ†’ verification -**How they work together**: The sre-agents:remediator agent (invoked) invokes this skill after the user executes the remediation playbook, providing final confirmation that the CVE is resolved. +**How they work together**: The `/remediation` skill invokes this skill after the user executes the remediation playbook, providing final confirmation that the CVE is resolved. ## Workflow @@ -381,7 +381,7 @@ When completing verification, provide output in this format: - **system-context**: Provides system context for verification scope - **cve-impact**: Initial impact assessment to compare against verification results -**Orchestration Example** (from sre-agents:remediator agent - invoked): +**Orchestration Example** (from `/remediation` skill): 1. User requests CVE remediation 2. Agent invokes playbook-generator โ†’ Creates playbook 3. User executes playbook manually diff --git a/rh-sre/skills/remediation/SKILL.md b/rh-sre/skills/remediation/SKILL.md new file mode 100644 index 00000000..2be93af3 --- /dev/null +++ b/rh-sre/skills/remediation/SKILL.md @@ -0,0 +1,277 @@ +--- +name: remediation +description: | + **CRITICAL**: Use this skill for ALL CVE remediation workflows. DO NOT use individual skills piecemeal for end-to-end remediation. + + Use when users request: + - CVE remediation playbooks or security patch deployment + - Multi-step remediation (validation โ†’ context โ†’ playbook โ†’ execution) + - Batch remediation across multiple systems or CVEs + - End-to-end CVE management (analysis + remediation + verification) + - Prioritizing and remediating CVEs (not just listing them) + - Emergency security response with immediate remediation plans + + DO NOT use for simple queries: + - "List critical CVEs" โ†’ Use `/cve-impact` skill + - "What's the CVSS score for CVE-X?" โ†’ Use `/cve-impact` or `/cve-validation` + - Standalone impact analysis without remediation โ†’ Use `/cve-impact` + + This skill orchestrates 6 specialized skills (cve-impact, cve-validation, system-context, playbook-generator, playbook-executor, remediation-verifier) for complete remediation workflows. +--- +model: inherit +color: red +metadata: + author: "Red Hat Ecosystem Engineering" + priority: "high" +--- + +# Remediation Skill + +End-to-end CVE remediation workflow. Orchestrates specialized skills for validation, context gathering, playbook generation, execution, and verification. + +## Prerequisites + +**Required MCP Servers**: `lightspeed-mcp` (CVE data, playbook generation), `aap-mcp-job-management`, `aap-mcp-inventory-management` (execution) + +**Related Skills** (this skill invokes them): +- `/mcp-lightspeed-validator` - Verify Lightspeed MCP before CVE operations +- `/mcp-aap-validator` - Verify AAP MCP before playbook execution +- `/cve-impact` - CVE risk assessment +- `/cve-validation` - CVE validation and remediation availability +- `/system-context` - System inventory and deployment context +- `/playbook-generator` - Ansible playbook generation +- `/playbook-executor` - Playbook execution via AAP +- `/remediation-verifier` - Post-remediation verification + +**Verification**: See Step 0 for MCP validation. Execute `/mcp-aap-validator` before Step 5 (playbook execution) if not already validated. + +## When to Use This Skill + +**Use this skill when**: +- User requests CVE remediation (playbook creation, patching, deployment) +- Full workflow needed: analysis โ†’ validation โ†’ playbook โ†’ execution โ†’ verification +- Batch remediation across multiple CVEs or systems + +**Do NOT use when**: +- User only wants CVE listing or impact analysis โ†’ Use `/cve-impact` +- User only wants CVE validation โ†’ Use `/cve-validation` +- User only wants playbook generation (no execution) โ†’ Use `/playbook-generator` directly + +## Workflow + +Execute skills in this order. **MANDATORY**: Use actual Skill tool invocations, NOT text pretending to invoke skills. **Each step must complete before the next begins**โ€”do not start Step N+1 until Step N has returned its result. + +### Upfront: Planned Tasks (Before Step 0) + +**When**: Before executing any step. **Do NOT start Step 0 until the user validates the plan.** + +**Action**: Present the planned task list using **Part A** of [references/01-remediation-plan-template.md](references/01-remediation-plan-template.md). Show the 7 tasks (validate MCP โ†’ impact โ†’ validate CVE โ†’ context โ†’ playbook โ†’ execute โ†’ verify) and ask "Proceed with this plan?" + +**Wait for explicit user response** ("yes" or "proceed") before invoking Step 0. If "abort" โ†’ stop. + +### Step 0: Validate MCP Prerequisites + +**Action**: Execute `/mcp-lightspeed-validator` (and `/mcp-aap-validator` before Step 5 if executing playbooks) + +**When**: Before any CVE or remediation operations. Can skip if already validated this session. + +**Sequencing (MANDATORY)**: Invoke validators **one at a time**. **Do NOT proceed to Step 1 until Step 0 is complete.** Wait for each validator to return explicit results (PASSED / FAILED / PARTIAL) before moving on. "Successfully loaded skill" alone does NOT mean validation completedโ€”you must see the actual validation outcome. + +**Invocation**: Use the Skill tool for ALL sub-skill invocations (validators, cve-validation, cve-impact, system-context, playbook-generator, playbook-executor, remediation-verifier). **Do NOT use "Task Output" with the skill name as task ID**โ€”that causes "No task found" errors (e.g. "No task found with ID: cve-validation"). See [skill-invocation.md](../../docs/references/skill-invocation.md). + +**Handle result**: If validation fails, stop and provide setup instructions. If passed, proceed to Step 1. **If any skill invocation fails** (e.g. "No task found with ID: ..."): Proceed with a warningโ€”do not block. Later steps will surface real errors if MCP is unavailable. + +### Step 1: Impact Analysis (If Requested or Needed) + +**Action**: Execute the `/cve-impact` skill + +**Invoke**: +``` +"Analyze CVE-XXXX-YYYY and assess its impact on affected systems" +``` + +**Expected**: Risk assessment, affected systems list, CVSS interpretation. Integrate into remediation planning. If user only wanted impact analysis, provide assessment and offer remediation options. + +### Step 2: Validate CVE (Remediatable Gate) + +**Action**: Execute the `/cve-validation` skill + +**Invoke**: +``` +"Validate CVE-XXXX-YYYY format, existence, and remediation availability" +``` + +**Expected**: Validation status including `remediation_status.automated_remediation_available` or `validation_status`. + +**Remediatable Gate** (MANDATORY): Trust cve-validation skill output. Do NOT re-interpret raw get_cve responseโ€”cve-validation uses advisory_available, remediation, advisories_list (not rules[]). See [cve-validation references/01-remediation-indicators.md](../cve-validation/references/01-remediation-indicators.md). +- **If remediatable** (`remediation_available: true` or `validation_status: "valid"`): Proceed to Step 3. +- **If NOT remediatable** (`remediation_available: false` or `validation_status: "not_remediable"`): + 1. Explain: "CVE-XXXX-YYYY has no automated remediation in Red Hat Lightspeed. Execution may have no effect." + 2. Suggest alternatives: manual patching, check Red Hat errata. + 3. Offer: "Continue anyway? (yes/no)" + 4. **If user says "yes"**: Proceed to Step 3 with warning: "โš ๏ธ Proceeding despite no automated remediationโ€”playbook generation or execution may have no effect." + 5. **If user says "no"**: Stop. Do not proceed to Steps 3โ€“5. + +**Batch**: For multiple CVEs, validate each. Proceed only with remediatable CVEs unless user explicitly confirms to include non-remediatable ones (with same warning). + +### Step 3: Gather Context + +**Action**: Execute the `/system-context` skill + +**Invoke**: +``` +"Gather system context for CVE-XXXX-YYYY: identify affected systems, RHEL versions, and deployment environments" +``` + +**Expected**: Context summary with remediation strategy. Use to inform playbook generation and execution planning. + +### Step 4: Generate Playbook + +**Action**: Execute the `/playbook-generator` skill + +**CRITICAL**: You MUST invoke `/playbook-generator`, NOT generate playbook text yourself. + +**Invoke**: +``` +"Generate an Ansible remediation playbook for CVE-XXXX-YYYY targeting systems [list of system UUIDs]. Apply Red Hat best practices and RHEL-specific patterns from documentation." +``` + +**Expected**: Ansible playbook from Red Hat Lightspeed (returned AS IS by playbook-generatorโ€”no modifications). Present to user. **The playbook-generator ONLY GENERATES**โ€”it does NOT execute. After presenting the playbook, present the Remediation Plan for user validation (see below). + +### Remediation Plan (User Validation) โ€” MANDATORY before Step 5 + +**When**: After Step 4 completes. **Do NOT proceed to Step 5 until the user validates the plan.** + +**Action**: Present the plan using the Summary + Table + Checklist format. **Read [references/01-remediation-plan-template.md](references/01-remediation-plan-template.md)** for the exact template. + +**Format**: +1. **Summary** โ€” 1โ€“2 sentences: what will happen and why +2. **Table** โ€” CVE | Target Systems | Key Action +3. **Checklist** โ€” Ordered steps (mark completed as "โ€” done") +4. **Confirm prompt** โ€” "yes"/"proceed", "dry-run only", or "abort" + +**Wait for explicit user response.** If "yes" or "proceed" โ†’ invoke playbook-executor. If "abort" โ†’ stop. If "dry-run only" โ†’ invoke playbook-executor with instruction to run dry-run only and stop. + +### Step 5: Execute Playbook (With User Confirmation) + +**Prerequisite**: Remediation Plan must be presented and user must have responded "yes" or "proceed" (or "dry-run only"). Do NOT invoke playbook-executor until plan validation is complete. + +**CRITICAL**: Before execution, you MUST: +1. Have presented the Remediation Plan (summary + table + checklist) +2. Have received user confirmation ("yes", "proceed", or "dry-run only") +3. Show playbook preview and key tasks when invoking playbook-executor +4. Recommend dry-run first; wait for explicit approval before actual execution + +**Action**: Execute the `/playbook-executor` skill + +**Invoke** (pass playbook metadata from playbook-generator and system-context): +``` +"Execute the generated playbook for CVE-XXXX-YYYY. Playbook file: [filename from playbook-generator]. Content: [in context from playbook-generator output]. Target systems: [list of system UUIDs from system-context]. Start with dry-run (check mode) if user requested it. Monitor job status until completion and report results." +``` + +**Git Flow path**: When playbook-executor performs Git Flow (write playbook to repo), it MUST use the absolute path for the Write tool: `/playbooks/remediation/`. Never use a relative path like `test-aap-project/playbooks/...`โ€”that causes "Error writing file" when the repo is outside the workspace. + +**Expected**: playbook-executor validates AAP, matches templates, offers dry-run, executes on approval, streams progress, generates report. **Validates job log for CVE handling**โ€”confirms from stdout that the playbook addressed the target CVE(s); reports โœ“ confirmation or โš ๏ธ warning if no evidence found. After success, suggest verification with `/remediation-verifier`. + +### Step 6: Verify Deployment (Optional) + +**Action**: Execute the `/remediation-verifier` skill (if user requests verification) + +**Invoke**: +``` +"Verify remediation success for CVE-XXXX-YYYY on systems [list of system UUIDs]. Check CVE status, package versions, and service health." +``` + +**Expected**: Verification report with pass/fail. Present results to user. + +## Dependencies + +### Required MCP Tools +- None (orchestration skillโ€”delegates to other skills that use MCP tools) + +### Required MCP Servers +- `lightspeed-mcp` - CVE data, playbook generation +- `aap-mcp-job-management` - Job launch and monitoring +- `aap-mcp-inventory-management` - Inventory for execution + +### Related Skills +- `cve-impact` - Step 1 +- `cve-validation` - Step 2 +- `system-context` - Step 3 +- `playbook-generator` - Step 4 +- `playbook-executor` - Step 5 +- `remediation-verifier` - Step 6 + +### Reference Documentation +- [references/01-remediation-plan-template.md](references/01-remediation-plan-template.md) - Plan format for user validation +- [lightspeed-mcp-tool-failures.md](../../docs/references/lightspeed-mcp-tool-failures.md) - Backend errors (e.g. explain_cves), user-friendly message, workarounds +- [cve-remediation-templates.md](../../docs/ansible/cve-remediation-templates.md) +- [package-management.md](../../docs/rhel/package-management.md) + +## Critical: Human-in-the-Loop Requirements + +This skill requires explicit user confirmation at: + +1. **Upfront Planned Tasks** (before Step 0) + - Present the 7-task plan. Wait for "yes" or "proceed" before starting any step. + - Do NOT invoke validators or other skills until the user confirms. + +2. **Remediation Plan Validation** (before Step 5) + - Present the plan: Summary + Table + Checklist + - Wait for user response: "yes"/"proceed", "dry-run only", or "abort" + - Do NOT invoke playbook-executor until the user validates the plan + +3. **Before Playbook Execution (Step 5)** + - Display playbook preview and key tasks + - Recommend dry-run first; wait for explicit approval before actual execution + +4. **Before Destructive Actions** + - Offer dry-run (check mode) before actual execution + - If dry-run approved, run first and show results + - Only proceed to actual execution after user confirms + +**Never assume approval**โ€”always wait for explicit user confirmation before execution. + +## MCP Tool Usage + +**vulnerability__explain_cves**: Requires a valid `system_uuid` from inventory. Do NOT call it unless you have the resolved UUID from Step 3 (system-context) or Step 1 (cve-impact). Never pass `system_uuid: "undefined"` or placeholder valuesโ€”this causes validation errors. For remediation availability at Step 2, use `get_cve` via cve-validation only. + +**Lightspeed tool failures**: If a tool fails with a cryptic backend error (e.g. `'dnf_modules'`), do NOT retry or expose the raw error. Use workarounds from [lightspeed-mcp-tool-failures.md](../../docs/references/lightspeed-mcp-tool-failures.md). + +## Error Handling + +- **Invalid CVE**: "CVE-XXXX-YYYY is not valid or doesn't exist. Please verify the CVE ID." +- **No Remediation Available**: "CVE-XXXX-YYYY doesn't have an automated remediation playbook. Manual patching required." +- **System Not Found**: "System XXXX is not in the Lightspeed inventory. Please ensure it's registered." +- **Batch Partial Failure**: "Successfully processed X of Y CVEs. Failed: [list]. Reason: [explanations]" +- **Lightspeed tool failures** (e.g. explain_cves `'dnf_modules'`): Do NOT show raw error. Use user-friendly message and workaround from [lightspeed-mcp-tool-failures.md](../../docs/references/lightspeed-mcp-tool-failures.md). + +## Output Format + +**Single CVE**: +``` +CVE-XXXX-YYYY Remediation Summary +CVSS Score: X.X (Severity) +Affected Packages: package-name-version +Ansible Playbook Generated: โœ“ +Target Systems: N systems +[Playbook YAML or AAP link] +[Execution instructions] +``` + +**Batch**: +``` +Batch Remediation Summary +CVEs: CVE-A, CVE-B, CVE-C +Target Systems: N systems +Total Fixes: X package updates +[Consolidated playbook] +[Execution instructions] +``` + +## Important Reminders + +- **Use actual tool calls**โ€”invoke skills via Skill tool, not text. If tool use count is 0, you are doing it wrong. +- **Orchestrate skills, don't call MCP tools directly**โ€”skills handle docs and tools. +- **Always ask for execution confirmation** before Step 5. +- **Safety**: Test in non-prod first, back up systems, schedule maintenance windows, verify after execution. diff --git a/rh-sre/skills/remediation/references/01-remediation-plan-template.md b/rh-sre/skills/remediation/references/01-remediation-plan-template.md new file mode 100644 index 00000000..c1080e90 --- /dev/null +++ b/rh-sre/skills/remediation/references/01-remediation-plan-template.md @@ -0,0 +1,85 @@ +# Remediation Plan Template + +Read this reference when presenting plans for user validation. + +## Part A: Upfront Planned Tasks (Before Step 0) + +**When**: Before executing any step. Present immediately after the user requests remediation. + +**Purpose**: Let the user validate the approach before any work begins. + +**Format**: +``` +## Remediation: CVE-XXXX-YYYY + +**Planned tasks** (in order): +1. Validate MCP (Lightspeed, AAP) +2. Impact analysis (assess CVE risk) +3. CVE validation (remediatable gate) +4. System context (affected systems, RHEL versions) +5. Generate playbook +6. Dry-run โ†’ User confirms โ†’ Execute +7. Verify (optional) + +โ“ Proceed with this plan? +- "yes" or "proceed" โ€” I'll start with Step 0 (validate MCP) +- "abort" โ€” Cancel +``` + +**Wait for user response** before invoking Step 0. Do NOT start any step until the user confirms. + +--- + +## Part B: Execution Plan (After Step 4, Before Step 5) + +**When**: After Step 4 (playbook generated) and before Step 5 (execution). The user must validate before proceeding. + +## Part B Format + +### 1. Summary (1โ€“2 sentences) + +``` +## Remediation Plan: CVE-XXXX-YYYY + +**Summary**: [One sentence describing what will happen and why.] +Example: "Remediate CVE-2026-24882 on ip-172-31-32-201 via Ansible playbook (httpd update to address CVE)." +``` + +### 2. Table (CVE, systems, key actions) + +``` +| CVE | Target Systems | Key Action | +|-----|----------------|------------| +| CVE-XXXX-YYYY | hostname-1, hostname-2 | Update package: httpd 2.4.x โ†’ 2.4.y | +``` + +For batch: one row per CVE or combined row if same action. + +### 3. Checklist (ordered steps) + +``` +**Execution steps**: +โ˜ Step 0: Validate MCP (Lightspeed, AAP) โ€” done +โ˜ Step 1: Impact analysis โ€” done +โ˜ Step 2: CVE validation โ€” done +โ˜ Step 3: System context โ€” done +โ˜ Step 4: Generate playbook โ€” done +โ˜ Step 5: Dry-run โ†’ Confirm โ†’ Execute +โ˜ Step 6: Verify (optional) +``` + +Mark completed steps as "โ€” done". Show only remaining steps as checkboxes if preferred. + +### 4. Confirm Prompt + +``` +โ“ Confirm to proceed? + +- "yes" or "proceed" โ€” Run dry-run first, then execute +- "dry-run only" โ€” Run dry-run only, no execution +- "abort" โ€” Cancel remediation + +Please respond with your choice. +``` + +**Wait for explicit user response** before invoking playbook-executor. diff --git a/rh-sre/skills/system-context/SKILL.md b/rh-sre/skills/system-context/SKILL.md index 63388c61..e9181433 100644 --- a/rh-sre/skills/system-context/SKILL.md +++ b/rh-sre/skills/system-context/SKILL.md @@ -14,7 +14,7 @@ description: | This skill gathers comprehensive system inventory and deployment context for CVE-affected systems, enabling informed remediation strategy decisions. -**Integration with Remediator Agent**: The sre-agents:remediator agent (invoked) orchestrates this skill as part of its Step 3 (Gather Context) workflow. For standalone system analysis, you can invoke this skill directly. +**Integration with Remediation Skill**: The `/remediation` skill orchestrates this skill as part of its Step 3 (Gather Context) workflow. For standalone system analysis, you can invoke this skill directly. ## When to Use This Skill @@ -25,12 +25,12 @@ This skill gathers comprehensive system inventory and deployment context for CVE - Classify systems by environment (dev/staging/prod) - Gather context before remediation planning -**Use the sre-agents:remediator agent when you need**: +**Use the `/remediation` skill when you need**: - End-to-end CVE remediation workflow - Integrated analysis โ†’ context โ†’ playbook โ†’ execution - Automated remediation strategy determination -**How they work together**: The sre-agents:remediator agent (invoked) uses this skill's output to determine remediation strategy (batch vs individual, Kubernetes pod eviction requirements, maintenance window needs, etc.). +**How they work together**: The `/remediation` skill uses this skill's output to determine remediation strategy (batch vs individual, Kubernetes pod eviction requirements, maintenance window needs, etc.). ## Workflow @@ -493,7 +493,7 @@ To improve system classification: - **playbook-generator**: Consumes context to generate appropriate remediation playbook - **remediation-verifier**: Uses system context to verify remediation on correct systems -**Orchestration Example** (from sre-agents:remediator agent - invoked): +**Orchestration Example** (from `/remediation` skill): 1. Agent invokes cve-impact โ†’ Gets risk level 2. Agent invokes system-context skill โ†’ Gets deployment architecture 3. Agent determines strategy: "Staging-first deployment recommended" diff --git a/scripts/generate_pack_data.py b/scripts/generate_pack_data.py index 37616fa4..aae0ec9a 100644 --- a/scripts/generate_pack_data.py +++ b/scripts/generate_pack_data.py @@ -13,11 +13,6 @@ # List of agentic packs to parse PACK_DIRS = ['rh-sre', 'rh-developer', 'ocp-admin', 'rh-support-engineer', 'rh-virt'] -# Mapping from directory name to key in docs/plugins.json (if different) -PACK_TO_PLUGINS_KEY = { - 'ocp-admin': 'rh-ocp-admin', # Directory is ocp-admin, but plugins.json key is rh-ocp-admin -} - def parse_yaml_frontmatter(file_path: Path) -> Dict[str, Any]: """ @@ -94,13 +89,10 @@ def parse_plugin_json(pack_dir: str, plugin_titles: Dict[str, str]) -> Dict[str, 'keywords': [] } - # Check if pack_dir has a different key in plugins.json - plugins_key = PACK_TO_PLUGINS_KEY.get(pack_dir, pack_dir) - if not plugin_path.exists(): # Use title from plugins.json if available - if plugins_key in plugin_titles: - defaults['title'] = plugin_titles[plugins_key] + if pack_dir in plugin_titles: + defaults['title'] = plugin_titles[pack_dir] return defaults try: @@ -111,8 +103,8 @@ def parse_plugin_json(pack_dir: str, plugin_titles: Dict[str, str]) -> Dict[str, result = {**defaults, **data} # Override with title from docs/plugins.json if available - if plugins_key in plugin_titles: - result['title'] = plugin_titles[plugins_key] + if pack_dir in plugin_titles: + result['title'] = plugin_titles[pack_dir] elif 'title' not in result: # Fallback: use name as title if not set result['title'] = result['name'] @@ -122,8 +114,8 @@ def parse_plugin_json(pack_dir: str, plugin_titles: Dict[str, str]) -> Dict[str, except Exception as e: print(f"Warning: Failed to parse {plugin_path}: {e}") # Use title from plugins.json if available even on error - if plugins_key in plugin_titles: - defaults['title'] = plugin_titles[plugins_key] + if pack_dir in plugin_titles: + defaults['title'] = plugin_titles[pack_dir] return defaults diff --git a/scripts/validate_skill_design.py b/scripts/validate_skill_design.py index d75140e2..cafb4ff2 100644 --- a/scripts/validate_skill_design.py +++ b/scripts/validate_skill_design.py @@ -36,7 +36,7 @@ "executor", "playbook-executor", "job-template-creator", - "remediator", + "remediation", ] # Required sections (DP6) - Prerequisites is optional From a051bca6b84323b32e1054177ba30b01bbe0d2ea Mon Sep 17 00:00:00 2001 From: Daniele Martinoli Date: Mon, 2 Mar 2026 19:18:33 +0100 Subject: [PATCH 10/20] fix(docs): Clarify known issues with MCP client parameter serialization - Added a note about the `limit` parameter being incorrectly serialized as `limit_` by some MCP clients, causing validation errors. - Updated documentation for `vulnerability__get_cves` and `mcp-lightspeed-validator` to reflect the workaround of omitting the `limit` parameter during connectivity tests. - Enhanced the `lightspeed-mcp-parameters` documentation to include details on handling the `limit` parameter correctly. Signed-off-by: [Your Name] [Your Email] Signed-off-by: Daniele Martinoli --- .../docs/references/lightspeed-mcp-parameters.md | 4 +++- .../references/lightspeed-mcp-tool-failures.md | 14 ++++++++++++++ rh-sre/skills/mcp-lightspeed-validator/SKILL.md | 2 +- 3 files changed, 18 insertions(+), 2 deletions(-) diff --git a/rh-sre/docs/references/lightspeed-mcp-parameters.md b/rh-sre/docs/references/lightspeed-mcp-parameters.md index 5cf15866..b1465f4f 100644 --- a/rh-sre/docs/references/lightspeed-mcp-parameters.md +++ b/rh-sre/docs/references/lightspeed-mcp-parameters.md @@ -50,11 +50,13 @@ Do not mix parameter names between servers. **Purpose**: List CVEs affecting the account with filtering. +**โš ๏ธ Known issue**: Some MCP clients serialize `limit` as `limit_`, causing "Unexpected keyword argument" errors. For connectivity tests, call with no parameters. For CVE queries, if you see this error, omit `limit` (default 10) or use other parameters only. + | Parameter | Type | Example | Notes | |-----------|------|---------|-------| | `impact` | string | `"7,6"` | Comma-separated impact IDs: 7=Critical, 6=High, 5=Important, 4=Moderate | | `sort` | string | `"-cvss_score"` | Use `-` prefix for descending | -| `limit` | integer | `20` | Max records per page | +| `limit` | integer | `20` | Max records per page. **Note**: Some clients bug: pass as `limit`; if error, omit (default 10) | | `advisory_available` | string | `"true"` | Filter remediatable CVEs: `"true"` = only with available advisory, `"true,false"` = all | **For remediatable CVEs** (user asks "which CVEs can I remediate?"): diff --git a/rh-sre/docs/references/lightspeed-mcp-tool-failures.md b/rh-sre/docs/references/lightspeed-mcp-tool-failures.md index 10961ae8..f2c661b4 100644 --- a/rh-sre/docs/references/lightspeed-mcp-tool-failures.md +++ b/rh-sre/docs/references/lightspeed-mcp-tool-failures.md @@ -18,6 +18,20 @@ When Lightspeed MCP tools fail with cryptic backend errors (e.g. KeyError, missi ## Known Failures and Workarounds +### vulnerability__get_cves โ€” `limit_` Unexpected keyword argument + +**Error**: `1 validation error for call[get_cves] limit_ Unexpected keyword argument [type=unexpected_keyword_argument]` + +**Cause**: Some MCP clients incorrectly serialize the `limit` parameter as `limit_`. The Lightspeed MCP server expects `limit` (no underscore). + +**Workaround**: For connectivity tests, call with **no parameters**โ€”the tool uses default `limit=10`: +``` +vulnerability__get_cves() +``` +Or pass only parameters that don't trigger the bug (e.g. `impact`, `sort`, `advisory_available`). Avoid passing `limit` when the client may serialize it as `limit_`. + +**Skills affected**: mcp-lightspeed-validator (connectivity test), cve-impact (account-level CVE queries). + ### vulnerability__explain_cves โ€” `'dnf_modules'` (or similar KeyError) **Error**: `Error calling tool 'explain_cves': 'dnf_modules'` diff --git a/rh-sre/skills/mcp-lightspeed-validator/SKILL.md b/rh-sre/skills/mcp-lightspeed-validator/SKILL.md index fab96813..e1f1528e 100644 --- a/rh-sre/skills/mcp-lightspeed-validator/SKILL.md +++ b/rh-sre/skills/mcp-lightspeed-validator/SKILL.md @@ -16,7 +16,7 @@ Use when validating Lightspeed MCP before CVE operations, troubleshooting connec ## Workflow -1. **Test connectivity**: Call `vulnerability__get_cves` (or `get_cves`) with `limit: 1` to verify the server responds. +1. **Test connectivity**: Call `vulnerability__get_cves` with **no parameters** (uses default limit=10). Do NOT pass `limit`โ€”some MCP clients incorrectly serialize it as `limit_`, causing validation errors. 2. **If it fails**: Provide a comprehensive message with possible root causes (see below). 3. **Report**: Output a table with validated servers and outcome (emojis). From 5b1a520d2a85a564effdbcc9f6a098125f3ab8e7 Mon Sep 17 00:00:00 2001 From: Daniele Martinoli Date: Mon, 2 Mar 2026 19:19:34 +0100 Subject: [PATCH 11/20] TODO file --- rh-sre/TODO.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 rh-sre/TODO.md diff --git a/rh-sre/TODO.md b/rh-sre/TODO.md new file mode 100644 index 00000000..85a2962d --- /dev/null +++ b/rh-sre/TODO.md @@ -0,0 +1,54 @@ +- [X] CVE must be remeditable +- [X] Check Job execution log to validate the CVE +- [X] Job Template must have check type or support check Prompt on Launch for dry-run mode. Stop otherwise +- [ ] Prompt on launch for inventory is preferred + +- [ ] Validate via script to save context +- [ ] Spec Driven Dev +- [ ] MCP: specify GS atstus +- [ ] Cursor install +- [x] AAP execution + +- [x] Skill stops if the MCP server is not available! + +- [x] Skill instructions to add docs: +``` + The remediation skill orchestrated these skills based on their documented workflows and best practices, but since the agent output didn't + explicitly report "I consulted file X.md," I defaulted to "Docs: N/A" in the summary. +``` + +- [x] New skill to make a execution report! + +- [ ] Skill instructions to avoid tool execution errors: +``` +โบ The first call failed with an "Unhandled error" because I only passed the per_page parameter without explicitly providing the filter + parameters like display_name. + + The second call succeeded because I explicitly passed display_name as an empty string along with per_page. Even though all parameters have + defaults according to the tool definition, the MCP tool implementation appears to require filter parameters to be explicitly provided in + the request, even if they're empty values. + + This is likely a quirk of how the underlying API or MCP tool handles parameter serializationโ€”it may not properly handle the case where + optional filter parameters are omitted entirely, but it works fine when they're explicitly set (even as empty strings). + + The fix was straightforward: include the filter parameters explicitly, which is a safer practice anyway for API consistency. +``` + +- [ ] Simplify Skill definition, too long! + +- [x] System prompt: can be set in the Skill definition? + +- [ ] Remediation must propose to review the playbook + +- [ ] Remediation must verify the CVE status at the end + + +- [ ] Simulated executions! +``` + This is a significant problem. The agent produced convincing-looking output that I reported as real results without verifying actual tool + execution occurred. +``` + +- [ ] Skill to run simulations + +- [ ] Skills and sub-skills vs agents and skills From 89d083a9a926f61d97f8f2743f1fd21bb2a63ddf Mon Sep 17 00:00:00 2001 From: Daniele Martinoli Date: Mon, 2 Mar 2026 21:39:42 +0100 Subject: [PATCH 12/20] fix linting issues Signed-off-by: Daniele Martinoli --- rh-sre/TODO.md | 54 -- rh-sre/skills/cve-impact/SKILL.md | 260 +-------- .../references/03-output-templates.md | 39 ++ .../cve-impact/references/04-examples.md | 37 ++ .../references/05-error-handling.md | 24 + rh-sre/skills/cve-validation/SKILL.md | 218 +------- .../references/03-output-template.md | 36 ++ .../cve-validation/references/04-examples.md | 35 ++ .../references/05-error-handling.md | 37 ++ rh-sre/skills/fleet-inventory/SKILL.md | 495 +---------------- .../references/01-parameter-reference.md | 49 ++ .../references/03-output-templates.md | 80 +++ .../fleet-inventory/references/04-examples.md | 32 ++ .../references/05-error-handling.md | 45 ++ rh-sre/skills/job-template-creator/SKILL.md | 507 +----------------- .../references/01-git-setup.md | 25 + .../references/02-web-ui-form.md | 24 + .../references/03-output-template.md | 20 + .../references/04-examples.md | 19 + rh-sre/skills/playbook-executor/SKILL.md | 10 +- rh-sre/skills/remediation/SKILL.md | 2 + .../01-remediation-plan-template.md | 2 +- rh-sre/skills/system-context/SKILL.md | 13 - 23 files changed, 548 insertions(+), 1515 deletions(-) delete mode 100644 rh-sre/TODO.md create mode 100644 rh-sre/skills/cve-impact/references/03-output-templates.md create mode 100644 rh-sre/skills/cve-impact/references/04-examples.md create mode 100644 rh-sre/skills/cve-impact/references/05-error-handling.md create mode 100644 rh-sre/skills/cve-validation/references/03-output-template.md create mode 100644 rh-sre/skills/cve-validation/references/04-examples.md create mode 100644 rh-sre/skills/cve-validation/references/05-error-handling.md create mode 100644 rh-sre/skills/fleet-inventory/references/01-parameter-reference.md create mode 100644 rh-sre/skills/fleet-inventory/references/03-output-templates.md create mode 100644 rh-sre/skills/fleet-inventory/references/04-examples.md create mode 100644 rh-sre/skills/fleet-inventory/references/05-error-handling.md create mode 100644 rh-sre/skills/job-template-creator/references/01-git-setup.md create mode 100644 rh-sre/skills/job-template-creator/references/02-web-ui-form.md create mode 100644 rh-sre/skills/job-template-creator/references/03-output-template.md create mode 100644 rh-sre/skills/job-template-creator/references/04-examples.md diff --git a/rh-sre/TODO.md b/rh-sre/TODO.md deleted file mode 100644 index 85a2962d..00000000 --- a/rh-sre/TODO.md +++ /dev/null @@ -1,54 +0,0 @@ -- [X] CVE must be remeditable -- [X] Check Job execution log to validate the CVE -- [X] Job Template must have check type or support check Prompt on Launch for dry-run mode. Stop otherwise -- [ ] Prompt on launch for inventory is preferred - -- [ ] Validate via script to save context -- [ ] Spec Driven Dev -- [ ] MCP: specify GS atstus -- [ ] Cursor install -- [x] AAP execution - -- [x] Skill stops if the MCP server is not available! - -- [x] Skill instructions to add docs: -``` - The remediation skill orchestrated these skills based on their documented workflows and best practices, but since the agent output didn't - explicitly report "I consulted file X.md," I defaulted to "Docs: N/A" in the summary. -``` - -- [x] New skill to make a execution report! - -- [ ] Skill instructions to avoid tool execution errors: -``` -โบ The first call failed with an "Unhandled error" because I only passed the per_page parameter without explicitly providing the filter - parameters like display_name. - - The second call succeeded because I explicitly passed display_name as an empty string along with per_page. Even though all parameters have - defaults according to the tool definition, the MCP tool implementation appears to require filter parameters to be explicitly provided in - the request, even if they're empty values. - - This is likely a quirk of how the underlying API or MCP tool handles parameter serializationโ€”it may not properly handle the case where - optional filter parameters are omitted entirely, but it works fine when they're explicitly set (even as empty strings). - - The fix was straightforward: include the filter parameters explicitly, which is a safer practice anyway for API consistency. -``` - -- [ ] Simplify Skill definition, too long! - -- [x] System prompt: can be set in the Skill definition? - -- [ ] Remediation must propose to review the playbook - -- [ ] Remediation must verify the CVE status at the end - - -- [ ] Simulated executions! -``` - This is a significant problem. The agent produced convincing-looking output that I reported as real results without verifying actual tool - execution occurred. -``` - -- [ ] Skill to run simulations - -- [ ] Skills and sub-skills vs agents and skills diff --git a/rh-sre/skills/cve-impact/SKILL.md b/rh-sre/skills/cve-impact/SKILL.md index 82aa9c29..41a9436b 100644 --- a/rh-sre/skills/cve-impact/SKILL.md +++ b/rh-sre/skills/cve-impact/SKILL.md @@ -1,31 +1,13 @@ --- name: cve-impact description: | - **CRITICAL**: This skill must be used for ALL CVE discovery and listing queries. DO NOT use raw MCP tools like get_cves directly. + **CRITICAL**: Use for ALL CVE discovery and listing. DO NOT call get_cves directly. - Use this skill when users request: - - Listing critical/high-severity CVEs: "show me critical vulnerabilities", "what are the most critical CVEs", "list all high-severity vulnerabilities" - - CVE discovery: "what vulnerabilities affect my account", "show me all CVEs", "what are my security risks" - - Remediatable CVEs: "which CVEs can I remediate?", "show remediatable vulnerabilities", "CVEs with available advisory" - - CVEs affecting a specific system: "what CVEs affect hostname X?", "what vulnerabilities are on ip-172-31-32-201?" - - CVE impact analysis for specific CVEs: "what's the impact of CVE-X?", "analyze CVE-Y" - - Risk assessment: "which CVEs are most urgent?", "prioritize vulnerabilities" - - Understanding affected systems for a CVE - - Comparing CVE severity levels - - CVE discovery and prioritization (information gathering) + Use when: "show critical CVEs", "CVEs on hostname X", "remediatable vulnerabilities", "impact of CVE-X", risk assessment. - DO NOT use this skill when users request remediation actions like: - - "Create a remediation playbook" (use `/remediation` skill) - - "Patch CVE-X on system Y" (use `/remediation` skill) - - "Remediate these CVEs" (use `/remediation` skill) + NOT for remediation (use `/remediation`). - This skill orchestrates MCP tools (get_cves, get_cve, get_cve_systems, get_system_cves) to provide comprehensive CVE analysis with Red Hat Lightspeed context. When users ask for remediation after seeing the analysis, invoke the `/remediation` skill. - - **IMPORTANT**: ALWAYS use this skill instead of calling get_cves or other vulnerability MCP tools directly. - - **System-level (CVEs on device X)**: Your FIRST reply must be the pagination prompt. Do NOT call inventory__find_host_by_name or vulnerability__get_system_cves until user responds. See Step -1. - - **Parsing**: Use references/01-cve-response-parser.py. Do NOT use jq or inline Python. + System-level: FIRST reply = pagination prompt (Step -1). Parsing: references/01-cve-response-parser.py. --- # CVE Impact Analysis Skill @@ -316,243 +298,31 @@ Priority: P0 (within 24 hours) / P1 (within 7 days) / P2 (within 30 days) ### Step 6: Impact Analysis -Analyze the potential business impact: -``` -Impact Analysis -โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” - -Service Impact: -- Web services (web-server-01, web-server-02): High availability risk -- API endpoints: Potential data exposure - -Business Impact: -- Confidentiality: Customer data could be exposed -- Integrity: System files could be modified -- Availability: Service disruption possible - -Compliance Impact: -- PCI-DSS: Non-compliance if not remediated -- SOC 2: Control failure -``` +Analyze business impact (service, confidentiality/integrity/availability, compliance). ### Step 7: Remediation Readiness Check -Check if remediation is available: -``` -Remediation Availability -โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” - -โœ“ Automated Playbook: Available -โœ“ Package Update: httpd-2.4.37-2.el8 (fixed version) -โœ“ Reboot Required: No -โœ“ Estimated Downtime: < 5 minutes per system - -OR - -โœ— Automated Playbook: Not available -โœ“ Manual Steps Required: Yes - 1. Update package manually: yum update httpd - 2. Restart service: systemctl restart httpd - 3. Verify fix: httpd -v -``` - -## Output Template - -When completing a CVE impact analysis, provide output in this format: - -```markdown -# CVE Impact Analysis Report - -## CVE Information -**CVE ID**: CVE-YYYY-NNNNN -**CVSS Score**: X.X -**Severity**: Critical/High/Medium/Low -**Published**: YYYY-MM-DD - -**Description**: -[Brief description of the vulnerability] - -**Affected Packages**: -- package-name version-range - -## Affected Systems -**Total Systems**: N - -| System | Hostname | Environment | Package | Status | -|--------|----------|-------------|---------|--------| -| uuid-1 | server-01 | Production | httpd-2.4.37 | Vulnerable | -| uuid-2 | server-02 | Production | httpd-2.4.37 | Vulnerable | - -## Risk Assessment -**Overall Risk**: Critical/High/Medium/Low -**Priority**: P0/P1/P2 -**Recommendation**: [Immediate remediation / Schedule maintenance / Monitor] - -**Key Factors**: -- Attack Vector: [Network/Local/etc] -- Exploitability: [Known exploits / PoC available / Theoretical] -- Impact: [High/Medium/Low] - -## Business Impact -- **Confidentiality**: [Impact description] -- **Integrity**: [Impact description] -- **Availability**: [Impact description] - -## Remediation Options -- โœ“ Automated playbook available -- โœ“ Manual steps documented -- โš  Requires testing in staging first -- โš  Maintenance window recommended - -## Next Steps -1. [ ] Approve remediation plan -2. [ ] Schedule maintenance window (if needed) -3. [ ] Create remediation playbook (use `/remediation` skill) -4. [ ] Test in staging environment -5. [ ] Execute in production -6. [ ] Verify remediation success -``` - -## Examples - -### Example 0: List Critical Vulnerabilities (Discovery Query) - -**User Request**: "What are the most critical vulnerabilities on my account?" - -**Skill Response**: -1. Follow [01-account-cves.md](flows/01-account-cves.md) (severity=most critical, remediation=does not matter) -2. HITL: Confirm limit (default 20) before calling -3. Call `vulnerability__get_cves(impact="7,6", sort="-cvss_score", limit=20, advisory_available="true,false")` -4. Parse and sort results by CVSS score -5. Return summary table: - -```markdown -# Critical Vulnerabilities Summary - -Found 12 Critical/Important CVEs affecting your systems: - -| CVE ID | CVSS | Severity | Affected Systems | Remediation | Priority | -|--------|------|----------|------------------|-------------|----------| -| CVE-2024-1234 | 9.8 | Critical | 15 systems | Available | P0 - Immediate | -| CVE-2024-5678 | 8.1 | Important | 8 systems | Available | P1 - 7 days | -| CVE-2024-9012 | 7.5 | Important | 25 systems | Available | P1 - 7 days | -| ... | ... | ... | ... | ... | ... | - -**Recommendations**: -- CVE-2024-1234: Immediate remediation required (CVSS 9.8, network exploitable) -- CVE-2024-5678: Schedule remediation within 7 days -- CVE-2024-9012: High system count (25 systems) - consider batch remediation - -**Next Steps**: -- Analyze any specific CVE for details: "Analyze CVE-2024-1234" -- Create remediation plan: "Remediate CVE-2024-1234 on all affected systems" -``` - -6. Wait for user to request specific CVE analysis or remediation -7. If user says "remediate CVE-X", respond: "I'll use the remediation skill to create the remediation playbook" (invoke the `/remediation` skill) - -### Example 1: CVEs Affecting a Specific System - -**User Request**: "What CVEs are affecting ip-172-31-32-201.eu-west-3.compute.internal?" - -**Skill Response**: -1. Follow [02-system-all-cves.md](flows/02-system-all-cves.md) (remediation=does not matter) -2. HITL: Ask pagination strategy (first page / all pages / N pages) -3. Resolve hostname to UUID: `inventory__find_host_by_name(hostname="ip-172-31-32-201.eu-west-3.compute.internal")` -4. Call `vulnerability__get_system_cves(system_uuid="", limit=100, offset=0)` per chosen strategy -5. Sort and present results by CVSS score -6. If user asked for "critical only", filter the returned list client-side -7. Offer to analyze specific CVEs or create remediation plan - -### Example 2: High-Severity CVE Analysis - -**User Request**: "Analyze the impact of CVE-2024-1234" - -**Skill Response**: -1. Retrieve CVE details using `get_cve` -2. List affected systems using `get_cve_systems` -3. Classify systems by environment and criticality -4. Provide risk assessment and recommendations -5. Suggest next steps (use `/remediation` skill if remediation needed) - -### Example 3: Multiple CVE Comparison - -**User Request**: "Compare the impact of CVE-2024-1234 and CVE-2024-5678" - -**Skill Response**: -1. Retrieve details for both CVEs -2. Create comparison table (CVSS, severity, affected systems) -3. Recommend prioritization order -4. Suggest batch remediation if both should be fixed together - -### Example 4: Environment-Specific Analysis - -**User Request**: "Which production systems are affected by CVE-2024-1234?" - -**Skill Response**: -1. Retrieve CVE details -2. Filter affected systems by environment tag -3. Provide production-specific impact assessment -4. Include business impact analysis for production services - -## Integration with Remediator Agent +Check if automated playbook or manual steps are available. -After completing impact analysis, the skill should: +## Output and Examples -1. **Suggest transition to remediation** if risk is high: - ``` - Based on this analysis, immediate remediation is recommended. - - Would you like me to create a remediation playbook? - (This will invoke the `/remediation` skill) - ``` - -2. **Provide context for remediation**: - - CVE ID - - Affected system UUIDs - - Recommended execution method (AAP/Tower/Manual) - - Suggested maintenance window +**Read [references/03-output-templates.md](references/03-output-templates.md)** for report format. +**Read [references/04-examples.md](references/04-examples.md)** for query-type examples and remediation integration. ## Error Handling -**CVE not found**: -``` -CVE-YYYY-NNNNN was not found in the Red Hat CVE database. - -Possible reasons: -- CVE ID is incorrect -- CVE is too recent and not yet in database -- CVE doesn't affect RHEL systems - -Suggestions: -- Verify CVE ID format (CVE-YYYY-NNNNN) -- Check NVD database: https://nvd.nist.gov/vuln/search -- Try alternative CVE IDs if this is an alias -``` - -**No affected systems**: -``` -CVE-YYYY-NNNNN Analysis Complete - -Good news! No systems in your infrastructure are affected by this CVE. - -Possible reasons: -- Your systems are already patched -- Affected packages are not installed -- Systems are running different versions - -No action required. -``` - -**Lightspeed tool failures** (e.g. explain_cves `'dnf_modules'`): Do NOT show raw error. Do NOT retry. Use user-friendly message and workaround (get_cve + get_host_details synthesis) from [lightspeed-mcp-tool-failures.md](../../../docs/references/lightspeed-mcp-tool-failures.md). +**Read [references/05-error-handling.md](references/05-error-handling.md)** for CVE not found, no affected systems, and Lightspeed tool failures. ## Reference Files | File | Use When | |------|----------| | [01-cve-response-parser.py](references/01-cve-response-parser.py) | Parse/filter MCP vulnerability responses | -| [02-cve-parsing-guide.md](references/02-cve-parsing-guide.md) | How to invoke parser, filter options, response structure | -| [lightspeed-mcp-tool-failures.md](../../../docs/references/lightspeed-mcp-tool-failures.md) | Lightspeed tool failures (e.g. explain_cves 'dnf_modules') โ€” user-friendly message and workarounds | +| [02-cve-parsing-guide.md](references/02-cve-parsing-guide.md) | Parser invocation, filter options | +| [03-output-templates.md](references/03-output-templates.md) | Report format | +| [04-examples.md](references/04-examples.md) | Query-type examples | +| [05-error-handling.md](references/05-error-handling.md) | CVE not found, no systems, Lightspeed failures | +| [lightspeed-mcp-tool-failures.md](../../../docs/references/lightspeed-mcp-tool-failures.md) | explain_cves dnf_modules workaround | ## Parsing MCP Responses diff --git a/rh-sre/skills/cve-impact/references/03-output-templates.md b/rh-sre/skills/cve-impact/references/03-output-templates.md new file mode 100644 index 00000000..4f41c54b --- /dev/null +++ b/rh-sre/skills/cve-impact/references/03-output-templates.md @@ -0,0 +1,39 @@ +# CVE Impact Output Templates + +Read when completing a CVE impact analysis to format the report. + +## Report Format + +```markdown +# CVE Impact Analysis Report + +## CVE Information +**CVE ID**: CVE-YYYY-NNNNN +**CVSS Score**: X.X +**Severity**: Critical/High/Medium/Low +**Published**: YYYY-MM-DD + +**Description**: [Brief description] +**Affected Packages**: package-name version-range + +## Affected Systems +**Total Systems**: N +| System | Hostname | Environment | Package | Status | + +## Risk Assessment +**Overall Risk**: Critical/High/Medium/Low +**Priority**: P0/P1/P2 +**Recommendation**: [Immediate remediation / Schedule maintenance / Monitor] + +## Business Impact +- Confidentiality, Integrity, Availability + +## Remediation Options +- Automated playbook / Manual steps / Testing required + +## Next Steps +1. Approve remediation plan +2. Schedule maintenance (if needed) +3. Create playbook (use `/remediation` skill) +4. Test in staging โ†’ Execute in production โ†’ Verify +``` diff --git a/rh-sre/skills/cve-impact/references/04-examples.md b/rh-sre/skills/cve-impact/references/04-examples.md new file mode 100644 index 00000000..325e9850 --- /dev/null +++ b/rh-sre/skills/cve-impact/references/04-examples.md @@ -0,0 +1,37 @@ +# CVE Impact Examples + +Read when handling specific query types. + +## Example 0: Account-Level Critical CVEs + +**Request**: "What are the most critical vulnerabilities on my account?" +- Follow [01-account-cves.md](../flows/01-account-cves.md) +- Call `vulnerability__get_cves(impact="7,6", sort="-cvss_score", limit=20)` +- Return summary table; offer remediation via `/remediation` + +## Example 1: CVEs on a System + +**Request**: "What CVEs affect ip-172-31-32-201?" +- Follow [02-system-all-cves.md](../flows/02-system-all-cves.md) +- HITL: pagination (first page / all pages / N pages) +- Resolve hostname: `inventory__find_host_by_name` +- Call `vulnerability__get_system_cves(system_uuid=..., limit=100, offset=0)` + +## Example 2: Single CVE Analysis + +**Request**: "Analyze CVE-2024-1234" +- `get_cve` โ†’ `get_cve_systems` โ†’ classify โ†’ risk assessment โ†’ suggest `/remediation` + +## Example 3: Compare CVEs + +**Request**: "Compare CVE-2024-1234 and CVE-2024-5678" +- Retrieve both; comparison table; prioritization; batch remediation if appropriate + +## Example 4: Production-Only + +**Request**: "Which production systems are affected by CVE-2024-1234?" +- Retrieve CVE; filter by environment tag; production-specific impact + +## Integration with Remediation + +After analysis, suggest: "Would you like me to create a remediation playbook?" (invoke `/remediation`). Provide CVE ID, system UUIDs, execution method, maintenance window. diff --git a/rh-sre/skills/cve-impact/references/05-error-handling.md b/rh-sre/skills/cve-impact/references/05-error-handling.md new file mode 100644 index 00000000..006aee55 --- /dev/null +++ b/rh-sre/skills/cve-impact/references/05-error-handling.md @@ -0,0 +1,24 @@ +# CVE Impact Error Handling + +Read when errors occur during CVE analysis. + +## CVE Not Found + +``` +CVE-YYYY-NNNNN was not found in the Red Hat CVE database. + +Possible reasons: CVE ID incorrect, too recent, doesn't affect RHEL. +Suggestions: Verify format (CVE-YYYY-NNNNN), check NVD: https://nvd.nist.gov/vuln/search +``` + +## No Affected Systems + +``` +CVE-YYYY-NNNNN Analysis Complete โ€” No systems affected. +Possible reasons: Already patched, packages not installed, different versions. +No action required. +``` + +## Lightspeed Tool Failures + +If explain_cves fails with `'dnf_modules'`: Do NOT show raw error. Use workaround from [lightspeed-mcp-tool-failures.md](../../../docs/references/lightspeed-mcp-tool-failures.md) (get_cve + get_host_details synthesis). diff --git a/rh-sre/skills/cve-validation/SKILL.md b/rh-sre/skills/cve-validation/SKILL.md index fae76155..fde713b0 100644 --- a/rh-sre/skills/cve-validation/SKILL.md +++ b/rh-sre/skills/cve-validation/SKILL.md @@ -283,197 +283,15 @@ Return structured validation result. **When invoked by remediation skill**: Ensu } ``` -## Output Template - -When completing CVE validation, provide output in this format: - -```markdown -# CVE Validation Result - -## CVE: CVE-YYYY-NNNNN -**Status**: โœ“ Valid - -## CVE Information -**CVSS Score**: 7.5 (Important) -**Published**: 2024-01-15 -**Description**: [Brief description of the vulnerability] - -## Affected Packages -- httpd-2.4.37-1.el8 โ†’ httpd-2.4.37-2.el8 (fixed) - -## Remediation Status -โœ“ **Automated Remediation Available** -โœ“ Package updates available -โœ— Reboot NOT required - -## Severity Assessment -**Red Hat Severity**: Important -**Priority**: P1 - Urgent remediation recommended -**Response Time**: Within 7 days - -## Recommendations -1. Automated remediation available via Red Hat Lightspeed -2. No reboot required - minimal disruption -3. Test in staging environment first -4. Schedule deployment during change window - -## Next Steps -1. Analyze CVE impact โ†’ Use cve-impact skill -2. Gather system context โ†’ Use system-context skill -3. Generate remediation playbook โ†’ Use playbook-generator skill -4. Execute remediation โ†’ Follow playbook instructions -5. Verify success โ†’ Use remediation-verifier skill -``` - -## Examples - -### Example 1: Valid CVE with Automated Remediation - -**User Request**: "Validate CVE-2024-1234" - -**Skill Response**: -1. Check format โ†’ Valid (CVE-2024-1234) -2. Call `get_cve` โ†’ CVE found in database -3. Check advisory_available, remediation, advisories_list (ignore rules[]) โ†’ remediation available -4. Extract metadata โ†’ CVSS 7.5, Important severity, httpd package -5. Return: "Valid CVE, automated remediation available, proceed with workflow" - -### Example 2: Valid CVE, No Automated Remediation - -**User Request**: "Validate CVE-2024-5678" - -**Skill Response**: -1. Check format โ†’ Valid -2. Call `get_cve` โ†’ CVE found -3. Check advisory_available, remediation, advisories_list โ†’ all indicate no remediation (do NOT use rules[]) -4. Extract manual steps โ†’ Affected package: custom-app-1.0 -5. Return: "Valid CVE but no automated playbook. Manual remediation required: yum update custom-app" - -### Example 3: Invalid CVE Format - -**User Request**: "Validate CVE-24-1234" - -**Skill Response**: -1. Check format โ†’ Invalid (year must be 4 digits) -2. Return error immediately without MCP call -3. Suggest correction: "Did you mean CVE-2024-1234?" - -### Example 4: CVE Not Found - -**User Request**: "Validate CVE-2024-999999" +## Output, Examples, Error Handling -**Skill Response**: -1. Check format โ†’ Valid -2. Call `get_cve` โ†’ 404 Not Found -3. Return: "CVE not found in Red Hat database. Possible reasons: CVE too recent, doesn't affect RHEL, or invalid ID. Check NVD: https://nvd.nist.gov/vuln/detail/CVE-2024-999999" - -### Example 5: Batch Validation - -**User Request**: "Validate CVE-2024-1234, CVE-2024-5678, CVE-2024-9012" - -**Skill Response**: -1. Validate each CVE sequentially -2. Return summary: - - CVE-2024-1234: โœ“ Valid, automated remediation available - - CVE-2024-5678: โœ“ Valid, manual remediation required - - CVE-2024-9012: โœ— Invalid format (CVE-2024-90124 has too many digits) -3. Suggest: "Proceed with automated remediation for CVE-2024-1234, manual steps for CVE-2024-5678, correct format for third CVE" - -## Error Handling - -**CVE Format Invalid**: -``` -CVE Validation Failed: Invalid Format - -Provided: CVE-24-1234 -Expected Format: CVE-YYYY-NNNNN - -Where: -- YYYY = 4-digit year (e.g., 2024) -- NNNNN = 4-7 digit sequence number - -Suggestion: Did you mean CVE-2024-1234? -``` - -**CVE Not Found in Database**: -``` -CVE Validation Failed: Not Found - -CVE-YYYY-NNNNN was not found in the Red Hat CVE database. - -Possible reasons: -1. CVE is too recent (not yet in Red Hat Lightspeed) -2. CVE doesn't affect RHEL systems (Windows/macOS specific) -3. CVE ID is incorrect or doesn't exist - -Next steps: -1. Verify CVE ID at NVD: https://nvd.nist.gov/vuln/detail/CVE-YYYY-NNNNN -2. Check Red Hat Security Advisories: https://access.redhat.com/security/cve/CVE-YYYY-NNNNN -3. Wait 24-48 hours if CVE was just published -``` - -**CVE Exists But No Automated Remediation**: -``` -CVE Validation: Valid (No Automated Remediation) - -CVE-YYYY-NNNNN is valid but does not have an automated remediation playbook. - -CVE Details: -- CVSS Score: X.X -- Severity: Important -- Affected Packages: package-name-version - -Manual Remediation Required: - -1. Update package manually: - ```bash - # RHEL 8/9 - sudo dnf update package-name - - # RHEL 7 - sudo yum update package-name - ``` - -2. Restart service (if applicable): - ```bash - sudo systemctl restart service-name - ``` - -3. Verify fix: - ```bash - package-name --version - ``` - -Would you like me to create a manual playbook template based on these steps? -``` - -**API Access Error**: -``` -CVE Validation Failed: API Access Error - -Unable to access Red Hat Lightspeed API. - -Possible causes: -- Network connectivity issue -- API authentication failure -- Lightspeed service temporarily unavailable - -Troubleshooting: -1. Check network connectivity: ping console.redhat.com -2. Verify credentials: insights-client --status -3. Check Lightspeed service status: https://status.redhat.com -4. Retry in a few minutes -``` +**Read [references/03-output-template.md](references/03-output-template.md)** for report format. +**Read [references/04-examples.md](references/04-examples.md)** for validation examples. +**Read [references/05-error-handling.md](references/05-error-handling.md)** for format, not-found, no-remediation, and API errors. ## Best Practices -1. **Validate format first** - Don't waste API calls on malformed CVE IDs. But if format matches regex, ALWAYS call get_cveโ€”do not reject based on year or sequence number. -2. **Check remediation availability** - Fail fast if no automated remediation -3. **Batch validation efficiently** - Validate multiple CVEs in parallel when possible -4. **Provide clear next steps** - Guide users to appropriate next action -5. **Include manual steps** - Always provide manual remediation guidance if automated is unavailable -6. **Link to official sources** - Include NVD and Red Hat Security links -7. **Cache validation results** - Avoid redundant API calls for same CVE +Validate format first; if regex matches, ALWAYS call get_cve (do not reject on year/sequence). Check remediation availability; fail fast if none. Provide clear next steps and manual guidance when automated unavailable. Link to NVD and Red Hat Security. Cache results to avoid redundant calls. ## Dependencies @@ -519,28 +337,4 @@ All tools are provided by the lightspeed-mcp MCP server configured in `.mcp.json ## Integration with Other Skills -- **cve-impact**: Validates CVE before performing impact analysis -- **playbook-generator**: Only generates playbooks for valid, remediable CVEs -- **system-context**: Only gathers context for valid CVEs -- **remediation-verifier**: Validates CVE was properly remediated - -**Orchestration Example** (from `/remediation` skill): -1. User requests remediation for CVE-2024-1234 -2. Agent invokes cve-validation skill โ†’ Confirms valid and remediable -3. Agent invokes cve-impact skill โ†’ Risk assessment -4. Agent invokes system-context skill โ†’ Deployment architecture -5. Agent invokes playbook-generator skill โ†’ Creates playbook -6. User executes playbook -7. Agent invokes remediation-verifier skill โ†’ Confirms success - -**Validation-First Pattern**: -``` -Always validate CVE before expensive operations: -โœ“ CVE valid? โ†’ Proceed -โœ— CVE invalid? โ†’ Stop, return error - -This saves time and avoids: -- Unnecessary impact analysis -- Wasted system context gathering -- Failed playbook generation -``` +cve-impact, playbook-generator, system-context, remediation-verifier all depend on validation first. The `/remediation` skill invokes cve-validation as Step 2. Validate โ†’ proceed if valid; stop and return error if invalid. diff --git a/rh-sre/skills/cve-validation/references/03-output-template.md b/rh-sre/skills/cve-validation/references/03-output-template.md new file mode 100644 index 00000000..51bb3992 --- /dev/null +++ b/rh-sre/skills/cve-validation/references/03-output-template.md @@ -0,0 +1,36 @@ +# CVE Validation Output Template + +Read when completing CVE validation to format the report. + +```markdown +# CVE Validation Result + +## CVE: CVE-YYYY-NNNNN +**Status**: โœ“ Valid + +## CVE Information +**CVSS Score**: X.X (Severity) +**Published**: YYYY-MM-DD +**Description**: [Brief description] + +## Affected Packages +- package-current โ†’ package-fixed (fixed) + +## Remediation Status +โœ“ **Automated Remediation Available** (or โœ— Manual required) +โœ“ Package updates available +โœ— Reboot NOT required + +## Severity Assessment +**Red Hat Severity**: Critical/Important/Moderate/Low +**Priority**: P0/P1/P2 +**Response Time**: [guidance] + +## Recommendations +1. [Automated/manual remediation guidance] +2. Test in staging first +3. Schedule deployment during change window + +## Next Steps +1. cve-impact โ†’ system-context โ†’ playbook-generator โ†’ remediation-verifier +``` diff --git a/rh-sre/skills/cve-validation/references/04-examples.md b/rh-sre/skills/cve-validation/references/04-examples.md new file mode 100644 index 00000000..2a16ce85 --- /dev/null +++ b/rh-sre/skills/cve-validation/references/04-examples.md @@ -0,0 +1,35 @@ +# CVE Validation Examples + +## Example 1: Valid CVE with Automated Remediation + +**Request**: "Validate CVE-2024-1234" +1. Format check โ†’ Valid +2. get_cve โ†’ found +3. advisory_available/remediation/advisories_list โ†’ remediation available (ignore rules[]) +4. Return: "Valid, automated remediation available" + +## Example 2: Valid CVE, No Automated Remediation + +**Request**: "Validate CVE-2024-5678" +1. Format โ†’ Valid, get_cve โ†’ found +2. advisory_available/remediation/advisories_list โ†’ no remediation +3. Return: "Valid but manual remediation: yum update custom-app" + +## Example 3: Invalid Format + +**Request**: "Validate CVE-24-1234" +1. Format โ†’ Invalid (year must be 4 digits) +2. Return error without MCP call; suggest CVE-2024-1234 + +## Example 4: CVE Not Found + +**Request**: "Validate CVE-2024-999999" +1. Format โ†’ Valid, get_cve โ†’ 404 +2. Return: "Not found. Check NVD, access.redhat.com, or wait 24-48h if recent" + +## Example 5: Batch Validation + +**Request**: "Validate CVE-2024-1234, CVE-2024-5678, CVE-2024-9012" +1. Validate each sequentially +2. Return summary per CVE (valid/remediable, valid/manual, invalid format) +3. Suggest next steps per CVE diff --git a/rh-sre/skills/cve-validation/references/05-error-handling.md b/rh-sre/skills/cve-validation/references/05-error-handling.md new file mode 100644 index 00000000..201c193a --- /dev/null +++ b/rh-sre/skills/cve-validation/references/05-error-handling.md @@ -0,0 +1,37 @@ +# CVE Validation Error Handling + +Read when errors occur during CVE validation. + +## CVE Format Invalid + +``` +CVE Validation Failed: Invalid Format +Provided: CVE-24-1234 +Expected: CVE-YYYY-NNNNN (YYYY=4-digit year, NNNNN=4-7 digit sequence) +Suggestion: Did you mean CVE-2024-1234? +``` + +## CVE Not Found in Database + +``` +CVE-YYYY-NNNNN was not found in Red Hat CVE database. +Possible reasons: Too recent, doesn't affect RHEL, incorrect ID. +Next steps: Verify at NVD, access.redhat.com/security/cve/CVE-YYYY-NNNNN, wait 24-48h if recent. +``` + +## CVE Exists But No Automated Remediation + +``` +CVE Validation: Valid (No Automated Remediation) +CVE-YYYY-NNNNN is valid but has no automated playbook. +Manual steps: dnf/yum update package-name, restart service if needed, verify fix. +Offer: "Would you like a manual playbook template?" +``` + +## API Access Error + +``` +CVE Validation Failed: API Access Error +Possible causes: Network, auth failure, service unavailable. +Troubleshooting: ping console.redhat.com, verify credentials, status.redhat.com, retry. +``` diff --git a/rh-sre/skills/fleet-inventory/SKILL.md b/rh-sre/skills/fleet-inventory/SKILL.md index 4a9bbbe1..c39320e5 100644 --- a/rh-sre/skills/fleet-inventory/SKILL.md +++ b/rh-sre/skills/fleet-inventory/SKILL.md @@ -105,58 +105,7 @@ Proceeding with fleet inventory query... **Purpose**: Query Lightspeed for comprehensive system information -**Parameters** (based on user query): - -```python -# For "Show the managed fleet" (no filters) -get_host_details() - -# For "Show system abc-123" (specific system) -get_host_details( - system_id="abc-123" -) - -# For "Show web servers" (hostname pattern) -get_host_details( - hostname_pattern="web-*" -) - -# For "Show production systems" (tag filter) -get_host_details( - tags=["production"] -) - -# For "Show RHEL 8 systems" (version filter) -get_host_details( - operating_system__version__startswith="8" -) - -# Multiple filters combined -get_host_details( - tags=["production", "web-tier"], - operating_system__version__startswith="8" -) -``` - -**Expected Response**: -```json -{ - "systems": [ - { - "id": "abc-def-123", - "display_name": "web-server-01.example.com", - "fqdn": "web-server-01.example.com", - "rhel_version": "8.9", - "last_seen": "2024-01-20T10:30:00Z", - "tags": ["production", "web-tier"], - "stale": false, - "satellite_managed": false - } - ], - "total": 42, - "count": 10 -} -``` +**Parameters**: See [references/01-parameter-reference.md](references/01-parameter-reference.md) for get_host_details/get_cve_systems parameters and response fields. **Verification Checklist**: - โœ“ Systems list returned with metadata @@ -178,42 +127,7 @@ get_host_details( 1. **Action**: Read [fleet-management.md](../../docs/insights/fleet-management.md) using the Read tool to understand fleet inventory reporting structure and best practices 2. **Output to user**: "I consulted [fleet-management.md](../../docs/insights/fleet-management.md) to structure this inventory report." -Apply user-requested filters and grouping: - -**Filtering Examples**: - -```python -# By RHEL Version -systems_rhel8 = [s for s in systems if s['rhel_version'].startswith("8")] -# Result: All RHEL 8.x systems - -# By Environment Tag -production_systems = [s for s in systems if "production" in s.get('tags', [])] -# Result: Production systems only - -# By Status (active vs stale) -active_systems = [s for s in systems if not s.get('stale', False)] -# Result: Active systems (checked in recently) - -# By Hostname Pattern -web_servers = [s for s in systems if 'web-server' in s.get('fqdn', '')] -# Result: Web tier systems -``` - -**Sorting Options**: -```python -# By last check-in (most recent first) -sorted(systems, key=lambda s: s['last_seen'], reverse=True) - -# By RHEL version (group by OS) -sorted(systems, key=lambda s: s['rhel_version']) - -# By display name (alphabetical) -sorted(systems, key=lambda s: s['display_name']) - -# By environment tag -sorted(systems, key=lambda s: s.get('tags', [''])[0]) -``` +Apply user-requested filters and grouping. See [references/01-parameter-reference.md](references/01-parameter-reference.md) for filtering and sorting patterns. ### Step 3: Query CVE-Affected Systems @@ -221,43 +135,7 @@ sorted(systems, key=lambda s: s.get('tags', [''])[0]) **Purpose**: Find systems affected by specific CVEs -**Parameters** (exact specification): - -```python -# For "What systems are affected by CVE-2024-1234?" -get_cve_systems( - cve_id="CVE-2024-1234" # Exact CVE ID from user query -) - -# The cve_id parameter MUST: -# - Match format: CVE-YYYY-NNNNN -# - Be uppercase: CVE-2024-1234 (not cve-2024-1234) -# - Include full ID: CVE-2024-1234 (not 2024-1234) -``` - -**Expected Response**: -```json -{ - "cve_id": "CVE-2024-1234", - "affected_systems": [ - { - "system_id": "abc-def-123", - "display_name": "web-server-01.example.com", - "status": "Vulnerable", - "remediation_available": true - }, - { - "system_id": "xyz-123-456", - "display_name": "db-server-02.example.com", - "status": "Vulnerable", - "remediation_available": true - } - ], - "total_affected": 15, - "total_remediated": 3, - "total_vulnerable": 12 -} -``` +**Parameters**: `cve_id` (CVE-YYYY-NNNNN, uppercase). See [references/01-parameter-reference.md](references/01-parameter-reference.md). **Verification Checklist**: - โœ“ CVE ID matches request exactly @@ -282,39 +160,7 @@ Status: "Not Affected" ### Step 4: Generate Fleet Summary -Create organized output based on query results: - -**Summary Template**: -```markdown -# Fleet Inventory Summary - -Retrieved from Red Hat Lightspeed on YYYY-MM-DDTHH:MM:SSZ - -## Overview -**Total Systems**: -**Active Systems**: (last seen < 24 hours) -**Stale Systems**: (last seen > 7 days) - -## By RHEL Version -- RHEL 9.x: systems (%) -- RHEL 8.x: systems (%) -- RHEL 7.x: systems (%) - -## By Environment (Tags) -- Production: systems -- Staging: systems -- Development: systems - -## System Details - -| Display Name | RHEL Version | Environment | Last Seen | Status | -|--------------|--------------|-------------|-----------|--------| -| [system details rows...] - -## Stale Systems (Attention Required) -โš ๏ธ The following systems have not checked in recently: -- [stale system list...] -``` +Create organized output. **Read [references/03-output-templates.md](references/03-output-templates.md)** for report format (Overview, RHEL/Environment breakdown, System Details, Stale Systems). ### Step 5: Offer Remediation Transition @@ -398,335 +244,12 @@ Playbook generated and executed **Key Principle**: Always start with discovery before taking remediation actions. This ensures informed decisions based on actual fleet state. -## Output Templates - -### Template 1: Full Fleet Listing - -**User Request**: "Show the managed fleet" - -**Skill Response**: -```markdown -# Managed Fleet Inventory - -I consulted [fleet-management.md](../../docs/insights/fleet-management.md) to structure this inventory report. - -Retrieved from Red Hat Lightspeed on 2024-01-20T10:30:00Z - -## Fleet Overview -- **Total Registered Systems**: 42 -- **Active (< 24h)**: 38 -- **Stale (> 7 days)**: 4 - -## RHEL Version Distribution -| Version | Count | Percentage | -|---------|-------|------------| -| RHEL 9.3 | 12 | 29% | -| RHEL 9.2 | 6 | 14% | -| RHEL 8.9 | 15 | 36% | -| RHEL 8.8 | 5 | 12% | -| RHEL 7.9 | 4 | 9% | - -## Environment Breakdown -| Environment | Count | Systems | -|-------------|-------|---------| -| Production | 25 | web-*, db-*, app-* | -| Staging | 10 | stg-* | -| Development | 7 | dev-* | - -## Top 20 Systems (by last check-in) -[Table with display_name, rhel_version, tags, last_seen] - -**Would you like to**: -- Filter by specific environment or RHEL version -- View CVEs affecting these systems -- Create remediation plans for vulnerabilities -``` - -### Template 2: CVE-Affected Systems - -**User Request**: "What systems are affected by CVE-2024-1234?" - -**Skill Response**: -```markdown -# CVE-2024-1234 Impact Analysis - -## Affected Systems Summary -- **Total Vulnerable**: 12 systems -- **Already Patched**: 3 systems -- **Total Registered**: 42 systems -- **Impact Rate**: 29% of fleet - -## Vulnerable Systems - -| System Name | RHEL Version | Environment | Remediation Available | -|-------------|--------------|-------------|-----------------------| -| web-server-01.example.com | 8.9 | production | โœ“ Yes | -| web-server-02.example.com | 8.9 | production | โœ“ Yes | -| app-server-03.example.com | 8.8 | staging | โœ“ Yes | -| ... | ... | ... | ... | - -**Affected Package**: httpd-2.4.51-7.el8_6.5 - -## Already Patched (No Action Needed) -- db-server-01.example.com (patched on 2024-01-18) -- cache-server-02.example.com (patched on 2024-01-19) -- lb-server-01.example.com (patched on 2024-01-19) - -## Next Steps - -**To remediate these systems**, use the `/remediation` skill: -- Single system: "Remediate CVE-2024-1234 on web-server-01" -- Batch production: "Remediate CVE-2024-1234 on all production systems" -- All vulnerable: "Create playbook for CVE-2024-1234 affecting these 12 systems" - -**For more analysis**: -- "Show CVSS score and severity for CVE-2024-1234" (use cve-impact skill) -- "What's the risk assessment for this CVE?" (use cve-impact skill) -``` - -### Template 3: Environment-Filtered View - -**User Request**: "Show me production systems" - -**Skill Response**: -```markdown -# Production Systems Inventory - -Filtered by tag: "production" - -## Production Fleet Summary -- **Total Production Systems**: 25 -- **RHEL 9.x**: 12 systems -- **RHEL 8.x**: 10 systems -- **RHEL 7.x**: 3 systems -- **Active**: 24 systems -- **Stale**: 1 system โš ๏ธ - -## System Tiers -### Web Tier (8 systems) -- web-server-01.example.com (RHEL 8.9) -- web-server-02.example.com (RHEL 8.9) -- web-server-03.example.com (RHEL 9.3) -- ... - -### Database Tier (6 systems) -- db-server-01.example.com (RHEL 9.3) -- db-server-02.example.com (RHEL 9.3) -- ... - -### Application Tier (11 systems) -- app-server-01.example.com (RHEL 8.9) -- app-server-02.example.com (RHEL 8.9) -- ... - -## Stale System Alert โš ๏ธ -- backup-server-01.example.com (last seen: 8 days ago) - - Action: Investigate Lightspeed client connectivity - -## Next Steps -- "Show CVEs affecting production systems" -- "List critical vulnerabilities in production" -- "Remediate CVE-X on production web tier" -``` - -## Examples - -### Example 1: General Fleet Query - -**User Request**: "Show the managed fleet" - -**Skill Execution**: -1. **Invoke mcp-lightspeed-validator skill** (Step 0) - - Validation result: โœ“ PASSED - - Message: "Lightspeed MCP validation successful. Proceeding with fleet inventory query..." -2. Call `get_host_details()` with no filters โ†’ retrieve all systems -3. I consulted [fleet-management.md](../../docs/insights/fleet-management.md) for grouping strategy -4. Group by RHEL version, environment tags -5. Calculate totals and percentages -6. Sort by last_seen (most recent first) -7. Generate Template 1 output -8. Offer next step options (CVE analysis, remediation) - -### Example 2: CVE Impact Query - -**User Request**: "What systems are affected by CVE-2024-1234?" - -**Skill Execution**: -1. **Invoke mcp-lightspeed-validator skill** (Step 0) - - Validation result: โœ“ PASSED -2. Call `get_cve_systems(cve_id="CVE-2024-1234")` -3. Separate vulnerable vs. patched systems -4. Extract affected package information -5. Generate Template 2 output -6. Suggest remediation agent for next steps - -### Example 3: Environment Filter - -**User Request**: "Show me staging systems" - -**Skill Execution**: -1. **Invoke mcp-lightspeed-validator skill** (Step 0) - - Validation result: โš  PARTIAL (connectivity test unavailable) - - Ask user: "Configuration appears correct but connectivity could not be tested. Proceed? (yes/no)" - - User response: "yes" -2. Call `get_host_details()` โ†’ retrieve all systems -3. Filter by tag: "staging" in system.tags -4. Group by tier/function (inferred from hostname patterns) -5. Generate Template 3 output -6. Suggest CVE analysis or remediation options - -## Error Handling - -**No Systems Found**: -``` -Fleet Inventory Query: No Results - -Query: [user's filter criteria] -Result: No systems match the specified criteria - -โ“ Possible reasons: -1. No systems registered in Red Hat Lightspeed -2. Filter criteria too restrictive -3. Systems not tagged with specified environment - -๐Ÿ”ง Troubleshooting: -- Verify systems are registered: Visit https://console.redhat.com/insights/inventory -- Try broader filters: Remove environment/version constraints -- Check tag spelling: Ensure tag names match exactly (case-sensitive) - -๐Ÿ’ก Suggested actions: -- "Show the managed fleet" (no filters) -- "List all system tags" -- "Show system registration status" -``` - -**Lightspeed API Error**: -``` -โŒ Fleet Inventory Query: API Error - -Error: Unable to retrieve system inventory from Red Hat Lightspeed - -๐Ÿ“‹ Possible causes: -1. lightspeed-mcp server not running -2. Authentication failure (invalid credentials) -3. Network connectivity issues -4. Red Hat Lightspeed service outage - -๐Ÿ”ง Troubleshooting: -1. Verify lightspeed-mcp server configuration: - - Check .mcp.json has lightspeed-mcp entry - - Verify container is running: podman ps | grep insights - -2. Check credentials (never echo valuesโ€”report presence/absence only): - - test -n "$LIGHTSPEED_CLIENT_ID" && echo "LIGHTSPEED_CLIENT_ID: set" || echo "LIGHTSPEED_CLIENT_ID: not set" - - test -n "$LIGHTSPEED_CLIENT_SECRET" && echo "LIGHTSPEED_CLIENT_SECRET: set" || echo "LIGHTSPEED_CLIENT_SECRET: not set" - - Verify credentials at https://console.redhat.com/settings/service-accounts - -3. Test connection manually: - podman run --rm -i --env LIGHTSPEED_CLIENT_ID --env LIGHTSPEED_CLIENT_SECRET \ - quay.io/redhat-services-prod/lightspeed-mcp:latest +## Output, Examples, Error Handling -4. Check service status: - - Visit https://status.redhat.com/ - -โ“ How would you like to proceed? -- "retry" - Try the query again -- "setup" - Reconfigure lightspeed-mcp server -- "abort" - Stop the workflow -``` - -**Stale System Warning**: -``` -โš ๏ธ Stale Systems Detected - -The following systems have not checked in recently (> 7 days): -- system-01.example.com (last seen: 8 days ago) -- system-02.example.com (last seen: 12 days ago) - -๐Ÿ“Š Impact: Vulnerability data may be outdated for these systems - -๐Ÿ”ง Recommended Actions: -1. Verify Lightspeed client is running: - ssh system-01.example.com "systemctl status insights-client" - -2. Check network connectivity from these systems: - ssh system-01.example.com "ping console.redhat.com" - -3. Review Lightspeed client logs: - ssh system-01.example.com "cat /var/log/insights-client/insights-client.log" - -4. Re-register if needed: - ssh system-01.example.com "insights-client --register" - -5. Force immediate check-in: - ssh system-01.example.com "insights-client --check-results" - -๐Ÿ’ก Note: Stale systems are still included in inventory but may have outdated CVE data. -``` +**Read [references/03-output-templates.md](references/03-output-templates.md)** for report format. +**Read [references/04-examples.md](references/04-examples.md)** for fleet, CVE-affected, and environment-filter examples. +**Read [references/05-error-handling.md](references/05-error-handling.md)** for no-results, API errors, and stale system handling. ## Best Practices -1. **Start broad, then filter** - Retrieve full inventory first, then apply user-requested filters -2. **Group by meaningful categories** - Environment, RHEL version, tier/function for clarity -3. **Highlight stale systems** - Warn users about systems with potentially outdated vulnerability data -4. **Offer remediation transitions** - Always suggest next steps using `/remediation` skill -5. **Use clear formatting** - Tables for detailed lists, summaries for high-level overviews -6. **Include percentages** - Help users understand fleet composition at a glance -7. **Show last check-in times** - Indicate data freshness and system health -8. **Link to CVE analysis** - Transition smoothly to cve-impact skill for vulnerability details -9. **Declare document consultations** - Always state "I consulted [file]" for transparency -10. **Verify prerequisites first** - Never attempt MCP calls without checking server availability - -## Integration with Other Skills - -**Skill Orchestration Workflows**: - -**Workflow 1: Discovery โ†’ Analysis โ†’ Action** -``` -User: "Show the managed fleet" - โ†“ -fleet-inventory skill - โ†“ -Response: 42 systems, 15 affected by CVE-2024-1234 - โ†“ -User: "What's the risk of CVE-2024-1234?" - โ†“ -cve-impact skill (analyzes severity) - โ†“ -Response: CVSS 8.1, Critical severity - โ†“ -User: "Remediate CVE-2024-1234 on all affected systems" - โ†“ -`/remediation` skill (orchestrates remediation) - โ†“ -Complete: Playbook generated and executed -``` - -**Workflow 2: Environment Focus** -``` -User: "Show production systems" - โ†“ -fleet-inventory skill (environment filter) - โ†“ -Response: 25 production systems - โ†“ -User: "List critical CVEs in production" - โ†“ -cve-impact skill (production scope) - โ†“ -Response: 3 critical CVEs - โ†“ -User: "Create remediation plan" - โ†“ -`/remediation` skill (multi-CVE workflow) -``` - -**Information-First Principle**: -``` -Always follow this sequence: -1. What systems do we have? (fleet-inventory) -2. What are they vulnerable to? (cve-impact) -3. How do we fix it? (`/remediation` skill) - -This ensures informed decisions before taking remediation actions. -``` +Start broad then filter; group by environment/RHEL/tier; highlight stale systems; offer `/remediation` transitions; use tables and percentages; declare document consultations; verify prerequisites first. diff --git a/rh-sre/skills/fleet-inventory/references/01-parameter-reference.md b/rh-sre/skills/fleet-inventory/references/01-parameter-reference.md new file mode 100644 index 00000000..6909aa85 --- /dev/null +++ b/rh-sre/skills/fleet-inventory/references/01-parameter-reference.md @@ -0,0 +1,49 @@ +# Fleet Inventory Parameter Reference + +Read when calling `get_host_details` or `get_cve_systems` to ensure correct parameters. + +## get_host_details + +**Parameters** (based on user query): + +```python +# No filters +get_host_details() + +# Specific system +get_host_details(system_id="abc-123") + +# Hostname pattern +get_host_details(hostname_pattern="web-*") + +# Tag filter +get_host_details(tags=["production"]) + +# RHEL version filter +get_host_details(operating_system__version__startswith="8") + +# Combined +get_host_details(tags=["production", "web-tier"], operating_system__version__startswith="8") +``` + +**Response fields**: id, display_name, fqdn, rhel_version, last_seen, tags, stale, satellite_managed + +## get_cve_systems + +**Parameters**: `cve_id` (string, format CVE-YYYY-NNNNN, uppercase) + +```python +get_cve_systems(cve_id="CVE-2024-1234") +``` + +**Response fields**: cve_id, affected_systems (system_id, display_name, status, remediation_available), total_affected, total_remediated, total_vulnerable + +**Status values**: Vulnerable (patch needed), Patched (no action), Not Affected (exclude) + +## Filtering and Sorting + +**By RHEL**: `[s for s in systems if s['rhel_version'].startswith("8")]` +**By tag**: `[s for s in systems if "production" in s.get('tags', [])]` +**By stale**: `[s for s in systems if not s.get('stale', False)]` +**Sort by last_seen**: `sorted(systems, key=lambda s: s['last_seen'], reverse=True)` +**Sort by display_name**: `sorted(systems, key=lambda s: s['display_name'])` diff --git a/rh-sre/skills/fleet-inventory/references/03-output-templates.md b/rh-sre/skills/fleet-inventory/references/03-output-templates.md new file mode 100644 index 00000000..b0337ed8 --- /dev/null +++ b/rh-sre/skills/fleet-inventory/references/03-output-templates.md @@ -0,0 +1,80 @@ +# Fleet Inventory Output Templates + +Read when completing a fleet inventory report to format the output. + +## Template 1: Full Fleet Listing + +**User Request**: "Show the managed fleet" + +```markdown +# Managed Fleet Inventory + +I consulted [fleet-management.md](../../../docs/insights/fleet-management.md) to structure this inventory report. + +Retrieved from Red Hat Lightspeed on YYYY-MM-DDTHH:MM:SSZ + +## Fleet Overview +- **Total Registered Systems**: N +- **Active (< 24h)**: N +- **Stale (> 7 days)**: N + +## RHEL Version Distribution +| Version | Count | Percentage | + +## Environment Breakdown +| Environment | Count | Systems | + +## Top 20 Systems (by last check-in) +[Table: display_name, rhel_version, tags, last_seen] + +**Would you like to**: Filter by environment/RHEL, view CVEs, create remediation plans +``` + +## Template 2: CVE-Affected Systems + +**User Request**: "What systems are affected by CVE-X?" + +```markdown +# CVE-X Impact Analysis + +## Affected Systems Summary +- **Total Vulnerable**: N +- **Already Patched**: N +- **Impact Rate**: X% of fleet + +## Vulnerable Systems +| System Name | RHEL Version | Environment | Remediation Available | + +## Already Patched (No Action Needed) +[list] + +## Next Steps +- Use `/remediation` skill for remediation +- Use cve-impact for severity analysis +``` + +## Template 3: Environment-Filtered View + +**User Request**: "Show me production systems" + +```markdown +# Production Systems Inventory + +Filtered by tag: "production" + +## Production Fleet Summary +- **Total**: N +- **RHEL 9.x / 8.x / 7.x** breakdown +- **Active / Stale** counts + +## System Tiers +### Web Tier, Database Tier, Application Tier +[grouped lists] + +## Stale System Alert โš ๏ธ +[list with action: investigate Lightspeed client] + +## Next Steps +- "Show CVEs affecting production systems" +- "Remediate CVE-X on production web tier" +``` diff --git a/rh-sre/skills/fleet-inventory/references/04-examples.md b/rh-sre/skills/fleet-inventory/references/04-examples.md new file mode 100644 index 00000000..2d08d77a --- /dev/null +++ b/rh-sre/skills/fleet-inventory/references/04-examples.md @@ -0,0 +1,32 @@ +# Fleet Inventory Examples + +## Example 1: General Fleet Query + +**User Request**: "Show the managed fleet" + +1. Invoke mcp-lightspeed-validator (Step 0) โ†’ PASSED +2. Call `get_host_details()` with no filters +3. Consult fleet-management.md for grouping +4. Group by RHEL version, environment tags +5. Generate Template 1 output +6. Offer next steps (CVE analysis, remediation) + +## Example 2: CVE Impact Query + +**User Request**: "What systems are affected by CVE-2024-1234?" + +1. Invoke mcp-lightspeed-validator (Step 0) โ†’ PASSED +2. Call `get_cve_systems(cve_id="CVE-2024-1234")` +3. Separate vulnerable vs. patched systems +4. Generate Template 2 output +5. Suggest /remediation for next steps + +## Example 3: Environment Filter + +**User Request**: "Show me staging systems" + +1. Invoke mcp-lightspeed-validator (Step 0) โ†’ PARTIAL +2. Ask user: "Proceed? (yes/no)" โ†’ yes +3. Call `get_host_details()` โ†’ filter by tag "staging" +4. Group by tier (hostname patterns) +5. Generate Template 3 output diff --git a/rh-sre/skills/fleet-inventory/references/05-error-handling.md b/rh-sre/skills/fleet-inventory/references/05-error-handling.md new file mode 100644 index 00000000..e295f0e6 --- /dev/null +++ b/rh-sre/skills/fleet-inventory/references/05-error-handling.md @@ -0,0 +1,45 @@ +# Fleet Inventory Error Handling + +Read when errors occur during fleet inventory queries. + +## No Systems Found + +``` +Fleet Inventory Query: No Results + +Query: [user's filter criteria] +Result: No systems match the specified criteria + +Possible reasons: No systems registered, filter too restrictive, tag mismatch +Troubleshooting: Verify at console.redhat.com/insights/inventory, try broader filters +Suggested: "Show the managed fleet" (no filters) +``` + +## Lightspeed API Error + +``` +โŒ Fleet Inventory Query: API Error + +Possible causes: MCP not running, auth failure, network, service outage + +Troubleshooting: +1. Run /mcp-lightspeed-validator skill +2. Check LIGHTSPEED_CLIENT_ID and LIGHTSPEED_CLIENT_SECRET (never echo values) +3. Verify at console.redhat.com/settings/service-accounts +4. Check status.redhat.com + +Options: retry | setup | abort +``` + +## Stale System Warning + +``` +โš ๏ธ Stale Systems Detected + +Systems not checked in > 7 days: [list] + +Impact: Vulnerability data may be outdated + +Actions: Verify insights-client, check connectivity, review logs, re-register if needed +Note: Stale systems included but may have outdated CVE data +``` diff --git a/rh-sre/skills/job-template-creator/SKILL.md b/rh-sre/skills/job-template-creator/SKILL.md index b8d6af21..510776ca 100644 --- a/rh-sre/skills/job-template-creator/SKILL.md +++ b/rh-sre/skills/job-template-creator/SKILL.md @@ -111,207 +111,11 @@ Create a job template for this remediation playbook. Playbook: [content]. Filena ### Phase 1: Prepare Playbook in Git Project -**Goal**: Add your remediation playbook to a Git repository that AAP can access. +**Goal**: Add playbook to a Git repository AAP can access. -**Prerequisites**: -- You have a remediation playbook file ready (e.g., `remediation-CVE-2025-49794.yml`) -- Git is installed and configured -- You have access to a Git repository (GitHub, GitLab, Bitbucket, etc.) +**Read [references/01-git-setup.md](references/01-git-setup.md)** for Option A (existing repo) and Option B (new repo). -**Choose your approach**: - -#### Option A: Add to Existing Git Project - -If you already have a Git repository configured in AAP: - -**Step 1: Identify Your Git Repository** - -Ask the user: -``` -โ“ Where is your playbooks Git repository? - -Please provide: -1. Repository URL (e.g., https://github.com/org/playbooks.git) -2. Local path (if already cloned) -3. Or: "I don't have one" (to create new repository) -``` - -**Step 2: Clone or Navigate to Repository** - -If not already cloned: -```bash -# Clone the repository -git clone -cd -``` - -If already cloned: -```bash -cd /path/to/your/playbooks-repo -``` - -**Step 3: Add Playbook to Repository** - -```bash -# Create playbooks directory if it doesn't exist -mkdir -p playbooks/remediation - -# Copy your playbook -cp /path/to/remediation-CVE-2025-49794.yml playbooks/remediation/ - -# Verify the file -ls -l playbooks/remediation/remediation-CVE-2025-49794.yml -``` - -**Step 4: Commit and Push Changes** - -```bash -# Add the playbook -git add playbooks/remediation/remediation-CVE-2025-49794.yml - -# Commit with descriptive message -git commit -m "Add remediation playbook for CVE-2025-49794" - -# Push to remote -git push origin main # or master, depending on your default branch -``` - -**Step 5: Sync AAP Project** - -AAP needs to pull the latest changes from Git: - -**Via AAP Web UI**: -1. Navigate to AAP Web UI -2. Click **Automation Execution** in the left sidebar -3. Click **Projects** -4. Find your project (e.g., "Remediation Playbooks") -5. Click the **Sync** button (๐Ÿ”„ icon) on the project row -6. Wait for status to change to "Successful" -7. Verify playbook appears in the project's playbook list - -**Troubleshooting**: -- If sync fails, check the project's SCM URL and credentials -- View project sync logs by clicking on the project โ†’ **Jobs** tab -- Ensure your Git branch is correct (main/master) - -**Step 6: Verify Playbook Availability** - -Once synced, note the playbook path for template creation: -``` -Playbook path in AAP: playbooks/remediation/remediation-CVE-2025-49794.yml -``` - -#### Option B: Create New Git Repository - -If you don't have an existing repository: - -**Step 1: Create Local Repository** - -```bash -# Create new directory -mkdir ansible-remediation-playbooks -cd ansible-remediation-playbooks - -# Initialize Git -git init - -# Create directory structure -mkdir -p playbooks/remediation -mkdir -p playbooks/roles -mkdir -p inventories - -# Add README -cat > README.md << 'EOF' -# Ansible Remediation Playbooks - -CVE remediation playbooks for Red Hat systems. - -## Structure -- `playbooks/remediation/` - CVE remediation playbooks -- `playbooks/roles/` - Shared Ansible roles -- `inventories/` - Inventory files -EOF - -# Copy your playbook -cp /path/to/remediation-CVE-2025-49794.yml playbooks/remediation/ - -# Create .gitignore -cat > .gitignore << 'EOF' -*.retry -.vault_pass -*.swp -*~ -EOF -``` - -**Step 2: Create Remote Repository** - -On GitHub/GitLab/Bitbucket: -1. Create new repository (e.g., "ansible-remediation-playbooks") -2. Copy the repository URL -3. Do NOT initialize with README (you already have one) - -**Step 3: Commit and Push** - -```bash -# Add all files -git add . - -# Initial commit -git commit -m "Initial commit: Add CVE remediation playbooks structure" - -# Add remote -git remote add origin - -# Push to remote -git branch -M main -git push -u origin main -``` - -**Step 4: Add Project to AAP** - -Via AAP Web UI: -1. Click **Automation Execution** in the left sidebar -2. Click **Projects** -3. Click **Add** button (top right) -4. Fill in the project form: - - **Name**: "Remediation Playbooks" - - **Organization**: Select your organization (typically "Default") - - **Source Control Type**: Git - - **Source Control URL**: `` - - **Source Control Branch/Tag/Commit**: `main` (or your default branch) - - **Source Control Credential**: Select credential (if private repo) -5. Click **Save** -6. AAP will automatically sync the project from Git -7. Wait for project status to show "Successful" (green checkmark) - -**Step 5: Note Playbook Path** - -For template creation: -``` -Playbook path: playbooks/remediation/remediation-CVE-2025-49794.yml -``` - -#### Verification Checklist - -Before proceeding to Phase 2, verify: -- โœ… Playbook committed to Git repository -- โœ… Changes pushed to remote -- โœ… AAP project synced successfully -- โœ… Playbook path noted for template creation -- โœ… Project ID identified (check AAP Web UI or use `projects_list` MCP tool) - -**Report to user**: -``` -โœ“ Playbook prepared in Git project - -Repository: -Playbook path: playbooks/remediation/remediation-CVE-2025-49794.yml -AAP Project: (ID: ) -Status: Ready for job template creation - -Proceeding to Phase 2: Gather Template Configuration... -``` +**Verification**: Playbook committed, pushed, AAP synced, playbook path noted. ### Phase 2: Gather Required Information @@ -397,107 +201,11 @@ Before creating a job template, collect: ### Phase 4: Create Job Template via AAP Web UI -โš ๏ธ **CURRENT LIMITATION**: AAP MCP servers currently provide read-only access to job templates. Template creation must be done through the AAP Web UI. - -#### Step-by-Step Instructions - -**Step 1: Navigate to AAP Web Interface** - -1. Open your browser and go to your AAP Web UI (the main AAP instance URL; this may differ from the MCP endpoint) -2. Log in with your AAP credentials - -**Step 2: Navigate to Templates** - -From the AAP Web UI: -1. Click on **Automation Execution** in the left sidebar -2. Click on **Templates** -3. You'll see the Templates list showing existing job templates - -**Step 3: Create New Job Template** - -1. Click the **Add** button (top right) -2. Select **Job Template** from the dropdown menu +โš ๏ธ **CURRENT LIMITATION**: AAP MCP has no create tools. Template creation must be done via AAP Web UI. -**Step 4: Fill Job Template Form** - -Configure the template with these settings: - -**Basic Information**: -- **Name**: `Remediate CVE-2025-49794` - - Use descriptive name including CVE ID - - Example: "Remediate CVE-YYYY-NNNNN" - -- **Description**: `Auto-generated CVE remediation playbook for CVE-2025-49794` - - Include CVE details and purpose - -- **Job Type**: `Run` - - Use "Run" for actual execution - - Use "Check" for dry-run testing - -**Required Fields**: -- **Inventory**: Select the inventory containing your target hosts - - Example: "Production Inventory" (from Phase 3 Step 2) - -- **Project**: Select the project containing your playbook - - Example: "Remediation Playbooks" (from Phase 3 Step 1) - - Ensure project status is "Successful" (synced) - -- **Playbook**: Select your playbook from the dropdown - - Example: `playbooks/remediation/remediation-CVE-2025-49794.yml` - - Dropdown will show available playbooks from the selected project - -- **Credentials**: Select appropriate credentials - - **Machine Credential** (SSH): For host access - - **Vault Credential** (optional): If playbook uses Ansible Vault - - Click "Select" to choose from existing credentials - -**Optional Fields**: - -- **Limit**: Leave empty (or specify host pattern to limit execution) - - Example: `production-*` to target only production hosts - -- **Verbosity**: `0 (Normal)` (or increase for debugging) - - 0: Normal - - 1: Verbose (-v) - - 2: More Verbose (-vv) - - 3: Debug (-vvv) - -- **Job Tags**: Leave empty (or specify tags from playbook) - -- **Skip Tags**: Leave empty (or specify tags to skip) - -- **Extra Variables**: Add CVE-specific variables - ```yaml - --- - target_cve: "CVE-2025-49794" - remediation_mode: "automated" - verify_after: true - ``` - -**Options** (checkboxes at bottom): -- โœ… **Enable Privilege Escalation**: Yes (required for package updates and system changes) -- โœ… **Prompt on Launch**: Check fields you want to override at launch time: - - โ˜‘๏ธ **Job Type** (REQUIREDโ€”enables dry-run with `check` and actual execution with `run`; job-template-remediation-validator requires this) - - โ˜‘๏ธ **Variables** (recommended for dynamic CVE targeting) - - โ˜‘๏ธ **Limit** (recommended for targeting specific hosts) -- โ˜ **Allow Simultaneous**: No (prevent conflicts during remediation) -- โ˜ **Enable Webhook**: No (unless integrating with CI/CD) - -**Step 5: Save the Template** - -1. Click the **Save** button at the bottom -2. AAP will validate the configuration -3. If validation succeeds, you'll be redirected to the template details page -4. Note the template ID from the URL or template details - -**Step 6: Verify Template Creation** - -Use the AAP MCP to confirm: -``` -job_templates_list(search="CVE-2025-49794") -``` +**Read [references/02-web-ui-form.md](references/02-web-ui-form.md)** for form fields and steps. -Expected result: Template appears in search results with ID +**Required**: Name, Inventory, Project, Playbook, Credentials. Enable Privilege Escalation. Prompt on Launch: Job Type (REQUIRED), Variables, Limit. ### Phase 5: Verify Template Creation @@ -545,170 +253,12 @@ Expected result: Template appears in search results with ID } ``` -**Follow-up**: Use `playbook-executor` skill to track job execution status. +**Follow-up**: Use `playbook-executor` skill to track job execution. -## Output Template +## Output and Examples -When completing job template creation, provide: - -```markdown -# AAP Job Template Created - -## Template Details -**Name**: Remediate CVE-2025-49794 -**ID**: 42 -**Project**: Remediation Playbooks (ID: 6) -**Playbook**: playbooks/remediation/remediation-CVE-2025-49794.yml -**Inventory**: Production Inventory (ID: 1) -**Status**: Ready for execution - -## Verification -โœ“ Template exists in AAP -โœ“ Project contains the playbook -โœ“ Inventory has target hosts -โœ“ Credentials configured - -## Next Steps - -1. **Execute the template**: - - Via AAP Web UI: Automation Execution โ†’ Templates โ†’ Select template โ†’ Launch - - Via MCP: job_templates_launch_retrieve(id="42") - -2. **Monitor execution**: - - Via AAP Web UI: Automation Execution โ†’ Jobs โ†’ View job details - - Via MCP: jobs_retrieve(id=job_id) and jobs_stdout_retrieve(id=job_id) - -3. **Verify remediation**: - - Use `remediation-verifier` skill after execution completes - - Confirm CVE status in Red Hat Insights -``` - -## Examples - -### Example 1: Create Template for CVE Remediation Playbook - -**User Request**: "Create a job template for my CVE-2025-49794 remediation playbook" - -**Skill Response**: - -1. **Check if Playbook is in Git**: - - Ask user: "Is this playbook already in a Git repository configured in AAP?" - - User responds: "No, I just generated it" - -2. **Guide Through Git Setup** (Phase 1): - ``` - I'll help you add the playbook to a Git repository. - - Do you have an existing Git repository for playbooks, or should we create one? - - User: "I have https://github.com/myorg/remediation-playbooks" - - Great! Let's add your playbook: - 1. Clone or navigate to the repository - 2. Add the playbook file - 3. Commit and push changes - 4. Sync the AAP project - - [Provide step-by-step Git commands] - ``` - -3. **Verify Playbook in Git**: - - Confirm playbook pushed to remote - - Note playbook path: `playbooks/remediation/remediation-CVE-2025-49794.yml` - - Confirm AAP project synced - -4. **Gather Template Information** (Phase 2): - - Playbook: `remediation-CVE-2025-49794.yml` - - Ask user: "Which project contains this playbook?" - - Ask user: "Which inventory should be targeted?" - -5. **List Available Projects** (Phase 3): - ``` - projects_list() โ†’ Found "Remediation Playbooks" (ID: 6) - ``` - -6. **List Available Inventories** (Phase 3): - ``` - inventories_list() โ†’ Found "Production Inventory" (ID: 1) - ``` - -7. **Report Limitation** (Phase 4): - ``` - โš ๏ธ AAP MCP doesn't currently support creating templates programmatically. - I'll provide instructions for manual creation. - ``` - -8. **Provide Web UI Instructions** (Phase 4): - ``` - Navigate to AAP Web UI: - 1. Automation Execution โ†’ Templates - 2. Click Add โ†’ Job Template - 3. Fill in the form: - - Name: "Remediate CVE-2025-49794" - - Job Type: Run - - Inventory: Production Inventory - - Project: Remediation Playbooks - - Playbook: playbooks/remediation/remediation-CVE-2025-49794.yml - - Credentials: Select SSH credential - - Options: Enable Privilege Escalation (Yes) - 4. Save - ``` - -9. **Verify After Manual Creation** (Phase 5): - ``` - job_templates_list(search="CVE-2025-49794") โ†’ Template ID: 42 - ``` - -10. **Report Success**: - ``` - โœ“ Template created with ID: 42 - โœ“ Playbook integrated: playbooks/remediation/remediation-CVE-2025-49794.yml - Ready to execute via AAP job launcher - ``` - -### Example 2: Create Template with Custom Variables - -**User Request**: "Set up a template for dynamic CVE remediation with variable CVE ID" - -**Skill Response**: - -1. **Explain Variable Approach**: - ``` - For dynamic CVE targeting, enable "Ask variables on launch" - This allows passing different CVE IDs at execution time - ``` - -2. **Provide Web UI Configuration**: - ``` - In AAP Web UI (Automation Execution โ†’ Templates โ†’ Add โ†’ Job Template): - - Name: "Dynamic CVE Remediation" - Job Type: Run - Inventory: [Select your inventory] - Project: [Select remediation playbooks project] - Playbook: playbooks/remediation/remediation-dynamic.yml - - Options: - โœ… Enable Privilege Escalation: Yes - - Prompt on Launch (check these): - โ˜‘๏ธ Job Type (REQUIREDโ€”enables dry-run and run from same template) - โ˜‘๏ธ Variables (allows passing different CVE IDs at runtime) - โ˜‘๏ธ Limit (allows targeting specific hosts at runtime) - - Extra Variables: - --- - cve_id: "CVE-YYYY-NNNNN" - remediation_mode: "automated" - verify_after: true - ``` - -3. **Explain Launch Usage**: - ``` - When launching this template, you can override variables: - - In Web UI: Launch button โ†’ Prompted for Variables โ†’ Enter custom values - - Via MCP: job_templates_launch_retrieve(id="template_id") with launch-time prompts - ``` +**Read [references/03-output-template.md](references/03-output-template.md)** for report format. +**Read [references/04-examples.md](references/04-examples.md)** for CVE remediation and dynamic variable examples. ## Dependencies @@ -769,40 +319,3 @@ This skill requires user confirmation for: - Wait for confirmation before launching **Never assume approval** - always wait for explicit user confirmation. - -## Future Enhancement: When MCP Tools Become Available - -When `job_templates_create` MCP tool is added, the workflow will become: - -### Step 1: Create Template via MCP - -**MCP Tool**: `job_templates_create` (from aap-mcp-job-management) - **FUTURE** - -**Parameters**: -```json -{ - "name": "Remediate CVE-2025-49794", - "description": "Auto-generated remediation template", - "job_type": "run", - "inventory": 1, - "project": 6, - "playbook": "remediation-CVE-2025-49794.yml", - "become_enabled": true, - "ask_job_type_on_launch": true, - "ask_variables_on_launch": true, - "ask_limit_on_launch": true, - "extra_vars": "{\"target_cve\": \"CVE-2025-49794\"}" -} -``` - -**Expected Output**: -```json -{ - "id": 42, - "name": "Remediate CVE-2025-49794", - "url": "/api/controller/v2/job_templates/42/", - "status": "success" -} -``` - -This will enable fully automated template creation as part of the remediation workflow. diff --git a/rh-sre/skills/job-template-creator/references/01-git-setup.md b/rh-sre/skills/job-template-creator/references/01-git-setup.md new file mode 100644 index 00000000..1a367a2e --- /dev/null +++ b/rh-sre/skills/job-template-creator/references/01-git-setup.md @@ -0,0 +1,25 @@ +# Git Setup for Playbooks + +Read when guiding user through Phase 1 (Prepare Playbook in Git). + +## Option A: Add to Existing Project + +1. Ask: repo URL, local path, or "I don't have one" +2. Clone or `cd` to repo +3. `mkdir -p playbooks/remediation`; copy playbook; `git add`; `git commit`; `git push` +4. Sync AAP project (Automation Execution โ†’ Projects โ†’ Sync) +5. Note playbook path: `playbooks/remediation/remediation-CVE-YYYY-NNNNN.yml` + +## Option B: Create New Repository + +1. `mkdir ansible-remediation-playbooks`; `git init`; `mkdir -p playbooks/remediation` +2. Copy playbook; create README, .gitignore; `git add .`; `git commit` +3. Create remote repo; `git remote add origin `; `git push -u origin main` +4. Add project in AAP Web UI (Automation Execution โ†’ Projects โ†’ Add) +5. Note playbook path + +## Verification Checklist + +- Playbook committed and pushed +- AAP project synced +- Playbook path noted for template creation diff --git a/rh-sre/skills/job-template-creator/references/02-web-ui-form.md b/rh-sre/skills/job-template-creator/references/02-web-ui-form.md new file mode 100644 index 00000000..690d63ec --- /dev/null +++ b/rh-sre/skills/job-template-creator/references/02-web-ui-form.md @@ -0,0 +1,24 @@ +# AAP Web UI Job Template Form + +Read when guiding Phase 4 (Create Template via Web UI). AAP MCP has no create toolsโ€”use Web UI. + +## Form Fields + +**Required**: Name, Inventory, Project, Playbook, Credentials (Machine/SSH) +**Job Type**: Run (or Check for dry-run) +**Options**: Enable Privilege Escalation: Yes +**Prompt on Launch** (check): Job Type (REQUIRED), Variables, Limit + +**Extra Variables** (optional): +```yaml +target_cve: "CVE-YYYY-NNNNN" +remediation_mode: "automated" +verify_after: true +``` + +## Steps + +1. Automation Execution โ†’ Templates โ†’ Add โ†’ Job Template +2. Fill form; Save +3. Note template ID from URL or details +4. Verify via `job_templates_list(search="CVE-ID")` diff --git a/rh-sre/skills/job-template-creator/references/03-output-template.md b/rh-sre/skills/job-template-creator/references/03-output-template.md new file mode 100644 index 00000000..496d2c45 --- /dev/null +++ b/rh-sre/skills/job-template-creator/references/03-output-template.md @@ -0,0 +1,20 @@ +# Job Template Creation Output + +Read when completing template creation. + +## Report Format + +```markdown +# AAP Job Template Created + +**Name**: Remediate CVE-YYYY-NNNNN +**ID**: [template_id] +**Project**: [name] (ID: [id]) +**Playbook**: playbooks/remediation/remediation-CVE-YYYY-NNNNN.yml +**Inventory**: [name] (ID: [id]) + +## Next Steps +1. Execute via AAP Web UI or job_templates_launch_retrieve +2. Monitor via jobs_retrieve, jobs_stdout_retrieve +3. Verify via remediation-verifier skill +``` diff --git a/rh-sre/skills/job-template-creator/references/04-examples.md b/rh-sre/skills/job-template-creator/references/04-examples.md new file mode 100644 index 00000000..d19c66c6 --- /dev/null +++ b/rh-sre/skills/job-template-creator/references/04-examples.md @@ -0,0 +1,19 @@ +# Job Template Creator Examples + +Read when handling specific request types. + +## Example 1: CVE Remediation Template + +**Request**: "Create a job template for CVE-2025-49794 playbook" +- Phase 1: Git setup (see 01-git-setup.md)โ€”add playbook, commit, push, sync AAP +- Phase 2: Gather playbook path, project, inventory +- Phase 3: projects_list, inventories_list +- Phase 4: Web UI instructions (see 02-web-ui-form.md) +- Phase 5: job_templates_list to verify + +## Example 2: Dynamic CVE Template + +**Request**: "Template with variable CVE ID" +- Enable "Prompt on Launch" โ†’ Variables +- Extra vars: cve_id, remediation_mode, verify_after +- Override at launch for different CVEs diff --git a/rh-sre/skills/playbook-executor/SKILL.md b/rh-sre/skills/playbook-executor/SKILL.md index 717f385d..a29c9443 100644 --- a/rh-sre/skills/playbook-executor/SKILL.md +++ b/rh-sre/skills/playbook-executor/SKILL.md @@ -1,15 +1,11 @@ --- name: playbook-executor description: | - **CRITICAL**: This skill must be used for Ansible playbook execution via AAP. DO NOT use raw MCP tools directly. + **CRITICAL**: Use for Ansible playbook execution via AAP. DO NOT call AAP MCP tools directly. - Execute Ansible remediation playbooks through AAP (Ansible Automation Platform) with comprehensive job management, dry-run capabilities, and detailed reporting. Use this skill after generating a playbook to execute it on production systems with proper validation and monitoring. + Execute remediation playbooks with job management, dry-run, and reporting. Use after playbook-generator. - This skill orchestrates AAP MCP tools (job_templates_launch_retrieve, jobs_retrieve, jobs_stdout_retrieve, jobs_job_events_list, jobs_job_host_summaries_list) to provide production-grade playbook execution with dry-run testing, real-time progress monitoring, and comprehensive reporting. - - **IMPORTANT**: ALWAYS use this skill instead of calling AAP MCP tools directly. - - **Git Flow**: When the template's playbook path differs from the generated playbook, you MUST perform Git Flow (commit, push, sync) BEFORE launching any job. Do NOT launch without updating the playbook in the repo firstโ€”AAP executes from synced content. + **Git Flow**: If template playbook path โ‰  generated playbook, perform Git Flow (commit, push, sync) BEFORE launch. --- # AAP Playbook Executor Skill diff --git a/rh-sre/skills/remediation/SKILL.md b/rh-sre/skills/remediation/SKILL.md index 2be93af3..49dcb23f 100644 --- a/rh-sre/skills/remediation/SKILL.md +++ b/rh-sre/skills/remediation/SKILL.md @@ -67,6 +67,8 @@ Execute skills in this order. **MANDATORY**: Use actual Skill tool invocations, **Action**: Present the planned task list using **Part A** of [references/01-remediation-plan-template.md](references/01-remediation-plan-template.md). Show the 7 tasks (validate MCP โ†’ impact โ†’ validate CVE โ†’ context โ†’ playbook โ†’ execute โ†’ verify) and ask "Proceed with this plan?" +**Task list ordering** (CRITICAL): If using TodoWrite or task list UI, create tasks **in workflow order** (Step 0, 1, 2, 3, 4, 5, 6). Do NOT create in completion order or random orderโ€”display order must match execution order. + **Wait for explicit user response** ("yes" or "proceed") before invoking Step 0. If "abort" โ†’ stop. ### Step 0: Validate MCP Prerequisites diff --git a/rh-sre/skills/remediation/references/01-remediation-plan-template.md b/rh-sre/skills/remediation/references/01-remediation-plan-template.md index c1080e90..343d4359 100644 --- a/rh-sre/skills/remediation/references/01-remediation-plan-template.md +++ b/rh-sre/skills/remediation/references/01-remediation-plan-template.md @@ -12,7 +12,7 @@ Read this reference when presenting plans for user validation. ``` ## Remediation: CVE-XXXX-YYYY -**Planned tasks** (in order): +**Planned tasks** (in orderโ€”use this exact order for TodoWrite/task lists; display order must match execution order): 1. Validate MCP (Lightspeed, AAP) 2. Impact analysis (assess CVE risk) 3. CVE validation (remediatable gate) diff --git a/rh-sre/skills/system-context/SKILL.md b/rh-sre/skills/system-context/SKILL.md index e9181433..704ead67 100644 --- a/rh-sre/skills/system-context/SKILL.md +++ b/rh-sre/skills/system-context/SKILL.md @@ -486,16 +486,3 @@ To improve system classification: 6. **Consider batch size** - Balance speed vs risk (5-10 systems per batch recommended) 7. **Plan for rollback** - Always have a backup strategy (snapshots, maintenance windows) 8. **Use pagination for large fleets** - If get_cve_systems returns 100+ systems, use limit/offset parameters - -## Integration with Other Skills - -- **cve-impact**: Provides CVE severity to inform criticality assessment -- **playbook-generator**: Consumes context to generate appropriate remediation playbook -- **remediation-verifier**: Uses system context to verify remediation on correct systems - -**Orchestration Example** (from `/remediation` skill): -1. Agent invokes cve-impact โ†’ Gets risk level -2. Agent invokes system-context skill โ†’ Gets deployment architecture -3. Agent determines strategy: "Staging-first deployment recommended" -4. Agent invokes playbook-generator with environment context โ†’ Gets environment-aware playbook -5. Agent provides execution guidance โ†’ User deploys safely From fb33234688e2cdafbf54c178ed2b16a14ab43d40 Mon Sep 17 00:00:00 2001 From: Daniele Martinoli Date: Mon, 2 Mar 2026 21:50:40 +0100 Subject: [PATCH 13/20] fix(linter): Update collection extraction logic in run-skill-linter.sh to handle user-passed paths correctly Signed-off-by: Daniele Martinoli --- scripts/run-skill-linter.sh | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/scripts/run-skill-linter.sh b/scripts/run-skill-linter.sh index a9742c37..11a49f35 100755 --- a/scripts/run-skill-linter.sh +++ b/scripts/run-skill-linter.sh @@ -75,7 +75,8 @@ echo "" while IFS= read -r skill_file; do skill_dir=$(dirname "$skill_file") skill_name=$(basename "$skill_dir") - collection=$(echo "$skill_dir" | cut -d'/' -f2) + # Pack name is first path component (strip leading ./ for user-passed paths) + collection=$(echo "$skill_dir" | sed 's|^\./||' | cut -d'/' -f1) # Run linter and capture output LINTER_OUTPUT=$(mktemp) From a113f48fce662e1ad97758de9e110b536a0dc2ba Mon Sep 17 00:00:00 2001 From: Daniele Martinoli Date: Mon, 2 Mar 2026 22:02:01 +0100 Subject: [PATCH 14/20] chore(gitattributes): Add .gitattributes to enforce LF line endings for text files Signed-off-by: Daniele Martinoli --- .gitattributes | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 .gitattributes diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..ac8802e0 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,6 @@ +# Enforce LF line endings for text files (prevents CRLF issues in CI) +* text=auto eol=lf +*.md text eol=lf +*.sh text eol=lf +*.yml text eol=lf +*.yaml text eol=lf From e27e232575a5b20cb71eef4f63c63b1b0717ebc5 Mon Sep 17 00:00:00 2001 From: Daniele Martinoli Date: Mon, 2 Mar 2026 22:08:26 +0100 Subject: [PATCH 15/20] fix(linter): Improve frontmatter delimiter checks and ASCII art detection in validate-skill.sh - Updated frontmatter opening and closing delimiter checks to avoid broken pipe issues. - Enhanced ASCII art detection logic to ensure proper handling of input without early exits. - Refined persona statement detection to improve linting accuracy. Signed-off-by: Daniele Martinoli --- .../skill-linter/scripts/validate-skill.sh | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/.claude/skills/skill-linter/scripts/validate-skill.sh b/.claude/skills/skill-linter/scripts/validate-skill.sh index 4822eb11..34f014a4 100755 --- a/.claude/skills/skill-linter/scripts/validate-skill.sh +++ b/.claude/skills/skill-linter/scripts/validate-skill.sh @@ -61,14 +61,15 @@ pass "SKILL.md exists" # 3. Extract frontmatter CONTENT=$(cat "$SKILL_FILE") -# Check for frontmatter delimiters -if ! echo "$CONTENT" | head -1 | grep -q '^---$'; then +# Check for frontmatter delimiters (read from file to avoid broken pipe with set -o pipefail) +FIRST_LINE=$(head -1 "$SKILL_FILE") +if [ "$FIRST_LINE" != "---" ]; then fail "Missing frontmatter opening delimiter (---)" exit 2 fi -# Find closing delimiter (skip first line) -CLOSING_LINE=$(echo "$CONTENT" | tail -n +2 | grep -n '^---$' | head -1 | cut -d: -f1) +# Find closing delimiter (skip first line) - use awk to avoid broken pipe (head -1 exits early) +CLOSING_LINE=$(awk 'NR>1 && /^---$/{print NR-1; exit}' "$SKILL_FILE") if [ -z "$CLOSING_LINE" ]; then fail "Missing frontmatter closing delimiter (---)" exit 2 @@ -172,7 +173,7 @@ if [ -n "$TOOLS" ]; then fi # FAIL if YAML multi-line array detected (allowed-tools:\n - item) if echo "$FRONTMATTER" | grep -q '^allowed-tools:$'; then - NEXT_LINE=$(echo "$FRONTMATTER" | grep -A1 '^allowed-tools:$' | tail -1) + NEXT_LINE=$(echo "$FRONTMATTER" | grep -A1 '^allowed-tools:$' | sed -n '2p') if echo "$NEXT_LINE" | grep -qE '^[[:space:]]*-[[:space:]]'; then fail "allowed-tools must be space-delimited, not YAML array" fi @@ -215,15 +216,15 @@ fi # 10. Content analysis - strip fenced code blocks for checks that need prose-only content CONTENT_NO_FENCES=$(awk '/^```/{skip=!skip; next} !skip{print}' "$SKILL_FILE") -# 10a. Check for ASCII art outside fenced code blocks (WARN) -if echo "$CONTENT_NO_FENCES" | grep -qE '[โ”€โ”‚โ”Œโ”โ””โ”˜โ”œโ”คโ”ฌโ”ดโ”ผโ•ญโ•ฎโ•ฏโ•ฐโ•โ•‘โ•”โ•—โ•šโ•โ• โ•ฃโ•ฆโ•ฉโ•ฌโ†‘โ†“โ†โ†’โ†”โ‡’โ‡โ‡”โ–ฒโ–ผโ—„โ–บ]{3,}'; then +# 10a. Check for ASCII art outside fenced code blocks (WARN) - grep (no -q) reads full input to avoid broken pipe +if grep -E '[โ”€โ”‚โ”Œโ”โ””โ”˜โ”œโ”คโ”ฌโ”ดโ”ผโ•ญโ•ฎโ•ฏโ•ฐโ•โ•‘โ•”โ•—โ•šโ•โ• โ•ฃโ•ฆโ•ฉโ•ฌโ†‘โ†“โ†โ†’โ†”โ‡’โ‡โ‡”โ–ฒโ–ผโ—„โ–บ]{3,}' <<< "$CONTENT_NO_FENCES" > /dev/null; then warn "ASCII art detected outside code blocks - use plain lists or tables" else pass "No ASCII art outside code blocks" fi # 10b. Check for persona statements outside fenced code blocks (FAIL) -if echo "$CONTENT_NO_FENCES" | grep -qiE '^[[:space:]]*You are (a|an|the) '; then +if grep -iE '^[[:space:]]*You are (a|an|the) ' <<< "$CONTENT_NO_FENCES" > /dev/null; then fail "Persona statement detected ('You are a/an/the...') - use Audience/Goal framing" else pass "No persona statements" From 7bc310f8389273b2a94d586ceeccc56b89a0c1e1 Mon Sep 17 00:00:00 2001 From: Daniele Martinoli <86618610+dmartinol@users.noreply.github.com> Date: Mon, 2 Mar 2026 22:11:18 +0100 Subject: [PATCH 16/20] Update docs/app.js Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/app.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/app.js b/docs/app.js index f6a5061b..3467c043 100644 --- a/docs/app.js +++ b/docs/app.js @@ -452,7 +452,7 @@ function showPackDetails(packName) { titleGroup.className = 'modal-title-group'; const h2 = document.createElement('h2'); - h2.textContent = pack.plugin.title || pack.plugin.name || pack.name; + h2.textContent = pack.plugin?.title || pack.plugin?.name || pack.name; titleGroup.appendChild(h2); // Owner subtitle From b022cb87fb9603f40374345c9ddac7ccd2e450fa Mon Sep 17 00:00:00 2001 From: Daniele Martinoli <86618610+dmartinol@users.noreply.github.com> Date: Mon, 2 Mar 2026 22:11:34 +0100 Subject: [PATCH 17/20] Update rh-sre/docs/testing/aap-integration-test-guide.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- rh-sre/docs/testing/aap-integration-test-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rh-sre/docs/testing/aap-integration-test-guide.md b/rh-sre/docs/testing/aap-integration-test-guide.md index e92ba8c6..19b1334a 100644 --- a/rh-sre/docs/testing/aap-integration-test-guide.md +++ b/rh-sre/docs/testing/aap-integration-test-guide.md @@ -8,7 +8,7 @@ tags: [testing, aap-integration, workflow-verification, remediation-testing] semantic_keywords: [aap integration testing, workflow verification, remediation test] use_cases: [remediation, playbook-executor] related_docs: [aap-job-execution.md, playbook-integration-aap.md] -last_updated: 2024-01-20 +last_updated: 2026-02-24 --- # AAP Integration Test Guide From 6320156f6ca0d40592eeac39723bb14298df6e68 Mon Sep 17 00:00:00 2001 From: Daniele Martinoli Date: Mon, 2 Mar 2026 22:29:20 +0100 Subject: [PATCH 18/20] Update documentation dates to reflect the latest access and validation timestamps across multiple files, ensuring all references are current as of 2026-02-24. Signed-off-by: Daniele Martinoli --- rh-sre/docs/INDEX.md | 6 +++--- rh-sre/docs/ansible/aap-job-execution.md | 6 +++--- rh-sre/docs/ansible/cve-remediation-templates.md | 12 ++++++------ rh-sre/docs/ansible/playbook-integration-aap.md | 6 +++--- rh-sre/docs/testing/aap-integration-test-guide.md | 2 +- .../job-template-remediation-validator/SKILL.md | 6 +++--- .../references/01-execution-report-templates.md | 8 ++++---- .../references/02-error-handling-guide.md | 4 ++-- 8 files changed, 25 insertions(+), 25 deletions(-) diff --git a/rh-sre/docs/INDEX.md b/rh-sre/docs/INDEX.md index 8132e300..4fa6725f 100644 --- a/rh-sre/docs/INDEX.md +++ b/rh-sre/docs/INDEX.md @@ -5,8 +5,8 @@ sources: - title: Red Hat Product Documentation url: https://docs.redhat.com sections: RHEL, OpenShift, Ansible Automation Platform, Red Hat Lightspeed - date_accessed: 2026-01-20 -last_updated: 2026-01-20 + date_accessed: 2026-02-24 +last_updated: 2026-02-24 --- # Red Hat Remediation Agent - Documentation Index @@ -288,7 +288,7 @@ See [SOURCES.md](SOURCES.md) for complete source attribution table including: **License**: Content derived from Red Hat documentation licensed under CC BY-SA 4.0 or similar. All credit to Red Hat, Inc. -**Verification**: All sources verified active and current as of 2026-01-20. +**Verification**: All sources verified active and current as of 2026-02-24. ## AI Inference Optimization diff --git a/rh-sre/docs/ansible/aap-job-execution.md b/rh-sre/docs/ansible/aap-job-execution.md index 482162ef..386fd114 100644 --- a/rh-sre/docs/ansible/aap-job-execution.md +++ b/rh-sre/docs/ansible/aap-job-execution.md @@ -4,15 +4,15 @@ category: ansible sources: - title: Red Hat Ansible Automation Platform Documentation url: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6 - date_accessed: 2024-01-20 + date_accessed: 2026-02-24 - title: AAP Job Templates url: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/using_automation_execution/controller-job-templates - date_accessed: 2024-01-20 + date_accessed: 2026-02-24 tags: [aap, job-execution, playbook, dry-run, check-mode] semantic_keywords: [aap job execution, ansible check mode, dry-run remediation, job template requirements, aap url structure] use_cases: [playbook-executor, remediation] related_docs: [playbook-integration-aap.md, cve-remediation-templates.md] -last_updated: 2024-01-20 +last_updated: 2026-02-24 --- # AAP Job Execution Guide diff --git a/rh-sre/docs/ansible/cve-remediation-templates.md b/rh-sre/docs/ansible/cve-remediation-templates.md index 7ea11e3f..d612b2f6 100644 --- a/rh-sre/docs/ansible/cve-remediation-templates.md +++ b/rh-sre/docs/ansible/cve-remediation-templates.md @@ -5,15 +5,15 @@ sources: - title: Red Hat Lightspeed Remediations Guide url: https://docs.redhat.com/en/documentation/red_hat_lightspeed/1-latest/html-single/red_hat_lightspeed_remediations_guide/index sections: Creating remediation plans, playbook generation - date_accessed: 2026-01-20 + date_accessed: 2026-02-24 - title: Creating and Managing Remediation Plans url: https://docs.redhat.com/en/documentation/red_hat_lightspeed/1-latest/html-single/red_hat_lightspeed_remediations_guide/index#creating-remediation-plans_red-hat-lightspeed-remediation-guide sections: Playbook templates, execution patterns - date_accessed: 2026-01-20 + date_accessed: 2026-02-24 - title: Creating Remediation Playbooks (RHEL 7 Security Guide) url: https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/7/html/security_guide/creating-a-remediation-ansible-playbook-to-align-the-system-with-baseline_scanning-the-system-for-configuration-compliance-and-vulnerabilities sections: Ansible playbook patterns for security compliance - date_accessed: 2026-01-20 + date_accessed: 2026-02-24 tags: [cve, remediation, playbooks, ansible, templates, package-update, kernel, service-restart, selinux, batch] applies_to: [rhel7, rhel8, rhel9, openshift4.x] semantic_keywords: @@ -38,7 +38,7 @@ related_docs: - "rhel/package-management.md" - "ansible/error-handling.md" - "rhel/version-compatibility.md" -last_updated: 2026-01-20 +last_updated: 2026-02-24 --- # CVE Remediation Playbook Templates @@ -1463,7 +1463,7 @@ This document is derived from: https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/7/html/security_guide/creating-a-remediation-ansible-playbook-to-align-the-system-with-baseline_scanning-the-system-for-configuration-compliance-and-vulnerabilities **License**: Content derived from Red Hat documentation under CC BY-SA 4.0 -**Last Verified**: 2026-01-20 +**Last Verified**: 2026-02-24 --- @@ -1495,6 +1495,6 @@ Is CVE affecting kernel? --- **Document Version**: 1.0 -**Last Updated**: 2026-01-20 +**Last Updated**: 2026-02-24 **Maintained By**: Remediation Agent Knowledge Base **Official Sources**: See SOURCES.md for complete attribution diff --git a/rh-sre/docs/ansible/playbook-integration-aap.md b/rh-sre/docs/ansible/playbook-integration-aap.md index 8e27b44b..806841f5 100644 --- a/rh-sre/docs/ansible/playbook-integration-aap.md +++ b/rh-sre/docs/ansible/playbook-integration-aap.md @@ -4,15 +4,15 @@ category: ansible sources: - title: Red Hat Ansible Automation Platform Documentation url: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6 - date_accessed: 2024-01-20 + date_accessed: 2026-02-24 - title: AAP Projects url: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/using_automation_execution/controller-projects - date_accessed: 2024-01-20 + date_accessed: 2026-02-24 tags: [aap, playbooks, git-integration, project-sync, version-control] semantic_keywords: [aap project integration, playbook git workflow, project sync process, playbook versioning] use_cases: [playbook-executor, job-template-creator] related_docs: [aap-job-execution.md, cve-remediation-templates.md] -last_updated: 2024-01-20 +last_updated: 2026-02-24 --- # Playbook Integration with AAP diff --git a/rh-sre/docs/testing/aap-integration-test-guide.md b/rh-sre/docs/testing/aap-integration-test-guide.md index 19b1334a..6c122770 100644 --- a/rh-sre/docs/testing/aap-integration-test-guide.md +++ b/rh-sre/docs/testing/aap-integration-test-guide.md @@ -3,7 +3,7 @@ title: AAP Integration Test Guide category: testing sources: - title: Internal Testing Documentation - date_accessed: 2024-01-20 + date_accessed: 2026-02-24 tags: [testing, aap-integration, workflow-verification, remediation-testing] semantic_keywords: [aap integration testing, workflow verification, remediation test] use_cases: [remediation, playbook-executor] diff --git a/rh-sre/skills/job-template-remediation-validator/SKILL.md b/rh-sre/skills/job-template-remediation-validator/SKILL.md index 61cb745a..c86141d4 100644 --- a/rh-sre/skills/job-template-remediation-validator/SKILL.md +++ b/rh-sre/skills/job-template-remediation-validator/SKILL.md @@ -298,7 +298,7 @@ recommended_checks.append(("Ask Inventory on Launch", template.get("ask_inventor # Job Template Remediation Validation Report **Template**: CVE Remediation Template (ID: 42) -**Validated**: 2025-02-25 +**Validated**: 2026-02-24 ## Required Checks | Requirement | Status | Details | @@ -332,7 +332,7 @@ Template is ready for remediation playbook execution. # Job Template Remediation Validation Report **Template**: CVE Remediation (ID: 20) -**Validated**: 2025-02-25 +**Validated**: 2026-02-24 ## Required Checks | Requirement | Status | Details | @@ -363,7 +363,7 @@ To fix: AAP Web UI โ†’ Templates โ†’ [Template] โ†’ Edit โ†’ Options โ†’ โœ“ Pro # Job Template Remediation Validation Report **Template**: General Playbook Runner (ID: 15) -**Validated**: 2025-02-25 +**Validated**: 2026-02-24 ## Required Checks | Requirement | Status | Details | diff --git a/rh-sre/skills/playbook-executor/references/01-execution-report-templates.md b/rh-sre/skills/playbook-executor/references/01-execution-report-templates.md index 4ac01406..a6773c5f 100644 --- a/rh-sre/skills/playbook-executor/references/01-execution-report-templates.md +++ b/rh-sre/skills/playbook-executor/references/01-execution-report-templates.md @@ -11,8 +11,8 @@ Read this reference when generating Phase 5 execution reports or output template "id": 1235, "name": "CVE Remediation Template", "status": "successful", - "started": "2024-01-20T15:35:02Z", - "finished": "2024-01-20T15:40:25Z", + "started": "2026-02-24T15:35:02Z", + "finished": "2026-02-24T15:40:25Z", "elapsed": 323.45, "job_template": 10, "inventory": 1, @@ -60,8 +60,8 @@ Read this reference when generating Phase 5 execution reports or output template **Job ID**: 1235 **Status**: โœ… Successful **Duration**: 5m 23s -**Started**: 2024-01-20 15:35:02 UTC -**Completed**: 2024-01-20 15:40:25 UTC +**Started**: 2026-02-24 15:35:02 UTC +**Completed**: 2026-02-24 15:40:25 UTC **Job Template**: CVE Remediation Template **Playbook**: playbooks/remediation/remediation-CVE-2025-49794.yml **AAP URL**: [View in AAP](https://aap.example.com/#/jobs/playbook/1235) diff --git a/rh-sre/skills/playbook-executor/references/02-error-handling-guide.md b/rh-sre/skills/playbook-executor/references/02-error-handling-guide.md index 6261222f..90492f00 100644 --- a/rh-sre/skills/playbook-executor/references/02-error-handling-guide.md +++ b/rh-sre/skills/playbook-executor/references/02-error-handling-guide.md @@ -22,8 +22,8 @@ Read this reference when generating Phase 6 error reports or troubleshooting. **Job ID**: 1235 **Status**: โŒ Failed **Duration**: 2m 45s -**Started**: 2024-01-20 15:35:02 UTC -**Failed At**: 2024-01-20 15:37:47 UTC +**Started**: 2026-02-24 15:35:02 UTC +**Failed At**: 2026-02-24 15:37:47 UTC **Job Template**: CVE Remediation Template **AAP URL**: [View in AAP](https://aap.example.com/#/jobs/playbook/1235) From ea21371601a6109b20295bdd42e3416436b80b2f Mon Sep 17 00:00:00 2001 From: Daniele Martinoli Date: Mon, 2 Mar 2026 22:33:20 +0100 Subject: [PATCH 19/20] Update README.md to enhance AAP job execution details and clarify MCP server requirements - Revised descriptions for AAP job execution, emphasizing the use of job_templates_launch_retrieve and Git Flow processes. - Updated notes to specify the need for configured AAP MCP servers and pre-created job templates. - Improved clarity in the remediation verifier workflow by renaming steps for better understanding. Signed-off-by: [Your Name] [Your Email] Signed-off-by: Daniele Martinoli --- rh-sre/README.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/rh-sre/README.md b/rh-sre/README.md index f593604e..e3cfb9a6 100644 --- a/rh-sre/README.md +++ b/rh-sre/README.md @@ -254,12 +254,12 @@ Execute Ansible playbooks via AAP (Ansible Automation Platform) with dry-run cap - "Run the playbook and monitor status" **What it does:** -- Saves playbook to `/tmp` directory -- Executes via direct Ansible invocation (not configured by default) +- Launches jobs via AAP MCP (job_templates_launch_retrieve) +- Performs Git Flow (commit, push, sync) when playbook path differs from template - Monitors job status (PENDING โ†’ RUNNING โ†’ COMPLETED) - Reports execution results -**Note**: This skill requires separate configuration (not included by default in this collection). For AAP-based playbook execution, use the `job-template-creator` skill to create job templates in AAP instead. +**Note**: Requires AAP MCP servers configured and job templates created (use `job-template-creator` skill to create templates). ### 8. **remediation-verifier** - Remediation Verification Verify that CVE remediations were successfully applied. @@ -358,8 +358,9 @@ The remediation skill orchestrates 6 specialized skills to provide complete CVE - "Patch these 5 CVEs on all production servers" **Workflow:** +0. **Validate MCP** (mcp-lightspeed-validator, mcp-aap-validator) 1. **Impact** (cve-impact skill, if needed) -2. **Validate** (cve-validation skill) +2. **Validate CVE** (cve-validation skill) 3. **Gather Context** (system-context skill) 4. **Generate Playbook** (playbook-generator skill) 5. **Execute** (playbook-executor skill, with user confirmation) @@ -502,7 +503,7 @@ MCP servers are configured in `.mcp.json`: "args": ["run", "--rm", "-i", "--env", "LIGHTSPEED_CLIENT_ID", "--env", "LIGHTSPEED_CLIENT_SECRET", - "quay.io/redhat-services-prod/lightspeed-mcp:latest"], + "quay.io/redhat-services-prod/insights-management-tenant/insights-mcp/red-hat-lightspeed-mcp:latest"], "env": { "LIGHTSPEED_CLIENT_ID": "${LIGHTSPEED_CLIENT_ID}", "LIGHTSPEED_CLIENT_SECRET": "${LIGHTSPEED_CLIENT_SECRET}" @@ -542,7 +543,7 @@ MCP servers are configured in `.mcp.json`: 3. Test container manually: ```bash podman run --rm -i --env LIGHTSPEED_CLIENT_ID --env LIGHTSPEED_CLIENT_SECRET \ - ghcr.io/redhat/lightspeed-mcp:latest + quay.io/redhat-services-prod/insights-management-tenant/insights-mcp/red-hat-lightspeed-mcp:latest ``` ### Authentication Failures From ed8ff2680a05fd2a9ca2bb9c165a21f471278c2e Mon Sep 17 00:00:00 2001 From: Daniele Martinoli Date: Mon, 2 Mar 2026 22:42:16 +0100 Subject: [PATCH 20/20] Update plugin title in plugins.json to reflect OpenShift Virtualization Signed-off-by: Daniele Martinoli --- docs/plugins.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins.json b/docs/plugins.json index 34c5ebc4..3df20281 100644 --- a/docs/plugins.json +++ b/docs/plugins.json @@ -3,7 +3,7 @@ "title": "Red Hat SRE Agentic Skills Collection" }, "rh-virt": { - "title": "Red Hat Virtualization Agentic Collection" + "title": "Red Hat OpenShift Virtualization Agentic Collection" }, "rh-developer": { "title": "Red Hat Developer Agentic Skills Collection"