• Stars
    star
    107
  • Rank 323,587 (Top 7 %)
  • Language
    C
  • License
    Apache License 2.0
  • Created almost 6 years ago
  • Updated over 4 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A tool for debugging macOS virtual machines

LLDBagility

LLDBagility is a tool for macOS kernel debugging that allows to connect LLDB to any macOS virtual machine running on a patched version of the VirtualBox hypervisor, thanks to the capabilities of virtual machine introspection offered by the Fast Debugging Protocol (FDP).

For more information, read the accompanying blog posts:

Features

LLDBagility implements a set of new LLDB commands that allows the debugger to:

  • attach to running macOS VirtualBox virtual machines and debug their kernel, stealthily, without the need of changing the guest OS (e.g. no necessity of DEVELOPMENT or DEBUG kernels, boot-args modification or SIP disabling) and with minimal changes to the configuration of the VM;
  • interrupt (and later resume) the execution of the guest kernel at any moment;
  • set hardware breakpoints anywhere in kernel code, even at the start of the boot process;
  • set hardware watchpoints that trigger on read and/or write accesses of the specified memory locations;
  • save and restore the state of the VM in a few seconds.

These commands are intended to be used alongside the ones already available in LLDB, like register read, memory write, breakpoint set (for software breakpoints), step and all the others. Furthermore, in case the Kernel Debug Kit of the debugged kernel is available for use (and possibly even when it isnโ€™t), the vast majority of lldbmacros also work as expected when loaded in the debugger.

Files

  • DWARFutils/: scripts for working with DWARF files
  • FDP/: Fast Debugging Protocol for macOS hosts and VirtualBox
  • KDKutils/: scripts for working with Kernel Debug Kits (KDKs) and lldbmacros
  • kdputils/: Python reimplementation of the KDP protocol
  • LLDBagility/: the tool
  • misc/: helper scripts for creating macOS Mojave VMs

Requisites

  • A recent version of macOS as host OS
  • A recent version of the LLDB debugger (can be installed with e.g. xcode-select --install)
  • The kdputils Python package (see the dedicated README)
  • A working build of VirtualBox with the FDP patch for macOS hosts, along with the PyFDP bindings (see the dedicated README)
  • A VirtualBox VM with any version of macOS as guest OS, along with a copy of the guest macOS kernel binary (not needed if the guest has the same kernel of the host, or if the Kernel Debug Kit of the guest kernel is installed in the host)

Note that both packages PyFDP and kdputils must be installed for the Python interpreter used by LLDB.

Installation

Assuming all requisites are satisfied, simply add command script import <path-to-LLDBagility>/LLDBagility/lldbagility.py to ~/.lldbinit.

Usage

  1. Start the macOS virtual machine to debug and LLDB;
  2. (required only if the kernel binary of the guest is different from the kernel of the host and no KDK for the guest kernel is installed in the host) in LLDB, execute the command target create <path-to-guest-kernel-binary>;
  3. in LLDB, execute the command fdp-attach <name-of-macos-vm> to start debugging the VM.

The new LLDB commands implemented by LLDBagility are:

  • fdp-attach or fa, to connect the debugger to a running macOS VirtualBox virtual machine;
  • fdp-hbreakpoint or fh, to set and unset read/write/execute hardware breakpoints;
  • fdp-interrupt or fi, to pause the execution of the VM and return the control to the debugger (equivalent to sudo dtrace -w -n "BEGIN { breakpoint(); }" );
  • fdp-save or fs, to save the current state of the VM;
  • fdp-restore or fr, to restore the VM to the last saved state.

In the debugger, use help <command> and <command> -h to see the command usage, like:

(lldb) help fdp-attach
     For more information run 'help fdp-attach'  Expects 'raw' input (see 'help raw-input'.)

Syntax: fdp-attach

    Connect to a macOS VM via FDP.
    The VM must have already been started.
    Existing breakpoints are deleted on attaching.
    Re-execute this command every time the VM is rebooted.

(lldb) fdp-attach -h
usage: fdp-attach [-h] vm_name

positional arguments:
  vm_name

optional arguments:
  -h, --help  show this help message and exit

