ansible-review.md

Ansible Review Example

Goal

Review Ansible roles and playbooks for idempotency, structure, security posture, and testability — without modifying any files.

---

Quick Reference

/ansible-review

Reviews a role or playbook directory for correctness and operational safety.

Expected output sections:

• Findings — specific task names, file paths, and line numbers
• Risk level — Low / Medium / High / Critical
• Affected files — role paths, playbook names, var files
• Remediation — concrete module substitutions, task rewrites, vault steps

---

Full Workflow: Webserver Role Review

Step 1 — Review the role

/ansible-review review the webserver role in roles/webserver for idempotency, structure, and security

Context

Role layout:

roles/webserver/
  tasks/
    main.yml
    install.yml
    configure.yml
    service.yml
  handlers/
    main.yml
  templates/
    nginx.conf.j2
  vars/
    main.yml          <- contains plaintext passwords
  defaults/
    main.yml
  molecule/           <- missing
  meta/
    main.yml

Example Output

## Findings

**F1 — shell module used instead of package module (install.yml:8)**
```yaml
# Current (not idempotent):
- name: Install nginx
  shell: apt-get install -y nginx

shell is not idempotent — re-running the playbook will always mark this task as "changed" and may produce unexpected output in check mode. Use the package (or apt) module with state: present.

• Severity: High
• Idempotency impact: Yes

F2 — shell module for service enable (service.yml:14)

# Current:
- name: Enable nginx service
  shell: systemctl enable nginx

Use ansible.builtin.service with enabled: true. The shell call also silently succeeds if systemctl is not available (containers, WSL).

• Severity: High
• Idempotency impact: Yes

F3 — Plaintext secrets in vars/main.yml

# vars/main.yml (line 3):
db_password: "hunter2"

Secrets committed in plaintext are exposed in version control and Ansible logs. Encrypt with ansible-vault encrypt_string and reference via vault lookup, or move to a vault-encrypted var file.

• Severity: Critical
• Security impact: Yes

F4 — No Molecule tests The molecule/ directory is absent. There is no automated idempotency or convergence test. Changes to the role cannot be validated without a live target.

• Severity: Medium

F5 — configure.yml copies template without a handler notify

# configure.yml:22:
- name: Deploy nginx config
  template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf

The task does not notify the Restart nginx handler. Config changes will not take effect until the next manual service restart.

• Severity: High
• Operational impact: Config drift between deployed template and running config.

F6 — meta/main.yml missing galaxy_info.min_ansible_version galaxy_info block exists but omits min_ansible_version. Operators on older Ansible versions will silently use the role with unpredictable results.

• Severity: Low

Risk Level

Critical — plaintext secrets in version control (F3) and two non-idempotent shell tasks (F1, F2) that will mark every run as changed and may fail in check mode or CI pipelines.

Affected Files

• roles/webserver/tasks/install.yml — F1
• roles/webserver/tasks/service.yml — F2
• roles/webserver/vars/main.yml — F3
• roles/webserver/tasks/configure.yml — F5
• roles/webserver/meta/main.yml — F6
• roles/webserver/molecule/ — F4 (missing)

Remediation

Immediate (Critical/High):

1. Rotate db_password — it is compromised. After rotation:

   ansible-vault encrypt_string 'new_password' --name 'db_password'

   Store the result in vars/vault.yml and add vars/main.yml to .gitignore (or encrypt the whole file with ansible-vault encrypt vars/main.yml).

2. Replace shell: apt-get install -y nginx with:

   - name: Install nginx
     ansible.builtin.package:
       name: nginx
       state: present

3. Replace shell: systemctl enable nginx with:

   - name: Enable and start nginx
     ansible.builtin.service:
       name: nginx
       enabled: true
       state: started

4. Add notify: Restart nginx to the template task in configure.yml:22.

Medium term:

5. Initialise Molecule:

   cd roles/webserver
   molecule init scenario --driver-name docker

   Add a convergence test and an idempotency assertion to the scenario.

6. Add min_ansible_version: "2.14" to meta/main.yml under galaxy_info.

Validation commands:

ansible-lint roles/webserver/
ansible-playbook site.yml --check --diff
molecule test -s default

---

### Step 2 — Plan the remediation

After reviewing, use the unified `/plan-change` command to create a
remediation plan:

/plan-change create a remediation plan for the webserver role findings

This produces the same structured plan output as any other change workflow,
with the Ansible-specific context automatically detected from the file types.

---

## Notes

- `/ansible-review` is read-only. No playbook or role file is modified.
- Always run `ansible-lint` as the first validation step after applying
  remediation — it catches idempotency and module-usage issues not visible
  from a static review.
- Vault findings are always Critical; surface them first in the output
  regardless of ordering in the original file scan.