Add alternative emulation through unicorn engine by ks0777 · Pull Request #57 · Fraunhofer-AISEC/archie

ks0777 · 2023-03-14T13:30:36Z

This PR adds the unicorn emulation engine to archie. It can be enabled by passing the --unicorn flag to the controller. With this option enabled, archie will emulate the experiments with the unicorn engine instead of QEMU. The (pre-)goldenrun is still emulated with QEMU which is necessary in order to obtain a state from which we can start our experiments from.

The alternative emulation mode was implemented in a seperate Rust library and integrated into archie with minimal changes to the faultclass and controller scripts. This allows for easy reuse of the filtering and processing functions that have previously been implemented for the experiment data returned by QEMU.

ks0777 · 2023-04-21T13:25:44Z

Waiting for unicorn-engine/unicorn#1812 to be merged. We need the additional Rust bindings in order to clear the tb cache after modifying instructions during a fault

e-shreve-ti · 2023-05-01T21:20:15Z

This is a nice addition! If I may, here is a suggestion to increase the flexibility of the solution toward supporting additional emulation engine support (even beyond qemu and unicorn):

Instead of a --unicorn argument to controller.py, do the following:
- Either change the --qemu option to --emu now or add an --emu option as an alternative to --qemu (they would do the same thing). The idea of adding --emu without replacing --qemu would be to deprecate --qemu toward only having --emu in a future update.
- The json file passed to --emu could then provide either a "qemu" or a "unicorn" member. The value of those members would be the path to the emulator binary (just as the "qemu" member is today.) However, if "qemu" member is provided then qemu is used, if "unicorn" member is provided then unicorn is used. Instead of passing the new bool value of unicorn_emulation to controller(), the controller() function can then just look for the "unicorn" member and set its internal boolean unicorn_emulation based on that. This also avoids the confusion for users of passing the path to unicorn in the "qemu" member.
- Update the "additional_qemu_args" member of the config.json to be called "additional_args", this will be clearer to users long-term.

The idea here is that if an additional emulation engine is added in the future, then the framework is already setup for that. The controller() function would just be modified to look for a new "otheremulatorname" member in the config file and take actions as needed there. It also means users don't have to match command line parameters to controller.py with the contents of the emulation JSON file-all the settings are in the JSON file.

ks0777 · 2023-05-03T17:11:21Z

Thanks for your suggestion! Including, the choice of emulation engine into the configuration files sounds a like a good idea. Note that when using Unicorn, the pre-goldenrun is still performed using QEMU in order to ensure compatibility with more firmware since Unicorn can not handle any hardware related functions. Unlike QEMU, the unicorn engine is invoked through a Python module which wraps a Rust library. The required data for the initialization of Unicorn is retrieved from the pre-goldenrun. Hence, there is no need to supply additional arguments or a path to the emulator binary for Unicorn. This may change in the future if we ever decide to add addtional emulation engines, but for now these arguments only apply to QEMU.

README.md

lukasauer · 2025-11-13T16:17:48Z

README.md

 make
+cd emulation_worker
+cargo build --release
+cp target/release/libemulation_worker.so ../emulation_worker.so


What's the advantage of this, can we just leave it in the build dir?

I can't directly import the .so if its directory is not in the PATH. An alternative would be to add the build directory to the path before importing the .so in faultclass.py. This is easily done with 4 lines of code but overall not really clean either imo. With this solution, however, there would be no more copies of the .so file which might be less confusing.

I agree, both solutions are not perfect. Maybe the best would be to adopt the same approach we are currently using for the faultplugin. That would mean not copying the library and instead adding a new config entry to qemuconf.json for specifying its location.

examples/stm32-timeout-wfi/run.sh

faultplugin/faultplugin.c

controller.py

faultclass.py

lukasauer · 2025-11-14T11:17:33Z

goldenrun.py

