ARM-X Firmware Emulation Framework
by Saumil Shah @therealsaumil
The ARM-X Firmware Emulation Framework is a collection of scripts, kernels and filesystems to be used with QEMU to emulate ARM/Linux IoT devices. ARM-X is aimed to facilitate IoT research by virtualising as much of the physical device as possible. It is the closest we can get to an actual IoT VM.
Devices successfully emulated with ARM-X so far:
- D-Link DIR-880L Wi-Fi Router
- Netgear Nighthawk R6250 Wi-Fi Router
- Netgear Nighthawk R6400 Wi-Fi Router
- Trivision NC227WF Wireless IP Camera
- Cisco RV130 Wi-Fi Router
Precursors of ARM-X have been used in Saumil Shah's popular ARM IoT Exploit Laboratory training classes where students have found four 0-day vulnerabilities in various ARM/Linux IoT devices.
ARM-X Architecture and Operations
ARM-X is a collection of scripts, kernels and filesystems residing in the
/armx directory. It uses
qemu-system-arm to boot up a virtual ARM/Linux environment. The
/armx directory is exported over NFS to also make the contents available within the QEMU guest.
The host system running
qemu-system-arm is assigned the IP address
192.168.100.1 and the QEMU guest is assigned
/armx directory is organised as follows:
devices: This file contains device definitions, one per line.
run/: This folder contains scripts necessary to parse the device configuration, preload nvram contents and eventually invoke the userland processes of the device being emulated.
run/launcher: The main script.
devicesfile and displays a menu of registered devices. Selecting one of the devices will in turn invoke
qemu-system-armwith the pre-defined QEMU options, corresponding Linux kernel and extracted root file system registered with the device.
template/: Sample configuration and layout for a new device. Make a copy of the template when beginning to emulate a new IoT device.
Each emulated device contains the following files/directories:
config: Contains the device's name and description, ASLR settings, location of its root file system and commands to issue after the kernel has booted up and transferred control to the userland.
nvram.ini: Contents of the device's non volatile memory, used for storing configuration settings. Contents of
nvram.iniare preloaded into the emulated nvram before invoking the userland init scripts.
kernel/: Contains a Linux kernel compiled (mostly via Buildroot) to closely match the properties of the emulated device such as kernel version, CPU support, VM_SPLIT, supported peripherals, etc.
rootfs/: Populated with the uncompressed file system extracted from the device's firmware.
run-init: Script invoked by the launcher.
The diagram below describes each stage of ARM-X:
/armx/run/launcher. This will display a menu as shown below. In this example, we select the Trivision TRI227WF Wireless IP Camera.
- Selecting one of the devices will launch it under QEMU. The kernel which is included in the
kernel/directory of the Trivision IP Camera's device configuration, is booted in
qemu-system-armand uses a pre-built Buildroot filesystem, which is referred to as
hostfs.ext2. Host and guest IP addresses are assigned to
hostfs.ext2contains several scripts and tools useful for running and dynamic analysis of the emulated device. The init scripts in
/armxdirectory over NFS. Thus, the contents of
/armxare shared by both the host and the QEMU guest.
To kick off the rest of the device startup, connect to the QEMU guest using SSH
ssh email@example.com. This brings up a menu as shown below:
- Selecting the option to launch the userland init scripts of the device results in
run-initbeing invoked from the corresponding device configuration directory within
/armx. First, the contents of
nvram.iniare loaded into the kernel's emulated nvram driver. Next, a
chrootjail is created using the
rootfsof the device. Lastly, the registered initialisation commands are invoked in the newly
rootfs, bringing up the device's services and init scripts.
- Once the device has fully "booted up" in ARM-X, it is available for testing and analysis. The image below shows the administration interface of the IP Camera loaded in a browser:
Creating your own emulated IoT Device
Before you begin to emulate an IoT device, you will need the following:
- Detailed analysis of the IoT device
- CPU (ARMv5/ARMv6/ARMv7)
- Linux Kernel version
- Extracted mtdblocks (rootfs)
- Contents of nvram
- Generate a compatible kernel using Buildroot or Linux Kernel sources
- A week for troubleshooting!
The following diagram outlines the overall process of IoT device emulation.
- Copy the
templatedirectory to make a new device configuration.
- Compile a matching kernel from source, and place it in the
- Copy the extracted
rootfsfrom the device's firmware into the
rootfs/directory. Typically these would be SquashFS or CramFS filesystems, uncompressed using
- Place the contents of extracted nvram in
- Edit the
configfile with the newly populated device firmware contents.
- Create a new device record in the
devicesfile. Pay close attention to QEMU command line options.
The following sample kernels are provided with the template.
zImage-18.104.22.168-vexpressARMv7 CPU on a
zImage-22.214.171.124-realview-rv130-nothumbARMv6 CPU on a
zImage-2.6.31-versatile-nothumbARMv5 CPU on a
However, it is encouraged to build a compatible kernel from source.
Presentation at Countermeasure 2019 on 7 November 2019.<iframe src="//www.slideshare.net/slideshow/embed_code/key/6P5quK19YMwYQ5" width="595" height="485" frameborder="0" marginwidth="0" marginheight="0" scrolling="no" style="border:1px solid #CCC; border-width:1px; margin-bottom:5px; max-width: 100%;" allowfullscreen> </iframe>
Release presentation at HITB+Cyberweek on 16 October 2019.<iframe src="https://www.slideshare.net/slideshow/embed_code/key/9FqUwLVZaoLaxO" width="595" height="485" frameborder="0" marginwidth="0" marginheight="0" scrolling="no" style="border:1px solid #CCC; border-width:1px; margin-bottom:5px; max-width: 100%;" allowfullscreen> </iframe>
The ARM IoT Firmware Laboratory - NEW TRAINING
An all new class where the ARM IoT EXPLOIT LABORATORY leaves off. The ARM IoT Firmware Laboratory dives into analysis, extraction and emulation of IoT device firmware, using a variety of techniques. Students shall be given ample hands on practice in emulating a variety of IoT devices. Lab exercises feature firmware extraction directly from the hardware, building a custom kernel and buildroot environment, extracting contents of nvram and emulating the device under ARM-X. The class also goes on to fuzzing and exploit development exercises for the emulated devices.
- OffensiveCon 2020, Berlin: https://www.offensivecon.org/trainings/2020/the-arm-iot-firmware-laboratory-2020.html
Pre-built VM with ARM-X installed
The ARM-X VM is compressed using 7-Zip. The archive is split into multiple files of 200MB each, because several cloud hosting providers impose a maximum limit. To extract the VM, use the 7z command line utility:
7z e armx-november2019.7z.001
SHA 256 Checksums:
562144c896ec586ef3676efdc44957b28638dde9c14e48bef54aeb16c01714e2 armx-november2019.7z.001 9755449202e8c7677a6987a8bb2b84b72320446813b4c9fafcefe0f135eded37 armx-november2019.7z.002 2fa814609c86b2ecf331508f38d4b24834d814cf2f203f499a6ffd7681f7ef26 armx-alpine.vmx c491a8d0181b4af5df4a8cd0009cbf392e534fba7ea1e5dc5524c631fe37d08e armx-s001.vmdk f5d961585bd4b3911f2394a0ee49eb7b928b7f22e20fcdd759b74786dafacff3 armx.vmdk
VirtualBox VM: (coming soon, but don't hold your breath)
Tutorial: Debugging With ARM-X
ARM-X is licensed under the Mozilla Public License v2.0 (MPLv2).
- v0.9.0 22-October-2019, Preview Release
- v0.9.1 19-November-2019