Notes to users

  • As per current FDP limitations, in the VirtualBox settings set the macOS VM to use one CPU only and less or equal than 2 GB of RAM
  • Do not connect multiple instances of LLDBagility to the same macOS VM at the same time
  • If the macOS VM reboots (for any reason), re-execute fdp-attach (the kernel slide changes and LLDB is not aware of this)
  • If debugging seems slow or intermittent, disable App Nap in the macOS host
  • Pause the kernel execution before setting software breakpoints or LLDB will complain
  • Pause the kernel execution before setting hardware breakpoints with fdp-hbreakpoint or LLDB will return Invalid expression
  • Preferably load lldbmacros after attaching, otherwise the error FATAL FAILURE: Unable to find kdp_thread state for this connection. is raised (and some macros breaks)

Example session

$ env PATH="/usr/bin:/bin:/usr/sbin:/sbin" lldb
(lldb) fdp-attach macos-mojave-18E226
LLDBagility
  Kernel load address: 0xffffff800d200000
  Kernel slide:        0xd000000
  Kernel version:      Darwin Kernel Version 18.5.0: Mon Mar 11 20:40:32 PDT 2019; root:xnu-4903.251.3~3/RELEASE_X86_64
Version: Darwin Kernel Version 18.5.0: Mon Mar 11 20:40:32 PDT 2019; root:xnu-4903.251.3~3/RELEASE_X86_64; stext=0xffffff800d200000
Kernel UUID: 4170BF94-38B6-364F-A1B0-2F7C2C30F9A9
Load Address: 0xffffff800d200000
warning: 'kernel' contains a debug script. To run this script in this debug session:

    command script import "/Library/Developer/KDKs/KDK_10.14.4_18E226.kdk/System/Library/Kernels/kernel.dSYM/Contents/Resources/DWARF/../Python/kernel.py"

To run all discovered debug scripts in this session:

    settings set target.load-script-from-symbol-file true

Kernel slid 0xd000000 in memory.
Loaded kernel file /Library/Developer/KDKs/KDK_10.14.4_18E226.kdk/System/Library/Kernels/kernel
Loading 62 kext modules .............................................................. done.
kernel was compiled with optimization - stepping may behave oddly; variables may not be available.
Process 1 stopped
* thread #1, stop reason = signal SIGSTOP
    frame #0: 0xffffff800d4c2fb6 kernel`pmap_pcid_activate(tpmap=0xffffff800dcc17e0, ccpu=<unavailable>, nopagezero=<unavailable>, copyio=<unavailable>) at pmap_pcid.c:343 [opt]
Target 0: (kernel) stopped.
(lldb) command script import "/Library/Developer/KDKs/KDK_10.14.4_18E226.kdk/System/Library/Kernels/kernel.dSYM/Contents/Resources/DWARF/../Python/kernel.py"
Loading kernel debugging from /Library/Developer/KDKs/KDK_10.14.4_18E226.kdk/System/Library/Kernels/kernel.dSYM/Contents/Resources/DWARF/../Python/kernel.py
. . .
xnu debug macros loaded successfully. Run showlldbtypesummaries to enable type summaries.
settings set target.process.optimization-warnings false
(lldb) showversion
Darwin Kernel Version 18.5.0: Mon Mar 11 20:40:32 PDT 2019; root:xnu-4903.251.3~3/RELEASE_X86_64
(lldb) showbootargs
"fs4:\System\Library\CoreServices\boot.efi" usb=0x800 keepsyms=1 -v -serial=0x1
(lldb) showproctree
PID    PROCESS        POINTER
===    =======        =======
0      kernel_task    [  0xffffff800de15968 ]
|--1      launchd          [  0xffffff801456df10 ]
|  |--11     kextcache        [  0xffffff801456daa0 ]
(lldb) c
Process 1 resuming
(lldb) fdp-interrupt
Process 1 stopped
* thread #3, name = '0xffffff8013da71d0', queue = '0x0', stop reason = signal SIGINT
    frame #0: 0xffffff800d4def80 kernel`machine_idle at pmCPU.c:181 [opt]
