diff --git a/submissions/mcp-aap-validator/evals/evals.json b/submissions/mcp-aap-validator/evals/evals.json new file mode 100644 index 0000000..c0e67e7 --- /dev/null +++ b/submissions/mcp-aap-validator/evals/evals.json @@ -0,0 +1,17 @@ +{ + "skill_name": "mcp-aap-validator", + "evals": [ + { + "id": "mcp-aap-validator-eval", + "name": "AAP MCP Validation Methodology", + "prompt": "You are a Red Hat SRE about to run a remediation workflow that uses Ansible Automation Platform. First you need to verify AAP connectivity.\n\nDescribe your AAP MCP validation methodology: what servers you test, what tool calls you use for validation, what the common failure modes are, and how you present the results.", + "expected_output": "A validation methodology that tests both AAP MCP servers (job-management and inventory-management), explains that AAP_MCP_SERVER must point to the MCP gateway endpoint (not the UI URL), and presents per-server PASSED/FAILED outcomes in a structured table.", + "assertions": [ + "The output describes testing both AAP MCP servers: job-management (job_templates_list) and inventory-management (inventories_list).", + "The output explains that AAP_MCP_SERVER must point to the MCP gateway endpoint, not the main AAP UI URL, and that 404 errors indicate a wrong URL.", + "The output describes common failure modes including expired tokens (401), insufficient RBAC permissions (403), and wrong URL (404).", + "The output presents validation results in a structured table with per-server PASSED/FAILED/PARTIAL outcomes." + ] + } + ] +} diff --git a/submissions/mcp-aap-validator/metadata.yaml b/submissions/mcp-aap-validator/metadata.yaml new file mode 100644 index 0000000..288fe0c --- /dev/null +++ b/submissions/mcp-aap-validator/metadata.yaml @@ -0,0 +1,5 @@ +name: mcp-aap-validator +description: "Validate AAP (Ansible Automation Platform) MCP server connectivity." +persona: rh-sre +version: "1.0.0" +eval_engine: ase diff --git a/submissions/mcp-aap-validator/skills/SKILL.md b/submissions/mcp-aap-validator/skills/SKILL.md new file mode 100644 index 0000000..08111b0 --- /dev/null +++ b/submissions/mcp-aap-validator/skills/SKILL.md @@ -0,0 +1,75 @@ +--- +name: mcp-aap-validator +description: '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. + + ' +license: Apache-2.0 +--- + +# MCP AAP Validator + +Validates connectivity to AAP MCP servers by running lightweight tool calls. + +## When to Use This Skill + +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 + +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). + +## Failure Message (Root Causes) + +When a tool call fails, include: + +``` +❌ AAP MCP connection failed + +**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 + +**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 +``` + +## Report Format + +Always end with a table: + +| Server | Outcome | +|--------|---------| +| aap-mcp-job-management | ✅ PASSED | +| aap-mcp-inventory-management | ✅ PASSED | + +Use ✅ for success, ❌ for failure, ⚠️ for partial (e.g. one server OK, one failed). + +## Dependencies + +### Required MCP Servers +- `aap-mcp-job-management` - AAP job template and execution +- `aap-mcp-inventory-management` - AAP inventory management + +### Required MCP Tools +- `job_templates_list` (from aap-mcp-job-management) - Connectivity test +- `inventories_list` (from aap-mcp-inventory-management) - Connectivity test + +### Related Skills +- `/playbook-executor` - Requires AAP MCP validation before execution +- `/job-template-creator` - Requires AAP MCP validation before template operations + +### Reference Documentation +- [AAP Integration Test Guide](../../docs/testing/aap-integration-test-guide.md) - AAP MCP setup, env vars, connectivity verification diff --git a/submissions/mcp-aap-validator/skills/references/INDEX.md b/submissions/mcp-aap-validator/skills/references/INDEX.md new file mode 100644 index 0000000..4fa6725 --- /dev/null +++ b/submissions/mcp-aap-validator/skills/references/INDEX.md @@ -0,0 +1,389 @@ +--- +title: Red Hat Remediation Agent - Documentation Index +category: meta +sources: + - title: Red Hat Product Documentation + url: https://docs.redhat.com + sections: RHEL, OpenShift, Ansible Automation Platform, Red Hat Lightspeed + date_accessed: 2026-02-24 +last_updated: 2026-02-24 +--- + +# Red Hat Remediation Agent - Documentation Index + +This knowledge base provides comprehensive Red Hat-specific patterns for CVE remediation on Kubernetes-managed RHEL systems. + +## Quick Navigation + +### Priority P0 (Core Documentation) +- **[CVE Remediation Playbook Templates](ansible/cve-remediation-templates.md)** ⭐ HIGHEST VALUE + - 6 production-ready Ansible playbook templates + - Package updates, kernel updates, service restarts, SELinux, batch remediation + +- **[RHEL Package Management](rhel/package-management.md)** + - DNF/YUM workflows for RHEL 7/8/9 + - Systemd service management + - Reboot detection and handling + +### Priority P1 (Extended Documentation) +- **[Red Hat Lightspeed Vulnerability Logic](insights/vulnerability-logic.md)** ✅ + - CVE risk assessment methodology + - CVSS score interpretation + - System inventory correlation + +- **[CVSS Scoring Reference](references/cvss-scoring.md)** ✅ + - CVSS v3.1 metrics breakdown + - 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 + - Migration considerations + +- **SELinux Context Remediation** (planned) + - SELinux context fixes in playbooks + - `restorecon` patterns + - Policy package updates + +- **Ansible Error Handling** (planned) + - Block/rescue/always patterns + - Rollback strategies + - Idempotency best practices + +- **OpenShift Node Maintenance** (planned) + - Node drain procedures + - Maintenance mode patterns + - Uncordoning after updates + +- **RHEL 9 Security Hardening** (planned) + - RHEL 9 security baseline + - CIS benchmark alignment + - Common hardening patterns + +### Priority P2 (Reference Documentation - Planned) +- **Ansible Playbook Patterns** (planned) + - Reusable playbook components + - Variable management + - Role organization + +- **Ansible Automation Platform Integration** (planned) + - AAP/Tower workflows + - Job template configuration + - Credential management + +- **OpenShift Rolling Updates** (planned) + - Deployment strategies + - StatefulSet handling + - Health check verification + +- **OpenShift Security & Compliance** (planned) + - OCP security best practices + - Compliance scanning + - Security context constraints + +- **Compliance Frameworks** (planned) + - PCI-DSS requirements + - SOC 2 controls + - NIST guidelines + +- **RHEL Systemd Services** (planned) + - Service management patterns + - Service restart logic + - Health checks + +## Documentation Structure + +``` +docs/ +├── INDEX.md (this file) ✅ +├── SOURCES.md (official Red Hat source attribution) ✅ +├── rhel/ # RHEL-specific patterns +│ ├── README.md ✅ +│ ├── package-management.md (P0) ✅ +│ ├── selinux-context.md (P1 - planned) +│ ├── systemd-services.md (P2 - planned) +│ ├── version-compatibility.md (P1 - planned) +│ └── security-hardening-rhel9.md (P1 - planned) +├── ansible/ # Ansible playbook patterns +│ ├── README.md ✅ +│ ├── cve-remediation-templates.md (P0) ⭐ ✅ +│ ├── playbook-patterns.md (P2 - planned) +│ ├── error-handling.md (P1 - planned) +│ ├── idempotency.md (P2 - planned) +│ └── aap-integration.md (P2 - planned) +├── insights/ # Red Hat Lightspeed patterns +│ ├── README.md ✅ +│ ├── vulnerability-logic.md (P1) ✅ +│ ├── remediation-workflow.md (P2 - planned) +│ └── system-inventory.md (P2 - planned) +├── references/ # Reference documentation +│ ├── README.md ✅ +│ ├── cvss-scoring.md (P1) ✅ +│ ├── compliance-frameworks.md (P2 - planned) +│ └── glossary.md (P2 - planned) +└── .ai-index/ # AI inference optimization + ├── semantic-index.json ✅ + ├── task-to-docs-mapping.json ✅ + ├── cross-reference-graph.json ✅ + └── generate-index.py (planned) +``` + +## How to Use This Documentation (For AI Agents) + +### 1. Intelligent Document Discovery + +**Always start by reading the semantic index**: +``` +Read: docs/.ai-index/semantic-index.json (~200 tokens) +``` + +The semantic index enables: +- **Query-based discovery**: Match semantic keywords to your task +- **Task mapping shortcuts**: Pre-computed doc sets for common workflows +- **CVE type inference**: Automatic doc selection based on CVE characteristics +- **System type detection**: Context-aware doc loading (K8s vs bare metal) + +### 2. Task-Based Document Loading + +**Example Workflow - Kernel CVE**: +``` +1. Read semantic-index.json +2. Detect: CVE type = "kernel" (requires reboot) +3. Load from task_mappings["kernel_cve"]: + - ansible/cve-remediation-templates.md (Template 4: Kernel Update) + - rhel/package-management.md (DNF/YUM workflows) +4. Generate playbook using patterns from loaded docs +``` + +**Token Savings**: ~2,500-4,000 tokens (85% reduction in navigation overhead) + +### 3. Progressive Disclosure Pattern + +**Load docs incrementally as needed**: +- **Phase 1 (Validation)**: Load vulnerability-logic.md for risk assessment +- **Phase 2 (Context)**: Load package-management.md for RHEL-specific considerations +- **Phase 3 (Generation)**: Load cve-remediation-templates.md for playbook patterns + +### 4. Cross-Reference Navigation + +Use the cross-reference graph to find related documentation: +``` +If reading: ansible/cve-remediation-templates.md +Also consider: + - rhel/package-management.md (complements: DNF patterns) ✅ + - insights/vulnerability-logic.md (prerequisite: for risk assessment) ✅ +``` + +## Common Remediation Workflows + +### Workflow 1: Simple Package CVE +**Task**: "Remediate CVE-2024-XXXX affecting httpd package on RHEL 8" + +**Required Docs**: +1. `ansible/cve-remediation-templates.md` (Template 1: Package Update) ✅ +2. `rhel/package-management.md` (DNF workflows) ✅ + +### Workflow 2: Kernel CVE +**Task**: "Remediate kernel CVE on RHEL production nodes" + +**Required Docs**: +1. `ansible/cve-remediation-templates.md` (Template 4: Kernel Update) ✅ +2. `rhel/package-management.md` (kernel update procedures) ✅ + +### Workflow 3: Batch Remediation +**Task**: "Remediate 5 CVEs across 20 RHEL servers" + +**Required Docs**: +1. `ansible/cve-remediation-templates.md` (Template 6: Batch) ✅ +2. `rhel/package-management.md` (for RHEL-specific patterns) ✅ + +### Workflow 4: Risk Assessment +**Task**: "Analyze impact of CVE-2024-YYYY" + +**Required Docs**: +1. `insights/vulnerability-logic.md` (Red Hat risk methodology) ✅ +2. `references/cvss-scoring.md` (CVSS interpretation) ✅ + +### Workflow 5: SELinux CVE +**Task**: "Fix SELinux context vulnerability" + +**Required Docs**: +1. `ansible/cve-remediation-templates.md` (Template 5: SELinux) ✅ +2. `rhel/package-management.md` (for RHEL-specific SELinux package handling) ✅ + +## Documentation Quality Standards + +All documents follow these standards: + +### YAML Frontmatter (Required) +```yaml +--- +title: [Document Title] +category: rhel|ansible|openshift|insights|references +sources: + - title: [Official Red Hat Doc Title] + url: [Official URL] + sections: [Relevant sections] + date_accessed: YYYY-MM-DD +tags: [keyword1, keyword2, keyword3] +applies_to: [rhel7, rhel8, rhel9, openshift4.x] +semantic_keywords: [keyword phrases for AI discovery] +use_cases: [use_case_ids for task mapping] +related_docs: [cross-references] +last_updated: YYYY-MM-DD +--- +``` + +### Content Structure (Required) +```markdown +# [Title] + +## Overview +[2-3 sentence summary] + +## When to Use This +[Specific scenarios] + +## [Main Content Sections] +### [Subsection] +**Context**: [When this applies] +**Pattern**: [How to implement] +**Example**: +```yaml +[Code block with working example] +``` +**Pitfalls**: [Common mistakes to avoid] + +## Related Documentation +- [Cross-references to other docs] + +## Quick Reference +[Summary table or bullet points] +``` + +### Code Examples +- **Lead with code**: Show working examples first, explain after +- **Production-ready**: Use real-world patterns (not toy examples) +- **Complete**: Include error handling, logging, verification +- **Tested**: Patterns validated on actual RHEL/OpenShift systems + +## Official Source Attribution + +**All documentation in this knowledge base is derived from official Red Hat sources**. + +See [SOURCES.md](SOURCES.md) for complete source attribution table including: +- Official Red Hat Product Documentation URLs +- Red Hat Customer Portal knowledge base articles +- OpenShift official documentation +- Red Hat Lightspeed documentation +- Red Hat security advisories and bulletins + +**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-02-24. + +## AI Inference Optimization + +This knowledge base includes an AI-optimized indexing layer in `docs/.ai-index/`: + +### Semantic Index (`semantic-index.json`) +- Document metadata with semantic keywords +- Use case mappings for task-based discovery +- RHEL version applicability +- System type applicability (bare metal, VM, K8s, OpenShift) +- Token estimates for each document +- Related docs cross-references + +### Task-to-Docs Mapping (`task-to-docs-mapping.json`) +- Pre-computed doc sets for common remediation workflows +- Required vs optional doc indicators +- Workflow execution order +- Estimated token usage per workflow + +### Cross-Reference Graph (`cross-reference-graph.json`) +- Document relationship graph +- Complement relationships (docs that enhance each other) +- Prerequisite relationships (foundational docs) +- Specialization relationships (conditional docs) +- Confidence scores for relationships + +### Index Generation (`generate-index.py`) +- Auto-generates indexes from YAML frontmatter +- Validates doc structure +- Updates semantic keywords +- Rebuilds cross-reference graph + +## Performance Benefits + +**Token Savings**: +- Simple Package CVE: 21% reduction (~1,000 tokens saved) +- Kernel CVE on K8s: 30% reduction (~1,900 tokens saved) +- Batch Remediation: 31% reduction (~1,800 tokens saved) +- Risk Assessment: 34% reduction (~1,100 tokens saved) +- **Average**: 29% reduction across all task types + +**Response Time**: +- 85% reduction in navigation overhead +- 30-40% faster end-to-end response time +- Fewer Read tool calls (direct doc access) + +**Accuracy**: +- Zero missed related docs (cross-reference graph ensures completeness) +- Zero irrelevant doc reads (semantic matching prevents false positives) +- 85% improvement in doc discovery accuracy + +## Quick Reference Tables + +### RHEL Version Support Matrix +| RHEL Version | Package Manager | Systemd | SELinux | Python | Status | +|--------------|-----------------|---------|---------|--------|--------| +| RHEL 7 | yum | 219 | Enforcing | 2.7 | Supported | +| RHEL 8 | dnf (yum alias) | 239 | Enforcing | 3.6 | Supported | +| RHEL 9 | dnf (yum alias) | 252 | Enforcing | 3.9 | Current | + +### OpenShift Version Support Matrix +| OCP Version | Kubernetes | RHEL CoreOS | Status | +|-------------|------------|-------------|--------| +| 4.7 | 1.20 | 8.x | Legacy | +| 4.8 | 1.21 | 8.x | Supported | +| 4.10 | 1.23 | 8.x | Supported | +| 4.16 | 1.29 | 9.x | Current | + +### CVE Severity Mapping (Red Hat) +| CVSS Score | Red Hat Severity | Priority | Response Time | +|------------|------------------|----------|---------------| +| 9.0-10.0 | Critical | P0 | 24 hours | +| 7.0-8.9 | Important | P1 | 7 days | +| 4.0-6.9 | Moderate | P2 | 30 days | +| 0.1-3.9 | Low | P3 | 90 days | + +## Documentation Maintenance + +### Update Process +1. Update or add markdown documentation +2. Update YAML frontmatter with sources and metadata +3. Run `python docs/.ai-index/generate-index.py` to regenerate indexes +4. Verify source URLs in SOURCES.md are current +5. Update "Last Verified" dates + +### Source Verification Schedule +- **Monthly**: Verify all source URLs are active +- **Quarterly**: Check for updated Red Hat documentation versions +- **Per CVE**: Validate remediation patterns against latest RH advisories + +## Support + +For questions about this documentation: +- Review [SOURCES.md](SOURCES.md) for original Red Hat documentation +- Consult official Red Hat Customer Portal: https://access.redhat.com +- Check Red Hat Product Documentation: https://docs.redhat.com + +**Important**: This is a derivative work for operational use. For authoritative information, always consult official Red Hat documentation at the URLs listed in SOURCES.md. diff --git a/submissions/mcp-aap-validator/skills/references/README.md b/submissions/mcp-aap-validator/skills/references/README.md new file mode 100644 index 0000000..3f8526e --- /dev/null +++ b/submissions/mcp-aap-validator/skills/references/README.md @@ -0,0 +1,40 @@ +--- +title: RHEL Documentation Overview +category: rhel +last_updated: 2026-01-20 +--- + +# RHEL Documentation Overview + +This directory contains Red Hat Enterprise Linux-specific guidance for CVE remediation. + +## Available Documentation + +### Priority P0 (Core) +- **[package-management.md](package-management.md)** - DNF/YUM workflows, reboot detection, service restarts + - RHEL 7/8/9 compatibility + - Package update patterns + - Repository management + - Subscription Manager integration + +### Future Enhancements (P1-P2 Priority) +- **selinux-context.md** - SELinux remediation patterns (planned) +- **security-hardening-rhel9.md** - RHEL 9 security baseline (planned) +- **version-compatibility.md** - RHEL 7/8/9 comparison matrix (planned) +- **systemd-services.md** - Service management patterns (planned) + +## When to Use These Docs + +**Use package-management.md when**: +- Creating playbooks that update packages +- Need to detect if reboot is required (needs-restarting) +- Working across multiple RHEL versions (7/8/9) +- Handling DNF/YUM differences +- Managing service restarts after package updates +- Troubleshooting repository or subscription issues + +## Quick Links + +- Official Red Hat RHEL 9 docs: https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9 +- Package management guide: https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html-single/managing_software_with_the_dnf_tool/index +- Source attribution: [../SOURCES.md](../SOURCES.md) diff --git a/submissions/mcp-aap-validator/skills/references/SOURCES.md b/submissions/mcp-aap-validator/skills/references/SOURCES.md new file mode 100644 index 0000000..0647809 --- /dev/null +++ b/submissions/mcp-aap-validator/skills/references/SOURCES.md @@ -0,0 +1,107 @@ +# Red Hat Documentation Sources + +This document provides attribution for all official Red Hat documentation sources used in the Remediation Agent knowledge base. + +## Source Attribution Table + +| Category | Document Title | Official Source URL | Sections Referenced | Last Verified | +|----------|---------------|---------------------|-------------------|---------------| +| **RHEL Package Management** | Managing Software with the DNF Tool (RHEL 9) | [docs.redhat.com](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html-single/managing_software_with_the_dnf_tool/index) | DNF commands, updating packages, repository management | 2026-01-20 | +| **RHEL Package Management** | Software Management in RHEL 9 Adoption Guide | [docs.redhat.com](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/considerations_in_adopting_rhel_9/assembly_software-management_considerations-in-adopting-rhel-9) | RHEL 7/8/9 compatibility, migration considerations | 2026-01-20 | +| **RHEL Package Management** | RHEL 9 Release Notes | [docs.redhat.com](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html-single/9.4_release_notes/index) | Version-specific package management features | 2026-01-20 | +| **Ansible CVE Remediation** | Red Hat Lightspeed Remediations Guide | [docs.redhat.com](https://docs.redhat.com/en/documentation/red_hat_insights/1-latest/html-single/red_hat_insights_remediations_guide/index) | Creating remediation plans, playbook generation | 2026-01-20 | +| **Ansible CVE Remediation** | Creating and Managing Remediation Plans | [docs.redhat.com](https://docs.redhat.com/en/documentation/red_hat_insights/1-latest/html/red_hat_insights_remediations_guide/creating-managing-playbooks_red-hat-insights-remediation-guide) | Playbook templates, execution patterns | 2026-01-20 | +| **Ansible CVE Remediation** | Automation Controller User Guide (AAP 2.4) | [docs.redhat.com](https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.4/html/automation_controller_user_guide/controller-setting-up-insights) | Setting up Lightspeed for AAP remediations | 2026-01-20 | +| **Ansible CVE Remediation** | Creating Remediation Playbooks (RHEL 7 Security Guide) | [docs.redhat.com](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) | Ansible playbook patterns for security compliance | 2026-01-20 | +| **OpenShift Pod Eviction** | Node Maintenance (OpenShift Virtualization 4.8-4.10) | [docs.redhat.com](https://docs.redhat.com/en/documentation/openshift_container_platform/4.10/html/virtualization/node-maintenance) | Node maintenance operator, draining nodes | 2026-01-20 | +| **OpenShift Pod Eviction** | Evicting Pods Using the Descheduler | [docs.openshift.com](https://docs.openshift.com/en/container-platform/4.8/nodes/scheduling/nodes-descheduler.html) | Pod eviction strategies, descheduler policies | 2026-01-20 | +| **OpenShift Pod Eviction** | How to Handle Evicted Pods in OpenShift | [access.redhat.com](https://access.redhat.com/solutions/3521071) | Troubleshooting evicted pods, remediation steps | 2026-01-20 | +| **OpenShift Pod Eviction** | OpenShift Container Platform 4.16 Nodes | [docs.redhat.com](https://docs.redhat.com/en/documentation/openshift_container_platform/4.16/pdf/nodes/OpenShift_Container_Platform-4.16-Nodes-en-US.pdf) | Node management, pod disruption budgets | 2026-01-20 | +| **Lightspeed CVE Assessment** | Assessing Security Vulnerabilities on RHEL Systems | [docs.redhat.com](https://docs.redhat.com/en/documentation/red_hat_insights/1-latest/html/assessing_and_monitoring_security_vulnerabilities_on_rhel_systems/vuln-cves_vuln-overview) | CVE identification, classification, threat intelligence | 2026-01-20 | +| **Lightspeed CVE Assessment** | Generating Vulnerability Service Reports | [access.redhat.com](https://access.redhat.com/documentation/en-us/red_hat_insights/1-latest/html-single/generating_vulnerability_service_reports/index) | Executive reports, CVE reports, data export | 2026-01-20 | +| **Lightspeed CVE Assessment** | Red Hat CVE Database | [access.redhat.com](https://access.redhat.com/security/security-updates/cve) | Official CVE entries, security updates | 2026-01-20 | +| **Lightspeed CVE Assessment** | A Complete View of System Vulnerabilities | [redhat.com/blog](https://www.redhat.com/en/blog/complete-view-system-vulnerabilities-using-red-hat-insights) | Vulnerability service overview, best practices | 2026-01-20 | +| **CVSS Scoring** | Severity Ratings | [access.redhat.com](https://access.redhat.com/security/updates/classification) | Four-point severity scale, CVSS v3.1 scoring | 2026-01-20 | +| **CVSS Scoring** | How We Classify Security Severity Levels | [access.redhat.com](https://access.redhat.com/solutions/725593) | CVSS metrics interpretation, severity guidelines | 2026-01-20 | +| **CVSS Scoring** | Security Update Policy | [access.redhat.com](https://access.redhat.com/security/lifecycle-security-update-policy) | Security lifecycle, update policies | 2026-01-20 | +| **CVSS Scoring** | Product Security Center | [access.redhat.com](https://access.redhat.com/security/) | Security advisories, bulletins, data feeds | 2026-01-20 | + +## Documentation Categories + +### RHEL (Red Hat Enterprise Linux) +- **Primary Source**: Red Hat Product Documentation (docs.redhat.com) +- **Focus**: Package management (DNF/YUM), systemd, SELinux, security hardening +- **Versions Covered**: RHEL 7, 8, 9 +- **Update Frequency**: Continuous (latest release notes include 2026 updates) + +### Ansible Automation Platform +- **Primary Source**: Red Hat Lightspeed Documentation + Ansible Automation Platform Documentation +- **Focus**: CVE remediation playbooks, automation patterns, AAP integration +- **Current Version**: Ansible Automation Platform 2.4 +- **Update Frequency**: Regular security advisories and feature updates + +### OpenShift Container Platform +- **Primary Source**: OpenShift Product Documentation (docs.redhat.com/openshift) +- **Focus**: Node maintenance, pod eviction, zero-downtime updates, security +- **Versions Covered**: OpenShift 4.7-4.16 +- **Update Frequency**: Per-release documentation updates + +### Red Hat Lightspeed +- **Primary Source**: Red Hat Lightspeed Documentation + Customer Portal +- **Focus**: Vulnerability assessment, CVE analysis, remediation planning, system inventory +- **Current Version**: 1-latest (continuously updated) +- **Update Frequency**: Real-time CVE database updates + +### Security & CVSS +- **Primary Source**: Red Hat Customer Portal - Product Security Center +- **Focus**: CVSS v3.1 scoring, severity classification, security advisories +- **Update Frequency**: Daily security bulletins and advisories + +## Attribution Format + +All documentation files in this knowledge base include YAML frontmatter with source attribution: + +```yaml +--- +title: [Document Title] +category: rhel|ansible|openshift|insights|references +sources: + - title: [Official Doc Title] + url: [Official URL] + sections: [Relevant sections] + date_accessed: YYYY-MM-DD +tags: [keywords] +applies_to: [rhel7, rhel8, rhel9, openshift4.x] +last_updated: YYYY-MM-DD +--- +``` + +## Verification + +All sources listed above were verified as active and current as of January 20, 2026. The sources are: + +1. **Official Red Hat Documentation** (docs.redhat.com) - Authoritative product documentation +2. **Red Hat Customer Portal** (access.redhat.com) - Knowledge base articles and security data +3. **Red Hat Corporate Website** (redhat.com) - Official blog posts and technical articles +4. **OpenShift Documentation** (docs.openshift.com) - OpenShift Container Platform guides + +## License and Usage + +This knowledge base is derived from official Red Hat documentation licensed under Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0) or similar Red Hat documentation licenses. All credit for the original content belongs to Red Hat, Inc. and its contributors. + +**Important**: This knowledge base is a derivative work for educational and operational purposes. For the most up-to-date and authoritative information, always consult the official Red Hat documentation at the URLs listed above. + +## Source Maintenance + +This source list is maintained as part of the Remediation Agent plugin. When documentation is updated or new sources are added: + +1. Update this SOURCES.md file with new entries +2. Update the YAML frontmatter in affected documentation files +3. Regenerate the semantic index using `docs/.ai-index/generate-index.py` +4. Update the "Last Verified" date in the table above + +## Contact + +For questions about Red Hat documentation sources or to report broken links: +- Red Hat Customer Portal: https://access.redhat.com/support +- Red Hat Documentation Feedback: https://docs.redhat.com (feedback links on each page) diff --git a/submissions/mcp-aap-validator/skills/references/aap-integration-test-guide.md b/submissions/mcp-aap-validator/skills/references/aap-integration-test-guide.md new file mode 100644 index 0000000..bc6d7f8 --- /dev/null +++ b/submissions/mcp-aap-validator/skills/references/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/mcps.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/submissions/mcp-aap-validator/skills/references/aap-job-execution.md b/submissions/mcp-aap-validator/skills/references/aap-job-execution.md new file mode 100644 index 0000000..386fd11 --- /dev/null +++ b/submissions/mcp-aap-validator/skills/references/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/submissions/mcp-aap-validator/skills/references/cve-remediation-templates.md b/submissions/mcp-aap-validator/skills/references/cve-remediation-templates.md new file mode 100644 index 0000000..d612b2f --- /dev/null +++ b/submissions/mcp-aap-validator/skills/references/cve-remediation-templates.md @@ -0,0 +1,1500 @@ +--- +title: CVE Remediation Playbook Templates +category: ansible +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-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-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-02-24 +tags: [cve, remediation, playbooks, ansible, templates, package-update, kernel, service-restart, selinux, batch] +applies_to: [rhel7, rhel8, rhel9, openshift4.x] +semantic_keywords: + - "package update" + - "kernel update" + - "service restart" + - "configuration change" + - "SELinux context" + - "batch remediation" + - "reboot handling" + - "rollback strategy" + - "idempotent playbook" + - "CVE patch" +use_cases: + - "package_update_cve" + - "kernel_cve" + - "service_restart_cve" + - "config_file_cve" + - "selinux_cve" + - "batch_remediation" +related_docs: + - "rhel/package-management.md" + - "ansible/error-handling.md" + - "rhel/version-compatibility.md" +last_updated: 2026-02-24 +--- + +# CVE Remediation Playbook Templates + +This document provides 6 production-ready Ansible playbook templates for CVE remediation on RHEL systems. All templates are based on official Red Hat Lightspeed remediation patterns and best practices. + +## Overview + +Red Hat Lightspeed automatically generates Ansible playbooks for CVE remediation. These templates represent the core patterns used in production environments, enhanced with: + +- **Error handling**: Block/rescue/always patterns for safe execution +- **Rollback capability**: Automated rollback on failure +- **Audit logging**: Comprehensive remediation tracking +- **Reboot handling**: Safe reboot detection and execution +- **Idempotency**: Safe to re-run without side effects +- **Health checks**: Pre-flight and post-flight validation + +## Template Index + +1. **[Template 1: Package Update](#template-1-package-update-most-common)** - Standard package updates (most common) +2. **[Template 2: Service Restart](#template-2-service-restart)** - Service configuration CVEs +3. **[Template 3: Configuration File Update](#template-3-configuration-file-update)** - Config file modifications +4. **[Template 4: Kernel Update with Reboot](#template-4-kernel-update-with-reboot)** - Kernel CVEs requiring reboot +5. **[Template 5: SELinux Context Update](#template-5-selinux-context-update)** - SELinux-related CVEs +6. **[Template 6: Batch Remediation](#template-6-batch-remediation)** - Multiple CVEs across fleet + +## When to Use Each Template + +| CVE Type | Affected Component | Template | Reboot Required? | K8s Considerations | +|----------|-------------------|----------|------------------|-------------------| +| Package vulnerability | User-space package | Template 1 | Usually no | Service restart if pod | +| Service configuration | Service daemon | Template 2 | No | Pod restart recommended | +| Config file issue | System config | Template 3 | Usually no | ConfigMap update if K8s | +| Kernel vulnerability | Linux kernel | Template 4 | Yes | Node drain required | +| SELinux context | File contexts | Template 5 | No | Rare in containerized | +| Multiple CVEs | Various | Template 6 | Depends | Batch node updates | + +--- + +## Template 1: Package Update (Most Common) + +### Use Case +Standard package updates for CVEs affecting user-space packages (httpd, openssl, glibc, etc.). This is the most common CVE remediation pattern. + +### When to Use +- CVE affects an installed package +- Fix available via package update (DNF/YUM) +- No kernel or system-critical components involved +- Service restart sufficient (no reboot needed) + +### Key Features +- RHEL version validation (7/8/9 compatibility) +- Automatic backup creation (RHEL 8/9 snapshots) +- Package update with cache refresh +- Reboot detection +- Conditional service restarts +- Audit logging +- Idempotent (safe to re-run) + +### Complete Playbook + +```yaml +--- +- name: CVE-YYYY-NNNNN Remediation - Package Update + hosts: affected_systems + become: true + gather_facts: true + + vars: + cve_id: "CVE-YYYY-NNNNN" + vulnerable_packages: + - package-name-1 + - package-name-2 + affected_services: [] # Optional: services to restart after update + + pre_tasks: + - name: Gather package facts + package_facts: + manager: auto + + - name: Verify system is RHEL + assert: + that: + - ansible_distribution == "RedHat" + - ansible_distribution_major_version in ["7", "8", "9"] + fail_msg: "This playbook is for Red Hat Enterprise Linux systems only" + success_msg: "RHEL {{ ansible_distribution_major_version }} detected" + + - name: Check current vulnerable package versions + debug: + msg: > + Package {{ item }} current version: + {{ ansible_facts.packages[item][0].version | default('not installed') }} + loop: "{{ vulnerable_packages }}" + when: item in ansible_facts.packages + + - name: Create backup point (RHEL 8/9 with Boom) + command: > + boom create --title "pre-{{ cve_id }}-{{ ansible_date_time.epoch }}" + when: + - ansible_distribution_major_version in ["8", "9"] + ignore_errors: true + register: backup_result + + - name: Log backup creation + debug: + msg: "Backup created: {{ backup_result.stdout | default('skipped or failed') }}" + + tasks: + - name: Update vulnerable packages + block: + - name: Update packages using DNF (RHEL 8/9) + dnf: + name: "{{ vulnerable_packages }}" + state: latest + update_cache: true + register: package_update + when: ansible_distribution_major_version in ["8", "9"] + + - name: Update packages using YUM (RHEL 7) + yum: + name: "{{ vulnerable_packages }}" + state: latest + update_cache: true + register: package_update + when: ansible_distribution_major_version == "7" + + - name: Verify package update success + assert: + that: + - package_update is changed or package_update is success + fail_msg: "Package update failed" + success_msg: "Packages updated successfully" + + rescue: + - name: Log package update failure + debug: + msg: "Package update failed: {{ package_update.msg | default('unknown error') }}" + + - name: Fail playbook on update error + fail: + msg: "CVE remediation failed - package update error" + + - name: Check if reboot is required + stat: + path: /var/run/reboot-required + register: reboot_required_file + + - name: Check if reboot is required (systemd method) + command: needs-restarting -r + register: needs_restarting + failed_when: false + changed_when: false + when: ansible_distribution_major_version in ["8", "9"] + + post_tasks: + - name: Gather updated package facts + package_facts: + manager: auto + + - name: Verify package versions after update + debug: + msg: > + Package {{ item }} updated version: + {{ ansible_facts.packages[item][0].version | default('not installed') }} + loop: "{{ vulnerable_packages }}" + when: item in ansible_facts.packages + + - name: Restart affected services (if no reboot needed) + systemd: + name: "{{ item }}" + state: restarted + loop: "{{ affected_services | default([]) }}" + when: + - affected_services is defined + - affected_services | length > 0 + - not (reboot_required_file.stat.exists | default(false)) + - needs_restarting.rc == 0 | default(true) + + - name: Wait for services to be active + systemd: + name: "{{ item }}" + state: started + loop: "{{ affected_services | default([]) }}" + when: + - affected_services is defined + - affected_services | length > 0 + - not (reboot_required_file.stat.exists | default(false)) + + - name: Log remediation success + lineinfile: + path: /var/log/cve-remediation.log + line: > + {{ ansible_date_time.iso8601 }} - {{ cve_id }} remediated - + {{ package_update.results | length | default(0) }} packages updated on {{ inventory_hostname }} + create: true + mode: '0644' + + - name: Notify if reboot required + debug: + msg: | + ⚠️ REBOOT REQUIRED ⚠️ + System: {{ inventory_hostname }} + Reason: Package update requires reboot + Action: Schedule maintenance window for reboot + when: > + reboot_required_file.stat.exists | default(false) or + (needs_restarting.rc != 0 | default(false)) + + - name: Create reboot notification file + copy: + content: | + CVE: {{ cve_id }} + Date: {{ ansible_date_time.iso8601 }} + Packages Updated: {{ vulnerable_packages | join(', ') }} + Reason: Package update requires system reboot + dest: "/root/REBOOT_REQUIRED_{{ cve_id }}.txt" + mode: '0644' + when: > + reboot_required_file.stat.exists | default(false) or + (needs_restarting.rc != 0 | default(false)) +``` + +### Usage Example + +```bash +# Create inventory file +cat > inventory.ini < remediate-cve-2024-1234.yml < + {{ ansible_date_time.iso8601 }} - {{ cve_id }} remediated - + {{ service_name }} service configuration updated on {{ inventory_hostname }} + create: true + mode: '0644' + + - name: Document configuration changes + copy: + content: | + CVE: {{ cve_id }} + Date: {{ ansible_date_time.iso8601 }} + Service: {{ service_name }} + Configuration File: {{ config_file }} + Backup Location: {{ backup_config.dest }} + Status: Remediation successful + dest: "/root/CVE_REMEDIATION_{{ cve_id }}.txt" + mode: '0644' +``` + +### Usage Example + +```yaml +# Remediate sshd CVE requiring config changes +- name: CVE-2024-5678 Remediation - SSH Weak Ciphers + hosts: all_servers + become: true + + vars: + cve_id: "CVE-2024-5678" + service_name: "sshd" + config_file: "/etc/ssh/sshd_config" + + tasks: + - name: Disable weak SSH ciphers + lineinfile: + path: "{{ config_file }}" + regexp: '^#?Ciphers.*' + line: 'Ciphers aes256-gcm@openssh.com,chacha20-poly1305@openssh.com,aes256-ctr' + backup: true + + - name: Disable weak MACs + lineinfile: + path: "{{ config_file }}" + regexp: '^#?MACs.*' + line: 'MACs hmac-sha2-512-etm@openssh.com,hmac-sha2-256-etm@openssh.com' + backup: true +``` + +### Pitfalls to Avoid + +❌ **Don't skip configuration validation**: Always test config syntax before restart +❌ **Don't forget backups**: Configuration rollback impossible without backups +❌ **Don't skip health checks**: Verify service functionality after restart +❌ **Don't use `state: reloaded` for critical changes**: Use `state: restarted` for security fixes + +--- + +## Template 3: Configuration File Update + +### Use Case +CVEs requiring modifications to system configuration files (not service-specific configs). + +### When to Use +- CVE affects system-level configuration (/etc/sysctl.conf, /etc/security/limits.conf, etc.) +- Fix involves file content changes +- No package updates or service restarts required +- Configuration takes effect via sysctl reload or next boot + +### Key Features +- Configuration file backup +- Atomic file updates +- Configuration validation +- Sysctl reload for kernel parameters +- Audit trail + +### Complete Playbook + +```yaml +--- +- name: CVE-YYYY-NNNNN Remediation - System Configuration Update + hosts: affected_systems + become: true + gather_facts: true + + vars: + cve_id: "CVE-YYYY-NNNNN" + config_file: "/etc/sysctl.conf" # Example: sysctl, limits, etc. + config_backup_dir: "/var/backups/cve-remediation" + sysctl_reload: true # Set to true if sysctl configuration + + pre_tasks: + - name: Create backup directory + file: + path: "{{ config_backup_dir }}" + state: directory + mode: '0755' + + - name: Backup current configuration + copy: + src: "{{ config_file }}" + dest: "{{ config_backup_dir }}/{{ config_file | basename }}.{{ ansible_date_time.epoch }}.bak" + remote_src: true + mode: preserve + register: backup_config + + - name: Record current configuration checksum + stat: + path: "{{ config_file }}" + checksum_algorithm: sha256 + register: original_config_stat + + tasks: + - name: Update configuration file + block: + # Example: Disable source routing (CVE mitigation) + - name: Set kernel parameter - Disable source routing + sysctl: + name: net.ipv4.conf.all.accept_source_route + value: '0' + state: present + reload: "{{ sysctl_reload }}" + sysctl_file: "{{ config_file }}" + when: config_file contains 'sysctl' + + - name: Set kernel parameter - Disable ICMP redirects + sysctl: + name: net.ipv4.conf.all.accept_redirects + value: '0' + state: present + reload: "{{ sysctl_reload }}" + sysctl_file: "{{ config_file }}" + when: config_file contains 'sysctl' + + # For non-sysctl configs, use lineinfile or blockinfile + - name: Update non-sysctl configuration + lineinfile: + path: "{{ config_file }}" + regexp: '^#?ParameterName.*' + line: 'ParameterName value' + backup: true + when: config_file not contains 'sysctl' + register: config_update + + - name: Verify configuration change + stat: + path: "{{ config_file }}" + checksum_algorithm: sha256 + register: new_config_stat + + - name: Assert configuration was modified + assert: + that: + - new_config_stat.stat.checksum != original_config_stat.stat.checksum + fail_msg: "Configuration file was not modified" + success_msg: "Configuration successfully updated" + + rescue: + - name: Log configuration failure + debug: + msg: "Configuration update failed - initiating rollback" + + - name: Restore configuration from backup + copy: + src: "{{ backup_config.dest }}" + dest: "{{ config_file }}" + remote_src: true + mode: preserve + + - name: Reload original sysctl configuration + command: sysctl -p {{ config_file }} + when: sysctl_reload and (config_file contains 'sysctl') + + - name: Fail playbook after rollback + fail: + msg: "CVE remediation failed - configuration rolled back" + + post_tasks: + - name: Verify sysctl parameters (if applicable) + command: sysctl net.ipv4.conf.all.accept_source_route net.ipv4.conf.all.accept_redirects + register: sysctl_verify + when: sysctl_reload and (config_file contains 'sysctl') + changed_when: false + + - name: Display sysctl values + debug: + msg: "{{ sysctl_verify.stdout_lines }}" + when: sysctl_reload and (config_file contains 'sysctl') + + - name: Log remediation success + lineinfile: + path: /var/log/cve-remediation.log + line: > + {{ ansible_date_time.iso8601 }} - {{ cve_id }} remediated - + {{ config_file }} updated on {{ inventory_hostname }} + create: true + mode: '0644' + + - name: Document configuration changes + copy: + content: | + CVE: {{ cve_id }} + Date: {{ ansible_date_time.iso8601 }} + Configuration File: {{ config_file }} + Backup Location: {{ backup_config.dest }} + Changes: Kernel parameters hardened per CVE mitigation + Status: Remediation successful + dest: "/root/CVE_REMEDIATION_{{ cve_id }}.txt" + mode: '0644' +``` + +### Usage Example + +```yaml +# Remediate kernel parameter CVE +- name: CVE-2024-9012 Remediation - Kernel Parameter Hardening + hosts: all_servers + become: true + + vars: + cve_id: "CVE-2024-9012" + config_file: "/etc/sysctl.conf" + sysctl_reload: true + + tasks: + - name: Disable IP forwarding + sysctl: + name: net.ipv4.ip_forward + value: '0' + state: present + reload: true + sysctl_file: /etc/sysctl.conf + + - name: Enable SYN cookies + sysctl: + name: net.ipv4.tcp_syncookies + value: '1' + state: present + reload: true + sysctl_file: /etc/sysctl.conf +``` + +### Pitfalls to Avoid + +❌ **Don't skip sysctl reload**: Changes won't take effect until reload or reboot +❌ **Don't modify production configs without backup**: Always create backups +❌ **Don't forget validation**: Verify sysctl values after reload +❌ **Don't use persistent=no for security fixes**: Security parameters should persist across reboots + +--- + +## Template 4: Kernel Update with Reboot + +### Use Case +Critical kernel CVEs requiring kernel package updates and system reboots. + +### When to Use +- CVE affects the Linux kernel +- Fix available via kernel package update +- System reboot mandatory for remediation +- High-impact operation requiring maintenance window + +### Key Features +- Kernel version validation +- Grub configuration backup +- Safe reboot with timeout +- Kubernetes node draining (if applicable) +- Post-reboot verification +- Health checks after reboot + +### Complete Playbook + +```yaml +--- +- name: CVE-YYYY-NNNNN Remediation - Kernel Update with Reboot + hosts: affected_systems + become: true + gather_facts: true + serial: 1 # Update one host at a time for safety + + vars: + cve_id: "CVE-YYYY-NNNNN" + kernel_package: "kernel" + reboot_timeout: 600 # 10 minutes + post_reboot_delay: 30 # Wait 30 seconds after reboot + kubernetes_node: false # Set to true if K8s node + drain_timeout: 300 # 5 minutes for node drain + + pre_tasks: + - name: Record current kernel version + command: uname -r + register: current_kernel + changed_when: false + + - name: Display current kernel + debug: + msg: "Current kernel: {{ current_kernel.stdout }}" + + - name: Check if system is a Kubernetes node + stat: + path: /etc/kubernetes/kubelet.conf + register: k8s_check + + - name: Set kubernetes_node fact + set_fact: + kubernetes_node: "{{ k8s_check.stat.exists }}" + + - name: Drain Kubernetes node (if applicable) + command: kubectl drain {{ inventory_hostname }} --ignore-daemonsets --delete-emptydir-data --force --timeout={{ drain_timeout }}s + delegate_to: localhost + when: kubernetes_node + register: drain_result + + - name: Log node drain + debug: + msg: "Node drained: {{ drain_result.stdout }}" + when: kubernetes_node + + - name: Create pre-update snapshot (RHEL 8/9) + command: > + boom create --title "pre-kernel-{{ cve_id }}-{{ ansible_date_time.epoch }}" + when: ansible_distribution_major_version in ["8", "9"] + ignore_errors: true + register: snapshot_result + + - name: Backup GRUB configuration + copy: + src: /etc/default/grub + dest: /var/backups/grub.{{ ansible_date_time.epoch }}.bak + remote_src: true + mode: preserve + + tasks: + - name: Update kernel package + block: + - name: Update kernel using DNF (RHEL 8/9) + dnf: + name: "{{ kernel_package }}" + state: latest + update_cache: true + register: kernel_update + when: ansible_distribution_major_version in ["8", "9"] + + - name: Update kernel using YUM (RHEL 7) + yum: + name: "{{ kernel_package }}" + state: latest + update_cache: true + register: kernel_update + when: ansible_distribution_major_version == "7" + + - name: Verify kernel update + assert: + that: + - kernel_update is changed or kernel_update is success + fail_msg: "Kernel update failed" + success_msg: "Kernel updated successfully" + + rescue: + - name: Log kernel update failure + debug: + msg: "Kernel update failed: {{ kernel_update.msg | default('unknown error') }}" + + - name: Uncordon Kubernetes node on failure + command: kubectl uncordon {{ inventory_hostname }} + delegate_to: localhost + when: kubernetes_node + ignore_errors: true + + - name: Fail playbook + fail: + msg: "CVE remediation failed - kernel update error" + + - name: Create reboot notification + copy: + content: | + CVE: {{ cve_id }} + Date: {{ ansible_date_time.iso8601 }} + System: {{ inventory_hostname }} + Current Kernel: {{ current_kernel.stdout }} + Action: System will reboot to apply kernel update + dest: "/root/REBOOTING_FOR_{{ cve_id }}.txt" + mode: '0644' + + - name: Log pre-reboot state + lineinfile: + path: /var/log/cve-remediation.log + line: > + {{ ansible_date_time.iso8601 }} - {{ cve_id }} - Pre-reboot - + Current kernel: {{ current_kernel.stdout }} - {{ inventory_hostname }} + create: true + mode: '0644' + + - name: Reboot system to apply kernel update + reboot: + reboot_timeout: "{{ reboot_timeout }}" + post_reboot_delay: "{{ post_reboot_delay }}" + msg: "Rebooting for CVE-{{ cve_id }} kernel update" + register: reboot_result + + post_tasks: + - name: Verify system is back online + wait_for_connection: + timeout: 300 + + - name: Gather facts after reboot + setup: + + - name: Record new kernel version + command: uname -r + register: new_kernel + changed_when: false + + - name: Verify kernel was updated + assert: + that: + - new_kernel.stdout != current_kernel.stdout + fail_msg: "Kernel was not updated - still running {{ current_kernel.stdout }}" + success_msg: "Kernel updated from {{ current_kernel.stdout }} to {{ new_kernel.stdout }}" + + - name: Verify all services are running + service_facts: + + - name: Check critical services + assert: + that: + - ansible_facts.services['sshd.service'].state == 'running' + fail_msg: "Critical services not running after reboot" + success_msg: "System health check passed" + + - name: Uncordon Kubernetes node + command: kubectl uncordon {{ inventory_hostname }} + delegate_to: localhost + when: kubernetes_node + register: uncordon_result + + - name: Wait for node to be ready + command: kubectl wait --for=condition=Ready node/{{ inventory_hostname }} --timeout=300s + delegate_to: localhost + when: kubernetes_node + + - name: Log remediation success + lineinfile: + path: /var/log/cve-remediation.log + line: > + {{ ansible_date_time.iso8601 }} - {{ cve_id }} remediated - + Kernel updated from {{ current_kernel.stdout }} to {{ new_kernel.stdout }} on {{ inventory_hostname }} + create: true + mode: '0644' + + - name: Document kernel update + copy: + content: | + CVE: {{ cve_id }} + Date: {{ ansible_date_time.iso8601 }} + System: {{ inventory_hostname }} + Previous Kernel: {{ current_kernel.stdout }} + New Kernel: {{ new_kernel.stdout }} + Reboot Duration: {{ reboot_result.elapsed }} seconds + Kubernetes Node: {{ kubernetes_node }} + Status: Remediation successful + dest: "/root/CVE_REMEDIATION_{{ cve_id }}.txt" + mode: '0644' + + - name: Clean up notification files + file: + path: "/root/REBOOTING_FOR_{{ cve_id }}.txt" + state: absent +``` + +### Usage Example + +```bash +# Kernel CVE remediation with Kubernetes integration +ansible-playbook -i k8s-nodes.ini remediate-kernel-cve.yml \ + --extra-vars "cve_id=CVE-2024-3456 kubernetes_node=true" \ + --limit production-worker-nodes \ + --ask-become-pass + +# Serial execution (one node at a time) is built into the playbook +# with 'serial: 1' directive +``` + +### Kubernetes/OpenShift Considerations + +**Before running this playbook on K8s nodes**: + +1. **Review pod disruption budgets**: Ensure critical apps can tolerate node drain +2. **Check StatefulSets**: May require special handling +3. **Verify cluster capacity**: Ensure remaining nodes can handle workload +4. **Schedule maintenance window**: Kernel updates are high-impact + +### Pitfalls to Avoid + +❌ **Don't reboot all nodes simultaneously**: Use `serial: 1` for safety +❌ **Don't forget post-reboot verification**: Ensure new kernel is running +❌ **Don't set short reboot timeouts**: Kernel updates can take 5-10 minutes + +--- + +## Template 5: SELinux Context Update + +### Use Case +CVEs affecting SELinux file contexts or requiring SELinux policy updates. + +### When to Use +- CVE involves SELinux context issues +- Fix requires `restorecon` or policy updates +- SELinux denials blocking remediation +- No package updates required (context-only fixes) + +### Key Features +- SELinux status validation +- Context backup +- Safe context restoration +- Policy module management +- AVC denial checking +- Rollback capability + +### Complete Playbook + +```yaml +--- +- name: CVE-YYYY-NNNNN Remediation - SELinux Context Update + hosts: affected_systems + become: true + gather_facts: true + + vars: + cve_id: "CVE-YYYY-NNNNN" + affected_paths: + - /path/to/affected/file1 + - /path/to/affected/dir/ + selinux_type: "httpd_sys_content_t" # Example context + backup_dir: "/var/backups/selinux-contexts" + + pre_tasks: + - name: Check SELinux status + command: getenforce + register: selinux_status + changed_when: false + failed_when: selinux_status.stdout not in ['Enforcing', 'Permissive'] + + - name: Verify SELinux is not disabled + assert: + that: + - selinux_status.stdout != 'Disabled' + fail_msg: "SELinux is disabled - this playbook requires SELinux to be enabled" + success_msg: "SELinux mode: {{ selinux_status.stdout }}" + + - name: Create backup directory + file: + path: "{{ backup_dir }}" + state: directory + mode: '0755' + + - name: Backup current SELinux contexts + shell: > + ls -Z {{ item }} > {{ backup_dir }}/{{ item | basename }}.{{ ansible_date_time.epoch }}.context + loop: "{{ affected_paths }}" + changed_when: false + + - name: Check for recent AVC denials + command: ausearch -m avc -ts recent + register: avc_denials + failed_when: false + changed_when: false + + - name: Log AVC denials if present + debug: + msg: "Recent AVC denials detected - review /var/log/audit/audit.log" + when: avc_denials.rc == 0 + + tasks: + - name: Apply SELinux context fixes + block: + - name: Restore default SELinux contexts + command: restorecon -Rv {{ item }} + loop: "{{ affected_paths }}" + register: restorecon_result + + - name: Set specific SELinux type (if needed) + sefcontext: + target: '{{ item }}(/.*)?' + setype: "{{ selinux_type }}" + state: present + loop: "{{ affected_paths }}" + when: selinux_type is defined + register: sefcontext_result + + - name: Apply new context after semanage + command: restorecon -Rv {{ item }} + loop: "{{ affected_paths }}" + when: sefcontext_result is changed + + - name: Verify contexts were applied + shell: ls -Z {{ item }} + loop: "{{ affected_paths }}" + register: context_verify + changed_when: false + + - name: Display new contexts + debug: + msg: "{{ context_verify.results | map(attribute='stdout_lines') | list }}" + + rescue: + - name: Log SELinux context failure + debug: + msg: "SELinux context update failed - review AVC denials" + + - name: Display backup location + debug: + msg: "Context backups available in {{ backup_dir }}" + + - name: Fail playbook + fail: + msg: "CVE remediation failed - SELinux context update error" + + post_tasks: + - name: Check for new AVC denials + command: ausearch -m avc -ts recent + register: new_avc_denials + failed_when: false + changed_when: false + + - name: Warn if new AVC denials + debug: + msg: "⚠️ New AVC denials detected - manual review required" + when: new_avc_denials.rc == 0 + + - name: Verify SELinux is still enforcing + command: getenforce + register: final_selinux_status + changed_when: false + + - name: Assert SELinux mode unchanged + assert: + that: + - final_selinux_status.stdout == selinux_status.stdout + fail_msg: "SELinux mode changed unexpectedly" + success_msg: "SELinux mode stable: {{ final_selinux_status.stdout }}" + + - name: Log remediation success + lineinfile: + path: /var/log/cve-remediation.log + line: > + {{ ansible_date_time.iso8601 }} - {{ cve_id }} remediated - + SELinux contexts updated for {{ affected_paths | length }} paths on {{ inventory_hostname }} + create: true + mode: '0644' + + - name: Document SELinux changes + copy: + content: | + CVE: {{ cve_id }} + Date: {{ ansible_date_time.iso8601 }} + System: {{ inventory_hostname }} + Affected Paths: {{ affected_paths | join(', ') }} + SELinux Type Applied: {{ selinux_type | default('default') }} + Backup Location: {{ backup_dir }} + Status: Remediation successful + dest: "/root/CVE_REMEDIATION_{{ cve_id }}.txt" + mode: '0644' +``` + +### Usage Example + +```yaml +# Remediate httpd SELinux context CVE +- name: CVE-2024-7890 Remediation - httpd SELinux Context + hosts: web_servers + become: true + + vars: + cve_id: "CVE-2024-7890" + affected_paths: + - /var/www/html + - /var/www/cgi-bin + selinux_type: "httpd_sys_content_t" + + tasks: + - name: Restore default contexts for web content + command: restorecon -Rv {{ item }} + loop: "{{ affected_paths }}" + + - name: Allow httpd network connections (if needed) + seboolean: + name: httpd_can_network_connect + state: true + persistent: true +``` + +### Pitfalls to Avoid + +❌ **Don't disable SELinux as a "fix"**: This defeats security +❌ **Don't use `setenforce 0`**: Keep SELinux enforcing +❌ **Don't skip AVC denial review**: Understand why denials occurred +❌ **Don't forget `restorecon -R`**: Recursive is critical for directories +❌ **Don't use `-F` flag casually**: Forces relabeling, may have side effects + +--- + +## Template 6: Batch Remediation + +### Use Case +Remediating multiple CVEs across a fleet of systems efficiently. + +### When to Use +- Multiple CVEs need remediation +- Large number of affected systems +- Want to minimize maintenance windows +- Need comprehensive remediation reporting + +### Key Features +- Multi-CVE handling +- Consolidated package updates +- Batch service restarts +- Progress tracking +- Detailed reporting +- Failure isolation (continues on non-critical errors) + +### Complete Playbook + +```yaml +--- +- name: Batch CVE Remediation - Multiple CVEs + hosts: affected_systems + become: true + gather_facts: true + serial: "{{ batch_size | default(5) }}" # Configurable batch size + + vars: + batch_id: "batch-{{ ansible_date_time.epoch }}" + batch_size: 5 # Process 5 systems concurrently + + cves: + - cve_id: "CVE-2024-1111" + packages: ["httpd", "httpd-tools"] + services: ["httpd"] + priority: "critical" + + - cve_id: "CVE-2024-2222" + packages: ["openssl", "openssl-libs"] + services: [] + priority: "important" + + - cve_id: "CVE-2024-3333" + packages: ["glibc", "glibc-common"] + services: [] + priority: "important" + + all_packages: "{{ cves | map(attribute='packages') | flatten | unique | list }}" + all_services: "{{ cves | map(attribute='services') | flatten | unique | select | list }}" + + report_dir: "/var/log/cve-remediation/{{ batch_id }}" + + pre_tasks: + - name: Create report directory + file: + path: "{{ report_dir }}" + state: directory + mode: '0755' + + - name: Log batch remediation start + copy: + content: | + Batch ID: {{ batch_id }} + Start Time: {{ ansible_date_time.iso8601 }} + System: {{ inventory_hostname }} + CVEs to Remediate: {{ cves | map(attribute='cve_id') | join(', ') }} + Total Packages: {{ all_packages | length }} + Total Services: {{ all_services | length }} + dest: "{{ report_dir }}/{{ inventory_hostname }}_start.txt" + mode: '0644' + + - name: Gather current package versions + package_facts: + manager: auto + + - name: Record pre-update package versions + copy: + content: | + {% for pkg in all_packages %} + {% if pkg in ansible_facts.packages %} + {{ pkg }}: {{ ansible_facts.packages[pkg][0].version }} + {% else %} + {{ pkg }}: not installed + {% endif %} + {% endfor %} + dest: "{{ report_dir }}/{{ inventory_hostname }}_pre_versions.txt" + mode: '0644' + + - name: Create backup snapshot (RHEL 8/9) + command: > + boom create --title "batch-{{ batch_id }}" + when: ansible_distribution_major_version in ["8", "9"] + ignore_errors: true + + tasks: + - name: Batch update all vulnerable packages + block: + - name: Update all packages in one transaction (RHEL 8/9) + dnf: + name: "{{ all_packages }}" + state: latest + update_cache: true + register: package_update + when: ansible_distribution_major_version in ["8", "9"] + + - name: Update all packages in one transaction (RHEL 7) + yum: + name: "{{ all_packages }}" + state: latest + update_cache: true + register: package_update + when: ansible_distribution_major_version == "7" + + - name: Verify package updates + package_facts: + manager: auto + + - name: Record post-update package versions + copy: + content: | + {% for pkg in all_packages %} + {% if pkg in ansible_facts.packages %} + {{ pkg }}: {{ ansible_facts.packages[pkg][0].version }} + {% else %} + {{ pkg }}: not installed + {% endif %} + {% endfor %} + dest: "{{ report_dir }}/{{ inventory_hostname }}_post_versions.txt" + mode: '0644' + + rescue: + - name: Log package update failures + copy: + content: | + Batch ID: {{ batch_id }} + System: {{ inventory_hostname }} + Status: FAILED + Error: {{ package_update.msg | default('Package update failed') }} + Failed Packages: {{ package_update.failures | default([]) | join(', ') }} + dest: "{{ report_dir }}/{{ inventory_hostname }}_FAILED.txt" + mode: '0644' + + - name: Continue despite package failures + debug: + msg: "Package updates failed on {{ inventory_hostname }} - see {{ report_dir }}/{{ inventory_hostname }}_FAILED.txt" + + - name: Check if reboot required + stat: + path: /var/run/reboot-required + register: reboot_required_file + + - name: Check needs-restarting (RHEL 8/9) + command: needs-restarting -r + register: needs_restarting + failed_when: false + changed_when: false + when: ansible_distribution_major_version in ["8", "9"] + + post_tasks: + - name: Restart affected services (if no reboot needed) + systemd: + name: "{{ item }}" + state: restarted + loop: "{{ all_services }}" + when: + - all_services | length > 0 + - not (reboot_required_file.stat.exists | default(false)) + - (needs_restarting.rc == 0) | default(true) + ignore_errors: true + register: service_restarts + + - name: Log service restart failures + copy: + content: | + {% for result in service_restarts.results | default([]) %} + {% if result.failed %} + Service: {{ result.item }} + Status: FAILED + Error: {{ result.msg | default('Unknown error') }} + {% endif %} + {% endfor %} + dest: "{{ report_dir }}/{{ inventory_hostname }}_service_failures.txt" + mode: '0644' + when: service_restarts.failed | default(false) + + - name: Generate CVE remediation summary + copy: + content: | + ======================================== + BATCH CVE REMEDIATION SUMMARY + ======================================== + Batch ID: {{ batch_id }} + System: {{ inventory_hostname }} + Completion Time: {{ ansible_date_time.iso8601 }} + + CVEs Remediated: + {% for cve in cves %} + - {{ cve.cve_id }} ({{ cve.priority }}) + Packages: {{ cve.packages | join(', ') }} + Services: {{ cve.services | join(', ') if cve.services else 'None' }} + {% endfor %} + + Package Updates: {{ all_packages | length }} packages + Service Restarts: {{ all_services | length }} services + + Reboot Required: {{ 'YES' if (reboot_required_file.stat.exists or (needs_restarting.rc != 0 | default(false))) else 'NO' }} + + {% if reboot_required_file.stat.exists or (needs_restarting.rc != 0 | default(false)) %} + ⚠️ REBOOT REQUIRED ⚠️ + Schedule maintenance window to reboot this system. + {% endif %} + + Status: {{ 'SUCCESS' if not (package_update.failed | default(false)) else 'PARTIAL' }} + + Reports Location: {{ report_dir }} + dest: "{{ report_dir }}/{{ inventory_hostname }}_SUMMARY.txt" + mode: '0644' + + - name: Log to central remediation log + lineinfile: + path: /var/log/cve-remediation.log + line: > + {{ ansible_date_time.iso8601 }} - Batch {{ batch_id }} - + Remediated {{ cves | length }} CVEs - + {{ all_packages | length }} packages updated - + {{ 'REBOOT REQUIRED' if (reboot_required_file.stat.exists or (needs_restarting.rc != 0 | default(false))) else 'No reboot' }} - + {{ inventory_hostname }} + create: true + mode: '0644' + + - name: Display remediation summary + debug: + msg: "{{ lookup('file', report_dir + '/' + inventory_hostname + '_SUMMARY.txt') }}" +``` + +### Usage Example + +```bash +# Remediate multiple CVEs across production fleet +ansible-playbook -i production-inventory.ini batch-remediation.yml \ + --extra-vars "batch_size=10" \ + --limit web_servers + +# Generate consolidated report +grep "Batch batch-" /var/log/cve-remediation.log | \ + awk '{print $1, $2, $NF}' | \ + sort > batch-remediation-summary.txt +``` + +### Reporting + +After execution, find detailed reports in `/var/log/cve-remediation//`: + +``` +/ +├── host1_start.txt # Remediation start details +├── host1_pre_versions.txt # Package versions before update +├── host1_post_versions.txt # Package versions after update +├── host1_SUMMARY.txt # Remediation summary +├── host1_FAILED.txt # Failures (if any) +└── host1_service_failures.txt # Service restart failures (if any) +``` + +### Pitfalls to Avoid + +❌ **Don't set batch_size too high**: Limits blast radius if failures occur +❌ **Don't skip pre/post version recording**: Critical for audit trail +❌ **Don't fail entire batch on single package error**: Use `ignore_errors` strategically +❌ **Don't batch kernel updates**: Kernel CVEs require serial execution (Template 4) +❌ **Don't forget consolidated reporting**: Management needs overall status + +--- + +## Cross-Reference Guide + +### For RHEL-Specific Operations +- **[package-management.md](../rhel/package-management.md)** - DNF/YUM workflows, reboot detection +- **[version-compatibility.md](../rhel/version-compatibility.md)** - RHEL 7/8/9 differences +- **[selinux-context.md](../rhel/selinux-context.md)** - SELinux remediation patterns +- **[systemd-services.md](../rhel/systemd-services.md)** - Service management patterns + +### For Error Handling & Rollback +- **[error-handling.md](./error-handling.md)** - Block/rescue/always patterns, rollback strategies +- **[idempotency.md](./idempotency.md)** - Safe re-run patterns + +### For Execution & Deployment +- **[aap-integration.md](./aap-integration.md)** - Ansible Automation Platform workflows + +### For Risk Assessment +- **[vulnerability-logic.md](../insights/vulnerability-logic.md)** - Red Hat Lightspeed risk methodology +- **[cvss-scoring.md](../references/cvss-scoring.md)** - CVSS interpretation + +--- + +## Official Red Hat Sources + +This document is derived from: + +1. **Red Hat Lightspeed Remediations Guide** + https://docs.redhat.com/en/documentation/red_hat_insights/1-latest/html-single/red_hat_insights_remediations_guide/index + +2. **Creating and Managing Remediation Plans** + https://docs.redhat.com/en/documentation/red_hat_insights/1-latest/html/red_hat_insights_remediations_guide/creating-managing-playbooks_red-hat-insights-remediation-guide + +3. **Creating Remediation Playbooks (RHEL 7 Security Guide)** + 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-02-24 + +--- + +## Quick Reference Table + +| Template | Use Case | Reboot? | K8s Impact | Priority | Complexity | +|----------|----------|---------|------------|----------|------------| +| 1. Package Update | User-space packages | Rare | Low | High | Low | +| 2. Service Restart | Service configs | No | Medium | Medium | Low | +| 3. Config Update | System configs | No | Low | Medium | Low | +| 4. Kernel Update | Kernel CVEs | Yes | High | Critical | High | +| 5. SELinux Context | SELinux issues | No | Low | Medium | Medium | +| 6. Batch Remediation | Multiple CVEs | Varies | Varies | High | High | + +## Template Selection Decision Tree + +``` +Is CVE affecting kernel? +├─ YES → Use Template 4 (Kernel Update) +└─ NO → Is CVE affecting multiple systems? + ├─ YES → Use Template 6 (Batch Remediation) + └─ NO → What component is affected? + ├─ Package → Use Template 1 (Package Update) + ├─ Service config → Use Template 2 (Service Restart) + ├─ System config → Use Template 3 (Config Update) + └─ SELinux context → Use Template 5 (SELinux) +``` + +--- + +**Document Version**: 1.0 +**Last Updated**: 2026-02-24 +**Maintained By**: Remediation Agent Knowledge Base +**Official Sources**: See SOURCES.md for complete attribution diff --git a/submissions/mcp-aap-validator/skills/references/cvss-scoring.md b/submissions/mcp-aap-validator/skills/references/cvss-scoring.md new file mode 100644 index 0000000..e0ccd3d --- /dev/null +++ b/submissions/mcp-aap-validator/skills/references/cvss-scoring.md @@ -0,0 +1,636 @@ +--- +title: CVSS Scoring and Red Hat Severity Mappings +category: references +sources: + - title: Severity Ratings (Red Hat Customer Portal) + url: https://access.redhat.com/security/updates/classification + sections: Red Hat severity ratings, CVSS usage + date_accessed: 2026-01-20 + - title: How We Classify Security Severity Levels + url: https://access.redhat.com/solutions/725593 + sections: Severity classification methodology + date_accessed: 2026-01-20 + - title: Security Update Policy + url: https://access.redhat.com/security/lifecycle-security-update-policy + sections: Security lifecycle, update policies + date_accessed: 2026-01-20 + - title: Product Security Center + url: https://access.redhat.com/security/ + sections: Security advisories, bulletins, CVSS data + date_accessed: 2026-01-20 +tags: [cvss, severity, scoring, risk-assessment, priority] +applies_to: [rhel6, rhel7, rhel8, rhel9] +semantic_keywords: + - "CVSS score" + - "severity rating" + - "Red Hat severity" + - "vulnerability scoring" + - "risk assessment" + - "priority matrix" + - "CVSS v3.1" + - "attack vector" + - "exploitability" + - "impact metrics" +use_cases: + - "risk_assessment" + - "cve_prioritization" + - "compliance_reporting" + - "stakeholder_communication" +related_docs: + - "insights/vulnerability-logic.md" + - "references/compliance-frameworks.md" + - "ansible/cve-remediation-templates.md" +last_updated: 2026-01-20 +--- + +# CVSS Scoring and Red Hat Severity Mappings + +This document explains CVSS (Common Vulnerability Scoring System) scoring and how Red Hat maps CVSS scores to severity ratings for prioritization. + +## Overview + +**CVSS (Common Vulnerability Scoring System)** is an industry-standard framework for assessing vulnerability severity. Red Hat uses **CVSS v3.1** for all vulnerabilities published since 2016. + +**Key Concepts**: +- **CVSS Base Score**: 0.0 (no risk) to 10.0 (critical) - measures inherent vulnerability characteristics +- **CVSS Temporal Score**: Adjusts base score for current exploit availability +- **CVSS Environmental Score**: Organization-specific adjustments +- **Red Hat Severity**: Critical/Important/Moderate/Low - Red Hat's assessment for their products + +**Important**: Red Hat severity ratings may differ from CVSS scores based on real-world exploitability in RHEL environments. + +## CVSS v3.1 Metrics + +CVSS base scores are calculated from 8 metrics across 3 categories: + +### Exploitability Metrics (How Easy to Exploit) + +#### 1. Attack Vector (AV) +**Question**: How is the vulnerability exploited? + +| Value | Score | Description | Example | +|-------|-------|-------------|---------| +| **Network (N)** | Highest | Remotely exploitable over network | Web service vulnerability | +| **Adjacent (A)** | High | Exploitable from adjacent network | WiFi attack, same subnet | +| **Local (L)** | Medium | Requires local access to system | Privilege escalation | +| **Physical (P)** | Lowest | Requires physical access | Console-only exploit | + +**Impact on Priority**: Network vulnerabilities are highest priority (remotely exploitable). + +#### 2. Attack Complexity (AC) +**Question**: How difficult is the attack to execute? + +| Value | Score | Description | Example | +|-------|-------|-------------|---------| +| **Low (L)** | Higher | Easy to exploit reliably | Standard buffer overflow | +| **High (H)** | Lower | Requires specific conditions | Race condition, timing-dependent | + +**Impact on Priority**: Low complexity = easier exploitation = higher priority. + +#### 3. Privileges Required (PR) +**Question**: What privileges must attacker have? + +| Value | Score | Description | Example | +|-------|-------|-------------|---------| +| **None (N)** | Highest | Unauthenticated attack | Public web service exploit | +| **Low (L)** | Medium | Basic user privileges needed | Authenticated user exploit | +| **High (H)** | Lowest | Admin/root privileges needed | Root-only privilege escalation | + +**Impact on Priority**: None required = widest attack surface = highest priority. + +#### 4. User Interaction (UI) +**Question**: Does exploitation require user action? + +| Value | Score | Description | Example | +|-------|-------|-------------|---------| +| **None (N)** | Higher | Fully automated | Wormable exploit | +| **Required (R)** | Lower | User must perform action | Phishing, clicking malicious link | + +**Impact on Priority**: No interaction = self-propagating = highest priority. + +### Scope Metric + +#### 5. Scope (S) +**Question**: Can the exploit impact resources beyond the vulnerable component? + +| Value | Score | Description | Example | +|-------|-------|-------------|---------| +| **Changed (C)** | Higher | Impacts other components | Container escape, VM escape | +| **Unchanged (U)** | Lower | Impacts only vulnerable component | Single service compromise | + +**Impact on Priority**: Changed scope = broader impact = higher priority. + +### Impact Metrics (What Damage) + +#### 6. Confidentiality (C) +**Question**: How much data can be disclosed? + +| Value | Score | Description | Example | +|-------|-------|-------------|---------| +| **High (H)** | 0.56 | Total information disclosure | Database dump, /etc/shadow leak | +| **Low (L)** | 0.22 | Limited disclosure | Single file read | +| **None (N)** | 0.00 | No confidentiality impact | Denial of service only | + +#### 7. Integrity (I) +**Question**: How much can data/systems be modified? + +| Value | Score | Description | Example | +|-------|-------|-------------|---------| +| **High (H)** | 0.56 | Total data modification | Root access, arbitrary code execution | +| **Low (L)** | 0.22 | Limited modification | Single file write | +| **None (N)** | 0.00 | No integrity impact | Read-only exploit | + +#### 8. Availability (A) +**Question**: How much is service availability impacted? + +| Value | Score | Description | Example | +|-------|-------|-------------|---------| +| **High (H)** | 0.56 | Total service disruption | System crash, complete DoS | +| **Low (L)** | 0.22 | Reduced performance | Resource exhaustion, slowdown | +| **None (N)** | 0.00 | No availability impact | Information disclosure only | + +## CVSS Score Calculation + +### Base Score Formula + +The CVSS v3.1 base score is calculated using a complex formula: + +``` +Impact = 1 - [(1 - C) × (1 - I) × (1 - A)] + +If Scope Unchanged: + BaseScore = Roundup(Minimum[(Impact + Exploitability), 10]) + +If Scope Changed: + BaseScore = Roundup(Minimum[1.08 × (Impact + Exploitability), 10]) + +Where: +Exploitability = 8.22 × AV × AC × PR × UI +``` + +**You don't need to calculate manually** - use CVSS calculators: +- FIRST CVSS Calculator: https://www.first.org/cvss/calculator/3.1 +- Red Hat CVE pages include calculated scores + +### CVSS Severity Ratings (FIRST Standard) + +| CVSS Score | Severity | Description | +|------------|----------|-------------| +| 9.0 - 10.0 | **Critical** | Easily exploitable, severe impact | +| 7.0 - 8.9 | **High** | Exploitable with moderate effort, significant impact | +| 4.0 - 6.9 | **Medium** | Requires specific conditions, moderate impact | +| 0.1 - 3.9 | **Low** | Difficult to exploit, limited impact | +| 0.0 | **None** | No impact | + +## Red Hat Severity Ratings + +Red Hat uses a **4-point severity scale** that may differ from CVSS: + +### Red Hat Severity Levels + +| Severity | Typical CVSS Range | Description | Response Time | Example | +|----------|-------------------|-------------|---------------|---------| +| **Critical** | 9.0-10.0 | Easily exploitable, widespread impact, remote code execution | 24-48 hours | Heartbleed, Shellshock | +| **Important** | 7.0-8.9 | Exploitable, significant impact, requires moderate effort | 7 days | Privilege escalation, data leak | +| **Moderate** | 4.0-6.9 | Requires specific conditions, limited scope | 30 days | Local DoS, limited info disclosure | +| **Low** | 0.1-3.9 | Difficult to exploit, minimal impact | 90 days | Minor information leaks | + +### Why Red Hat Severity ≠ CVSS Score + +Red Hat Product Security considers additional factors: + +**Exploitability in Real World**: +- Is the vulnerable code path actually used in typical RHEL deployments? +- Are default RHEL configurations vulnerable? +- Do RHEL security features (SELinux, firewall) mitigate the vulnerability? + +**Example 1: CVSS Higher Than Red Hat Severity** +``` +CVE: CVE-2024-XXXX +CVSS Score: 8.5 (High) +Red Hat Severity: Moderate + +Reason: +- Vulnerability requires non-default configuration +- Feature rarely enabled in production RHEL systems +- SELinux blocks exploitation in enforcing mode +- Red Hat downgrades to Moderate based on real-world risk +``` + +**Example 2: Red Hat Severity Higher Than CVSS** +``` +CVE: CVE-2024-YYYY +CVSS Score: 6.5 (Medium) +Red Hat Severity: Important + +Reason: +- CVSS calculated for generic software +- In RHEL context, vulnerability is more exploitable +- Commonly used RHEL service affected +- Red Hat elevates to Important based on customer environment +``` + +## Priority Decision Matrix + +Combine Red Hat severity with other factors to determine priority: + +### Priority Calculation + +| Red Hat Severity | Vulnerable Status | Production System | Known Exploit | Priority | Response | +|------------------|------------------|-------------------|---------------|----------|----------| +| Critical | Vulnerable | Yes | Yes | **P0** | 24 hours | +| Critical | Vulnerable | Yes | No | **P0** | 48 hours | +| Critical | Vulnerable | No | - | **P1** | 7 days | +| Important | Vulnerable | Yes | Yes | **P1** | 7 days | +| Important | Vulnerable | Yes | No | **P1** | 14 days | +| Important | Vulnerable | No | - | **P2** | 30 days | +| Moderate | Vulnerable | Yes | - | **P2** | 30 days | +| Moderate | Vulnerable | No | - | **P3** | 90 days | +| Low | Vulnerable | - | - | **P3** | 90 days | +| Any | Affected but not vulnerable | - | - | **P3** | Next maintenance window | + +### Decision Tree + +``` +1. What is Red Hat Severity? + ├─ Critical → Continue to 2 + ├─ Important → Continue to 2 + ├─ Moderate → P2 (unless production + exploit = P2) + └─ Low → P3 + +2. Is system Vulnerable or Affected but not vulnerable? + ├─ Vulnerable → Continue to 3 + └─ Affected but not vulnerable → P3 + +3. Is this a production system? + ├─ Yes → Continue to 4 + └─ No → P1 (Critical) or P2 (Important) + +4. Is exploit known/available? + ├─ Yes → P0 + └─ No → P0 (Critical) or P1 (Important) +``` + +## CVSS Vector String + +CVSS scores include a **vector string** encoding all metrics: + +**Example Vector String**: +``` +CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H +``` + +**Decoded**: +- **AV:N** - Attack Vector: Network +- **AC:L** - Attack Complexity: Low +- **PR:N** - Privileges Required: None +- **UI:N** - User Interaction: None +- **S:C** - Scope: Changed +- **C:H** - Confidentiality Impact: High +- **I:H** - Integrity Impact: High +- **A:H** - Availability Impact: High + +**Score**: 10.0 (Critical) + +**Interpretation**: Remotely exploitable, no authentication, no user interaction, impacts all CIA aspects - **highest severity**. + +## Common CVE Patterns + +### Pattern 1: Critical Remote Code Execution + +**Typical Metrics**: +- AV:N (Network) +- AC:L (Low complexity) +- PR:N (No privileges) +- UI:N (No interaction) +- C:H/I:H/A:H (Full impact) + +**CVSS Score**: 9.0-10.0 +**Red Hat Severity**: Critical +**Example**: Heartbleed (CVE-2014-0160) + +**Priority**: P0 - Immediate remediation + +### Pattern 2: Privilege Escalation + +**Typical Metrics**: +- AV:L (Local) +- AC:L (Low complexity) +- PR:L (Low privileges) +- UI:N (No interaction) +- C:H/I:H/A:H (Full impact after escalation) + +**CVSS Score**: 7.8 +**Red Hat Severity**: Important +**Example**: Dirty COW (CVE-2016-5195) + +**Priority**: P1 - 7 day remediation window + +### Pattern 3: Information Disclosure + +**Typical Metrics**: +- AV:N (Network) +- AC:L (Low complexity) +- PR:N (No privileges) +- UI:N (No interaction) +- C:H/I:N/A:N (Confidentiality only) + +**CVSS Score**: 7.5 +**Red Hat Severity**: Important or Moderate (depends on data sensitivity) + +**Priority**: P1-P2 depending on data criticality + +### Pattern 4: Denial of Service + +**Typical Metrics**: +- AV:N (Network) +- AC:L (Low complexity) +- PR:N (No privileges) +- UI:N (No interaction) +- C:N/I:N/A:H (Availability only) + +**CVSS Score**: 7.5 +**Red Hat Severity**: Moderate (unless critical service) + +**Priority**: P2 - 30 days (unless high-availability requirement) + +## Compliance Framework Mappings + +### PCI-DSS Requirements + +**PCI-DSS v4.0 Requirement 6.3.3**: Patch critical and high vulnerabilities within defined timeframes + +| CVSS Score | PCI-DSS Timeline | Remediation Deadline | +|------------|------------------|----------------------| +| 9.0-10.0 (Critical) | Within 30 days | **30 days max** | +| 7.0-8.9 (High) | Within 30 days | **30 days max** | +| 4.0-6.9 (Medium) | Risk-based approach | Organization-defined | +| 0.1-3.9 (Low) | Risk-based approach | Organization-defined | + +**Compliance Note**: PCI-DSS uses CVSS scores, not Red Hat severity ratings. + +### SOC 2 Trust Service Criteria + +**CC7.1**: Detect and respond to security incidents + +- **All CVSS 7.0+**: Must be tracked, remediated, documented +- **Remediation process**: Must demonstrate timely response +- **Audit trail**: Document priority decisions and remediation timeline + +### NIST 800-53 + +**SI-2**: Flaw Remediation + +- **High-impact systems**: Remediate high/critical within 30 days +- **Moderate-impact**: Remediate within 60 days +- **Low-impact**: Remediate within 90 days + +Map CVSS to NIST impact: +- CVSS 9.0-10.0 → High impact +- CVSS 7.0-8.9 → Moderate impact +- CVSS < 7.0 → Low impact + +See: [compliance-frameworks.md](compliance-frameworks.md) for detailed mappings + +## Real-World Examples + +### Example 1: Log4Shell (CVE-2021-44228) + +**CVSS v3.1 Vector**: +``` +CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H +``` + +**Metrics**: +- Attack Vector: Network (remotely exploitable) +- Attack Complexity: Low (trivial to exploit) +- Privileges Required: None (unauthenticated) +- User Interaction: None (fully automated) +- Scope: Changed (RCE impacts entire system) +- Impact: H/H/H (full compromise) + +**Score**: 10.0 +**Red Hat Severity**: Critical +**Response**: P0 - Immediate remediation (24 hours) + +**Why P0**: +- Remotely exploitable +- No authentication +- Widespread usage (logging library) +- Active exploitation in wild +- Full system compromise possible + +### Example 2: Spectre Variant 1 (CVE-2017-5753) + +**CVSS v3.1 Vector**: +``` +CVSS:3.1/AV:L/AC:H/PR:L/UI:N/S:C/C:H/I:N/A:N +``` + +**Metrics**: +- Attack Vector: Local (requires local access) +- Attack Complexity: High (timing attack, difficult) +- Privileges Required: Low (unprivileged user) +- Scope: Changed (can read across privilege boundaries) +- Impact: C:H (information disclosure), I:N, A:N + +**Score**: 5.6 (Medium by CVSS) +**Red Hat Severity**: Important (elevated due to CPU-level impact) +**Response**: P1 - 7 day remediation window + +**Why Red Hat Elevated**: +- Affects all modern CPUs +- Hardware-level vulnerability +- Difficult to fully mitigate +- Widespread impact across cloud/virtualization + +### Example 3: Sudo Heap Overflow (CVE-2021-3156) + +**CVSS v3.1 Vector**: +``` +CVSS:3.1/AV:L/AC:L/PR:L/UI:N/S:U/C:H/I:H/A:H +``` + +**Metrics**: +- Attack Vector: Local +- Attack Complexity: Low (reliable exploit available) +- Privileges Required: Low (any local user) +- Scope: Unchanged +- Impact: H/H/H (root access) + +**Score**: 7.8 (High) +**Red Hat Severity**: Important +**Response**: P1 - 7 days + +**Why Important**: +- Local privilege escalation to root +- sudo installed by default on all RHEL systems +- Any local user can exploit +- Reliable exploits available + +## Integration with Remediation Agent + +### CVE Impact Skill Workflow + +```yaml +# Step 1: Retrieve CVE data (use vulnerability-logic.md) +- Get CVSS score from Red Hat Lightspeed +- Get Red Hat severity rating +- Check vulnerable vs affected status + +# Step 2: Interpret CVSS (use THIS document) +- Understand CVSS metrics (AV, AC, PR, UI, S, C, I, A) +- Map CVSS to Red Hat severity +- Check for discrepancies (explain to user) + +# Step 3: Calculate priority (use THIS document) +- Apply priority decision matrix +- Consider: severity + vulnerable status + production + exploit +- Output: P0/P1/P2/P3 with reasoning + +# Step 4: Recommend action +- P0: Immediate remediation (use cve-remediation-templates.md) +- P1: Schedule within 7 days +- P2: Next maintenance window +- P3: Backlog +``` + +### Remediator Agent Integration + +```yaml +# Input from CVE Impact Skill: +priority: P0 +cvss_score: 9.8 +red_hat_severity: Critical +reasoning: "Network RCE, no auth required, production systems affected" + +# Remediator Agent Decision: +if priority == "P0": + - Generate playbook immediately (Template 1 or 4) + - Recommend emergency change process + - Execute with minimal delay + +if priority == "P1": + - Generate playbook + - Schedule maintenance window + - Allow time for testing in staging + +if priority == "P2" or "P3": + - Add to remediation backlog + - Batch with other low-priority CVEs + - Include in next quarterly patching cycle +``` + +## Best Practices + +### 1. Trust Red Hat Severity Over Raw CVSS + +Red Hat Product Security analyzes vulnerabilities in the context of RHEL systems. Their severity ratings account for: +- Default RHEL configurations +- SELinux policies +- Firewall defaults +- Real-world usage patterns + +✅ **Use Red Hat severity for prioritization decisions** +⚠️ CVSS is a helpful reference but not the sole factor + +### 2. Document Prioritization Decisions + +Create an audit trail: +```markdown +CVE-2024-XXXX Prioritization Decision +Date: 2024-01-15 +CVSS Score: 8.5 (High) +Red Hat Severity: Moderate +Assigned Priority: P2 + +Rationale: +- CVSS high due to network vector +- Red Hat downgraded to Moderate (non-default config required) +- No active exploitation detected +- Non-production systems only affected +- Decision: P2 (30-day remediation window) + +Approved by: [Security Team Lead] +``` + +### 3. Re-evaluate on New Information + +Priorities can change: +- **Exploit published**: P2 → P1 +- **Active exploitation**: Any → P0 +- **Configuration change**: Affected but not vulnerable → Vulnerable + +Set up alerts for CVE status changes. + +### 4. Communicate in Business Terms + +Translate CVSS for stakeholders: + +**For Technical Teams**: +``` +CVE-2024-XXXX: CVSS 9.8 (Critical) +Attack Vector: Network, No Auth Required +Impact: Remote Code Execution +Priority: P0 - Patch within 24 hours +``` + +**For Management**: +``` +CVE-2024-XXXX: Critical Severity +Risk: Attackers can remotely compromise our web servers +Business Impact: Customer data exposure, service outage +Action Required: Emergency patching tonight +Estimated Downtime: 30 minutes per server +``` + +## Quick Reference + +### CVSS to Red Hat Severity (Typical Mapping) + +| CVSS Range | Red Hat Severity | Priority | Response Time | +|------------|------------------|----------|---------------| +| 9.0-10.0 | Critical | P0 | 24-48 hours | +| 7.0-8.9 | Important | P1 | 7 days | +| 4.0-6.9 | Moderate | P2 | 30 days | +| 0.1-3.9 | Low | P3 | 90 days | + +**Note**: Actual Red Hat severity may differ - always check CVE page. + +### Priority Override Conditions + +Escalate priority if: +- **Active exploitation** detected (any severity → P0) +- **Production critical system** affected (+1 priority level) +- **Compliance deadline** approaching (adjust to meet deadline) +- **Wormable vulnerability** (self-propagating → P0) + +Downgrade priority if: +- **Affected but not vulnerable** (-1 priority level) +- **Non-production only** (-1 priority level) +- **Compensating controls** in place (-1 priority level) + +## Related Documentation + +- **[Red Hat Lightspeed Vulnerability Logic](../insights/vulnerability-logic.md)** - How Lightspeed assesses CVEs +- **[CVE Remediation Templates](../ansible/cve-remediation-templates.md)** - Playbooks for remediation +- **[Compliance Frameworks](compliance-frameworks.md)** - PCI-DSS, SOC 2, NIST requirements + +## Official Red Hat Sources + +This document is derived from: + +1. **Severity Ratings** + https://access.redhat.com/security/updates/classification + +2. **How We Classify Security Severity Levels** + https://access.redhat.com/solutions/725593 + +3. **Security Update Policy** + https://access.redhat.com/security/lifecycle-security-update-policy + +4. **Product Security Center** + https://access.redhat.com/security/ + +**License**: Content derived from Red Hat documentation under CC BY-SA 4.0 +**Last Verified**: 2026-01-20 diff --git a/submissions/mcp-aap-validator/skills/references/lightspeed-mcp-parameters.md b/submissions/mcp-aap-validator/skills/references/lightspeed-mcp-parameters.md new file mode 100644 index 0000000..212ee6c --- /dev/null +++ b/submissions/mcp-aap-validator/skills/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/RedHatInsights/insights-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/submissions/mcp-aap-validator/skills/references/lightspeed-mcp-tool-failures.md b/submissions/mcp-aap-validator/skills/references/lightspeed-mcp-tool-failures.md new file mode 100644 index 0000000..f2c661b --- /dev/null +++ b/submissions/mcp-aap-validator/skills/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/submissions/mcp-aap-validator/skills/references/package-management.md b/submissions/mcp-aap-validator/skills/references/package-management.md new file mode 100644 index 0000000..f7e4252 --- /dev/null +++ b/submissions/mcp-aap-validator/skills/references/package-management.md @@ -0,0 +1,738 @@ +--- +title: RHEL Package Management for CVE Remediation +category: rhel +sources: + - title: Managing Software with the DNF Tool (RHEL 9) + url: https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html-single/managing_software_with_the_dnf_tool/index + sections: DNF commands, updating packages, repository management + date_accessed: 2026-01-20 + - title: Software Management in RHEL 9 Adoption Guide + url: https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/considerations_in_adopting_rhel_9/assembly_software-management_considerations-in-adopting-rhel-9 + sections: RHEL 7/8/9 compatibility, migration considerations + date_accessed: 2026-01-20 + - title: Updating RHEL 9 Content + url: https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/managing_software_with_the_dnf_tool/assembly_updating-rhel-9-content_managing-software-with-the-dnf-tool + sections: Package update procedures, reboot detection + date_accessed: 2026-01-20 +tags: [dnf, yum, package-management, rhel, updates, systemd, reboot-detection] +applies_to: [rhel7, rhel8, rhel9] +semantic_keywords: + - "DNF package manager" + - "YUM package manager" + - "package update" + - "repository management" + - "reboot detection" + - "systemd service management" + - "needs-restarting" + - "subscription manager" +use_cases: + - "package_update_cve" + - "rhel_version_compatibility" + - "reboot_detection" + - "service_restart_after_update" +related_docs: + - "ansible/cve-remediation-templates.md" + - "rhel/version-compatibility.md" + - "rhel/systemd-services.md" +last_updated: 2026-01-20 +--- + +# RHEL Package Management for CVE Remediation + +This document provides comprehensive guidance on package management across RHEL 7, 8, and 9 for CVE remediation scenarios. + +## Overview + +Red Hat Enterprise Linux uses different package managers across versions: +- **RHEL 7**: YUM (Yellowdog Updater Modified) +- **RHEL 8**: DNF (Dandified YUM) with `yum` as an alias +- **RHEL 9**: DNF with `yum` as an alias + +**Key Insight**: In RHEL 8 and 9, `yum` is a symbolic link to `dnf` for backward compatibility. All YUM commands work identically in RHEL 8/9 via DNF. + +## DNF vs YUM Command Compatibility + +### Command Equivalence Table + +| Operation | RHEL 7 (YUM) | RHEL 8/9 (DNF) | Notes | +|-----------|--------------|----------------|-------| +| Update package | `yum update httpd` | `dnf update httpd` or `yum update httpd` | Identical behavior | +| Install package | `yum install httpd` | `dnf install httpd` or `yum install httpd` | Identical behavior | +| Remove package | `yum remove httpd` | `dnf remove httpd` or `yum remove httpd` | Identical behavior | +| Search packages | `yum search keyword` | `dnf search keyword` or `yum search keyword` | Identical behavior | +| List installed | `yum list installed` | `dnf list installed` or `yum list installed` | Identical behavior | +| Clean cache | `yum clean all` | `dnf clean all` or `yum clean all` | Identical behavior | +| Check updates | `yum check-update` | `dnf check-update` or `yum check-update` | Identical behavior | + +### Ansible Module Compatibility + +```yaml +# RHEL 7 - Use yum module +- name: Update packages (RHEL 7) + yum: + name: httpd + state: latest + when: ansible_distribution_major_version == "7" + +# RHEL 8/9 - Use dnf module (preferred) +- name: Update packages (RHEL 8/9) + dnf: + name: httpd + state: latest + when: ansible_distribution_major_version in ["8", "9"] + +# Universal approach - yum module works on all versions +- name: Update packages (All RHEL versions) + package: + name: httpd + state: latest + # Uses appropriate package manager automatically +``` + +## Package Update Patterns for CVE Remediation + +### Pattern 1: Single Package Update + +**Use Case**: CVE affects a specific package (e.g., httpd, openssl, glibc) + +```yaml +- name: Update vulnerable package + dnf: + name: httpd + state: latest + update_cache: true + register: package_update + when: ansible_distribution_major_version in ["8", "9"] + +- name: Update vulnerable package (RHEL 7) + yum: + name: httpd + state: latest + update_cache: true + register: package_update + when: ansible_distribution_major_version == "7" +``` + +**Key Options**: +- `state: latest` - Updates to newest available version +- `update_cache: true` - Refreshes repository metadata before update +- `register: package_update` - Captures update results for verification + +### Pattern 2: Multiple Related Packages + +**Use Case**: CVE affects a package and its dependencies (e.g., openssl + openssl-libs) + +```yaml +- name: Update vulnerable packages and dependencies + dnf: + name: + - openssl + - openssl-libs + - openssl-devel + state: latest + update_cache: true + register: package_update +``` + +**Why This Matters**: Some CVEs affect shared libraries. Updating only the main package may leave vulnerabilities in dependent libraries. + +### Pattern 3: Kernel Package Updates + +**Use Case**: Kernel CVEs requiring reboot + +```yaml +- name: Update kernel package + dnf: + name: kernel + state: latest + update_cache: true + register: kernel_update + +- name: Record current kernel before reboot + command: uname -r + register: current_kernel + changed_when: false + +# Reboot will be handled separately +# See: Template 4 in cve-remediation-templates.md +``` + +**Important**: Kernel updates **always** require a reboot. New kernel is not active until system restarts. + +### Pattern 4: Security-Only Updates + +**Use Case**: Apply only security updates, not all available updates + +```bash +# RHEL 8/9 - Security updates only +dnf update --security + +# RHEL 7 - Requires yum-plugin-security +yum update --security +``` + +**Ansible Equivalent**: +```yaml +- name: Apply security updates only (RHEL 8/9) + command: dnf update -y --security + register: security_updates + when: ansible_distribution_major_version in ["8", "9"] +``` + +## Repository Management + +### Enabling/Disabling Repositories + +```yaml +- name: Enable repository for specific package + command: subscription-manager repos --enable=rhel-9-for-x86_64-appstream-rpms + when: ansible_distribution_major_version == "9" + +- name: Update package from specific repo + dnf: + name: httpd + state: latest + enablerepo: rhel-9-for-x86_64-appstream-rpms +``` + +### Repository List (RHEL 9) + +Common repositories for CVE remediation: +- `rhel-9-for-x86_64-baseos-rpms` - Base OS packages +- `rhel-9-for-x86_64-appstream-rpms` - Application streams +- `rhel-9-for-x86_64-supplementary-rpms` - Supplementary packages + +### Verifying Repository Configuration + +```yaml +- name: List enabled repositories + command: subscription-manager repos --list-enabled + register: enabled_repos + changed_when: false + +- name: Display enabled repos + debug: + msg: "{{ enabled_repos.stdout_lines }}" +``` + +## Reboot Detection Patterns + +### Method 1: Check for Reboot-Required File + +```yaml +- name: Check if reboot is required (file-based) + stat: + path: /var/run/reboot-required + register: reboot_required_file + +- name: Notify if reboot needed + debug: + msg: "⚠️ System reboot required" + when: reboot_required_file.stat.exists +``` + +**Note**: Not all RHEL systems create this file. More reliable method below. + +### Method 2: needs-restarting Command (RHEL 8/9) + +**Most Reliable Method for RHEL 8/9** + +```yaml +- name: Check if reboot is required (needs-restarting) + command: needs-restarting -r + register: needs_restarting + failed_when: false + changed_when: false + when: ansible_distribution_major_version in ["8", "9"] + +- name: Determine reboot requirement + set_fact: + reboot_required: "{{ needs_restarting.rc != 0 }}" + when: ansible_distribution_major_version in ["8", "9"] + +- name: Display reboot status + debug: + msg: "Reboot required: {{ reboot_required }}" +``` + +**Exit Codes**: +- `0` - No reboot required +- `1` - Reboot required (kernel, glibc, systemd, or other core component updated) + +### Method 3: Check Specific Package Updates + +```yaml +- name: Check if kernel was updated + shell: | + LATEST_KERNEL=$(rpm -q kernel --last | head -1 | awk '{print $1}') + RUNNING_KERNEL=$(uname -r) + if [[ "$LATEST_KERNEL" != "kernel-$RUNNING_KERNEL" ]]; then + echo "reboot_needed" + fi + register: kernel_check + changed_when: false + +- name: Set reboot flag if kernel changed + set_fact: + reboot_required: true + when: "'reboot_needed' in kernel_check.stdout" +``` + +### Comprehensive Reboot Detection + +**Recommended Pattern for CVE Remediation**: + +```yaml +- name: Comprehensive reboot detection + block: + - name: Check needs-restarting (RHEL 8/9) + command: needs-restarting -r + register: needs_restarting + failed_when: false + changed_when: false + when: ansible_distribution_major_version in ["8", "9"] + + - name: Check reboot-required file + stat: + path: /var/run/reboot-required + register: reboot_file + + - name: Check if kernel was updated + shell: | + rpm -q --last kernel | head -1 | \ + grep -q "$(uname -r)" || echo "kernel_updated" + register: kernel_check + changed_when: false + failed_when: false + + - name: Determine final reboot requirement + set_fact: + reboot_required: > + {{ + reboot_file.stat.exists | default(false) or + (needs_restarting.rc != 0 | default(false)) or + ('kernel_updated' in kernel_check.stdout) + }} + + - name: Display reboot requirement + debug: + msg: | + Reboot Required: {{ reboot_required }} + Reason: {% if reboot_file.stat.exists %}reboot-required file exists{% elif needs_restarting.rc != 0 %}needs-restarting check{% elif 'kernel_updated' in kernel_check.stdout %}kernel update{% else %}unknown{% endif %} +``` + +## Service Restart After Package Updates + +### Pattern 1: Restart Specific Services + +```yaml +- name: Restart httpd after package update + systemd: + name: httpd + state: restarted + when: + - package_update is changed + - not reboot_required + +- name: Wait for service to be active + systemd: + name: httpd + state: started + retries: 3 + delay: 5 +``` + +### Pattern 2: Restart Services Requiring Updates (RHEL 8/9) + +```yaml +- name: Find services that need restarting + command: needs-restarting -s + register: services_to_restart + changed_when: false + when: ansible_distribution_major_version in ["8", "9"] + +- name: Parse service names + set_fact: + service_list: "{{ services_to_restart.stdout_lines | map('regex_replace', '^(.+)\\.service$', '\\1') | list }}" + when: services_to_restart.stdout_lines | length > 0 + +- name: Restart services that need it + systemd: + name: "{{ item }}" + state: restarted + loop: "{{ service_list }}" + when: + - service_list is defined + - not reboot_required + ignore_errors: true +``` + +**`needs-restarting -s` Output Example**: +``` +httpd.service +NetworkManager.service +sshd.service +``` + +### Pattern 3: Conditional Service Restart Based on Package + +```yaml +- name: Map packages to services + set_fact: + package_service_map: + httpd: httpd + nginx: nginx + sshd: sshd + openssl: [httpd, nginx, sshd] # Multiple services may use openssl + +- name: Restart services for updated packages + systemd: + name: "{{ package_service_map[item] }}" + state: restarted + loop: "{{ package_update.results | map(attribute='item') | list }}" + when: + - package_update is changed + - item in package_service_map + - not reboot_required +``` + +## Package Version Verification + +### Pre/Post Update Version Comparison + +```yaml +- name: Gather package facts before update + package_facts: + manager: auto + +- name: Record pre-update versions + set_fact: + pre_update_versions: "{{ ansible_facts.packages }}" + +- name: Update packages + dnf: + name: "{{ vulnerable_packages }}" + state: latest + register: package_update + +- name: Gather package facts after update + package_facts: + manager: auto + +- name: Compare versions + debug: + msg: | + Package: {{ item }} + Before: {{ pre_update_versions[item][0].version | default('not installed') }} + After: {{ ansible_facts.packages[item][0].version | default('not installed') }} + loop: "{{ vulnerable_packages }}" + when: item in ansible_facts.packages +``` + +### Verify Specific Package Version + +```yaml +- name: Verify package is at required version + shell: | + rpm -q {{ package_name }} --queryformat '%{VERSION}-%{RELEASE}' + register: package_version + changed_when: false + +- name: Assert minimum version + assert: + that: + - package_version.stdout is version(minimum_version, '>=') + fail_msg: "Package {{ package_name }} is {{ package_version.stdout }}, required >= {{ minimum_version }}" + success_msg: "Package {{ package_name }} version {{ package_version.stdout }} meets requirements" +``` + +## Rollback and Backup Strategies + +### RHEL 8/9 Snapshot with Boom + +```yaml +- name: Install boom-boot (if not present) + dnf: + name: boom-boot + state: present + when: ansible_distribution_major_version in ["8", "9"] + +- name: Create pre-update snapshot + command: boom create --title "pre-cve-{{ cve_id }}-{{ ansible_date_time.epoch }}" + register: snapshot_result + ignore_errors: true + when: ansible_distribution_major_version in ["8", "9"] + +- name: Log snapshot creation + debug: + msg: "Snapshot created: {{ snapshot_result.stdout }}" + when: snapshot_result is success +``` + +### Package Downgrade (Emergency Rollback) + +```yaml +- name: Downgrade package to previous version + dnf: + name: httpd-2.4.37-1.el8 + state: present + allow_downgrade: true + when: ansible_distribution_major_version in ["8", "9"] + +- name: Downgrade package (RHEL 7) + yum: + name: httpd-2.4.37-1.el7 + state: present + when: ansible_distribution_major_version == "7" +``` + +**Warning**: Downgrades should be rare and only for emergency rollback. May cause dependency issues. + +## Subscription Manager Integration + +### Verify System Registration + +```yaml +- name: Check subscription status + command: subscription-manager status + register: subscription_status + changed_when: false + failed_when: false + +- name: Assert system is registered + assert: + that: + - "'Overall Status: Current' in subscription_status.stdout or 'Overall Status: Simple Content Access' in subscription_status.stdout" + fail_msg: "System is not properly subscribed to Red Hat repositories" + success_msg: "System subscription is current" +``` + +### Refresh Subscription + +```yaml +- name: Refresh subscription data + command: subscription-manager refresh + when: subscription_status.rc != 0 + +- name: Update repository metadata + command: dnf clean all && dnf makecache + when: ansible_distribution_major_version in ["8", "9"] +``` + +## RHEL Version-Specific Considerations + +### RHEL 7 + +- **Package Manager**: YUM (Python 2.7-based) +- **Systemd Version**: 219 +- **Reboot Detection**: No `needs-restarting -r`, use alternative methods +- **Security Updates**: Requires `yum-plugin-security` package + +```yaml +- name: Install security plugin (RHEL 7) + yum: + name: yum-plugin-security + state: present + when: ansible_distribution_major_version == "7" +``` + +### RHEL 8 + +- **Package Manager**: DNF 4.x (Python 3.6-based), `yum` is alias +- **Systemd Version**: 239 +- **Reboot Detection**: `needs-restarting -r` available +- **Module Streams**: AppStream concept introduced + +```yaml +- name: Enable module stream (RHEL 8) + command: dnf module enable httpd:2.4 -y + when: ansible_distribution_major_version == "8" +``` + +### RHEL 9 + +- **Package Manager**: DNF 4.x (Python 3.9-based), `yum` is alias +- **Systemd Version**: 252 +- **Reboot Detection**: `needs-restarting -r` available +- **New in 9.7**: Multisig DNF plugin for quantum-safe RPM verification + +```yaml +- name: Install multisig plugin (RHEL 9.7+) + dnf: + name: python3-dnf-plugin-multisig + state: present + when: + - ansible_distribution_major_version == "9" + - ansible_distribution_version is version('9.7', '>=') +``` + +## Common Pitfalls and Solutions + +### Pitfall 1: Not Refreshing Repository Cache + +**Problem**: Updates fail or don't detect new packages +**Solution**: Always use `update_cache: true` + +```yaml +# ❌ Bad - may miss new package versions +- dnf: + name: httpd + state: latest + +# ✅ Good - ensures latest metadata +- dnf: + name: httpd + state: latest + update_cache: true +``` + +### Pitfall 2: Ignoring Reboot Requirements + +**Problem**: CVE remains exploitable after "update" +**Solution**: Always check and handle reboots + +```yaml +# ✅ Complete pattern +- name: Update package + dnf: + name: kernel + state: latest + +- name: Check reboot requirement + command: needs-restarting -r + register: needs_reboot + failed_when: false + +- name: Notify if reboot needed + debug: + msg: "⚠️ REBOOT REQUIRED - CVE not fully remediated until reboot" + when: needs_reboot.rc != 0 +``` + +### Pitfall 3: Not Verifying Package Update Success + +**Problem**: Package update silently fails, CVE remains +**Solution**: Use `register` and verify changes + +```yaml +- name: Update package + dnf: + name: httpd + state: latest + register: package_update + +- name: Verify update occurred + assert: + that: + - package_update is changed or package_update is success + fail_msg: "Package update failed - CVE remediation incomplete" +``` + +### Pitfall 4: Restarting Services When Reboot Required + +**Problem**: Wasted effort, service restart won't apply kernel updates +**Solution**: Conditional service restarts + +```yaml +- name: Restart service only if no reboot needed + systemd: + name: httpd + state: restarted + when: + - package_update is changed + - not reboot_required # Don't restart if rebooting anyway +``` + +### Pitfall 5: Using Wrong Package Manager Module + +**Problem**: Playbook fails on different RHEL versions +**Solution**: Use version-conditional tasks or `package` module + +```yaml +# ✅ Best - works on all RHEL versions +- name: Update package (universal) + package: + name: httpd + state: latest + +# ✅ Also good - version-specific +- name: Update package (RHEL 8/9) + dnf: + name: httpd + state: latest + when: ansible_distribution_major_version in ["8", "9"] +``` + +## Quick Reference Commands + +### Package Operations +```bash +# Update single package +dnf update httpd + +# Update all security patches +dnf update --security + +# Update multiple packages +dnf update httpd httpd-tools + +# Check for available updates +dnf check-update + +# List installed packages +dnf list installed + +# Show package info +dnf info httpd + +# Search for package +dnf search webserver +``` + +### Reboot Detection +```bash +# Check if reboot needed (RHEL 8/9) +needs-restarting -r + +# List services needing restart +needs-restarting -s + +# Check current kernel vs installed +uname -r +rpm -q kernel --last | head -1 +``` + +### Repository Management +```bash +# List enabled repos +subscription-manager repos --list-enabled + +# Enable specific repo +subscription-manager repos --enable=repo-name + +# Refresh repo metadata +dnf clean all && dnf makecache +``` + +## Related Documentation + +- **[CVE Remediation Templates](../ansible/cve-remediation-templates.md)** - Playbook templates using these patterns +- **[RHEL Version Compatibility](version-compatibility.md)** - Detailed RHEL 7/8/9 differences +- **[Systemd Services](systemd-services.md)** - Service management patterns +- **[SELinux Context](selinux-context.md)** - SELinux considerations for package updates + +## Official Red Hat Sources + +This document is derived from: + +1. **Managing Software with the DNF Tool (RHEL 9)** + https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html-single/managing_software_with_the_dnf_tool/index + +2. **Software Management in RHEL 9 Adoption Guide** + https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/considerations_in_adopting_rhel_9/assembly_software-management_considerations-in-adopting-rhel-9 + +3. **Updating RHEL 9 Content** + https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/managing_software_with_the_dnf_tool/assembly_updating-rhel-9-content_managing-software-with-the-dnf-tool + +**License**: Content derived from Red Hat documentation under CC BY-SA 4.0 +**Last Verified**: 2026-01-20 diff --git a/submissions/mcp-aap-validator/skills/references/playbook-integration-aap.md b/submissions/mcp-aap-validator/skills/references/playbook-integration-aap.md new file mode 100644 index 0000000..806841f --- /dev/null +++ b/submissions/mcp-aap-validator/skills/references/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/submissions/mcp-aap-validator/skills/references/skill-invocation.md b/submissions/mcp-aap-validator/skills/references/skill-invocation.md new file mode 100644 index 0000000..132854c --- /dev/null +++ b/submissions/mcp-aap-validator/skills/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/submissions/mcp-aap-validator/skills/references/vulnerability-logic.md b/submissions/mcp-aap-validator/skills/references/vulnerability-logic.md new file mode 100644 index 0000000..0edc1eb --- /dev/null +++ b/submissions/mcp-aap-validator/skills/references/vulnerability-logic.md @@ -0,0 +1,568 @@ +--- +title: Red Hat Lightspeed Vulnerability Assessment Logic +category: insights +sources: + - title: Assessing and Monitoring Security Vulnerabilities on RHEL Systems + url: https://docs.redhat.com/en/documentation/red_hat_insights/1-latest/html/assessing_and_monitoring_security_vulnerabilities_on_rhel_systems/vuln-cves_vuln-overview + sections: CVE identification, classification, threat intelligence + date_accessed: 2026-01-20 + - title: Generating Vulnerability Service Reports + url: https://access.redhat.com/documentation/en-us/red_hat_insights/1-latest/html-single/generating_vulnerability_service_reports/index + sections: Executive reports, CVE reports, data export + date_accessed: 2026-01-20 + - title: Red Hat CVE Database + url: https://access.redhat.com/security/security-updates/cve + sections: Official CVE entries, security updates + date_accessed: 2026-01-20 + - title: A Complete View of System Vulnerabilities + url: https://www.redhat.com/en/blog/complete-view-system-vulnerabilities-using-red-hat-insights + sections: Vulnerability service overview, best practices + date_accessed: 2026-01-20 +tags: [insights, vulnerability, cve, risk-assessment, threat-intelligence] +applies_to: [rhel6, rhel7, rhel8, rhel9] +semantic_keywords: + - "Red Hat Lightspeed" + - "CVE assessment" + - "vulnerability classification" + - "threat intelligence" + - "security rules" + - "affected but not vulnerable" + - "vulnerable status" + - "CVSS score" + - "severity rating" + - "remediation priority" +use_cases: + - "risk_assessment" + - "cve_impact_analysis" + - "remediation_prioritization" + - "vulnerability_reporting" +related_docs: + - "references/cvss-scoring.md" + - "ansible/cve-remediation-templates.md" + - "references/compliance-frameworks.md" +last_updated: 2026-01-20 +--- + +# Red Hat Lightspeed Vulnerability Assessment Logic + +This document explains how Red Hat Lightspeed assesses CVE vulnerabilities, classifies risk, and prioritizes remediation for RHEL systems. + +## Overview + +The Red Hat Lightspeed vulnerability service provides automated CVE assessment for RHEL systems registered with Lightspeed. It analyzes CVE impact, determines exploitability, and generates remediation recommendations. + +**Key Capabilities**: +- Automated CVE identification on registered systems +- Threat intelligence integration +- Remediation playbook generation +- Executive and technical reporting +- Compliance tracking + +## CVE Classification + +### Vulnerable vs Affected But Not Vulnerable + +Red Hat Lightspeed categorizes CVEs into two primary classifications: + +#### Vulnerable +**Definition**: System is running flawed code with an **open path to exploitation**. + +**Characteristics**: +- CVE exists in installed package +- No mitigating factors present +- Exploit path is viable +- System is exposed to risk + +**Example**: RHEL 8 system running `httpd-2.4.37-1.el8` with CVE-2024-1234 affecting versions < 2.4.37-2.el8 +- Package is vulnerable +- No compensating controls +- **Status**: Vulnerable ✗ + +**Action Required**: Immediate remediation recommended + +#### Affected But Not Vulnerable +**Definition**: System has the vulnerable code, but **exploitation is not currently possible**. + +**Characteristics**: +- CVE exists in installed package +- Mitigating factors prevent exploitation +- Configuration blocks exploit path +- Feature not enabled/used + +**Mitigating Factors**: +- SELinux blocking exploit path +- Firewall preventing network access +- Service not enabled/running +- Feature compiled out or disabled +- Red Hat backported fix without version number change + +**Example**: RHEL 8 system running `httpd-2.4.37-1.el8` with network-based CVE +- Package contains vulnerable code +- Firewall blocks external HTTP access +- **Status**: Affected but not vulnerable ⚠ + +**Action Required**: Lower priority, monitor for configuration changes + +### Security Rules + +**Security Rules** are CVEs that receive **elevated visibility** due to heightened risk. + +**Criteria for Security Rule Status**: +- Significant media coverage +- Active exploitation in the wild +- High CVSS score (typically ≥ 8.0) +- Affects critical infrastructure +- Red Hat Product Security team escalation + +**Example**: Log4Shell (CVE-2021-44228) +- CVSS 10.0 +- Widespread exploitation +- Affects many RHEL systems +- **Designated as Security Rule** + +**Impact**: +- Appears in executive dashboards +- Priority remediation recommended +- Enhanced reporting and tracking +- Compliance audit visibility + +## Red Hat Severity Ratings + +Red Hat uses a **4-point severity scale** in addition to CVSS scores: + +| Severity | CVSS Range | Description | Response Time | +|----------|-----------|-------------|---------------| +| **Critical** | 9.0-10.0 | Easily exploitable, widespread impact, no user interaction | 24-48 hours | +| **Important** | 7.0-8.9 | Exploitable with moderate effort, significant impact | 7 days | +| **Moderate** | 4.0-6.9 | Requires specific conditions, limited impact | 30 days | +| **Low** | 0.1-3.9 | Difficult to exploit, minimal impact | 90 days | + +**Red Hat Severity ≠ CVSS Score** + +Red Hat severity considers: +- **Exploitability**: How easily can it be exploited? +- **Impact**: What damage can it cause? +- **Affected configurations**: How common is the vulnerable configuration? +- **Compensating controls**: Are mitigations available? +- **Customer environment**: How are customers actually using the software? + +**Example**: +- **CVSS Score**: 8.5 (Important) +- **Red Hat Severity**: Moderate +- **Reason**: Requires non-default configuration rarely used in production + +## Vulnerability Assessment Workflow + +### Step 1: System Registration + +```bash +# Register system with Red Hat Lightspeed +insights-client --register + +# Verify registration +insights-client --status +``` + +**What Lightspeed Collects**: +- Installed packages and versions +- Running services +- System configuration +- SELinux status +- Firewall rules (high-level) +- Subscription data + +**Privacy**: Lightspeed collects system metadata only, not application data or files. + +### Step 2: CVE Identification + +Lightspeed automatically: +1. Scans installed packages against Red Hat CVE database +2. Compares package versions to affected ranges +3. Identifies all applicable CVEs +4. Updates daily as new CVEs published + +**CVE Sources**: +- Red Hat Product Security team +- NVD (National Vulnerability Database) +- Red Hat engineering analysis +- Customer-reported vulnerabilities + +### Step 3: Exploitability Analysis + +For each identified CVE, Lightspeed determines exploitability: + +**Factors Analyzed**: +- SELinux policies (can SELinux block the exploit?) +- Service status (is the vulnerable service running?) +- Network exposure (is the service accessible remotely?) +- Feature enablement (is the vulnerable feature enabled?) +- Configuration (does config prevent exploitation?) + +**Example Analysis**: +``` +CVE-2024-1234: httpd remote code execution +Package: httpd-2.4.37-1.el8 (vulnerable version) + +Exploitability Check: +✓ Service running: YES (httpd.service active) +✓ Network accessible: YES (port 80/443 open) +✓ SELinux blocking: NO (httpd_can_network_connect enabled) +✓ Feature enabled: YES (mod_cgi loaded) + +Conclusion: VULNERABLE +``` + +### Step 4: Threat Intelligence Integration + +Lightspeed integrates external threat intelligence: + +**Data Sources**: +- Known exploits in the wild +- CISA Known Exploited Vulnerabilities (KEV) catalog +- Security researcher disclosures +- Red Hat threat intelligence feeds + +**Impact on Priority**: +- **Active exploitation** → Escalate to Critical +- **Proof-of-concept available** → Increase priority +- **Theoretical only** → Standard priority + +### Step 5: Remediation Recommendation + +Lightspeed generates remediation recommendations: + +**Automated Playbook Available**: +``` +CVE-2024-1234 Remediation +───────────────────────── +Status: Automated remediation available +Package: httpd-2.4.37-1.el8 → httpd-2.4.37-2.el8 +Reboot Required: No +Estimated Time: 5 minutes +Ansible Playbook: ✓ Available + +Actions: +1. Download playbook from Lightspeed console +2. Review and customize for your environment +3. Execute via Ansible Automation Platform +4. Verify remediation success +``` + +**Manual Remediation Required**: +``` +CVE-2024-5678 Remediation +───────────────────────── +Status: Manual remediation required +Package: custom-app-1.0 (not in Red Hat repos) +Guidance: Contact vendor for patch + +Actions: +1. Review vendor security advisory +2. Test vendor-provided patch in staging +3. Schedule maintenance window +4. Apply patch manually +5. Re-scan with Lightspeed to verify +``` + +## Remediation Prioritization + +### Priority Decision Matrix + +Lightspeed prioritizes CVEs based on multiple factors: + +| Factor | Weight | Description | +|--------|--------|-------------| +| **Severity** | 40% | Red Hat severity rating (Critical/Important/Moderate/Low) | +| **Exploitability** | 30% | Vulnerable vs Affected but not vulnerable | +| **Business Impact** | 20% | System criticality (production vs dev/test) | +| **Active Threats** | 10% | Known exploitation in the wild | + +**Example Calculation**: +``` +CVE-2024-1234: +- Severity: Important (7.0) → Score: 7.0 × 0.40 = 2.8 +- Exploitability: Vulnerable → Score: 10 × 0.30 = 3.0 +- Business Impact: Production → Score: 10 × 0.20 = 2.0 +- Active Threats: PoC available → Score: 7.0 × 0.10 = 0.7 + +Total Priority Score: 8.5 / 10 → P1 (High Priority) +``` + +### Recommended Response Times + +| Priority | Response Time | Typical Scenarios | +|----------|---------------|-------------------| +| **P0** | 24 hours | Critical + Vulnerable + Production + Active exploitation | +| **P1** | 7 days | Important + Vulnerable + Production | +| **P2** | 30 days | Moderate + Vulnerable or Important + Affected but not vulnerable | +| **P3** | 90 days | Low severity or non-production systems | + +## Reporting Capabilities + +### Executive Reports (PDF) + +**Purpose**: High-level summary for leadership +**Contents**: +- Total CVE count by severity +- Trend analysis (improving/worsening) +- Top 10 critical CVEs +- Remediation progress metrics +- Compliance posture + +**Generated via Lightspeed Console or API** + +### CVE Reports (PDF) + +**Purpose**: Detailed technical analysis +**Contents**: +- Filtered CVE list (by severity, date, system) +- Per-CVE details (CVSS, description, affected systems) +- Remediation guidance +- Timeline for resolution + +### Vulnerability Data Export (CSV/JSON) + +**Purpose**: Integration with other tools (SIEM, ticketing) +**Contents**: +- Complete CVE dataset +- System-to-CVE mapping +- Remediation status +- Custom fields + +**Example Export**: +```csv +CVE,Severity,CVSS,Affected_Systems,Remediation_Available,Status +CVE-2024-1234,Important,7.5,15,Yes,Vulnerable +CVE-2024-5678,Moderate,5.3,8,No,Affected_but_not_vulnerable +``` + +## Integration with Remediation Agent + +When using the remediation-agent plugin: + +### Step 1: Risk Assessment (Use This Doc) + +```yaml +# CVE Impact Skill uses vulnerability-logic.md +- Retrieve CVE data from Lightspeed +- Understand Red Hat severity rating +- Check if "vulnerable" or "affected but not vulnerable" +- Assess business impact +- Determine priority (P0/P1/P2/P3) +``` + +### Step 2: Remediation (Use Templates) + +```yaml +# Remediator Agent uses cve-remediation-templates.md +- If priority = P0/P1: Generate playbook immediately +- If priority = P2: Schedule for maintenance window +- If priority = P3: Add to backlog + +# Use appropriate template based on CVE type +- Package CVE → Template 1 (Package Update) +- Kernel CVE → Template 4 (Kernel Update) +- Service CVE → Template 2 (Service Restart) +``` + +## API Integration + +### Lightspeed API Endpoints + +**Get CVE Information**: +```bash +# Via lightspeed-mcp tool +vulnerability_get_cve_info(cve_id="CVE-2024-1234") + +# Returns: +{ + "cve_id": "CVE-2024-1234", + "severity": "Important", + "cvss_score": 7.5, + "publish_date": "2024-01-15", + "description": "...", + "affected_packages": ["httpd-2.4.37"], + "remediation_available": true +} +``` + +**List Affected Systems**: +```bash +vulnerability_list_cves(cve_id="CVE-2024-1234") + +# Returns: +{ + "systems": [ + { + "uuid": "abc-123", + "hostname": "web-server-01", + "status": "vulnerable", + "package": "httpd-2.4.37-1.el8" + } + ] +} +``` + +## Best Practices + +### 1. Regular Scanning + +- **Daily scans**: Automated via `insights-client` systemd timer +- **On-demand scans**: After patching to verify remediation +- **Post-change scans**: After system configuration changes + +```bash +# Force immediate scan +insights-client --force-reregister +``` + +### 2. Understand Context + +Don't remediate solely based on CVSS: +- ✅ Check Red Hat severity rating +- ✅ Verify "vulnerable" vs "affected but not vulnerable" +- ✅ Consider system criticality +- ✅ Review threat intelligence +- ❌ Don't auto-patch based on CVSS alone + +### 3. Prioritize Production + +``` +Production Vulnerable > Production Affected > Non-Prod Vulnerable +``` + +### 4. Track Remediation Progress + +- Use Lightspeed dashboards +- Export metrics for management +- Set SLAs per priority level +- Audit remediation completion + +### 5. Compliance Integration + +Map CVE remediation to compliance frameworks: +- **PCI-DSS**: High/Critical CVEs must be remediated per timeline +- **SOC 2**: Vulnerability management process documented +- **NIST**: CVE scoring aligns with NIST guidelines + +See: [compliance-frameworks.md](../references/compliance-frameworks.md) + +## Common Scenarios + +### Scenario 1: Security Rule Announced + +``` +Notification: CVE-2024-9999 designated as Security Rule +Severity: Critical (CVSS 9.8) +Affected Systems: 127 systems + +Workflow: +1. Read vulnerability-logic.md to understand Security Rule criteria +2. Assess: 127 systems × Critical severity = P0 priority +3. Generate batch remediation playbook (Template 6) +4. Execute rolling updates (serial: 5 for safety) +5. Verify all systems remediated within 24 hours +``` + +### Scenario 2: Affected But Not Vulnerable + +``` +CVE: CVE-2024-1111 +Status: Affected but not vulnerable +Reason: SELinux prevents exploitation + +Workflow: +1. Read vulnerability-logic.md to understand classification +2. Document why not vulnerable (SELinux policy blocks exploit) +3. Monitor for configuration changes (if SELinux disabled → becomes vulnerable) +4. Remediate during next maintenance window (not urgent) +5. Update documentation for audit purposes +``` + +### Scenario 3: No Automated Remediation + +``` +CVE: CVE-2024-2222 +Package: third-party-app-1.0 +Remediation: Manual steps required + +Workflow: +1. Check Red Hat CVE database for guidance +2. Contact vendor for security advisory +3. Create custom remediation playbook +4. Test in staging environment +5. Document manual steps for audit trail +``` + +## Troubleshooting + +### Issue: System Not Showing CVEs + +**Possible Causes**: +- System not registered with Lightspeed +- `insights-client` service not running +- Subscription not active +- Network connectivity issues + +**Resolution**: +```bash +# Check registration +insights-client --status + +# Re-register if needed +insights-client --register + +# Force update +insights-client --force-reregister +``` + +### Issue: CVE Shows "Affected But Not Vulnerable" When It Shouldn't + +**Possible Causes**: +- Lightspeed detected mitigating factor (SELinux, firewall) +- Configuration analysis outdated +- False positive + +**Resolution**: +1. Review system configuration +2. Verify mitigating factors actually present +3. If Lightspeed wrong: Contact Red Hat support +4. Override classification if necessary (document reason) + +### Issue: Remediation Playbook Failed + +**Possible Causes**: +- Package dependency conflicts +- Repository not accessible +- System requires reboot (not detected) + +**Resolution**: +1. Review playbook execution logs +2. Check `package_update.results` for errors +3. Consult [package-management.md](../rhel/package-management.md) for troubleshooting +4. Re-run with increased verbosity: `ansible-playbook -vvv` + +## Related Documentation + +- **[CVSS Scoring Reference](../references/cvss-scoring.md)** - Detailed CVSS interpretation +- **[CVE Remediation Templates](../ansible/cve-remediation-templates.md)** - Playbook templates for remediation +- **[Compliance Frameworks](../references/compliance-frameworks.md)** - Compliance requirements per CVE severity + +## Official Red Hat Sources + +This document is derived from: + +1. **Assessing and Monitoring Security Vulnerabilities on RHEL Systems** + https://docs.redhat.com/en/documentation/red_hat_insights/1-latest/html/assessing_and_monitoring_security_vulnerabilities_on_rhel_systems/vuln-cves_vuln-overview + +2. **Generating Vulnerability Service Reports** + https://access.redhat.com/documentation/en-us/red_hat_insights/1-latest/html-single/generating_vulnerability_service_reports/index + +3. **Red Hat CVE Database** + https://access.redhat.com/security/security-updates/cve + +4. **A Complete View of System Vulnerabilities Using Red Hat Lightspeed** + https://www.redhat.com/en/blog/complete-view-system-vulnerabilities-using-red-hat-insights + +**License**: Content derived from Red Hat documentation under CC BY-SA 4.0 +**Last Verified**: 2026-01-20