Skip to content

Getting Started

Requirements

  • Python 3.10+
  • Access to a running Havoc server
  • Optional API key from the Havoc web UI (/api-keys)

Install From Source

git clone <your-sdk-repo-url>
cd metalware-sdk
python3 -m venv .venv
. .venv/bin/activate
pip install -e .

This installs:

  • Python package metalware_sdk
  • CLI command havoc

Configure CLI

havoc setup
  • Prompts for server URL
  • Verifies connectivity using GET {url}/api/dashboard
  • Optionally stores API key
  • Stores config in ~/.config/havoc/config.json (mode 0600)

Config precedence: 1. HAVOC_URL overrides config url 2. HAVOC_API_KEY overrides config token 3. verify_ssl is currently read from config only

First Submission

CLI:

havoc submit firmware.elf

Useful options: - --mcu cortexm (default and currently only CLI-supported value) - --workers N - --timeout 3600|10m|24h|0 - --tag value (repeatable, max 16 tags)

Python:

from metalware_sdk import HavocClient
from metalware_sdk.havoc_common_schema import CortexMGeneric, Image, ImageFormat, Mcu

client = HavocClient(base_url="http://localhost:8080")
metadata = client.upload_file("firmware.elf", label="firmware.elf")

image = Image(
    image_format=ImageFormat(Elf=metadata.id),
    entry_address=0,
    dma_buffers=[],
    patches=[],
    symbols=[],
    handlers=[],
)

analysis = client.create_analysis(
    mcu=Mcu(CortexMGeneric=CortexMGeneric()),
    image=image,
    auto=True,
)

print(analysis.analysis_id)

Repository Layout

  • src/metalware_sdk/: SDK implementation
  • examples/: runnable scripts
  • tests/: current repository test placeholder
  • docs/: markdown docs for docs-site ingestion