Convert Figma logo to code with AI

osandov logodrgn

Programmable debugger

1,799
168
1,799
86
View on GitHub

Top Related Projects

volatilityfoundation's avatar

volatility

7,257

An advanced memory forensics framework

radareorg's avatar

radare2

20,547

UNIX-like reverse engineering framework and command-line toolset

google's avatar

rekall

1,930

Rekall Memory Forensic Framework

mandiant's avatar

flare-floss

3,337

FLARE Obfuscated String Solver - Automatically extract obfuscated strings from malware.

NationalSecurityAgency's avatar

ghidra

51,154

Ghidra is a software reverse engineering (SRE) framework

Quick Overview

Drgn is a programmable debugger, allowing users to write Python scripts to debug programs and operating systems. It provides a powerful and flexible interface for analyzing complex software systems, with a focus on Linux kernel debugging.

Pros

  • Highly extensible and customizable through Python scripting
  • Supports both user space and kernel debugging
  • Can be used for live systems and core dumps
  • Provides a rich API for introspecting complex data structures

Cons

  • Steep learning curve for users unfamiliar with debugging concepts
  • Limited documentation for advanced use cases
  • Primarily focused on Linux systems, limiting its use for other platforms
  • Requires root access for kernel debugging, which may not be available in all environments

Code Examples

  1. Accessing kernel data structures:
import drgn

prog = drgn.program_from_kernel()
init_task = prog['init_task']
print(f"Init task command: {init_task.comm.string_().decode()}")
  1. Iterating through process list:
import drgn

prog = drgn.program_from_kernel()
for task in prog['init_task'].tasks:
    print(f"PID: {task.pid.value_()}, Command: {task.comm.string_().decode()}")
  1. Examining memory contents:
import drgn

prog = drgn.program_from_kernel()
address = 0xffffffff81000000
size = 16
data = prog.read(address, size)
print(f"Memory at {hex(address)}: {data.hex()}")

Getting Started

To get started with drgn:

  1. Install drgn:
pip install drgn
  1. Create a Python script (e.g., debug.py) with your debugging logic:
import drgn

prog = drgn.program_from_kernel()
# Add your debugging code here
  1. Run the script with root privileges:
sudo python3 debug.py

Note: For user space debugging, use drgn.program_from_pid() or drgn.program_from_core_dump() instead of drgn.program_from_kernel().

Competitor Comparisons

volatilityfoundation logo

volatility

7,257

An advanced memory forensics framework

Pros of Volatility

  • Mature and widely-used memory forensics framework with extensive plugin ecosystem
  • Supports a broad range of operating systems and file formats
  • Large community and extensive documentation

Cons of Volatility

  • Can be slower for large memory dumps
  • Requires specific profile files for each OS version
  • Less flexible for custom analysis tasks

Code Comparison

Volatility (Python 2.x):

import volatility.utils as utils
import volatility.plugins.common as common

class MyPlugin(common.AbstractWindowsCommand):
    def calculate(self):
        addr_space = utils.load_as(self._config)
        # Plugin-specific analysis code

drgn (Python 3.x):

import drgn

prog = drgn.program_from_core_dump("/path/to/vmcore")
for task in prog.type("struct task_struct").list_for_each_entry("tasks"):
    print(task.comm.string_())

Summary

Volatility is a mature, widely-used memory forensics framework with extensive plugin support and broad OS compatibility. drgn, on the other hand, is a newer, more flexible debugger that offers faster performance and easier custom analysis capabilities, particularly for Linux systems. While Volatility uses a plugin-based architecture, drgn provides a more direct, programmatic approach to memory analysis.

radareorg logo

radare2

20,547

UNIX-like reverse engineering framework and command-line toolset

Pros of radare2

  • More mature and widely used project with a larger community
  • Supports a broader range of architectures and file formats
  • Offers a rich set of features for reverse engineering and binary analysis

Cons of radare2

  • Steeper learning curve due to its extensive feature set
  • Can be slower for large binaries compared to drgn's focused approach
  • Less specialized for kernel debugging compared to drgn

Code Comparison

radare2:

RCore *core = r_core_new();
r_core_cmd_str(core, "aaa");
r_core_cmd_str(core, "pdf@main");
r_core_free(core);

drgn:

prog = drgn.Program()
prog.load_debug_info()
main_func = prog.symbol('main')
print(main_func.type)

Summary

radare2 is a comprehensive reverse engineering framework with broad support for various architectures and file formats. It offers a wide range of features but can be more complex to learn. drgn, on the other hand, is more focused on kernel debugging and provides a simpler, Python-based interface for analysis tasks. While radare2 is more versatile, drgn excels in its specific domain of kernel debugging and analysis.

google logo

rekall

1,930

Rekall Memory Forensic Framework

Pros of Rekall

  • More mature project with longer development history
  • Broader feature set for memory forensics and incident response
  • Larger community and more extensive documentation

Cons of Rekall

  • Less actively maintained in recent years
  • Heavier and more complex codebase
  • Steeper learning curve for new users

Code Comparison

Rekall example:

from rekall import session
s = session.Session(filename="memory.dmp")
pslist = s.plugins.pslist()
for proc in pslist.filter_processes():
    print(proc.name, proc.pid)

drgn example:

import drgn
prog = drgn.program_from_core_dump("memory.dmp")
for task in prog.type('struct task_struct').list_for_each_entry('tasks'):
    print(task.comm.string_(), task.pid)

Summary

Rekall is a more established memory forensics framework with a wider range of features, while drgn is a newer, lightweight debugger focused on Linux kernel debugging. Rekall offers more comprehensive analysis capabilities, but drgn provides a simpler, more focused approach for kernel debugging tasks. The choice between them depends on specific use cases and user preferences.

mandiant logo

flare-floss

3,337

FLARE Obfuscated String Solver - Automatically extract obfuscated strings from malware.

Pros of flare-floss

  • Specialized for malware analysis and reverse engineering
  • Automated string extraction and deobfuscation capabilities
  • Active development and support from Mandiant

Cons of flare-floss

  • Limited to specific use cases in malware analysis
  • May require additional tools for comprehensive debugging
  • Less flexible for general-purpose debugging tasks

Code comparison

flare-floss:

def extract_strings(vw, fva):
    strings = []
    for va, s in vw.getStrings():
        if vw.isValidPointer(va):
            strings.append((va, s))
    return strings

drgn:

def print_task_name(prog, task):
    name = task.comm.string_()
    pid = task.pid.value_()
    print(f"Task: {name} (PID: {pid})")

Summary

flare-floss is a specialized tool for malware analysis and string extraction, while drgn is a more general-purpose debugger and systems programming tool. flare-floss excels in automated string analysis for reverse engineering, but drgn offers greater flexibility for kernel and userspace debugging across various scenarios. The choice between them depends on the specific requirements of the debugging or analysis task at hand.

NationalSecurityAgency logo

ghidra

51,154

Ghidra is a software reverse engineering (SRE) framework

Pros of Ghidra

  • Comprehensive reverse engineering suite with a wide range of features
  • Graphical user interface for easier navigation and analysis
  • Large community support and regular updates from NSA

Cons of Ghidra

  • Steeper learning curve due to its extensive feature set
  • Heavier resource consumption, especially for large binaries
  • Primarily focused on static analysis, with limited dynamic capabilities

Code Comparison

drgn:

prog = drgn.Program()
prog.set_core_dump("/path/to/core")
print(prog.thread_list())

Ghidra:

Program program = getCurrentProgram();
Listing listing = program.getListing();
Function function = listing.getFunctionAt(currentAddress);

Summary

drgn is a lightweight, Python-based debugger focused on Linux kernel and userspace debugging, offering a simpler interface for quick analysis. Ghidra, on the other hand, is a full-featured reverse engineering tool with a graphical interface, supporting multiple architectures and file formats. While drgn excels in its simplicity and Linux-specific features, Ghidra provides a more comprehensive set of tools for general-purpose reverse engineering tasks.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

drgn

|pypi badge| |ci badge| |docs badge| |black badge|

.. |pypi badge| image:: https://img.shields.io/pypi/v/drgn :target: https://pypi.org/project/drgn/ :alt: PyPI

.. |ci badge| image:: https://github.com/osandov/drgn/workflows/CI/badge.svg :target: https://github.com/osandov/drgn/actions :alt: CI Status

.. |docs badge| image:: https://readthedocs.org/projects/drgn/badge/?version=latest :target: https://drgn.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status

.. |black badge| image:: https://img.shields.io/badge/code%20style-black-000000.svg :target: https://github.com/psf/black

