ansible-validator

# Ansible Validator ## Overview Comprehensive toolkit for validating, linting, and testing Ansible playbooks, roles, and collections. This skill provides automated workflows for ensuring Ansible code quality, syntax validation, dry-run testing with check mode and molecule, and intelligent documentation lookup for custom modules and collections with version awareness. **Default behavior:** When validating any Ansible role with a `molecule/` directory, attempt Molecule automatically using `bash scripts/test_role.sh <role-path>`. If Molecule cannot run due to environment/runtime limits, mark Molecule as `BLOCKED`, report why, and continue all non-Molecule validation steps. ## Trigger Guidance Use this skill when the request is about validating or debugging existing Ansible code, not generating new code. Common trigger phrases: - "validate this playbook" - "lint this role" - "why is ansible-lint failing" - "run check mode safely" - "test this role with molecule" - "find security issues in these Ansible files" - "module not found in this collection" ## When to Use This Skill Apply this skill when encountering any of these scenarios: - Working with Ansible files (`.yml`, `.yaml` playbooks, roles, inventories, vars) - Validating Ansible playbook syntax and structure - Linting and formatting Ansible code - Performing dry-run testing with `ansible-playbook --check` - Testing roles and playbooks with Molecule - Debugging Ansible errors or misconfigurations - Understanding custom Ansible modules, collections, or roles - Ensuring infrastructure-as-code best practices - Security validation of Ansible playbooks - Version compatibility checks for collections and modules ## Preflight (Run First) Run preflight before validation to avoid dead ends: ```bash bash scripts/setup_tools.sh ``` Command path assumption: run commands from this skill root (`devops-skills-plugin/skills/ansible-validator`) or use absolute paths. Preflight requirements: - Baseline validation: `ansible`, `ansible-playbook`, `ansible-lint` (plus `yamllint` recommended) - Molecule execution: `molecule` plus an available runtime (`docker` or `podman`) - Security scanning: `checkov` (wrapper can bootstrap if missing) Deterministic fallback rules: - If baseline tools are missing but Python + pip are available, wrapper scripts bootstrap temporary environments automatically. - If wrapper bootstrap fails (offline index, pip failure, missing Python), run direct commands for available tools, mark missing stages as `BLOCKED`, and continue. - If Molecule runtime is unavailable (Docker/Podman missing or daemon not running), skip Molecule execution, mark as `BLOCKED`, and continue remaining stages. ## Wrapper vs Direct Command Routing Use wrappers by default for consistent behavior and fallback handling. | Validation scenario | Default command | Use direct command when | Fallback if command cannot run | |---|---|---|---| | Playbook syntax/lint | `bash scripts/validate_playbook.sh <playbook.yml>` | User asks for a single focused check only (`ansible-playbook --syntax-check`, `ansible-lint`, or `yamllint`) | Run any available direct checks and report skipped checks as `BLOCKED` | | Role structural validation | `bash scripts/validate_role.sh <role-dir>` | User asks only for specific sub-checks (for example, structure only) | Run structure/YAML checks that are possible and report missing stages | | Role Molecule execution | `bash scripts/test_role.sh <role-dir> [scenario]` | User explicitly asks for manual stage-by-stage Molecule commands | Mark Molecule `BLOCKED` with reason and continue non-Molecule role checks | | Security scanning | `bash scripts/validate_playbook_security.sh <path>` or `bash scripts/validate_role_security.sh <path>` plus `bash scripts/scan_secrets.sh <path>` | User requests raw Checkov output formatting or custom flags | Run whichever scanner is available; if one is missing, run the other and report coverage gap | | Module/collection discovery | `bash scripts/extract_ansible_info_wrapper.sh <path>` | Python environment is already known-good and user wants direct parser output | If extraction fails, manually inspect `requirements.yml`/`galaxy.yml` and continue with best-effort lookup | ## Validation Workflow Follow this deterministic workflow and never stop at a missing dependency: ``` 0. Preflight ├─> Run: bash scripts/setup_tools.sh ├─> Record tool/runtime readiness └─> Continue even when optional tools are missing 1. Identify scope ├─> Single playbook validation ├─> Role validation ├─> Collection validation └─> Multi-playbook/inventory validation 2. Syntax Validation ├─> Run ansible-playbook --syntax-check ├─> Run yamllint for YAML syntax └─> Report as PASS/FAIL/BLOCKED 3. Lint and Best Practices ├─> Run ansible-lint (comprehensive linting) ├─> Check for deprecated modules (see references/module_alternatives.md) ├─> **DETECT NON-FQCN MODULE USAGE** (apt vs ansible.builtin.apt) │ └─> Run bash scripts/check_fqcn.sh to identify short module names │ └─> Recommend FQCN alternatives from references/module_alternatives.md ├─> Verify role structure └─> Report linting issues 4. Dry-Run Testing (check mode) ├─> Run ansible-playbook --check (if inventory available) ├─> Analyze what would change └─> Report potential issues 5. Molecule Testing (for roles with molecule/) - AUTOMATIC ATTEMPT ├─> Check if molecule/ directory exists in role ├─> If present, run: bash scripts/test_role.sh <role-path> [scenario] ├─> If script exits 2, mark Molecule as BLOCKED (environment/runtime issue) ├─> If script exits 1, mark Molecule as FAIL (role/test issue) └─> Continue remaining validation regardless of Molecule outcome 6. Custom Module/Collection Analysis (if detected) ├─> Extract module/collection information ├─> Identify versions ├─> Lookup documentation (Context7 first, then web.search_query fallback) └─> Provide version-specific guidance 7. Security and Best Practices Review - DUAL SCANNING DEFAULT ├─> Run bash scripts/validate_playbook_security.sh or validate_role_security.sh (Checkov) ├─> Run bash scripts/scan_secrets.sh for hardcoded secret detection │ └─> This catches secrets Checkov may miss (passwords, API keys, tokens) ├─> If one scanner is unavailable, run the other and report reduced coverage ├─> Validate privilege escalation ├─> Review file permissions └─> Identify common anti-patterns 8. Reference Routing ├─> Map each error/warning class to the matching reference file ├─> Extract concrete remediation from references (not file-name-only mention) └─> Include source section + fix guidance in final report 9. Final Report (required format) ├─> Summary counts: PASS / FAIL / BLOCKED / SKIPPED ├─> Findings grouped by severity ├─> Tool/runtime blockers with exact command that failed └─> Next actions to reach full validation coverage ``` **Status contract:** `BLOCKED` means validation could not run due to environment/runtime constraints; `FAIL` means the Ansible code or tests failed. ## Error-Class Reference Routing When issues are detected, consult the mapped reference and include a specific remediation excerpt in the report. | Error class | Typical detector | Required reference | Required action | |---|---|---|---| | YAML parse/format errors | `yamllint`, `ansible-playbook --syntax-check` | `references/common_errors.md` (Syntax Errors) | Quote the matching syntax fix pattern and apply corrected YAML structure | | Module/action resolution errors | `ansible-playbook`, `ansible-lint` | `references/common_errors.md` (Module/Collection Errors) | Provide install/version fix commands (`ansible-galaxy collection install ...`) | | Deprecated or non-FQCN module usage | `ansible-lint`, `bash scripts/check_fqcn.sh` | `references/module_alternatives.md` | Provide exact FQCN/module replacement per finding | | Template/variable errors | `ansible-playbook`, check mode | `references/common_errors.md` (Template/Variable Errors), `references/best_practices.md` (Variable Management) | Recommend `default()`, `required()`, or type conversion fixes | | Connection/inventory/privilege errors | `ansible-playbook --check`, runtime output | `references/common_errors.md` (Connection, Inventory, Privilege sections) | Provide corrected inventory/auth/become configuration | | Security policy failures (CKV_*) | `validate_*_security.sh` / Checkov | `references/security_checklist.md` | Map failed policy to a secure task rewrite | | Hardcoded secrets | `bash scripts/scan_secrets.sh` | `references/security_checklist.md` (Secrets Management) | Replace with Vault/env/external secret manager approach | | Role structure/idempotency warnings | `validate_role.sh`, Molecule idempotence | `references/best_practices.md` | Provide role layout or idempotency remediation steps | External documentation lookup trigger: - If the issue involves a custom/private collection or unknown module parameters not covered locally, run module discovery + documentation lookup (see section 7). ## Core Capabilities ### 1. YAML Syntax Validation **Purpose:** Ensure YAML files are syntactically correct before Ansible parsing. **Tools:** - `yamllint` - YAML linter for syntax and formatting - `ansible-playbook --syntax-check` - Ansible-specific syntax validation **Workflow:** ```bash # Check YAML syntax with yamllint yamllint playbook.yml # Or for entire directory yamllint -c .yamllint . # Check Ansible playbook syntax ansible-playbook playbook.yml --syntax-check ``` **Common Issues Detected:** - Indentation errors - Invalid YAML syntax - Duplicate keys - Trailing whitespace - Line length violations - Missing colons or quotes **Best Practices:** - Always run yamllint before ansible-lint - Use 2-space indentation consistently - Configure yamllint rules in `.yamllint` - Fix YAML syntax errors first, then Ansible-specific issues ### 2. Ansible Lint **Purpose:** Enforce Ansible best practices and catch common errors. **Workflow:** ```bash # Lint a single playbook ansible-lint playbook.yml # Lint all playbooks in directory ansible-lint . # Lint with specific rules ansible-lint -t yaml,syntax playbook.yml # Skip specific rules ansible-lint -x yaml[line-length] playbook.yml # Output parseable format ansible-lint -f pep8 playbook.yml # Show rule details ansible-lint -L ``` **Common Issues Detected:** - Deprecated modules or syntax - Missing task names - Improper use of `command` vs `shell` - Unquoted template expressions - Hard-coded values that should be variables - Missing `become` directives - Inefficient task patterns - Jinja2 template errors - Incorrect variable usage - Role dependencies issues **Severity Levels:** - **Error:** Must fix - will cause failures - **Warning:** Should fix - potential issues - **Info:** Consider fixing - best practice violations **Auto-fix approach:** - ansible-lint supports `--fix` for auto-fixable issues - Always review changes before applying - Some issues require manual intervention ### 3. Security Scanning (Checkov) **Purpose:** Identify security vulnerabilities and compliance violations in Ansible code using Checkov, a static code analysis tool for infrastructure-as-code. **What Checkov Provides Beyond ansible-lint:** While ansible-lint focuses on code quality and best practices, Checkov specifically targets security policies and compliance: - **SSL/TLS Security:** Certificate validation enforcement - **HTTPS Enforcement:** Ensures secure protocols for downloads - **Package Security:** GPG signature verification for packages - **Cloud Security:** AWS, Azure, GCP misconfiguration detection - **Compliance Frameworks:** Maps to security standards - **Network Security:** Firewall and network policy validation **Workflow:** ```bash # Scan playbook for security issues bash scripts/validate_playbook_security.sh playbook.yml # Scan entire directory bash scripts/validate_playbook_security.sh /path/to/playbooks/ # Scan role for security issues bash scripts/validate_role_security.sh roles/webserver/ # Direct checkov usage checkov -d . --framework ansible # Scan with specific output format checkov -d . --framework ansible --output json # Scan and skip specific checks checkov -d . --framework ansible --skip-check CKV_ANSIBLE_1 ``` **Common Security Issues Detected:** **Certificate Validation:** - **CKV_ANSIBLE_1:** URI module disabling certificate validation - **CKV_ANSIBLE_2:** get_url disabling certificate validation - **CKV_ANSIBLE_3:** yum disabling certificate validation - **CKV_ANSIBLE_4:** yum disabling SSL verification **HTTPS Enforcement:** - **CKV2_ANSIBLE_1:** URI module using HTTP instead of HTTPS - **CKV2_ANSIBLE_2:** get_url using HTTP instead of HTTPS **Package Security:** - **CKV_ANSIBLE_5:** apt installing packages without GPG signature - **CKV_ANSIBLE_6:** apt using force parameter bypassing signatures - * - *CKV2_ANSIBLE_4:** dnf installing packages without GPG signature - **CKV2_ANSIBLE_5:** dnf disabling SSL verification - **CKV2_ANSIBLE_6:** dnf disabling certificate validation **Error Handling:** - **CKV2_ANSIBLE_3:** Block missing error handling **Cloud Security (when managing cloud resources):** - **CKV_AWS_88:** EC2 instances with public IPs - **CKV_AWS_135:** EC2 instances without EBS optimization **Example Violation:** ```yaml # BAD - Disables certificate validation - name: Download file get_url: url: https://example.com/file.tar.gz dest: /tmp/file.tar.gz validate_certs: false # Security issue! # GOOD - Certificate validation enabled - name: Download file get_url: url: https://example.com/file.tar.gz dest: /tmp/file.tar.gz validate_certs: true # Or omit (true by default) ``` **Integration with Validation Workflow:** Checkov complements ansible-lint: 1. **ansible-lint** catches code quality issues, deprecated modules, best practices 2. **Checkov** catches security vulnerabilities, compliance violations, cryptographic issues **Best Practice:** Run both tools for comprehensive validation: ```bash # Complete validation workflow bash scripts/validate_playbook.sh playbook.yml # Syntax + Lint bash scripts/validate_playbook_security.sh playbook.yml # Security ``` **Output Format:** Checkov provides clear security scan results: ``` Security Scan Results: Passed: 15 checks Failed: 2 checks Skipped: 0 checks Failed Checks: Check: CKV_ANSIBLE_2 - "Ensure that certificate validation isn't disabled with get_url" FAILED for resource: tasks/main.yml:download_file File: /roles/webserver/tasks/main.yml:10-15 ``` **Remediation Resources:** - Checkov Policy Index: https://www.checkov.io/5.Policy%20Index/ansible.html - Ansible Security Checklist: `references/security_checklist.md` - Ansible Best Practices: `references/best_practices.md` **Installation:** Checkov is automatically installed in a temporary environment if not available system-wide. For permanent installation: ```bash pip3 install checkov ``` **When to Use:** - Before deploying to production - In CI/CD pipelines for automated security checks - When working with sensitive infrastructure - For compliance audits and security reviews - When downloading files or installing packages - When managing cloud resources with Ansible ### 4. Playbook Syntax Check **Purpose:** Validate playbook syntax without executing tasks. **Workflow:** ```bash # Basic syntax check ansible-playbook playbook.yml --syntax-check # Syntax check with inventory ansible-playbook -i inventory playbook.yml --syntax-check # Syntax check with extra vars ansible-playbook playbook.yml --syntax-check -e @vars.yml # Check all playbooks for file in *.yml; do ansible-playbook "$file" --syntax-check done ``` **Validation Checks:** - YAML parsing - Playbook structure - Task definitions - Variable references - Module parameter syntax - Jinja2 template syntax - Include/import statements **Error Handling:** - Parse error messages for specific issues - Check for typos in module names - Verify variable definitions - Ensure proper indentation - Check file paths for includes/imports ### 5. Dry-Run Testing (Check Mode) **Purpose:** Preview changes that would be made without actually applying them. **Workflow:** ```bash # Run in check mode (dry-run) ansible-playbook -i inventory playbook.yml --check # Check mode with diff ansible-playbook -i inventory playbook.yml --check --diff # Check mode with verbose output ansible-playbook -i inventory playbook.yml --check -v # Check mode for specific hosts ansible-playbook -i inventory playbook.yml --check --limit webservers # Check mode with tags ansible-playbook -i inventory playbook.yml --check --tags deploy # Step through tasks ansible-playbook -i inventory playbook.yml --check --step ``` **Check Mode Analysis:** When reviewing check mode output, focus on: 1. **Task Changes:**