Target 0: (kernel) stopped.
(lldb) showproctree
PID    PROCESS        POINTER
===    =======        =======
0      kernel_task    [  0xffffff800de15968 ]
|--1      launchd          [  0xffffff801456df10 ]
|  |--220    com.apple.Ambien [  0xffffff80179d1d50 ]
|  |--219    sharedfilelistd  [  0xffffff80179d21c0 ]
|  |--218    CVMCompiler      [  0xffffff80179d2630 ]
|  |--217    CVMServer        [  0xffffff80179d2aa0 ]
. . .
|  |--40     uninstalld       [  0xffffff801456d1c0 ]
|  |--39     wifiFirmwareLoad [  0xffffff801456d630 ]
|  |--37     UserEventAgent   [  0xffffff801456daa0 ]
|  |--36     syslogd          [  0xffffff801456e380 ]
(lldb) showipcsummary
task                 pid    #acts  tablesize  command
0xffffff8013d89cc0   0      94     21         kernel_task
0xffffff8013d8a840   1      4      1194       launchd
0xffffff8014e42b80   86     6      341        loginwindow
0xffffff8014e45980   37     5      512        UserEventAgent
0xffffff8014e425c0   39     2      42         wifiFirmwareLoad
. . .
0xffffff80179d6000   218    2      42         CVMCompiler
0xffffff80179d8e00   219    4      85         sharedfilelistd
0xffffff80179d93c0   220    4      85         com.apple.Ambien
Total Table size: 13619

License

All the material in this repository is released under the Apache License version 2.0, with the exception of the VirtualBox sources patched for FDP which are released under the GNU General Public License version 2 in accordance with the VirtualBox license.

More Repositories

1

binbloom

Raw binary firmware analysis software
C
493
star
2

kdigger

Kubernetes focused container assessment and context discovery tool for penetration testing
Go
424
star
3

quarkspwdump

Dump various types of Windows credentials without injecting in any process.
C
418
star
4

rewind

Snapshot-based coverage-guided windows kernel fuzzer
Rust
307
star
5

arybo

Manipulation, canonicalization and identification of mixed boolean-arithmetic symbolic expressions
C++
293
star
6

irma

IRMA is an asynchronous & customizable analysis system for suspicious files.
JavaScript
268
star
7

conf-presentations

Quarkslab conference talks
263
star
8

dreamboot

UEFI bootkit
C
230
star
9

binmap

system scanner
C++
216
star
10

legu_unpacker_2019

Scripts to unpack APK protected by Legu
Python
211
star
11

AERoot

AERoot is a command line tool that allows you to give root privileges on-the-fly to any process running on the Android emulator with Google Play flavors AVDs.
Python
195
star
12

android-restriction-bypass

PoC to bypass Android restrictions
C++
194
star
13

peetch

An eBPF playground
Python
184
star
14

titanm

This repository contains the tools we used in our research on the Google Titan M chip
C
181
star
15

qbindiff

Quarkslab Bindiffer but not only !
Python
169
star
16

quokka

Quokka: A Fast and Accurate Binary Exporter
C++
165
star
17

NFLlib

NTT-based Fast Lattice library
C++
165
star
18

pastis

PASTIS: Collaborative Fuzzing Framework
Python
154
star
19

samsung-trustzone-research

Reverse-engineering tools and exploits for Samsung's implementation of TrustZone
Python
143
star
20

qsynthesis

Greybox Synthesizer geared for deobfuscation of assembly instructions.
Python
136
star
21

pyrrha

A tool for firmware cartography
Python
135
star
22

llvm-passes

Collection of various llvm passes
C++
115
star
23

qb-sync

qb-sync is an open source tool to add some helpful glue between IDA Pro and Windbg. Its core feature is to dynamically synchronize IDA's graph windows with Windbg's position.
C++
115
star
24

starlink-tools

A collection of tools for security research on Starlink's User Terminal
Python
112
star
25

tritondse

Triton-based DSE library with loading and exploration capabilities (and more!)
Python
102
star
26

sspam

Symbolic Simplification with PAttern Matching
Python
100
star
27

android-fuzzing

C
100
star
28

CVE-2020-0069_poc

C
97
star
29

minik8s-ctf