-    return [config_qemu["max_instruction_count"], experiment["data"], faultconfig]
+    return [
+        config_qemu["max_instruction_count"],
+        experiments[0]["data"],


This breaks if we do not have a pregolden run (if no start address is specified in the config). Not sure what the best way to handle this is.

(pre-)goldenrun experiment results are now stored in distinct variables instead of a list with varying size. If no pre-goldenrun was performed None is returned.

Code looks good. Is it a problem for the unicorn system if we do not have a memory dump from the pregoldenrun in configs without start address?

That's a problem, yes. We would either have to implement a pure unicorn mode that does not require the bootstrapping through QEMU or print an error and abort when unicorn emulation is requested without a start address. Is there a reason why you would not want to specify a start address? In the hybrid QEMU+Unicorn mode specifying a start address will always improve performance since the state is restored from the start address instead of fully emulating each run from the beginning.

I guess the only use case would be faulting the very first executed instruction. I think at least for now it makes sense to only print an error if no start address is specified in Unicorn mode.

hdf5logger.py

initialization

…n; allow multiple PT_LOAD segments

faultplugin/faultplugin.c

 	g_string_append_printf(out, "Current Version of QEMU Plugin is %i, Min Version is %i\n", info->version.cur, info->version.min);
+	architecture = malloc(strlen(info->target_name)+1);
+	if (!architecture) return -1;
+	strcpy(architecture, info->target_name);


faultplugin/faultplugin.c

 	g_autoptr(GString) out = g_string_new("");
 	g_string_printf(out, "QEMU Injection Plugin\n Current Target is %s\n", info->target_name);
 	g_string_append_printf(out, "Current Version of QEMU Plugin is %i, Min Version is %i\n", info->version.cur, info->version.min);
+	architecture = malloc(strlen(info->target_name)+1);


ks0777 force-pushed the unicorn branch 6 times, most recently from 64ab813 to 8d197d3 Compare March 23, 2023 11:39

ks0777 force-pushed the unicorn branch 3 times, most recently from 9e429da to 12a47c2 Compare April 25, 2023 14:39

ks0777 force-pushed the unicorn branch from 12a47c2 to efb1106 Compare May 9, 2023 13:50

ks0777 force-pushed the unicorn branch 2 times, most recently from 539dd18 to 9808021 Compare October 23, 2025 15:16

lukasauer reviewed Nov 14, 2025

View reviewed changes

ks0777 force-pushed the unicorn branch from e7a95ee to dbe7a22 Compare November 18, 2025 14:57

ks0777 added 13 commits January 5, 2026 11:05

add full memory and memory map dump option to faultplugin

631f56e

dump full memory state after pregoldenrun and pass to unicorn worker

331f918

add unicorn emulation worker with meminfo logging and pregoldenrun

2e84241

initialization

implement fault types

5b41bd4

implement fault lifetimes

5ea4e69

add endpoint logging

90cf5b5

add tbinfo logs

a1ac90e

add tbexec logs

b509af9

filter tbexec/tbinfo entries

b32f39e

add memory and arm/riscv register dumps

d7a7eb0

dump pregoldenrun memory map; handle registerdumps

575b61c

add logging framework

9757fa8

remove modified tbs from cache during emulation

244c641

ks0777 added 14 commits January 5, 2026 11:06

fix emulation_worker

0c316e2

read pregoldenrun from backup

e721d76

fix log entry in gitignore

9e8b023

include basic unicorn tests in ci pipeline

868eee0

update python dependencies

9b09415

fix register table selection for riscv

cfdf338

fix dead link

c11682f

undo stm32-timeout-wfi run.sh changes

6122c8e

remove unused variable

f818272

remove unused workflow

3264dba

controller.py: remove print; remove duplicate engine_output definitio…

1f3bad9

…n; allow multiple PT_LOAD segments

controller.py: only parse pregoldenrun backup in unicorn mode

a74f941

faultclass.py: remove unnecessary return

8839c34

goldenrun.py: fix exception for configs without start address

1b8dc35

ks0777 force-pushed the unicorn branch from dbe7a22 to 5a292ea Compare January 5, 2026 10:32

github-advanced-security bot found potential problems Jan 5, 2026

View reviewed changes

ks0777 force-pushed the unicorn branch from 5a292ea to 27c5041 Compare January 5, 2026 13:12

add aarch64 support to unicorn emulation

7cffe59

ks0777 force-pushed the unicorn branch from 27c5041 to 7cffe59 Compare January 5, 2026 16:10

Conversation

ks0777 commented Mar 14, 2023

Uh oh!

ks0777 commented Apr 21, 2023

Uh oh!

e-shreve-ti commented May 1, 2023

Uh oh!

ks0777 commented May 3, 2023

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Check failure

Check notice

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants