Debugging - angr Management

Overview

angr Management is a PySide6 (Qt) application that can be debugged using standard Python debugging tools. This guide covers debugging techniques for both the GUI and backend components.

Running in Development Mode

Standard Launch

Run angr Management directly from source:

python -m angrmanagement

Or use the installed entry point:

angr-management
# or
am

Command Line Options

Useful debugging flags:

# Run with profiling enabled
angr-management --profiling

# Open specific binary
angr-management /path/to/binary

# Run in headless mode (no GUI)
angr-management --no-gui

# Interactive IPython mode
angr-management --interactive

# Run script before launching
angr-management --script setup.py

# Enable autoreload (reload modules on job start)
angr-management --autoreload

# Show version
angr-management --version

Headless Mode

For testing without the GUI:

angr-management --no-gui --script your_script.py

Python Debugger

Using pdb

Insert breakpoints in code:

import pdb; pdb.set_trace()

Then run normally:

python -m angrmanagement

Using debugpy

angr Management bundles debugpy for remote debugging. Start with debugpy:

import debugpy

# Listen on port 5678
debugpy.listen(("localhost", 5678))
print("Waiting for debugger...")
debugpy.wait_for_client()

# Your code here
from angrmanagement.ui.main_window import MainWindow
main = MainWindow(show=True)

Connect from VS Code with this launch configuration:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Attach",
      "type": "debugpy",
      "request": "attach",
      "connect": {
        "host": "localhost",
        "port": 5678
      }
    }
  ]
}

Using VS Code

Launch configuration for direct debugging:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "angr Management",
      "type": "debugpy",
      "request": "launch",
      "module": "angrmanagement",
      "args": [],
      "console": "integratedTerminal",
      "justMyCode": false
    },
    {
      "name": "angr Management (with binary)",
      "type": "debugpy",
      "request": "launch",
      "module": "angrmanagement",
      "args": ["/path/to/binary"],
      "console": "integratedTerminal",
      "justMyCode": false
    }
  ]
}

Qt Debugging

Enable Qt Debug Output

Set environment variables:

export QT_DEBUG_PLUGINS=1
export QT_LOGGING_RULES="*.debug=true"
python -m angrmanagement

This shows:

Plugin loading details
Qt internal warnings
Event processing information

Qt Inspector

For visual debugging of the Qt widget hierarchy:

from PySide6.QtWidgets import QApplication

app = QApplication.instance()
# Enable inspector
app.setProperty("QT_INSPECTOR", True)

QTest for Interactive Testing

Test UI components programmatically:

from PySide6.QtTest import QTest
from PySide6.QtCore import Qt
from angrmanagement.ui.main_window import MainWindow

# Create headless window
main = MainWindow(show=False)

# Simulate interactions
QTest.mouseClick(main.some_button, Qt.LeftButton)
QTest.keyClick(main.some_input, Qt.Key_Enter)

# Check results
assert main.some_value == expected

Logging

Application Logging

angr Management uses Python’s logging system:

import logging

# Enable debug logging
logging.basicConfig(level=logging.DEBUG)

# Or configure specific loggers
logging.getLogger('angrmanagement').setLevel(logging.DEBUG)
logging.getLogger('angr').setLevel(logging.INFO)

angr Profiling

Enable angr’s profiling logger:

python -m angrmanagement --profiling

Or in code:

import angr
angr.loggers.profiling_enabled = True

Interactive Mode

IPython Console

Launch with interactive mode:

angr-management --interactive

Or with a script:

angr-management --script setup.py --interactive

The script’s globals are available in the script_globals variable.

Embedded Console

angr Management includes an embedded IPython console (via qtconsole). Access it from:

Menu: View → Console
Keyboard: Check command palette for shortcuts

The console has access to:

main_window  # MainWindow instance
workspace    # Current workspace
instance     # Current instance
project      # Current angr project

Debugging Analysis Jobs

Job Manager

angr Management runs analyses in background threads via the Job Manager. Debug jobs:

# In code or console
from angrmanagement.logic.jobmanager import JobManager

job_manager = main_window.workspace.job_manager

# List active jobs
for job in job_manager._jobs:
    print(f"{job.name}: {job.status}")

# Wait for all jobs
job_manager.join_all_jobs()

Thread Debugging

Identify the GUI thread:

from PySide6.QtCore import QThread
from angrmanagement.logic import GlobalInfo

# Check if running in GUI thread
if QThread.currentThread() == GlobalInfo.gui_thread:
    print("Running in GUI thread")
else:
    print("Running in background thread")

Memory Profiling