.. start-introduction

drgn (pronounced "dragon") is a debugger with an emphasis on programmability. drgn exposes the types and variables in a program for easy, expressive scripting in Python. For example, you can debug the Linux kernel:

.. code-block:: pycon

>>> from drgn.helpers.linux import list_for_each_entry
>>> for mod in list_for_each_entry('struct module',
...                                prog['modules'].address_of_(),
...                                'list'):
...    if mod.refcnt.counter > 10:
...        print(mod.name)
...
(char [56])"snd"
(char [56])"evdev"
(char [56])"i915"

Although other debuggers like GDB <https://www.gnu.org/software/gdb/>_ have scripting support, drgn aims to make scripting as natural as possible so that debugging feels like coding. This makes it well-suited for introspecting the complex, inter-connected state in large programs.

Additionally, drgn is designed as a library that can be used to build debugging and introspection tools; see the official tools <https://github.com/osandov/drgn/tree/main/tools>_.

drgn was developed at Meta <https://opensource.fb.com/>_ for debugging the Linux kernel (as an alternative to the crash <https://crash-utility.github.io/>_ utility), but it can also debug userspace programs written in C. C++ support is in progress.

.. end-introduction

Documentation can be found at drgn.readthedocs.io <https://drgn.readthedocs.io>_.

.. start-installation

Installation

Package Manager ^^^^^^^^^^^^^^^

drgn can be installed using the package manager on some Linux distributions.

.. image:: https://repology.org/badge/vertical-allrepos/drgn.svg :target: https://repology.org/project/drgn/versions :alt: Packaging Status

  • Fedora >= 32

    .. code-block:: console

    $ sudo dnf install drgn

  • RHEL/CentOS >= 8

    Enable EPEL <https://docs.fedoraproject.org/en-US/epel/#_quickstart>_. Then:

    .. code-block:: console

    $ sudo dnf install drgn

  • Oracle Linux >= 8

    Enable the ol8_addons or ol9_addons repository and install drgn:

    .. code-block:: console

    $ sudo dnf config-manager --enable ol8_addons  # OR: ol9_addons
$ sudo dnf install drgn

    Drgn is also available for Python versions in application streams. For example, use dnf install python3.12-drgn to install drgn for Python 3.12. See the documentation for drgn in Oracle Linux 9 <https://docs.oracle.com/en/operating-systems/oracle-linux/9/drgn/how_to_install_drgn.html>_ and Oracle Linux 8 <https://docs.oracle.com/en/operating-systems/oracle-linux/8/drgn/how_to_install_drgn.html>_ for more information.

  • Arch Linux

    .. code-block:: console

    $ sudo pacman -S drgn

  • Debian >= 12 (Bookworm)

    .. code-block:: console

    $ sudo apt install python3-drgn

  • Gentoo

    .. code-block:: console

    $ sudo emerge dev-debug/drgn

  • openSUSE

    .. code-block:: console

    $ sudo zypper install python3-drgn

  • Ubuntu

    All supported Ubuntu releases except for 22.04 (jammy) ships with drgn - but generally the version that was in Debian unstable at the time that Ubuntu release is branched.

    To get the latest version, including on jammy, enable the michel-slm/kernel-utils PPA <https://launchpad.net/~michel-slm/+archive/ubuntu/kernel-utils>_.

    To install drgn itself, with or without the PPA:

    .. code-block:: console

    $ sudo apt install python3-drgn

pip ^^^

If your Linux distribution doesn't package the latest release of drgn, you can install it with pip <https://pip.pypa.io/>_.

First, install pip <https://packaging.python.org/guides/installing-using-linux-tools/#installing-pip-setuptools-wheel-with-linux-package-managers>_. Then, run:

.. code-block:: console

$ sudo pip3 install drgn

This will install a binary wheel by default. If you get a build error, then pip wasn't able to use the binary wheel. Install the dependencies listed below <#from-source>_ and try again.

Note that RHEL/CentOS 6, Debian Stretch, Ubuntu Trusty, and Ubuntu Xenial (and older) ship Python versions which are too old. Python 3.6 or newer must be installed.

From Source ^^^^^^^^^^^

