pyGdbToolkit: embedded debugging and security audits from GDB

H2Lab is releasing pyGdbToolkit, a collection of GDB commands for embedded debugging and security audits, especially on Arm Cortex-M microcontrollers. The source code is available on GitHub, and the package is published on PyPI.

Why pyGdbToolkit

Debugging an embedded target often means moving between GDB, vendor utilities, reference material, and small scripts. pyGdbToolkit brings several useful inspections directly into the GDB session and presents their results as readable reports. It reads target memory through the existing GDB connection, without requiring a separate probe protocol or vendor IDE.

What it provides

lscpu identifies the Cortex-M core and, on supported STM32 devices, reports the documented product line and available device signatures.
fault_info decodes Cortex-M fault status and the stacked exception context; showstack inspects stack frames and layout.
svd loads CMSIS-SVD descriptions to read registers and bit fields, write values, monitor changes, or export a JSON snapshot.
secscan audit checks Cortex-M security configuration, including MPU permissions, exception handlers, TrustZone, and STM32 read-out protection when applicable.
rtos exposes project and task information for Camelot, the currently supported RTOS.

Usage

Install the package in a Python environment compatible with GDB’s embedded Python (GDB must be built with Python support):

python3 -m pip install pyGdbToolkit

After connecting to and halting the target in GDB, load the commands and inspect the target:

(gdb) py import pyGdbToolkit
(gdb) lscpu
(gdb) svd load
(gdb) svd show GPIOA
(gdb) secscan audit

For fault analysis, run fault_info after the target stops in a fault handler. Use svd read /path/to/device.svd to load a specific SVD file when automatic detection is unavailable. The repository includes a gdbinit example and detailed documentation for each command.

Availability

pyGdbToolkit requires Python 3.12 or newer and GDB with embedded Python support. Its dependencies, requests and rich, are installed with the package. It is distributed under the Apache 2.0 license. Find the source, documentation, and tests on the GitHub repository, or install it from PyPI.