Home

Welcome to the avatar-python wiki!

Configuration script :

Avatar Python is configurable through a Dictionary object where you must define the Analyzer, the Emulator and the Target.

configuration = {
    "version"                       : 1.0
    "output_directory"              : <output directory>,
    "configuration_directory"       : os.getcwd(),
        "analyzer"                  : {"name" : "analyzer",     "configuration": analyzer_configuration },
        "emulator"                  : {"name" : "emulator",    "configuration": emulator_configuration },
        "target"                    : {"name" : "target", "configuration": target_configuration },
}

The main class of Avatar-Python is System which exposes all the available feature. The first argument is the configuration previously defined and some optional arguments such as Debug and Trace.

avatar = System(configuration, ["--debug", "--trace"])

Next you need to fill Analyzer/Emulator/Target 'configuration' fields :

The Target

The target represents the way you will communicate with the device under test. Supported targets are listed below :

• Openocd Telnet : Through a TCP socket, Openocd is listening Telnet commands. This mode is pretty slow...

• Openocd Gdb : Avatar-python implements the GDB-MI protocol to communicate with OpenOcd GDB-Server.

• GDB : The GDB-MI client directly communicates with the GDB stub on the device under test. You need to load the stub before (see How To Load The GDB Stub section).

• SuperspeedJtag library : Avatar-Python uses the SuperspeedJtag library to communicate directly with device through a JTAG interface. Check SuperspeedJtag documentation to see supported chip.

The Emulator

QEmu is the only one Emulator supported at this time.

emulator_configuration = {
    "emulator_configuration"  : <qemu arguments>,
    "machine_configuration"   : <machine json>,
        "avatar_configuration"      : {
            "gdb_address"                : "<protocol>:<address>:<port>",
            "gdb_additional_arguments"   : ["--data-directory= <path> ")],
            "gdb_path"                   : <path>
    }
}

You have to configure three things :

• Emulator Configuration that defines QEmu starting arguments :

"halt_processor_on_startup": True/False,
"trace_instructions": True/False,
"trace_microops": True/False,
"gdb": "tcp::<address>,server,nowait",
"append": ["-serial", "tcp::8888,server,nowait"],
"qmp": "tcp::<address>,server,nowait",

• The Virtual machine configuration :

"architecture": "arm",
"cpu_model": "cortex-m3",
"entry_address": 0xHEX,
"memory_map":   virtual_machine_memory,

• The virtual machine memory configuration is dictionary represented as below:

{"size": 0xHEX, "name": "A_NAME", "map": [{"address": 0xHEX, "type": "CODE/DATA", "permissions": "wrx"}]},

The Analyzer

For Klee refer to the page here

For S2E refer to the page here

For Angr refer to the page here