Ansible Pack
URL slug: ansible
This page describes how the Ansible pack reads changes and groups them into analysis units. It is for engineers who review Ansible changes.
The pack reads a unified git diff and creates units for changed tasks, play-level keys and configuration hunks. Rules flag privilege, secret, hardening, performance and reliability issues.
Which files it reads
Section titled “Which files it reads”| Path glob | Read as |
|---|---|
*playbook*.yml, *playbook*.yaml, *site.yml | Playbooks: plays and their tasks |
*roles/*/tasks/*.yml, *roles/*/handlers/*.yml | Task files: lists of tasks |
*roles/*/defaults/*.yml, *group_vars/*, *host_vars/* | Variables |
*requirements.yml | Galaxy roles and collections |
*ansible.cfg | Configuration |
The pack also recognises Ansible by content. sniff() scores 0.8 for a root list of plays or named tasks with a module key, such as ansible.builtin.apt: or copy:. YAML with a mapping at its root scores 0.0. A root list with keys from another format, such as image, uses, run or script, also scores 0.0.
How the pack parses changes
Section titled “How the pack parses changes”parse_diff in opentremor_pack_ansible/parser.py reads each diff hunk:
- It reads hunks with core’s
iter_hunksfromopentremor_core.libs.diff. It skips files that are neither YAML nor recognised by filename. - It locates changed lines with core’s
iter_yaml_blocksfromopentremor_core.libs.yaml_diff. Each block gets a key path, such as("- name: Configure web", "tasks", "- name: Install nginx", "ansible.builtin.apt"). - It groups blocks by their owner. The owner is the innermost task under
tasks,pre_tasks,post_tasks,handlers,block,rescueoralways, or a root task in a task file. A playbook change outside a task belongs to the play. Other changes are grouped into anunknownunit. - It builds each task’s body from the hunk, including the context lines shown there.
Variable files, requirements.yml and ansible.cfg produce one unit per hunk. Input that is not a diff, such as a pasted playbook, is read as a new file.
Unit identity
Section titled “Unit identity”| Unit | type | name |
|---|---|---|
| A task | Its module, such as ansible.builtin.apt | Its name:, or the module if it has no name |
A play’s own keys (hosts, become, vars, roles, and others) | play | The play’s first value, such as Configure web servers |
| A hunk of a variables file | vars | The file path |
A hunk of requirements.yml | requirements | The file path |
A hunk of ansible.cfg | config | The file path |
| Changed lines whose task the hunk does not show | unknown | Their key path |
Added and unchanged lines determine a task’s identity. If a task changes from shell to apt, its type is apt. A deleted task is named from its removed lines. A renamed task (- name: old to - name: new) is one unit with the new name.
Action from diff markers
Section titled “Action from diff markers”| Markers present in the unit | action |
|---|---|
+ only | add |
- only | delete |
| Both | modify |
Diff markers stay in the body
Section titled “Diff markers stay in the body”The body keeps its +, - and space prefixes. Rules use these markers to distinguish a new validate_certs: false from one that was already present, or a removed checksum: from an unchanged one.
Unit shape
Section titled “Unit shape”{ "hash": "<sha256 of the normalised body>", "type": "community.general.ufw", "name": "Allow SSH", "action": "modify", "body": "- - name: Allow SSH from the office network\n+ - name: Allow SSH\n community.general.ufw:\n ...", "metadata": { "generated_at_utc": "2026-10-26T10:30:00Z", "source_path": "playbooks/web.yml", "group_path": null }}Rulesets
Section titled “Rulesets”Rules are Markdown files in this package’s opentremor_pack_ansible/rules/ directory:
| File | Variant | Served at |
|---|---|---|
generic-rules.md | Default (generic) | GET /v1/ansible/rules |
debian-rules.md | debian | GET /v1/ansible/rules?rule_type=debian |
rhel-rules.md | rhel | GET /v1/ansible/rules?rule_type=rhel |
All three files define the same rule IDs. The variants tailor rules for OS families. The Debian rules refer to apt, ufw and the sudo group; the RHEL rules refer to dnf/yum, firewalld and the wheel group.
The pack can suggest a variant based on package modules in the input. It counts apt, apt_key, apt_repository and deb822_repository for Debian, and dnf, dnf5, yum, yum_repository and rpm_key for RHEL. The family with more matches is suggested; a tie or no matches produces no suggestion. The suggestion is shown to a person and is not applied automatically.
What the rules cover
Section titled “What the rules cover”| Rule ID | Area | What it catches |
|---|---|---|
| ANS-001 | Privilege | Review prompt: become: true at play level |
| ANS-002 | Privilege | shell or command built from variables |
| ANS-003 | Privilege | shell, command or raw used where a module exists |
| ANS-004 | TLS | validate_certs: false, or removal of validate_certs: true |
| ANS-005 | Supply chain | get_url without checksum, or a download piped to a shell |
| ANS-006 | Secrets | A literal secret instead of a Vault or secret-manager reference |
| ANS-007 | Secrets | Review prompt: a secret printed or registered without no_log |
| ANS-008 | Hardening | PermitRootLogin yes or PasswordAuthentication yes |
| ANS-009 | Public exposure | A firewall rule open to every source |
| ANS-010 | Hardening | A world-writable mode, or a private key readable by others |
| ANS-011 | Supply chain | A package repository without signing checks, or unauthenticated packages |
| ANS-012 | Privilege | A plain-text user password, or a new account in a privileged group |
| ANS-013 | Hardening | Review prompt: ignore_errors on a hardening task |
| ANS-014 | Destructive | state: absent on data, or rm -rf on a variable path |
| ANS-015 | Supply chain | An unpinned Galaxy role or collection, a branch pin, or a new source |
| ANS-PERF-001 to -004 | Performance | A package module in a loop, a long task without async, unused fact gathering, or increased fan-out |
| ANS-REL-001 to -005 | Reliability | Config written without validate:, restart without serial, restart outside a handler, command or shell without idempotency controls, or max_fail_percentage removed |
Performance and Reliability rules have LOW or MEDIUM severity. They appear in the review but do not fail the merge check on their own. Core keeps an organization’s unedited rows in step with these files (OpenTremor-core#0034).
Worked example
Section titled “Worked example”diff --git a/playbooks/web.yml b/playbooks/web.yml--- a/playbooks/web.yml+++ b/playbooks/web.yml@@ -24,5 +19,5 @@ - name: Fetch the app release ansible.builtin.get_url: url: https://releases.example.com/app-1.4.2.tar.gz dest: /opt/app/app.tar.gz- checksum: "sha256:9f2c4e1d..."+ validate_certs: falseThe pack creates one unit: type ansible.builtin.get_url, name Fetch the app release, action modify. The LLM can match ANS-004 to the added validate_certs: false and ANS-005 to the removed checksum.
The pack’s demo sample in opentremor_pack_ansible/demo/ includes this change and four others from the same playbook.