To get the development version of drgn, you will need to build it from source. First, install dependencies:

  • Fedora

    .. code-block:: console

    $ sudo dnf install autoconf automake check-devel elfutils-devel gcc git libkdumpfile-devel libtool make pkgconf python3 python3-devel python3-pip python3-setuptools

  • RHEL/CentOS/Oracle Linux

    .. code-block:: console

    $ sudo dnf install autoconf automake check-devel elfutils-devel gcc git libtool make pkgconf python3 python3-devel python3-pip python3-setuptools

    Optionally, install libkdumpfile-devel from EPEL on RHEL/CentOS >= 8 or install libkdumpfile <https://github.com/ptesarik/libkdumpfile>_ from source if you want support for the makedumpfile format. For Oracle Linux >= 7, libkdumpfile-devel can be installed directly from the corresponding addons repository (e.g. ol9_addons).

    Replace dnf with yum for RHEL/CentOS/Oracle Linux < 8.

    When building on RHEL/CentOS/Oracle Linux < 8, you may need to use a newer version of GCC, for example, using the devtoolset-12 developer toolset. Check your distribution's documentation for information on installing and using these newer toolchains.

  • Debian/Ubuntu

    .. code-block:: console

    $ sudo apt install autoconf automake check gcc git liblzma-dev libelf-dev libdw-dev libtool make pkgconf python3 python3-dev python3-pip python3-setuptools zlib1g-dev

    Optionally, install libkdumpfile from source if you want support for the makedumpfile format.

  • Arch Linux

    .. code-block:: console

    $ sudo pacman -S --needed autoconf automake check gcc git libelf libkdumpfile libtool make pkgconf python python-pip python-setuptools

  • Gentoo

    .. code-block:: console

    $ sudo emerge --noreplace --oneshot dev-build/autoconf dev-build/automake dev-libs/check dev-libs/elfutils sys-devel/gcc dev-vcs/git dev-libs/libkdumpfile dev-build/libtool dev-build/make dev-python/pip virtual/pkgconfig dev-lang/python dev-python/setuptools

  • openSUSE

    .. code-block:: console

    $ sudo zypper install autoconf automake check-devel gcc git libdw-devel libelf-devel libkdumpfile-devel libtool make pkgconf python3 python3-devel python3-pip python3-setuptools

Then, run:

.. code-block:: console

$ git clone https://github.com/osandov/drgn.git
$ cd drgn
$ python3 setup.py build
$ sudo python3 setup.py install

.. end-installation

See the installation documentation <https://drgn.readthedocs.io/en/latest/installation.html>_ for more options.

Quick Start

.. start-quick-start

drgn debugs the running kernel by default; run sudo drgn. To debug a running program, run sudo drgn -p $PID. To debug a core dump (either a kernel vmcore or a userspace core dump), run drgn -c $PATH. Make sure to install debugging symbols <https://drgn.readthedocs.io/en/latest/getting_debugging_symbols.html>_ for whatever you are debugging.

Then, you can access variables in the program with prog['name'] and access structure members with .:

.. code-block:: pycon

$ sudo drgn
>>> prog['init_task'].comm
(char [16])"swapper/0"

You can use various predefined helpers:

.. code-block:: pycon

>>> len(list(bpf_prog_for_each()))
11
>>> task = find_task(115)
>>> cmdline(task)
[b'findmnt', b'-p']

You can get stack traces with stack_trace() and access parameters or local variables with trace['name']:

.. code-block:: pycon

>>> trace = stack_trace(task)
>>> trace[5]
#5 at 0xffffffff8a5a32d0 (do_sys_poll+0x400/0x578) in do_poll at ./fs/select.c:961:8 (inlined)
>>> poll_list = trace[5]['list']
>>> file = fget(task, poll_list.entries[0].fd)
>>> d_path(file.f_path.address_of_())
b'/proc/115/mountinfo'

.. end-quick-start

See the user guide <https://drgn.readthedocs.io/en/latest/user_guide.html>_ for more details and features.

.. start-for-index

Getting Help

  • The GitHub issue tracker <https://github.com/osandov/drgn/issues>_ is the preferred method to report issues.
  • There is also a Linux Kernel Debuggers Matrix room <https://matrix.to/#/#linux-debuggers:matrix.org>_.

License

Copyright (c) Meta Platforms, Inc. and affiliates.

drgn is licensed under the LGPLv2.1 <https://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html>_ or later.

.. end-for-index