Welcome to avatar², the target orchestration framework with focus on dynamic analysis of embedded devices' firmware!

Avatar² is developed and maintained by Eurecom's S3 Group.

Building

Building avatar² is easy!

Docker

You can easily get started with two commands:

$ docker-compose build
$ docker-compose run --rm avatar2-arm

We provide under the docker/ directory two dockerfile avatar2-core.Dockerfile and avatar2.Dockerfile . The main difference between the two images is that the latter includes QEMU. For more example on available images, refer to the docker-compose.yml file.

PyPI

Avatar² is also present on PyPI!

We recommands you to use a Python virtual environment.

First, make sure that all the dependencies are present:

apt-get install python-pip python-setuptools python-dev cmake

Afterwards, use pip to install avatar2:

python3 -m pip install avatar2

Now you will need to install the supported endpoints you would like to use, such as debuggers (gdb-multiarch, openocd) and emulators (qemu-system-*, panda-system-*, etc.).

The old avatar2-installer tries to fetch and install them automatically, but is not actively supported.

python -m avatar2.installer

Building manually

Avatar² can also be built manually.

The following three commands are enough to install the core.

$ git clone https://github.com/avatartwo/avatar2.git avatar2
$ cd avatar2
$ python -m pip install .

For more detailed installation instructions, we encourage you to take a look at avatar2-core.Dockerfile and avatar2.Docker, as they provide step-by-step commands similar to shell instructions.

Afterwards, the different target endpoints can be built, such as QEmu or PANDA. For doing so, we are providing build-scripts for Ubuntu 20.04 - while other distributions are not officially supported (yet), the scripts are known to work with slight modifications on other distributions as well.

$ cd targets
$ ./build_*.sh

Please Note: These scripts add the restricted repository to /etc/apt/sources.list for fetching the dependencies. If you are not comfortable with this, please consider building avatar² in a VM/Container or install the dependencies manually and adjust the scripts.

Getting started

For discovering the power of avatar² and getting a feeling of its usage, we recommend highly checking out the handbook here on github. Additionally, a documentation of the API is provided here and some exemplary avatar²-scripts can be found here. Additionally, another good way to get started with avatar² is to read the official avatar² paper or to watch the 34c3-talk.

For further support or follow-up questions, feel free to send a mail to avatar2 [at] lists.eurecom.fr, our public mailing list, on which you can subscribe here.

Additionally, you can find us on slack for more vivid means of communication - if you want an invite, just send us a mail!

Publications

The following publications describe, use, or extend the avatar² framework:

1. M. Muench, D. Nisi, A. Francillon, D. Balzarotti. "Avatar²: A Multi-target Orchestration Platform." Workshop on Binary Analysis Research (BAR), San Diego, California, February 2018.
   • Paper - Code
2. M. Muench, J. Stijohann, F. Kargl, A. Francillon, D. Balzarotti. "What You Corrupt Is Not What You Crash: Challenges in Fuzzing Embedded Devices." Network and Distributed System Security Symposium (NDSS), San Diego, California, 2018.
   • Paper - Code
3. D. Maier, B. Radtke, B. Harren. "Unicorefuzz: On the Viability of Emulation for Kernelspace Fuzzing." Workshop on Offensive Technologies (WOOT), Santa Clara, California, August 2019.
   • Paper - Code
4. E. Gustafson, M. Muench, C. Spensky, N. Redini, A. Machiry, A. Francillon, D. Balzarotti, Y. E. Choe, C. Kruegel, G. Vigna. "Toward the Analysis of Embedded Firmware through Automated Re-hosting." Symposium on Resarch in Attacks, Intrusions, and Defenses (RAID), Beijing, China, September 2019.
   • Paper - Code
5. A.A. Clements, E. Gustafson, T. Scharnowski, P. Grosen, D. Fritz, C. Kruegel, G. Vigna, S. Bagchi, M. Payer. "HALucinator: Firmware Re-hosting Through Abstraction Layer Emulation." USENIX Security Symposium, August 2020.
   • Paper - Code
6. C. Cao, L. Guan, J. Ming, P. Liu. "Device-agnostic Firmware Execution is Possible: A Concolic Execution Approach for Peripheral Emulation." Annual Computer Security Applications Conference (ACSAC), December 2020.
   • Paper - Code
7. G. Hernandez, M. Muench, D. Maier, A. Milburn, S. Park, T. Scharnowski, T. Tucker, P. Traynor, K. R.B. Butler. "FirmWire: Transparent Dynamic Analysis for Cellular Baseband Firmware." Symposium on Network and Distributed System Security (NDSS), April 2022.
   • Paper - Code

Acknowledgements

The avatar² project was partially funded through, and supported by, SIEMENS AG - Technology.