A beginner-friendly CTF about Kubernetes security.
Shell
74
star
30

QBDL

QuarkslaB Dynamic Linker library
C++
71
star
31

iMITMProtect

Prevent Apple to mess with keys
C
70
star
32

whvp

PoC for a snapshot-based coverage-guided fuzzer targeting Windows kernel components
Rust
67
star
33

mattermost-plugin-e2ee

End-to-end encryption plugin for Mattermost
TypeScript
66
star
34

aosp_dataset

Large Commit Precise Vulnerability Dataset based on AOSP CVE
Python
57
star
35

llvm-dev-meeting-tutorial-2015

Material for an LLVM Tutorial presented at LLVM Dev Meeting 2015
TeX
47
star
36

dxfx

DxFx is a proof-of-concept DJI Pilot unpacker
Python
31
star
37

irma-probe

IRMA probe
25
star
38

irma-frontend

IRMA frontend
25
star
39

irma-ansible-old

IRMA ansible
24
star
40

libleeloo

Library to manage big sets of integers (and IPv4 ranges)
C++
23
star
41

sboot-binwalk

Python
21
star
42

irma-brain

IRMA brain
21
star
43

nodescan

Asynchronous scanning library
C++
19
star
44

pixiefail

PoC for PixieFail vulnerabilities
Python
18
star
45

python-binexport

Python interface for Binexport, the Bindiff export format
Python
14
star
46

numbat

Library to manipulate and create Sourcetrail databases
Python
14
star
47

bgraph

BGraph is a tool designed to generate dependencies graphs from Android.bp soong files.
Python
14
star
48

training_ecu

Hardware and software for the ECU we use during trainings
C++
14
star
49

dataset-call-graph-blogpost-material

12
star
50

idascript

Utilities scripts and Python module to facilitate executing idapython scripts in IDA.
Python
10
star
51

python-bindiff

Python module wrapping Bindiff usage into a Python API.
Python
10
star
52

BVWhiteBox

This PoC illustrates our work on asymmetric white-box cryptography, it can be used to generate a set of lookup tables used for lattice-based white-box scheme
Python
10
star
53

tpmee

Python
9
star
54

nvidia-ngx-wrapper

C
9
star
55

sstic-tame-the-qemu

C
9
star
56

ip_conv_sse

C++
9
star
57

crypto-condor

crypto-condor is a Python library for compliance testing of implementations of cryptographic primitives
C
8
star
58

qsig

QSig: Patch signature generation - detection tool
Python
8
star
59

linksys-wag200G

Some binaries and tools for the Linksys WAG200N router
C
7
star
60

windbg-vtl

JavaScript debugger extension for WinDbg that allows to dump the partitions running on Hyper-V
JavaScript
7
star
61

keyringer

Fork of keyringer from https://keyringer.pw (added some features like tree view, additional checks, ...)
Shell
7
star
62

irma-common

IRMA common
7
star
63

ansible-selenium-server

a Vagrant VM using Ansible to provide a Selenium Server
Shell
7
star
64

irmacl

irma api command line client
Python
6
star
65

land_of_cxx

C++
6
star
66

hooking-golang-playground

Various experiments with golang internals
C
4
star
67

erlang-prism

PRISM is a disassembler for Erlang BEAM virtual machine bytecode
Python
4
star
68

qb.backup

The server-side script of the qb.backup orchestration solution.
Python
4
star
69

wirego

C
4
star
70

wdnis_tool

CMake
3
star
71

diffing-portal

Static site for diffing portal
Jupyter Notebook
3
star
72

ziphyr

On-the-fly zip of streamed file with optional zipcrypto.
Python
2
star
73

python-zipstream

forked from allanlei/python-zipstream
Python
2
star
74

ansible-playbook-qb.backup

An example Ansible playbook deploying the roles qb.backup and qb.backup_server.
1
star
75

irma-web-ui

IRMA Web User Interface
JavaScript
1
star
76

irma-probe-tutorial

1
star
77

irmacl-async

Asynchronous client library for IRMA API
Python
1
star
78

can-workshop

Files for the Grehack 2021 workshop: Revers3 me if you CAN
Python
1
star