ARM-X Firmware Emulation Framework

October 2019

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 192.168.100.2 via tap0 interface.

The /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. launcher parses the devices file and displays a menu of registered devices. Selecting one of the devices will in turn invoke qemu-system-arm with 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.ini are 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:

Invoke /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-arm and uses a pre-built Buildroot filesystem, which is referred to as hostfs.ext2. Host and guest IP addresses are assigned to 192.168.100.1 and 192.168.100.2 respectively.

hostfs.ext2 contains several scripts and tools useful for running and dynamic analysis of the emulated device. The init scripts in hostfs.ext2 mount the /armx directory over NFS. Thus, the contents of /armx are 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 root@192.168.100.2. This brings up a menu as shown below:

Selecting the option to launch the userland init scripts of the device results in run-init being invoked from the corresponding device configuration directory within /armx. First, the contents of nvram.ini are loaded into the kernel's emulated nvram driver. Next, a chroot jail is created using the rootfs of the device. Lastly, the registered initialisation commands are invoked in the newly chrooted 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:

Release Presentation

ARM-X was released at HITB+Cyberweek on October 16 2019. Here are the slides from the talk at HITB+Cyberweek:

Introducing ARM-X from Saumil Shah

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.

Upcoming classes:

44CONnect Training December 2020, London: https://44con.com/44con-training/arm-iot-firmware-laboratory-2020-preview/
OffensiveCon 2020, Berlin: https://www.offensivecon.org/trainings/2020/the-arm-iot-firmware-laboratory-2020.html

Downloads

Pre-built VM with ARM-X installed

VMware VM: https://armx.exploitlab.net/armx-preview-vm.zip

VirtualBox VM: (coming soon, but don't hold your breath)

SHA256sum: 53545d507238fa4e63528a762512de0bce97784260c8e4e23512f2f9eb18d350

ARM-X Code

Github: https://github.com/therealsaumil/armx/

TODO

Clean up the documentation

END

ARM-X is licensed under the Mozilla Public License v2.0 (MPLv2).

v0.9 22-October-2019, Preview Release

threatintel-c/armx