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/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" 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 diff --git a/CLAUDE.md b/CLAUDE.md index 5699ac47..cb1f6727 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 @@ -221,7 +210,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 +234,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; agents orchestrate 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..9eb31af7 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. @@ -152,15 +200,21 @@ Skills performing critical operations MUST require explicit confirmation. 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 + - Ask: "Type 'DELETE' to proceed" + - Only proceed on exact match ``` **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/app.js b/docs/app.js index 28c321bf..3467c043 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..3df20281 --- /dev/null +++ b/docs/plugins.json @@ -0,0 +1,17 @@ +{ + "rh-sre": { + "title": "Red Hat SRE Agentic Skills Collection" + }, + "rh-virt": { + "title": "Red Hat OpenShift Virtualization Agentic Collection" + }, + "rh-developer": { + "title": "Red Hat Developer Agentic Skills Collection" + }, + "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..0c57acf1 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": "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/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 51a55346..e3cfb9a6 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,22 +246,22 @@ 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). +### 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:** - "Execute this remediation playbook" - "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). -### 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:** @@ -285,11 +299,11 @@ 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) -### 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,11 +332,25 @@ Create AAP job templates for executing Ansible playbooks through Ansible Automat - Verifies template creation - Prepares for AAP-based playbook execution -## Agent +### 13. **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 + +## 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" @@ -330,11 +358,13 @@ 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) +0. **Validate MCP** (mcp-lightspeed-validator, mcp-aap-validator) +1. **Impact** (cve-impact skill, if needed) +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) +6. **Verify** (remediation-verifier skill) **Capabilities:** - Single CVE on single system @@ -343,7 +373,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 | |--------------|-------------|--------| @@ -353,12 +383,13 @@ 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 | +| "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 @@ -396,7 +427,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 +435,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 @@ -420,7 +451,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 @@ -428,7 +459,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) @@ -441,7 +472,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 @@ -472,20 +503,20 @@ 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}" } }, "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 +527,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 @@ -511,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 @@ -533,7 +565,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 +574,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 @@ -571,9 +603,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 @@ -584,6 +615,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 @@ -593,7 +625,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 @@ -601,7 +633,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 dd84ef0c..00000000 --- a/rh-sre/agents/remediator.md +++ /dev/null @@ -1,315 +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. - -## 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) - -**Invoke the cve-impact skill** using the Skill tool: - -``` -Skill: cve-impact -Args: CVE-ID [system-filter] -``` - -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 - -**Invoke the cve-validation skill** using the Skill tool: - -``` -Skill: cve-validation -Args: CVE-ID -``` - -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 - -**Invoke the system-context skill** using the Skill tool: - -``` -Skill: system-context -Args: CVE-ID [system-filter] -``` - -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 - -**Invoke the playbook-generator skill** using the Skill tool: - -``` -Skill: playbook-generator -Args: CVE-ID system-list [cve-type] [strategy] -``` - -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 and IMMEDIATELY ask for execution confirmation. DO NOT provide manual execution options first - the automated execution via playbook-executor skill is the primary workflow. - -### 5. Execute Playbook (With User Confirmation) - -**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: - -``` -Skill: playbook-executor -Args: playbook-yaml-content CVE-ID -``` - -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 - -**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. - -**Alternative Execution Options** (If user declines automated execution): - -If the user prefers manual execution, provide these options: - -**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` - -**Ansible Automation Platform (AAP)**: -- Import playbook to AAP project repository -- Create job template with inventory and credentials -- Execute via AAP web console - -**Ansible Tower**: -- Similar to AAP workflow for legacy Tower installations - -### 6. Verify Deployment (Optional) - -**Invoke the remediation-verifier skill** using the Skill tool (if user requests verification): - -``` -Skill: remediation-verifier -Args: CVE-ID system-list -``` - -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 - -- **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 -- **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. - -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..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 @@ -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 @@ -281,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 new file mode 100644 index 00000000..386fd114 --- /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: 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: 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: 2026-02-24 +--- + +# 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://{your-aap-instance}/#/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://{your-aap-instance}/#/templates/job_template/{TEMPLATE_ID}/details +``` + +**Example**: +``` +https://aap.example.com/#/templates/job_template/10/details +``` + +### Project URL + +**Format**: +``` +https://{your-aap-instance}/#/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/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 new file mode 100644 index 00000000..806841f5 --- /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: 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: 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: 2026-02-24 +--- + +# 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_MCP_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/references/lightspeed-mcp-parameters.md b/rh-sre/docs/references/lightspeed-mcp-parameters.md new file mode 100644 index 00000000..b1465f4f --- /dev/null +++ b/rh-sre/docs/references/lightspeed-mcp-parameters.md @@ -0,0 +1,89 @@ +--- +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. + +**⚠️ 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. **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?"): +``` +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..f2c661b4 --- /dev/null +++ b/rh-sre/docs/references/lightspeed-mcp-tool-failures.md @@ -0,0 +1,69 @@ +--- +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__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'` + +**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 new file mode 100644 index 00000000..6c122770 --- /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: 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] +related_docs: [aap-job-execution.md, playbook-integration-aap.md] +last_updated: 2026-02-24 +--- + +# 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_MCP_SERVER="https://your-aap-mcp-endpoint.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 (your AAP instance URL) +- [ ] 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_MCP_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 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 +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 remediation skill 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_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 + +### 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/cve-impact/SKILL.md b/rh-sre/skills/cve-impact/SKILL.md index a400f2eb..41a9436b 100644 --- a/rh-sre/skills/cve-impact/SKILL.md +++ b/rh-sre/skills/cve-impact/SKILL.md @@ -1,32 +1,26 @@ --- 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" - - 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 sre-agents:remediator agent) - - "Patch CVE-X on system Y" (use sre-agents:remediator agent) - - "Remediate these CVEs" (use sre-agents:remediator agent) + NOT for remediation (use `/remediation`). - 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. - - **IMPORTANT**: ALWAYS use this skill instead of calling get_cves or other vulnerability MCP tools directly. + System-level: FIRST reply = pagination prompt (Step -1). Parsing: references/01-cve-response-parser.py. --- # 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 +30,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 +38,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 +58,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) +#### CRITICAL: System-Level — HITL FIRST (Before Any Other Action) -**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 +**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". -**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) +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) +``` + +**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) @@ -279,218 +298,46 @@ 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 sre-agents:remediator agent) -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. Call `get_cves(severity=["Critical", "Important"], sort_by="cvss_score", limit=20)` -2. Parse and sort results by CVSS score -3. 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 +Check if automated playbook or manual steps are available. -**Next Steps**: -- Analyze any specific CVE for details: "Analyze CVE-2024-1234" -- 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) - -### Example 1: 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 sre-agents:remediator agent if remediation needed) - -### Example 2: 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 3: 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 +## Output and Examples -## Integration with Remediator Agent - -After completing impact analysis, the skill should: - -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 sre-agents:remediator agent) - ``` - -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. +**Read [references/05-error-handling.md](references/05-error-handling.md)** for CVE not found, no affected systems, and Lightspeed tool failures. -Possible reasons: -- CVE ID is incorrect -- CVE is too recent and not yet in database -- CVE doesn't affect RHEL systems +## Reference Files -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 -``` +| 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) | 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 | -**No affected systems**: -``` -CVE-YYYY-NNNNN Analysis Complete +## Parsing MCP Responses -Good news! No systems in your infrastructure are affected by this CVE. +**REQUIRED**: Use the skill's parser script for all vulnerability response parsing. Do NOT use jq, inline Python, or other ad-hoc JSON parsing. -Possible reasons: -- Your systems are already patched -- Affected packages are not installed -- Systems are running different versions +**Do NOT generate inline Python** to aggregate multiple page files—the parser accepts multiple file paths and produces aggregated reports. -No action required. -``` +**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 @@ -519,6 +366,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 +393,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 +401,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-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 36456d37..fde713b0 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 { @@ -256,197 +283,15 @@ Return structured validation result: } ``` -## 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 remediation_available → true -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 remediation_available → false -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" - -**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 +## Output, Examples, Error Handling -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 -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 @@ -476,41 +321,20 @@ 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`. ## 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 sre-agents:remediator agent - invoked): -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/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/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/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..c39320e5 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 @@ -109,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 @@ -182,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 @@ -225,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 @@ -273,7 +147,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 @@ -286,49 +160,17 @@ 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 -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 +212,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,342 +237,19 @@ 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 ``` **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 sre-agents:remediator agent (invoke the `sre-agents:remediator` agent): -- 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: - - echo $LIGHTSPEED_CLIENT_ID - - echo $LIGHTSPEED_CLIENT_SECRET - - Verify credentials at https://console.redhat.com/settings/service-accounts +## Output, Examples, Error Handling -3. Test connection manually: - podman run --rm -i --env LIGHTSPEED_CLIENT_ID --env LIGHTSPEED_CLIENT_SECRET \ - quay.io/redhat-services-prod/lightspeed-mcp:latest - -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 sre-agents:remediator agent (the `sre-agents:remediator` agent) -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" - ↓ -sre-agents:remediator agent (orchestrates remediation - invoke the `sre-agents:remediator` agent) - ↓ -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" - ↓ -sre-agents:remediator agent (multi-CVE workflow - invoke the `sre-agents:remediator` agent) -``` - -**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? (sre-agents:remediator agent via the `sre-agents:remediator` agent) - -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 f4f64087..510776ca 100644 --- a/rh-sre/skills/job-template-creator/SKILL.md +++ b/rh-sre/skills/job-template-creator/SKILL.md @@ -37,20 +37,16 @@ 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 -**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,23 +73,36 @@ 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) +## 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 -**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 @@ -102,207 +111,11 @@ Use the Skill tool: ### Phase 1: Prepare Playbook in Git Project -**Goal**: Add your remediation playbook to a Git repository that 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.) - -**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 . +**Goal**: Add playbook to a Git repository AAP can access. -# Initial commit -git commit -m "Initial commit: Add CVE remediation playbooks structure" +**Read [references/01-git-setup.md](references/01-git-setup.md)** for Option A (existing repo) and Option B (new repo). -# 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 @@ -388,106 +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: `${AAP_SERVER}` -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 - -**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**: +⚠️ **CURRENT LIMITATION**: AAP MCP has no create tools. Template creation must be done via AAP Web UI. -- **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: - - ☑️ **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 @@ -535,169 +253,12 @@ Expected result: Template appears in search results with ID } ``` -**Follow-up**: Use `playbook-executor` skill to track job execution status. - -## Output Template - -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 +**Follow-up**: Use `playbook-executor` skill to track job execution. -## Next Steps +## Output and Examples -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): - ☑️ 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 @@ -717,6 +278,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 @@ -757,39 +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_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/job-template-remediation-validator/SKILL.md b/rh-sre/skills/job-template-remediation-validator/SKILL.md new file mode 100644 index 00000000..c86141d4 --- /dev/null +++ b/rh-sre/skills/job-template-remediation-validator/SKILL.md @@ -0,0 +1,414 @@ +--- +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 remediation skill 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, 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**: Execute the `/mcp-aap-validator` skill + +**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 | +| **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) + +| 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 | +| **Ask Inventory on Launch** | Enables inventory override at launch | `ask_inventory_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**: Execute the `/mcp-aap-validator` 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)) +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: +- `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)) +recommended_checks.append(("Ask Inventory on Launch", template.get("ask_inventory_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} | +| 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 | +|-------|--------|---------| +| 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. 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 6 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**: 2026-02-24 + +## 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 | +| Ask Inventory on Launch | ✓ | true | + +## Overall Result +✓ PASSED + +Template is ready for remediation playbook execution. +``` + +### 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**: 2026-02-24 + +## 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" + +**Skill Response**: + +``` +# Job Template Remediation Validation Report + +**Template**: General Playbook Runner (ID: 15) +**Validated**: 2026-02-24 + +## 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 4: 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 6f47be1f..a1c4f708 100644 --- a/rh-sre/skills/mcp-aap-validator/SKILL.md +++ b/rh-sre/skills/mcp-aap-validator/SKILL.md @@ -1,507 +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 +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). -**Action**: Check that required environment variables are set (without exposing values) +## Failure Message (Root Causes) -**Required Environment Variables**: -- `AAP_SERVER` - Base URL for AAP instance -- `AAP_API_TOKEN` - Authentication token for AAP API +When a tool call fails, include: -**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_SERVER" -test -n "$AAP_API_TOKEN" - -# Or check and report boolean result -if [ -n "$AAP_SERVER" ]; then - echo "✓ AAP_SERVER is set" -else - echo "✗ AAP_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 ``` +❌ AAP MCP connection failed -**Report to user**: -- ✓ "Environment variable AAP_SERVER is set" -- ✓ "Environment variable AAP_API_TOKEN is set" -- ✗ "Environment variable AAP_SERVER is not set" -- ✗ "Environment variable AAP_API_TOKEN is not set" - -**If missing**: Proceed to Human Notification Protocol (Step 4) - -### Step 3: Test MCP Server Connection - -**Action**: Attempt connectivity test to verify server accessibility - -**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) - - Success: Server responds with valid data - - Failure: Connection timeout, auth error, or server unavailable - -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) - - Success: Server responds with valid data - - Failure: Connection timeout, auth error, or server unavailable +**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 -**Report to user**: -- ✓ "Successfully connected to aap-mcp-job-management" -- ✓ "Successfully connected to aap-mcp-inventory-management" -- ⚠ "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**: -- `401 Unauthorized`: Invalid or expired AAP_API_TOKEN -- `403 Forbidden`: Token lacks required permissions -- `404 Not Found`: Incorrect AAP_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_SERVER}/job_management/mcp", - "headers": { - "Authorization": "Bearer ${AAP_API_TOKEN}" - } - }, - "aap-mcp-inventory-management": { - "url": "https://${AAP_SERVER}/inventory_management/mcp", - "headers": { - "Authorization": "Bearer ${AAP_API_TOKEN}" - } - } - } - } - -🔗 Documentation: See rh-sre/README.md for AAP MCP setup -``` - -For missing environment variables: +**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 ``` -❌ 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_API_TOKEN="your-api-token" +## Report Format -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 +Always end with a table: -⚠️ SECURITY: Never commit tokens to source control - - Use environment variables or secure secret management - - Rotate tokens regularly - - Restrict token permissions to minimum required +| Server | Outcome | +|--------|---------| +| aap-mcp-job-management | ✅ PASSED | +| aap-mcp-inventory-management | ✅ PASSED | -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 server is accessible: - - Check AAP_SERVER URL is correct - - Test connectivity: curl -I ${AAP_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_SERVER}/job_management/mcp - - Inventory Management: ${AAP_SERVER}/inventory_management/mcp - - Verify endpoints are exposed and accessible - -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 - -5. Check AAP service status: - - Verify AAP platform is running - - Check AAP MCP proxy/gateway is operational - - Review AAP logs for errors - -6. Restart to reload MCP servers after configuration changes -``` - -**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 - -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**: -``` -✓ AAP MCP Validation: 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_SERVER is set -✓ Environment variable AAP_API_TOKEN is set -✓ Job management server connectivity verified -✓ Inventory management 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 -``` - -**Partial success case**: -``` -⚠ 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_SERVER` - Base URL for AAP instance (e.g., "https://aap.example.com") -- `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_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_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_API_TOKEN="your-api-token" +- `job_templates_list` (from aap-mcp-job-management) - Connectivity test +- `inventories_list` (from aap-mcp-inventory-management) - Connectivity test -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_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_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..e1f1528e 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` 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). -**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 515d4415..a29c9443 100644 --- a/rh-sre/skills/playbook-executor/SKILL.md +++ b/rh-sre/skills/playbook-executor/SKILL.md @@ -1,464 +1,498 @@ --- 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**: Use for Ansible playbook execution via AAP. DO NOT call AAP 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 remediation playbooks with job management, dry-run, and reporting. Use after playbook-generator. - 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. - - **IMPORTANT**: ALWAYS use this skill instead of calling execute_playbook or get_job_status directly. + **Git Flow**: If template playbook path ≠ generated playbook, perform Git Flow (commit, push, sync) BEFORE launch. --- -# Ansible Playbook Executor Skill +# AAP Playbook Executor Skill + +This skill executes Ansible remediation playbooks through AAP (Ansible Automation Platform) with full job management capabilities. + +**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 + +**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) - 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 +- `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_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 -This skill executes Ansible remediation playbooks and tracks their execution status through the mock Ansible MCP server. +### Prerequisite Validation -**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. +**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**: Execute the `/mcp-aap-validator` skill + +**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_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 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**: +**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 (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 `/remediation` skill invokes this skill after generating a remediation playbook, managing the full workflow from analysis to verification. ## Workflow -### 1. Save Playbook to Temporary Location +**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. -**CRITICAL: Playbooks MUST be saved under /tmp for container access** +### Phase 0: Validate AAP MCP Prerequisites -The ansible-mcp-server runs in a container with `/tmp` mounted to `/playbooks`. All playbooks must be saved to `/tmp` on the host. +**Action**: Execute the `/mcp-aap-validator` skill -```python -import tempfile -import os +**Note**: Can skip if validation was performed earlier in this session and succeeded. -# Create temporary file with .yml extension in /tmp directory -temp_fd, temp_path = tempfile.mkstemp(suffix='.yml', prefix='remediation-', dir='/tmp') +**How to invoke**: Execute the `/mcp-aap-validator` skill -# Write playbook content to file -with os.fdopen(temp_fd, 'w') as f: - f.write(playbook_yaml_content) +**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 -# temp_path now contains the absolute path to the playbook file -# Example: /tmp/remediation-abc123.yml -``` +### Phase 1: Job Template Selection and Playbook Preparation -**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 +**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. -## Critical: Human-in-the-Loop Requirements +**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`). -This skill executes code on production systems. **Explicit user confirmation is REQUIRED** before playbook execution. +**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. -**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 +#### Step 1.1: Derive Playbook Path - This playbook will: - - Execute on: N production systems - - Require reboot: [Yes/No] - - Estimated downtime: X minutes per system - - Affected services: [list] +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` - Playbook file: /tmp/remediation-CVE-YYYY-NNNNN.yml +#### Step 1.2: List Templates and Validate Each Candidate - ❓ Execute this playbook now? +**MCP Tool**: `job_templates_list` (from aap-mcp-job-management) - Options: - - "yes" or "execute" - Proceed with playbook execution - - "review" - Show playbook content again - - "abort" - Cancel execution +**Parameters**: +- `page_size`: 50 (retrieve up to 50 templates) +- `search`: "" (search for all templates) - Please respond with your choice. - ``` -4. **Wait for Explicit Confirmation**: Do not execute without "yes" or "execute" +**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 -**Never assume approval** - always wait for explicit user confirmation before executing playbooks on production systems. +Build two lists: +- **exact_match**: `template.playbook` equals `our_playbook_path` (normalize slashes; match if equal or basenames match) +- **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`) -### 2. Execute Playbook +**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.** -**ONLY after receiving explicit user confirmation**, proceed with execution. +#### Step 1.3: Scenario Selection (MANDATORY - Do Not Skip) -**MCP Tool**: `execute_playbook` (from ansible-mcp-server) +**Scenario 1 - Same playbook path** (exact_match not empty): -**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` +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. -**Path Conversion Logic**: -``` -IMPORTANT: Convert host path to container path before calling execute_playbook +- **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. -Host path: /tmp/remediation-CVE-2024-1234.yml -Container path: /playbooks/remediation-CVE-2024-1234.yml +**Scenario 2 - Different playbook path** (compatible_other not empty, exact_match empty): -Python conversion: -container_path = host_path.replace('/tmp/', '/playbooks/') -``` +**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. -**Expected Output**: -```json -{ - "job_id": "job_12345", - "status": "PENDING", - "playbook_path": "/playbooks/remediation-CVE-2024-1234.yml" -} -``` +- **If yes**: Execute Git Flow. **BLOCK Phase 3** until Git Flow completes and user confirms "sync complete". +- **If no**: Fall through to Scenario 3. -**Verification**: +**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): + +Execute the `/job-template-creator` skill with instruction: ``` -✓ job_id returned (string - used for status tracking) -✓ status = "PENDING" (job queued for execution) -✓ playbook_path uses container path (/playbooks/) +"Create a job template for this remediation playbook. Playbook: [content]. Filename: [filename]. Path: [our_playbook_path]. CVE: [cve_id]. Target systems: [list]." ``` -**Error Handling**: -``` -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/ +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. -If execute_playbook fails: -→ Retry once after verifying file exists -→ If retry fails, report error to user with troubleshooting steps -``` +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. -### 3. Track Job Status +**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. -**MCP Tool**: `get_job_status` (from ansible-mcp-server) +**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 -**Parameters**: -- `job_id`: Job identifier from execute_playbook response - - Example: `"job_12345"` - - Format: String returned from execute_playbook +#### Git Flow (for Scenario 1 Override and Scenario 2) - MANDATORY HITL -**Expected Output** (varies by job status): -```json -// When PENDING -{ - "job_id": "job_12345", - "status": "PENDING", - "started_at": null, - "completed_at": null -} +**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. -// When RUNNING -{ - "job_id": "job_12345", - "status": "RUNNING", - "started_at": "2024-01-20T15:30:02Z", - "completed_at": null -} +**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 -// When COMPLETED -{ - "job_id": "job_12345", - "status": "COMPLETED", - "started_at": "2024-01-20T15:30:02Z", - "completed_at": "2024-01-20T15:30:07Z" -} -``` +**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. -**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) +**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) -Status Transitions: -PENDING → RUNNING → COMPLETED -``` +**Note**: Git must be configured. Use Run tool for git commands. -**Polling Strategy**: -``` -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 -``` +**Do NOT proceed to Phase 3 (Dry-Run) until user confirms sync complete.** -**Status Interpretation**: -``` -Status: PENDING -→ Job queued, not yet started -→ Action: Continue polling +### Phase 2: Git Flow (MANDATORY before Phase 3) -Status: RUNNING -→ Playbook execution in progress -→ Action: Continue polling, update user on progress +**BLOCKING**: You MUST NOT proceed to Phase 3 (Dry-Run) until Git Flow is complete. -Status: COMPLETED -→ Playbook execution finished successfully -→ Action: Stop polling, report success +**When**: Scenario 1 (same path, update content) or Scenario 2 (different path). See Phase 1 Step 1.3. -Status: FAILED (if supported by server) -→ Playbook execution encountered errors -→ Action: Report failure, provide troubleshooting guidance -``` +**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 -**Error Handling**: -``` -If get_job_status returns "Job not found": -→ Error: Invalid job_id or job expired -→ Action: Report error, suggest re-executing playbook +**If any unchecked**: STOP. Do Git Flow. Do NOT launch the job. -If polling timeout (>60 seconds): -→ Warning: Job taking longer than expected -→ Action: Continue polling but warn user -``` +### Phase 3: Dry-Run Execution (Recommended) -### 4. Report Execution Results +**Prerequisite**: Phase 2 (Git Flow) MUST be complete. User must have confirmed "sync complete". -Generate execution summary with job details: +**Goal**: Test playbook in check mode before actual execution to simulate changes. -```markdown -# Playbook Execution Report +**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. -## 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 +#### Step 3.1–3.2: Display Preview and Offer Dry-Run -## Playbook Information -**Playbook Path**: /tmp/remediation-CVE-2024-1234.yml -**CVE**: CVE-2024-1234 -**Target Systems**: 5 systems +Show playbook structure per reference. Offer dry-run with options: yes / no / abort. **ONLY if user confirms**, proceed. -## Execution Timeline -1. T+0s: Job submitted (PENDING) -2. T+2s: Execution started (RUNNING) -3. T+7s: Execution completed (COMPLETED) +#### Step 3.3: Launch Dry-Run Job -## Next Steps -- Verify remediation success using remediation-verifier skill -- Check affected systems are no longer vulnerable -- Update vulnerability tracking system -``` +**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. -### 5. Cleanup Temporary Files +**MCP Tool**: `job_templates_launch_retrieve` (from aap-mcp-job-management) -After job completion, clean up temporary playbook file: +**Parameters**: `id`, `requestBody` with `job_type: "check"`, `extra_vars`, `limit` -```python -import os +**Key**: `job_type: "check"` - Runs Ansible in check mode (dry-run) -# After job completes successfully -if os.path.exists(temp_path): - os.remove(temp_path) - print(f"Cleaned up temporary playbook: {temp_path}") -``` +#### Step 3.4: Monitor Dry-Run Progress -**Cleanup Strategy**: -- Remove temp file after COMPLETED status -- Keep temp file if FAILED status (for debugging) -- Warn user if cleanup fails (not critical) +Poll `jobs_retrieve` every 2 seconds. Use `jobs_job_events_list` for live task updates. -## Output Template +#### Step 3.5: Display Dry-Run Results -When completing playbook execution, provide output in this format: +**MCP Tools**: `jobs_stdout_retrieve` (id, format: "txt"), `jobs_job_host_summaries_list` (id). Use display format from reference. -```markdown -# Ansible Playbook Execution +#### Step 3.6: Proceed to Actual Execution? -## Execution Started -**Playbook**: remediation-CVE-2024-1234.yml -**Job ID**: job_12345 -**Status**: Submitted for execution +Ask per reference. Wait for "yes" or "execute". -Monitoring job status... +### Phase 4: Actual Execution -## Status Updates -- T+0s: PENDING (job queued) -- T+2s: RUNNING (execution started) -- T+7s: COMPLETED (execution finished) +**ONLY execute if user explicitly confirms** (either after dry-run or directly if they skipped dry-run). -## Execution Complete ✓ +#### Step 4.1: Final Confirmation -**Job ID**: job_12345 -**Status**: COMPLETED -**Duration**: 5 seconds -**Started**: 2024-01-20T15:30:02Z -**Completed**: 2024-01-20T15:30:07Z +``` +⚠️ CRITICAL: Playbook Execution Confirmation Required -## 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 +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 -2. Update tracking: - - Mark CVE-2024-1234 as remediated in vulnerability tracker - - Document remediation in change management system +Job Template: CVE Remediation Template (ID: 10) +AAP URL: https://aap.example.com/jobs/ -3. Monitor systems: - - Watch for 24-48 hours for any issues - - Verify Red Hat Lightspeed reflects patched status -``` +❓ Execute this playbook now? -## Examples +Options: +- "yes" or "execute" - Proceed with execution +- "abort" - Cancel execution -### Example 1: Execute Single CVE Remediation +Please respond with your choice. +``` -**User Request**: "Execute the playbook for CVE-2024-1234" +Wait for explicit "yes" or "execute" response. -**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" +#### Step 4.2: Launch Production Job -### Example 2: Track Long-Running Playbook +**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. -**User Request**: "Check status of job_67890" +**MCP Tool**: `job_templates_launch_retrieve` (from aap-mcp-job-management) -**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" +**Parameters**: +```json +{ + "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" + } +} +``` -### Example 3: Handle Job Not Found +**Key Parameter**: `job_type: "run"` - Runs Ansible in execution mode (actual changes) -**User Request**: "Check status of job_99999" +**Expected Output**: +```json +{ + "job": 1235, + "status": "pending", + "url": "/api/controller/v2/jobs/1235/" +} +``` -**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" +#### Step 4.3: Monitor Execution Progress -## Error Handling +**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" -**Playbook File Not Found**: +**Progress Display**: ``` -Execution Failed: Playbook file not found - -Container Path: /playbooks/remediation-CVE-2024-1234.yml -Host Path: /tmp/remediation-CVE-2024-1234.yml - -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 - -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 +⏳ 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) ``` -**Job Execution Timeout**: -``` -Execution Timeout: Job running longer than expected +**Update every 2 seconds** until completion. -Job ID: job_12345 -Status: RUNNING -Duration: 65 seconds (exceeded 60s threshold) +### Phase 5: Execution Report -Action: Continuing to monitor job status -Note: Some playbooks may take longer for large-scale remediations -``` +**Goal**: Generate comprehensive report with job details, per-host results, and full output. -**Job Status Polling Error**: -``` -Status Check Failed: Unable to retrieve job status +**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. -Job ID: job_12345 -Error: Network timeout +#### Step 5.1–5.4: Gather Data -Troubleshooting: -1. Check ansible-mcp-server is running -2. Verify network connectivity -3. Retry status check manually: get_job_status(job_id="job_12345") -``` +**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 + +#### Step 5.5: Generate Report + +Format all gathered data per reference. Use Success / Partial Success / Failure template based on job status. + +#### Step 5.6: Validate Job Log for CVE Handling (MANDATORY) + +**Goal**: Confirm from the job stdout that the playbook actually addressed the target CVE(s). + +**Input**: Target CVE ID(s) from invocation (e.g. CVE-2025-49794). Job stdout from `jobs_stdout_retrieve` (already gathered in Step 5.4). + +**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` + +**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. + +**Read [references/02-error-handling-guide.md](references/02-error-handling-guide.md)** for: Error categories, error report template, troubleshooting steps, relaunch parameters. + +#### Step 6.1: Parse Error Output + +**MCP Tool**: `jobs_stdout_retrieve`. Analyze output for error categories per reference. + +#### Step 6.2: Generate Error Report + +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 relaunch: **MCP Tool** `jobs_relaunch_retrieve` with `hosts: "failed"`, `job_type: "run"` per reference. + +## Reference Files + +| 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 ### 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 +- `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 +- `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-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 -- None required (execution skill) +- [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 + +## Critical: Human-in-the-Loop Requirements + +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**: + ``` + ❓ 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. **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 (invoked) +- **`/remediation` skill**: Orchestrates full workflow including playbook execution -**Orchestration Example** (from sre-agents:remediator agent - invoked): +**Orchestration Example** (from `/remediation` skill): 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 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 - playbook-executor: Confirms execution on production systems is approved 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..a6773c5f --- /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": "2026-02-24T15:35:02Z", + "finished": "2026-02-24T15: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**: 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) + +## 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..90492f00 --- /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**: 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) + +## 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 05cdaa24..a9234cdd 100644 --- a/rh-sre/skills/playbook-generator/SKILL.md +++ b/rh-sre/skills/playbook-generator/SKILL.md @@ -1,230 +1,138 @@ --- 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. + 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 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 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 +**🚨 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 +- Get a remediation playbook from Red Hat Lightspeed (returned unmodified) - Standalone playbook generation without full remediation workflow -**Use the sre-agents:remediator agent when you need**: +**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 `/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**: 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 `/remediation` skill orchestrates this skill after gathering system context +2. This skill generates the optimized playbook +3. The remediation skill then invokes `/playbook-executor` for execution via AAP MCP +4. Finally, `/remediation-verifier` confirms success ## Workflow -### 1. Documentation Consultation - -**CRITICAL**: Document consultation MUST happen BEFORE playbook generation. - -**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) +**🚨 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. -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 +### 1. Playbook Generation (MCP Tool) -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 -``` -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 +❓ Reply with A, B, or C: ``` -### 4. Playbook Generation +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." -**CRITICAL**: Document consultation MUST happen BEFORE tool invocation (see Step 1). +**NEVER** auto-generate a playbook from your knowledge when the tool fails without explicit user confirmation for option B. -**MCP Tool**: `create_vulnerability_playbook` or `remediations__create_vulnerability_playbook` (from lightspeed-mcp) +### 5. Return Playbook AS IS (No Modifications) -**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 +**CRITICAL**: Return the playbook exactly as the MCP tool provides it. Do NOT add, remove, or modify any content. -**Expected Output**: Base Ansible playbook YAML that will be enhanced with patterns from documentation +**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 -### 5. Playbook Enhancement +**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 -Apply Red Hat best practices from documentation to the generated playbook: +### 6. Playbook Validation (Minimal) -**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 -``` +Before returning, verify only: +- YAML is returned (the MCP tool output) +- No modifications were applied -**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 -``` - -**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" -``` - -**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 -``` - -**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) -``` - -### 6. Playbook Validation - -Validate the generated playbook: - -``` -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 @@ -250,12 +158,15 @@ 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 # 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] @@ -275,6 +186,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: @@ -290,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 @@ -305,84 +242,56 @@ 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) -- 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 @@ -425,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 @@ -441,26 +350,18 @@ 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. **🚨 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 @@ -468,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..49dcb23f --- /dev/null +++ b/rh-sre/skills/remediation/SKILL.md @@ -0,0 +1,279 @@ +--- +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?" + +**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 + +**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..343d4359 --- /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—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) +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..704ead67 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 @@ -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 sre-agents:remediator agent - invoked): -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 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..aae0ec9a 100644 --- a/scripts/generate_pack_data.py +++ b/scripts/generate_pack_data.py @@ -41,12 +41,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 @@ -64,6 +90,9 @@ def parse_plugin_json(pack_dir: str) -> Dict[str, Any]: } if not plugin_path.exists(): + # Use title from plugins.json if available + if pack_dir in plugin_titles: + defaults['title'] = plugin_titles[pack_dir] return defaults try: @@ -71,10 +100,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 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'] + + 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 pack_dir in plugin_titles: + defaults['title'] = plugin_titles[pack_dir] return defaults @@ -235,6 +276,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 +292,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 +301,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 +321,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'])}") 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) 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