Ansible Roles are akin to functions in programming languages. You can resuse and share your Ansible code with others using Roles.

We have all been there. Creating infrastructure from scratch, installing the same apps, tools for a new pentesting gig, red team engagement, or a fancy new bug bounty target. Having a reliable toolset built from scratch is an invaluable asset for such exercises. I have used Ansible to provision new virtual machines with my favorite tools at my disposal. This way I can treat my red team infra as cattle and not as pets ref

Anatomy of an Ansible Role

An Ansible role has a defined directory structure with eight main standard directories. The folder structure is pretty self explanatory.

roles/
    common/               # this hierarchy represents a "role"
        tasks/            #
            main.yml      #  <-- tasks file can include smaller files
        handlers/         #
            main.yml      #  <-- handlers file
        templates/        #  <-- files for use with the template resource
            ntp.conf.j2   #  <------- templates end in .j2
        files/            #
            bar.txt       #  <-- files for use with the copy resource
            foo.sh        #  <-- script files for use with the script resource
        vars/             #
            main.yml      #  <-- variables associated with this role
        defaults/         #
            main.yml      #  <-- default lower priority variables for this role
        meta/             #
            main.yml      #  <-- role dependencies
        library/          # roles can also include custom modules

The following two files are the most that you will need to work with for simple Roles.

  • tasks/main.yml: Your main list of tasks that the role executes goes here.
  • vars/main.yml: Variables for the roles.

Creating an Ansible Role

bbot is a fantastic OSINT tool for finding targets during pentest or bug bounty exercises.

Let’s create a role for installing bbot. You can create a skeleton Role using the following command.

$ ansible-galaxy init ansible-role-bbot
- Role ansible-role-bbot was created successfully

As you can see, we get a pre-built skeleton for our Ansible role. We can now go about editing the necessary files as per our requirement.

$ tree ansible-role-bbot/
ansible-role-bbot/
├── README.md
├── defaults
│   └── main.yml
├── files
├── handlers
│   └── main.yml
├── meta
│   └── main.yml
├── tasks
│   └── main.yml
├── templates
├── tests
│   ├── inventory
│   └── test.yml
└── vars
    └── main.yml

8 directories, 8 files

vars/main.yml

I like renaming the vars/main.yml file to vars/<toolName>.yml.

mv vars/main.yml vars/bbot.yml

Add the following content to the file.

---
# vars file for ansible-role-bbot
bbot_package: bbot

package_names:
  - python3-pip
  - unzip

bbot is a python based tool. It uses python-pip to download additional python modules.

tasks/main.yml

All the tasks for installing bbot will go in this file. Add the following to this file.

---
# tasks file for ansible-role-bbot
- name: Load var file
  ansible.builtin.include_vars: "{{ lookup('first_found', params) }}"
  vars:
    params:
      files:
        - bbot.yml
      paths:
        - "{{ role_path }}/vars"
  tags:
  - bbot

- name: Install pip
  ansible.builtin.apt:
    name: "{{ package_names }}"
    update_cache: true
  tags:
  - bbot

- name: Install bbot python package
  ansible.builtin.pip:
    name: "{{ bbot_package }}"
  tags:
  - bbot

Here we load the bbot.yml file from the /vars folder in the first task. We then install pip in the second task. And finally we install bbot in the third task.

Using Roles in your Playbooks

  1. Place the role directory ansible-role-bbot inside the roles/ folder where your playbooks are located.
├── playbook.yml
└── roles
    ├── ansible-role-bbot
  1. Call or use the Role in your playbook.yml file.
---
- hosts: all
  become: yes
  become_method: sudo
  tasks:
    - name: Install bbot
      ansible.builtin.include_role:
        name: ansible-role-bbot
      tags:
        - bbot

   - name: Install masscan
     ansible.builtin.include_role:
       name: ansible-role-masscan
     tags:
       - masscan

Conclusion

Ansible roles are an excellent way to structure and define what your Red or Blue Team infrastructure should look like. It is worth learning how to use them. You can create an arsenal of Ansible Roles that will provision your favourite Red or Blue tooling. Here are some of the Roles I have created.

  • masscan
  • bbot
  • gobuster

References