A tool designed for consistent and safe capture of off network web resources.
As a network defender doing full life-cycle analysis of an attack, it is often useful to capture an off network web resource to help complete the picture and learn more about the advasary. However, doing so has inherit risks especially in the coure of an investigation where it is easy for an analyst, no matter the skill level, to make a mistake or forget to capture data.
Boomerang looks to fill this gap by providing a consistent and safe method for analysts of all skill levels to retreieve desired resources in addition to providing metadata about the server providing the files.
What are some use cases for boomerang?
- Pulling the payload at the other side of a phishing link
- Retrieve the next stage of a piece of malware
- Grab the payload of a strategic web compromise
- Checkout that suspicious website
How does it work?
Boomerang operates in a client-minion model like the one shown below.
Client
The client can be anything that has been configured to talk to the minion's API. In the most simple form this is a CLI script like the example one provided. However, useage of boomerang can easily be integrated into other tools or automated workflows using the PyMinion bindings provided in this repo.
Minion
The minion is where the work of retreiving the resources is done. All data regarding the request is then packaged up and sent back to the client for analysis. Depending on the resources the minion is beeing used to retrieve, it is advisable to deploy minions in an isolated enviornment such as VPS service or an isolated network segment.
Anything I should know about using this tool?
OPSEC (Operational Security) should be the first thing on your mind when using boomerang. While Boomerang was designed with safety in mind, it is important to remember that when using the tool you are potentially reaching out and touching advesary controlled infrastructure. As such each request to a resource leaves a "fingerprint" that could potentially be used to the advasaries advantage. Weigh the risks and benefits before using boomerang to retrieve a resource.
Since interaction with boomerang's minions is done through RESTful API calls, any number of tools or languages can be used.
Boomerang comes with a basic CLI client that can be used to to interact with your minions. To make use of this client you will need to install PyMinion (bindings for the minion API).
From the repo directory:
cd pyminion
python setup.py install
The minion has been successfully installed and tested on Ubuntu Server 14.04 and 16.04, both running Python 2.7.x. It has also been succesfully installed on Centos7. However, minor issues arrose with website mode and Xvfb on a headless Centos Box. The following instructions are for a Ubuntu install but similar steps can be followed for your flavor of choice.
cd minion
sudo apt-get install -y libz-dev
sudo pip install -r requirements.txt
sudo apt-get install -y python-pyside xvfb
All dependencies for the minion should now be install. To test the minion's functionality, run the minion by:
python minion.py
Production Install
For a production enviornment, it is highly recommended that you run the minion inside a WSGI compatiable appliaction web server like gunicorn.
Boomerang has two basic modes of operation: basic and website.
In basic mode, the minion is used to fetch a single discrete resource (ie. a binary, an image, a webpage without it's dependencies).
When executed, a basic fetch will attempt to retrieve the requested resource. Upon a succesful fetch, a zip file is returned to the analyst which contains the following:
- A JSON formated file containing information about the fetch transaction as well as any gathered information about the server.
- A zip file password protected with the password
infected
containing the requested resource
Basic mode can be executed with a POST request to a minion at the root URL. The POST must be JSON formated with the following fields:
Field | Required | Notes |
---|---|---|
url | yes | must be fully qualified with either http:// or https:// explicitly part of the URL |
user-agent | no | if none is provided, the default configured in the minion's config file will be used |
Example
curl -H "Content-Type: application/json" -X POST -d '{"url":"http://google.com","user-agent":"Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko"}' http://<minion domain or ip>:<port>/
###Website Mode
In website mode, the minion is used to fetch the full contents of a single webpage including it's images, scripts, etc. In addition the minion will use the data collected to render a screenshot of what the page looks like. Upon a succesful fetch, a zip file is returned to the analyst which contains the following:
- A JSON formated file containing information about the fetch transaction as well as any gathered information about the server.
- A zip file password protected with the password
infected
containing: - All gathered resources with naming convention resource<0-n>
- screenshot.png
Website mode can be executed with a POST request to a minion at the /website
endpoint. The POST must be JSON formated with the following fields:
Field | Required | Notes |
---|---|---|
url | yes | must be fully qualified with either http:// or https:// explicitly part of the URL |
user-agent | no | if none is provided, the default configured in the minion's config file will be used |
Example
curl -H "Content-Type: application/json" -X POST -d '{"url":"http://google.com","user-agent":"Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko"}' http://<minion domain or ip>:<port>/website
The following is the usage for boomerang using the bommerang_cli.py example
positional arguments:
uri Target URI to be fetched
optional arguments:
-h, --help show this help message and exit
-p PATH, --path PATH path to where the resulting packaged should be stored
[default: current working directory]
-v, --verbose Tells emr-boomerang to output the json results to
stdout in addition to storing them in the defined path
-u UA, --useragent UA
Set the User-Agent String to be used. [default:
randomly selected from a pre-loaded list]
--mode {basic,website}
Set the fetch mode to be used. [default: basic]
examples
Basic fetch:
python bommerang_cli.py http://google.com
Example with website mode and printing the transaction and server JSON data to the commandline:
python bommerang_cli.py -v -mode website http://google.com