Using pytest-profiling

Run tests with memory profiling:

pytest --profile-mem

Using memory_profiler

Install and use memory_profiler:

pip install memory_profiler
python -m memory_profiler -m angrmanagement

Or decorate specific functions:

from memory_profiler import profile

@profile
def my_function():
    # Code to profile
    pass

Common Debugging Scenarios

Debugging a Crash

Enable core dumps (Linux/macOS):

ulimit -c unlimited
python -m angrmanagement

Run with faulthandler:

import faulthandler
faulthandler.enable()

from angrmanagement.__main__ import main
main()

Check Qt crash handlers:

export QT_FATAL_WARNINGS=1
python -m angrmanagement

Debugging UI Freezes

Check for blocking operations in GUI thread:

from PySide6.QtCore import QThread
import time

start = time.time()
# Your code
if QThread.currentThread() == GlobalInfo.gui_thread:
    duration = time.time() - start
    if duration > 0.1:
        print(f"Warning: GUI thread blocked for {duration}s")

Use QTimer to defer work:

from PySide6.QtCore import QTimer

QTimer.singleShot(0, lambda: expensive_operation())

Debugging Plugin Issues

Check plugin loading:

from angrmanagement.plugins import PluginManager

pm = PluginManager(main_window)
pm.discover_and_initialize_plugins()

# List loaded plugins
for plugin in pm.loaded_plugins:
    print(f"{plugin.name}: {plugin.enabled}")

Performance Analysis

Using cProfile

python -m cProfile -o output.prof -m angrmanagement

Analyze results:

import pstats
stats = pstats.Stats('output.prof')
stats.sort_stats('cumulative')
stats.print_stats(20)

Using pytest-profiling

For test profiling:

pytest --profile

Autoreload for Development

Enable module reloading on each job start:

angr-management --autoreload

This reloads Python modules before starting each analysis job, useful for rapid iteration without restarting the GUI.

Debugging Binary Analysis

Access angr Objects

In the console or via API:

# Get current project
project = main_window.workspace.main_instance.project.am_obj

# Run analysis with debugging
cfg = project.analyses.CFGFast()
print(cfg.graph.nodes())

# Access specific functions
func = project.kb.functions[0x400000]
print(func.blocks)

Enable angr Debugging

import logging

logging.getLogger('angr.analyses').setLevel(logging.DEBUG)
logging.getLogger('angr.engines').setLevel(logging.DEBUG)

Environment Variables

Useful environment variables for debugging:

# Qt debugging
export QT_DEBUG_PLUGINS=1
export QT_LOGGING_RULES="*.debug=true"
export QT_FATAL_WARNINGS=1

# Python debugging
export PYTHONDEVMODE=1
export PYTHONASYNCIODEBUG=1

# angr debugging
export ANGR_LOGFILE=/tmp/angr.log

Overview

Plugin Development

UI Development

Advanced

​Overview

​Running in Development Mode

​Standard Launch

​Command Line Options

​Headless Mode

​Python Debugger

​Using pdb

​Using debugpy

​Using VS Code

​Qt Debugging

​Enable Qt Debug Output

​Qt Inspector

​QTest for Interactive Testing

​Logging

​Application Logging

​angr Profiling

​Interactive Mode

​IPython Console

​Embedded Console

​Debugging Analysis Jobs

​Job Manager

​Thread Debugging

​Memory Profiling

​Using pytest-profiling

​Using memory_profiler

​Common Debugging Scenarios

​Debugging a Crash

​Debugging UI Freezes

​Debugging Plugin Issues

​Performance Analysis

​Using cProfile

​Using pytest-profiling

​Autoreload for Development

​Debugging Binary Analysis

​Access angr Objects

​Enable angr Debugging

​Environment Variables

Build docs developers (and LLMs) love

Overview

Running in Development Mode

Standard Launch

Command Line Options

Headless Mode

Python Debugger

Using pdb

Using debugpy

Using VS Code

Qt Debugging

Enable Qt Debug Output

Qt Inspector

QTest for Interactive Testing

Logging

Application Logging

angr Profiling

Interactive Mode

IPython Console

Embedded Console

Debugging Analysis Jobs

Job Manager

Thread Debugging

Memory Profiling

Using pytest-profiling

Using memory_profiler

Common Debugging Scenarios

Debugging a Crash

Debugging UI Freezes

Debugging Plugin Issues

Performance Analysis

Using cProfile

Using pytest-profiling

Autoreload for Development

Debugging Binary Analysis

Access angr Objects

Enable angr Debugging

Environment Variables