ARMX Firmware Emulation Framework

by Saumil Shah @therealsaumil

June 2021

NEW RELEASE: ARMX ON DOCKER

ARMX Docker

A brand new Docker container running ARMX. Going ahead, all official ARMX releases shall be released as Docker images. Lightweight, Compact, Easy.

Shut up and give me the g00diez

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

A brand new ARMX Docker image is ready for use! The old "Preview VM" is now discontinued in favour of the Docker image.

QUICK INSTALL STEPS

Step 1 - Clone this repository

git clone --depth 1 --single-branch  https://github.com/therealsaumil/armx.git

Step 2 - Build the docker volume and image

cd armx
./build-armx-volume
./build-armx-docker

Step 3 - Run ARMX!

Open a terminal, and start the armx-docker container:

./run-armx-docker

You will be greeted with a purple shell prompt [r0@ARMX-DOCKER 🐳:~$]. After a while, it is common to have many terminals attached to the container. Coloured shell prompts makes it easy to remember where you are.

Next, start the ARMX launcher:

[r0@ARMX-DOCKER 🐳:~$] launcher

and select any emulated device that you wish to run.

Step 4 - Launch the emulated device's userland processes.

Next, open a new terminal and attach to the running armx-docker container:

./armx-docker-shell

All attached container shells have a blue shell prompt. Invoke the userspace command to bring up the userland processes of the emulated target:

[r0@armx-docker shell 🐚:~$] userspace

Read the documentation for more details.

INTRODUCING

ARMX

The ARMX Firmware Emulation Framework is a collection of scripts, kernels and filesystems to be used with QEMU to emulate ARM/Linux IoT devices. ARMX 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.

ARMX Launcher

Devices successfully emulated with ARMX so far:

Precursors of ARMX have been used in Saumil Shah's popular ARM IoT Exploit Laboratory training classes where students have found four several 0-day vulnerabilities in various ARM/Linux IoT devices.

ARMX Architecture

ARMX 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.

Architecture

ARMX is packaged as a Docker image. The diagram below shows how the docker container is organised:

Docker Architecture

The docker image consists of:

The /armx directory

The /armx directory is organised as follows:

Directory Structure

The run/ directory also contains a few commands that can be used from the host to interact with processes running within an ARMX emulated device.

armxps, armxmaps and armxgdb are explained in detail in the Debugging With ARMX tutorial.

Contents of an emulated device

Each emulated device contains the following files/directories:

Running an emulated device in ARMX

The diagram below describes each stage of ARMX:

ARMX Operations

There are five steps in running an emulated device:

  1. Launcher - choose from a list of available emulated devices
  2. Select a device and boot its kernel and its hostfs
  3. Userspace - choose from a list of available userspace actions
  4. Start the devices' userspace processes
  5. Optionally drop into the hostfs shell

Step 1: The Launcher

Invoke launcher.

ARMX Launcher Command

This will display a menu as shown below. In this example, we select the Trivision TRI227WF Wireless IP Camera.

ARMX Launcher

Step 2: Start a device

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.

ARMX Kernel Boot Up

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.

Step 3: Userspace

You will need to attach to the running armx-docker container and invoke the userspace command at the shell prompt.

ARMX Userspace Command

Internally the userspace command simply connects to the QEMU guest using SSH ssh root@192.168.100.2. This brings up a menu as shown below:

ARMX Trivision Init

Step 4: Start the userspace processes

Selecting the option to launch the userspace processes 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.

ARMX Trivision Started

Step 5: Device booted up and ready

Once the device has fully "booted up" in ARMX, it is available for testing and analysis. The image below shows the administration interface of the IP Camera loaded in a browser. Note, to access the internal ports on 192.168.100.2 we will rely on port forwarding performed by socat. By default, the following ports are forwarded:

localhost:20080 -> 192.168.100.2:80
localhost:20443 -> 192.168.100.2:443
localhost:28080 -> 192.168.100.2:8080

To access the web administration interface for the booted up device, open a browser and navigate to localhost:28000. This in turn will forward your request to 192.168.100.2:80 inside the armx-docker container.

ARMX Admin Interface

Overriding the forwarded ports

ARMX port forwarding is controlled by the PORTFWD environment variable. It is a comma separated list containing FORWARDED_PORT:INTERNAL_PORT pairs. To override the default port forwarding, simply set the contents of PORTFWD before invoking run-armx-docker:

export PORTFWD="28000:8000,25800:5800"
./run-armx-docker

Creating your own emulated IoT Device

Before you begin to emulate an IoT device, you will need the following:

The following diagram outlines the overall process of IoT device emulation.

Adding a new device

Steps involved:

  1. Copy the template directory to make a new device configuration.
  2. Compile a matching kernel from source, and place it in the kernel/ directory. You may also symlink an existing kernel if you wish to.
  3. Copy the extracted rootfs from the device's firmware into the rootfs/ directory. Typically these would be SquashFS or CramFS filesystems, uncompressed using binwalk or unsquashfs or cramfsck. Optionally you may also create a compressed tar.bz2 archive of the root file system.
  4. Place the contents of extracted nvram in nvram.ini
  5. If you wish to emulate MTD flash, dump the contents of your device's flash memory and create two 64MB files named flash0.bin and flash1.bin and place them in the flashmem/ directory. Optionally you may also compress them in a tar.bz2 archive. You will then need to define the MTD partition layout to be passed to the kernel in the mtdparts file.
  6. Place any shared libraries that you wish to inject using LD_PRELOAD in the preload/ directory. Usually these shared libraries contain hooked functions necessary for certain emulated binaries to work properly.
  7. Edit the config file with the newly populated device firmware contents.
  8. Create a new device record in the devices-extra file. Pay close attention to QEMU command line options.

The following sample kernels are provided with the template.

However, it is encouraged to build a compatible kernel from source.

The ARMX Activity Log File

The June 2021 release of ARMX comes with a feature to enable activity logs. This comes in very handy in troubleshooting errors when adding a new device to ARMX. To enable logging, edit the /armx/debuglogs file:

# Uncomment logpath= to enable ARMX and QEMU console output logging.
# Only one logpath= should be uncommented.
#
#logpath=/home/r0/workspace/logs/
#logpath=/armx/logs/

It is recommended to use /home/r0/workspace/logs since the workspace directory is shared between the container and the host.

ARMX In The Public

Presentation at Countermeasure 2019 on 7 November 2019. 👇

INSIDE ARMX - Countermeasure 2019 from Saumil Shah

Release presentation at HITB+Cyberweek on 16 October 2019. 👇

Introducing ARMX from Saumil Shah

Announcing ARMX Docker on 15 June 2021. 👇

Announcing ARMX Docker - DC11332 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 ARMX. The class also goes on to fuzzing and exploit development exercises for the emulated devices.

Upcoming classes:

Ringzer0 #VirtualVegas August 2021, Online Remote Training: (4 day class) https://ringzer0.training/arm-iot-exploitlab.html

Downloads

The pre-built ARMX PREVIEW VM is now discontinued. You are encouraged to use ARMX on Docker

ARMX Code

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

ARMX Documentation

END

ARMX is licensed under the Mozilla Public License v2.0 (MPLv2).