A project describes a firmware-fuzzing campaign (see DefinitionsDefinitions for more details). To create a new project, simply follow the next few steps:

1. Upload Your Firmware Binary

Open your web browser and navigate to:
bash
http://<host>:<port>
You will see the Metalware home screen:
Image without caption
Click the New Project button. This opens a form for uploading your firmware binary. Select an appropriate name and architecture for your project.
💡
See Supported TargetsSupported Targets for the types of targets and image formats we support.
Image without caption

2. Check the Inferred Configuration

Metalware will try to automatically infer an image configuration and a device configuration from the uploaded file:
  • Image Configuration
    • For an ELF file, Metalware will try to infer the vector table address of the image. A vector table contains the initial stack pointer and exception handlers and is normally found at the start of the text section.
    • For a RAW file (.bin), Metalware will try to infer the base address of the firmware file.
  • Device Memory Layout
    • The inferred memory layout should match the one found in the reference manual of the device.

ELF images

An ELF is assumed to contain all code necessary to run the firmware.
If you upload an ELF, you will be presented with the following screen asking you to confirm the inferred device memory layout and vector table address for the image:
Image without caption

RAW images

A RAW image is made up of one or more firmware files.
If you upload a stripped firmware file (.bin), you will be asked to configure it and optionally add additional such files that make up your RAW image:
Image without caption
For example, a second file may be necessary for the bootloader, which you can select via Upload File:
Image without caption
💡
It is sufficient to get the memory configuration correct enough to successfully create the project. When you submit the form, the tool will check the validity of your memory configuration by executing the firmware (we call this a “dry run” of your firmware).
💡
Without knowing everything about the hardware the firmware runs on, it is common to miss memory regions in the initial configuration while still passing the dry run. This is acceptable as any missing memory regions will be caught during fuzzing and can be easily be added to the device configuration later.

Memory Layout Guidelines

Each memory region will fall into one of the following categories:
Memory Type
Data Source
Description
ROM
Your firmware image.
Flash and ROM-like memory in your SoC’s memory space.
RAM
Initialized to 0.
Volatile memory (e.g., DRAM, SRAM).
MMIO
Fuzzed.
Memory-mapped I/O for peripherals or secondary memory (e.g., UART, Bluetooth, HSM, Zigbee, external flash).
💡
If your firmware assumes presence of an External Flash (separate from program flash) with a particular configuration loaded, designate that region as MMIO rather than RAM so that fuzzer will handle any values read from NVRAM.
General Guidelines
  • Define small, distinct MMIO regions for board-specific peripherals (i.e. Nordic’s chip id).
  • If your firmware interfaces with secondary storage (e.g., external flash, EEPROM, NVRAM) that does not host the firmware image, map that memory region as MMIO.
  • For Cortex-M only:
    • Allocate a large, contiguous MMIO region for external peripherals (0x40_000_000 is typical). This is automatically inferred for Cortex-M images.

4. Click “Create Project”

Once you’ve verified the memory maps, click the Create Project button.
Metalware will perform a dry run of your firmware to ensure that the memory map is correctly configured.
✅ Success : If the configuration is correct, you will see a confirmation message in the Status box:
Image without caption
❌ Failure: If there is an error (e.g., a memory segment is too small or missing), you will see an error message similar to the example below:
Image without caption
This error above indicates that the RAM region may be undersized:
  • We ALREADY have a RAM memory region starting at 0x20000000 of size 0x1000.
  • Emulator fails to write to unmapped memory address: 0x20005ac4.
Bumping the size of the region to 0x10000 in this case resolves the issue.