Getting Started

Start by checking the documentation here:

Getting Started Documentation

You can find the complete list of roles here: Full List of Roles

Tests

Quickstart

1. Install Ansible on your control machine (see getting started section).
2. Install python-minimal on the remote machine (for Ubuntu 16.04+) or locally if using Ansible locally.
3. Copy the example inventory and files from here: Example Inventory (You can download the repo and copy the example1 folder).
4. Refer to Quickstart.md for additional guidance.

Example Playbook

---

- name: Deploy burp2 servers
  become: yes
  become_method: sudo
  hosts: burp2_servers
  roles:
    - role: coffeeitworks.burp2_server
      tags:
        - "burp2_server_all"
        - "burp2_server"

Install this role with the following command:

ansible-galaxy install -r requirements.yml

This will download and install the necessary roles.

Make sure to modify the IP address in inventory/test.

Run the playbook using:

ansible-playbook -i inventory/ roles.burp2_servers.yml -v -u pablo --ask-pass

Later, you can customize some variables by adding your own values in group_vars or host_vars.

Requirements

If you want to use this role with CentOS greater than 8, make sure to install:

- src: https://github.com/robertdebock/ansible-role-powertools
  name: ansible-role-powertools

Role Name

This role is for deploying and maintaining burp2_server. It builds the specified version of burp listed in defaults/main.yml and configures it for centralized management.

Refer to FEATURES.md for additional details.

Installing This Role

To install the role, run:

ansible-galaxy install coffeeitworks.burp2_server

For more information, visit: Installing Roles

Preparing the Variables

You will need to customize the variables before running the playbook. Organize the variable files in the group_vars directory:

mkdir -p group_vars/burp2_servers

Inside this folder, create a file named after the group or host for specific options.

Example file: group_vars/burp2_servers/burp2_server_vars.yml

You can also check default variables in defaults/main.yml, which can be overridden.

Role Variables: Complete List of Modules

Configure Burp UI Agent

The Burp UI agent is now managed through a separate role. It's recommended to use the Burp UI agent with Python 3.

Configure Burp Manual Delete

This feature is enabled by default:

burp_manual_delete_enabled: true

Configure Burp Autoupgrade

This feature is also enabled by default:

burp_server_autoupgrade_enabled: true

Set Port Per Operation

Enabled by default since version 2.1.10:

burp_server_port_per_operation_bool: true

You can set different ports for various operations like backup, restore, etc.

Activate Clients from Git Repository

Example configuration:

burp_repos:
  - { repo: "http://host/group/repo.git", version: "master", dir: "linux_clients" }

Add Clients from a List

You can add a list of clients for specific executions:

burp2_add_manual_clients:
  - name: client_name
    profile: profile_name (optional)
    password: client_password (optional)

You can provide this list during execution using the command line.

Configure Your Own Profiles

You can create custom profiles by checking defaults/main.yml.

Example:

profiles_templates:
  - name: profile_lnxsrv
    content:
      - "hard_quota=65Gb"
      - "soft_quota=50Gb"

Add Custom Lines to burp-server.conf

You can add your custom lines as follows:

burp_server_custom_lines:
  - "someextra=line"

Remove Clients from a List

You can specify clients to remove from a list:

burp_remove_clients:
  - name: client_to_remove

You can use this variable during runtime as well.

Dependencies

You can choose the service manager using the variable:

burp_sv_type: systemd

You can use systemctl commands to control the service for systemd.

For supervisor, use:

sudo supervisorctl restart buiagent/burp-server/burp-restore

Upgrading Your OS

After upgrading your Linux distribution, it's highly recommended to recompile and reinstall Burp.

Example:

ansible-playbook -i production burp-servers.yml -l client -e "burp_force_reinstall=yes"

License

MIT License

Author Information

This role was created by Diego Daguerre, with contributions from Pablo Estigarribia. Pablo is currently the main developer.

Testing the Role

To test this role, make sure Docker is installed and running, then execute the following script:

sudo systemctl start docker
./run_local_molecule_basic.sh

To clean up instances afterward, use:

./run_local_molecule_destroy.sh

This approach uses Docker images, so no need for additional installations.

For developers, there is a separate role for Burp server testing available here.