Skip to content

Python SDK Reference

Imports

from metalware_sdk import HavocClient
from metalware_sdk.havoc_common_schema import *
from metalware_sdk.havoc_analysis import HavocAnalysis
from metalware_sdk.havoc_extras import TestcaseInput
from metalware_sdk.replay_debugger import ReplayDebugger, WatchType

HavocClient

Main HTTP client (src/metalware_sdk/havoc_client.py).

Constructor:

HavocClient(base_url: str, verify_ssl: bool = True, token: str | None = None)

If token is provided, client sets Authorization: Bearer <token>.

File and configuration: - upload_file(file_path, label="unnamed") -> FileMetadata - infer_config(file_id, mcu) -> InferredConfig - infer_config_from_file(file_path, mcu) -> InferredConfig

Analysis lifecycle: - create_analysis(mcu, image, auto=True, worker_count=None, timeout_secs=None, tags=None) -> HavocAnalysis - get_analysis(analysis_id) -> HavocAnalysis - get_analyses() -> list - analysis_exists(analysis_id) -> bool - delete_analysis(analysis_id) -> None - stop_analysis(analysis_id) -> None - get_analysis_status(analysis_id) -> AnalysisStatusResponse

Analysis configuration: - set_tags(analysis_id, tags) -> None - set_fuzzer_config(analysis_id, fuzzer_config) -> None - get_fuzzer_config(analysis_id) -> FuzzerConfig - set_image(analysis_id, image) -> None - get_analysis_image(analysis_id) -> Image - set_memory_map(analysis_id, memory_map) -> None - get_mcu(analysis_id) -> Mcu

Run methods: - start_run(analysis_id, params: RunParams) -> str - get_run_status(run_id) -> RunStatus - stop_run(run_id) -> None - get_runs(analysis_id) -> list[tuple[str, RunSummary]] - get_run_stats(run_id) -> RunStats - get_testcases(run_id) -> list[Testcase] - get_testcase_input(run_id, testcase_id) -> TestcaseInput

Debug/session: - start_debug_session(run_id, testcase_id) -> None - send_debug_command(run_id, testcase_id, command) -> str|dict

Dashboard/server: - get_dashboard_status() -> dict - update_settings(**kwargs) -> dict - inject_image(zip_path) -> None - inject_analysis(zip_path) -> str

HavocAnalysis

Convenience wrapper bound to one analysis_id (src/metalware_sdk/havoc_analysis.py).

Creation:

analysis = client.get_analysis(analysis_id)

Primary methods: - get_status, stop, delete - start_run, get_runs, get_run_status, stop_run, get_run_stats, get_testcases - set_tags / get_tags - set_fuzzer_config / get_fuzzer_config - set_image / get_image - add_raw_image, add_elf_image - get_memory_map, set_memory_map

ReplayDebugger

High-level helper over debug-session commands (src/metalware_sdk/replay_debugger.py).

Creation starts a session immediately:

dbg = ReplayDebugger(client, run_id, testcase_id)

Execution: - run, step, step_back, step_block, step_back_block, rewind

Break/watch points: - add_breakpoint, remove_breakpoint, add_watchpoint, remove_watchpoint, list_breakpoints, list_watchpoints

Registers/memory: - Registers: read_register, write_register, list_registers - Memory: read_memory, write_memory

Disassembly/trace/input: - Disassembly: disassemble, disassemble_range, print_asm - Trace: backtrace, print_backtrace, state - Input editing: get_input, write_input, fork_input

WatchType values: - WatchType.READ - WatchType.WRITE

TestcaseInput

TestcaseInput.from_bytes(...) parses raw testcase-input bytes into channel map:

  • Magic: b"hav\\x02"
  • Channel count limit: <= 0x10000
  • Per-channel data limit: <= 0x100000

Representation is a table-like string (__repr__) for quick printing.

Error Handling

  • HTTP/API errors are wrapped as RuntimeError by _make_request.
  • Missing files raise FileNotFoundError before upload/inject methods.
  • Client/helpers do not retry automatically; add retries in caller code when needed.