diff --git a/Ghidra/Debug/Debugger-agent-dbgeng/build.gradle b/Ghidra/Debug/Debugger-agent-dbgeng/build.gradle index bc1588aa03..2a1634af5a 100644 --- a/Ghidra/Debug/Debugger-agent-dbgeng/build.gradle +++ b/Ghidra/Debug/Debugger-agent-dbgeng/build.gradle @@ -13,6 +13,9 @@ * See the License for the specific language governing permissions and * limitations under the License. */ +// Not technically a Java project, but required to be a Help project +apply from: "${rootProject.projectDir}/gradle/javaProject.gradle" +apply from: "${rootProject.projectDir}/gradle/helpProject.gradle" apply from: "$rootProject.projectDir/gradle/distributableGhidraModule.gradle" apply from: "$rootProject.projectDir/gradle/nativeProject.gradle" apply from: "$rootProject.projectDir/gradle/hasPythonPackage.gradle" @@ -20,6 +23,11 @@ apply from: "$rootProject.projectDir/gradle/hasPythonPackage.gradle" apply plugin: 'eclipse' eclipse.project.name = 'Debug Debugger-agent-dbgeng' +dependencies { + // Only for Help :/ + api project(':Debugger-rmi-trace') +} + ext.tlb = file("build/os/win_x86_64/dbgmodel.tlb") if ("win_x86_64".equals(getCurrentPlatformName())) { diff --git a/Ghidra/Debug/Debugger-agent-dbgeng/certification.manifest b/Ghidra/Debug/Debugger-agent-dbgeng/certification.manifest index ac548173e4..94243ffcdf 100644 --- a/Ghidra/Debug/Debugger-agent-dbgeng/certification.manifest +++ b/Ghidra/Debug/Debugger-agent-dbgeng/certification.manifest @@ -10,6 +10,8 @@ data/debugger-launchers/local-dbgeng-trace.bat||GHIDRA||||END| data/debugger-launchers/local-dbgeng.bat||GHIDRA||||END| data/debugger-launchers/remote-dbgeng.bat||GHIDRA||||END| data/debugger-launchers/svrcx-dbgeng.bat||GHIDRA||||END| +src/main/help/help/TOC_Source.xml||GHIDRA||||END| +src/main/help/help/topics/dbgeng/dbgeng.html||GHIDRA||||END| src/main/py/LICENSE||GHIDRA||||END| src/main/py/MANIFEST.in||GHIDRA||||END| src/main/py/README.md||GHIDRA||||END| diff --git a/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/kernel-dbgeng.bat b/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/kernel-dbgeng.bat index 13ae2099f0..1b1d5ee79c 100644 --- a/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/kernel-dbgeng.bat +++ b/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/kernel-dbgeng.bat @@ -8,7 +8,7 @@ ::@desc ::@menu-group local ::@icon icon.debugger -::@help TraceRmiLauncherServicePlugin#dbgeng_kernel +::@help dbgeng#win_kernel ::@enum Connection:str Remote Local EXDI ::@env OPT_PYTHON_EXE:file!="python" "Python command" "The path to the Python 3 interpreter. Omit the full path to resolve using the system PATH." :: Use env instead of args, because "all args except first" is terrible to implement in batch diff --git a/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/local-dbgeng-attach.bat b/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/local-dbgeng-attach.bat index d0f788bc90..a55e48385b 100644 --- a/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/local-dbgeng-attach.bat +++ b/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/local-dbgeng-attach.bat @@ -8,7 +8,7 @@ ::@desc ::@menu-group local ::@icon icon.debugger -::@help TraceRmiLauncherServicePlugin#dbgeng_attach +::@help dbgeng#attach ::@env OPT_PYTHON_EXE:file!="python" "Python command" "The path to the Python 3 interpreter. Omit the full path to resolve using the system PATH." ::@env OPT_TARGET_PID:int=0 "Process id" "The target process id" ::@env OPT_ATTACH_FLAGS:int=0 "Attach flags" "Attach flags" diff --git a/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/local-dbgeng-ext.bat b/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/local-dbgeng-ext.bat index b695b8d1d2..570325f1b8 100644 --- a/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/local-dbgeng-ext.bat +++ b/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/local-dbgeng-ext.bat @@ -9,7 +9,7 @@ ::@desc ::@menu-group local ::@icon icon.debugger -::@help TraceRmiLauncherServicePlugin#dbgeng_ext +::@help dbgeng#ext ::@env OPT_PYTHON_EXE:file!="python" "Python command" "The path to the Python 3 interpreter. Omit the full path to resolve using the system PATH." :: Use env instead of args, because "all args except first" is terrible to implement in batch ::@env OPT_TARGET_IMG:file="" "Image" "The target binary executable image" diff --git a/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/local-dbgeng-trace.bat b/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/local-dbgeng-trace.bat index 55f5b46e65..8f844d2d3c 100644 --- a/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/local-dbgeng-trace.bat +++ b/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/local-dbgeng-trace.bat @@ -8,7 +8,7 @@ ::@desc ::@menu-group local ::@icon icon.debugger -::@help TraceRmiLauncherServicePlugin#dbgeng_trace +::@help dbgeng#ttd ::@env OPT_PYTHON_EXE:file!="python" "Python command" "The path to the Python 3 interpreter. Omit the full path to resolve using the system PATH." :: Use env instead of args, because "all args except first" is terrible to implement in batch ::@env OPT_TARGET_TRACE:file="" "Trace (.run)" "The target trace image" diff --git a/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/local-dbgeng.bat b/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/local-dbgeng.bat index bbc7eb143c..be4136c9a0 100644 --- a/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/local-dbgeng.bat +++ b/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/local-dbgeng.bat @@ -9,7 +9,7 @@ ::@desc ::@menu-group local ::@icon icon.debugger -::@help TraceRmiLauncherServicePlugin#dbgeng +::@help dbgeng#local ::@env OPT_PYTHON_EXE:file!="python" "Python command" "The path to the Python 3 interpreter. Omit the full path to resolve using the system PATH." :: Use env instead of args, because "all args except first" is terrible to implement in batch ::@env OPT_TARGET_IMG:file="" "Image" "The target binary executable image" diff --git a/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/remote-dbgeng.bat b/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/remote-dbgeng.bat index e40f2453c1..7c2e328a1c 100644 --- a/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/remote-dbgeng.bat +++ b/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/remote-dbgeng.bat @@ -8,7 +8,7 @@ ::@desc ::@menu-group local ::@icon icon.debugger -::@help TraceRmiLauncherServicePlugin#dbgeng_remote +::@help dbgeng#remote ::@env OPT_PYTHON_EXE:file!="python" "Python command" "The path to the Python 3 interpreter. Omit the full path to resolve using the system PATH." ::@env OPT_CONNECT_STRING:str="" "Connection" "Connection-string arguments (a la .server)" ::@env WINDBG_DIR:dir="" "Path to dbgeng.dll directory" "Path containing dbgeng and associated DLLS (if not Windows Kits)." diff --git a/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/svrcx-dbgeng.bat b/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/svrcx-dbgeng.bat index cdfa7cda4c..7c12a4a01e 100644 --- a/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/svrcx-dbgeng.bat +++ b/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/svrcx-dbgeng.bat @@ -9,7 +9,7 @@ ::@desc ::@menu-group local ::@icon icon.debugger -::@help TraceRmiLauncherServicePlugin#dbgeng_svrcx +::@help dbgeng#svrcx ::@env OPT_PYTHON_EXE:file!="python" "Python command" "The path to the Python 3 interpreter. Omit the full path to resolve using the system PATH." :: Use env instead of args, because "all args except first" is terrible to implement in batch ::@env OPT_TARGET_IMG:str="" "Image" "The target binary executable image" diff --git a/Ghidra/Debug/Debugger-agent-dbgeng/src/main/help/help/TOC_Source.xml b/Ghidra/Debug/Debugger-agent-dbgeng/src/main/help/help/TOC_Source.xml new file mode 100644 index 0000000000..3f4fed1048 --- /dev/null +++ b/Ghidra/Debug/Debugger-agent-dbgeng/src/main/help/help/TOC_Source.xml @@ -0,0 +1,31 @@ + + + + + + + + + + + + + + + + + + + + + + + diff --git a/Ghidra/Debug/Debugger-agent-dbgeng/src/main/help/help/topics/dbgeng/dbgeng.html b/Ghidra/Debug/Debugger-agent-dbgeng/src/main/help/help/topics/dbgeng/dbgeng.html new file mode 100644 index 0000000000..1f5f2af3fd --- /dev/null +++ b/Ghidra/Debug/Debugger-agent-dbgeng/src/main/help/help/topics/dbgeng/dbgeng.html @@ -0,0 +1,277 @@ + + + + + + + Debugger Launchers: Windows Debugger (WinDbg, dbgeng.dll) + + + + + +

Debugger Launchers: Windows Debugger (WinDbg, dbgeng.dll)

+ +

Integration with WinDbg is achieved by implementing a console debugger in Python 3 based on + dbgeng.dll (via pybag). This DLL represents the Microsoft Windows Debugger engine, and + so is best suited for debugging Windows user-space targets. This DLL also backs WinDbg and + several other debuggers on Windows. By default, the launcher will search for this DLL in an + installation of the Windows Debugging Kits version 10. If it does not find it there, it will + probably crash with a message in the Terminal.

+ +

The following launchers based on Microsoft's dbgeng.dll are included out of the + box:

+ +

Local

+ +

The plain "dbgeng" defaults to launching the current program as a user-mode process + on the local system. If there is no current program, this launcher cannot be used. Clearing the + Image option will cause this launcher to fail.

+ +

Please note on some system configurations, one of the debugger's dependencies + dbghelp.dll may get loaded from the system directory instead of from the WinDbg + installation, usually because a security product has pre-loaded it into the Python process. You + might work around this by copying the affected DLLs from your WinDbg installation into your + Python installation.

+ +

Setup

+ +

Installing WinDbg is highly recommended. If you wish to forego installing WinDbg, you can + use the DLL provided with Windows, which is substantially less capable, by manually pointing + this connector to C:\Windows\system32. If you do this, some commands, e.g. + .server, will not be available.

+ +

If you have access to PyPI, setting up your Python 3 environment is done using Pip. Please + note the version specifier for Protobuf.

+ + + +

If you are offline, or would like to use our provided packages, we still use Pip, but with a + more complicated invocation:

+ + + +

If you get an import error regarding distutils, it is due to a transitive + dependency on a buggy version of capstone. Work around it by installing + setuptools.

+ +

Options

+ + + +

Once running, you are presented with a command-line interface in Ghidra's Terminal. This CLI + accepts your usual WinDbg (kd) commands. You can escape from this CLI and enter a Python 3 REPL + by entering ".exit". This is not an actual kd command, but our implementation + understands this to mean exit the kd REPL. From the Python 3 REPL, you can access the + underlying Python-based API pybag. This is an uncommon need, but may be useful for + diagnostics and/or workarounds. To re-enter the kd REPL, enter "repl()". + Alternatively, if you are trying to quit, but typed ".exit", just type + "quit()" to terminate the session.

+ +

Extended Local

+ +

The "dbgeng-ext" launcher extends the base dbgeng launcher adding extra + options (a la IDebugClient's CreateProcess2).

+ +

Options

+ + + +

Attach

+ +

This launcher allows the user to attach to a local running process. Options are the same as + those for the base dbgeng, except for ProcessId and AttachFlags

+ +

Options

+ + + +

Remote

+ +

This launcher connects to a remote debugger that has opened a port for remote control.

+ +

Options

+ + + +

Process Server

+ +

The "dbgeng-svrcx" launcher extends the base dbgeng launcher adding an option for + connecting through a remote process server.

+ +

Options

+ + + +

Windows Kernel

+ +

This version of the dbgeng should be used for kernel-debugging of a remote machine. Options + are the same as the base dbgeng, except for the connection-string arguments. For remote + debugging, the target machine should be booted with the appropriate options, set using BCDEDIT + or the equivalent, such as:

+ + + +

where IP= the address of the machine runing Ghidra.

+ +

Options

+ + + + + +

EXDI

+ +

Setup for EXDI connections is fairly complicated and difficult to get correct. The argument + string typically should be something like:

+ + + +

The CLSID here should match the CLSID in the exdiConfigData.xml file in the debugger + architectural directory. If windbg has been run using EXDI at some point, there will also be an + entry in the System Registry for this CLSID. The InprocServer32 subentry for this CLSID in the + Registry should point to a copy of ExdiGdbSrv.dll, typically the one in the same directory. + This DLL must reside somewhere that the debugger has permission to load from, i.e. not in the + WindowsApps directory tree. The exdiConfigData file should be configured for the target + you're using. We heavily recommend using displayCommPackets==yes, as many of the tasks + take considerable time, and this is the only indicator of progress.

+ +

The Kd=Guess parameter causes the underlying engine to scan memory for the kernel's + base address, which will probably not be provided by the gdbstub. (Kd=NtBaseAddr is also + a valid option, as is eliminating the parameter, but, currently, we have no idea how to point + the configuration at a correct value. Using this option will cause the load to spin + pointlessly.) If you can, we highly recommend breaking the target near the base address, as the + search proceeds down through memory starting at the current program counter. If the difference + between the PC and the base address is large, the loading process will punt before useful + values are detected. If anyone understand how to extend this search (or knows how to set the + base address to sidestep the scan), we would really love some guidance.

+ +

TTD (Time-Travel Debugging)

+ +

This is a nascent extension to our launcher for the Windows Debugger. The launcher itself + functions, but lacks full integration. In particular, Ghidra's concept of time is not mapped + directly to the TTD concept of time. TTD uses a major/minor scheme for ordering events, where + the major index changes when TTD must record a change in state. Events, including thread + creation/termination, module loads/unloads, syscalls, and other asynchronous changes, merit new + major indices. When you step forward or backward in a trace, the dbgeng API will increment and + decrement correspondingly. Ghidra, on the other hand, will only increment.

+ +

Options

+ +

This launcher has basically the same options as the WinDbg launcher, except that arguments + are not included and the DLL path must contain TTDReplay.dll and the scripts that + implement TTD. These are most easily obtained by installing WinDbg Preview or later.

+ + diff --git a/Ghidra/Debug/Debugger-agent-drgn/build.gradle b/Ghidra/Debug/Debugger-agent-drgn/build.gradle index 443df89fbf..e67d8ad504 100644 --- a/Ghidra/Debug/Debugger-agent-drgn/build.gradle +++ b/Ghidra/Debug/Debugger-agent-drgn/build.gradle @@ -13,8 +13,16 @@ * See the License for the specific language governing permissions and * limitations under the License. */ +// Not technically a Java project, but required to be a Help project +apply from: "${rootProject.projectDir}/gradle/javaProject.gradle" +apply from: "${rootProject.projectDir}/gradle/helpProject.gradle" apply from: "$rootProject.projectDir/gradle/distributableGhidraModule.gradle" apply from: "$rootProject.projectDir/gradle/hasPythonPackage.gradle" apply plugin: 'eclipse' eclipse.project.name = 'Debug Debugger-agent-drgn' + +dependencies { + // Only for Help :/ + api project(':Debugger-rmi-trace') +} diff --git a/Ghidra/Debug/Debugger-agent-drgn/certification.manifest b/Ghidra/Debug/Debugger-agent-drgn/certification.manifest index d342dc4565..7b4c28f4e0 100644 --- a/Ghidra/Debug/Debugger-agent-drgn/certification.manifest +++ b/Ghidra/Debug/Debugger-agent-drgn/certification.manifest @@ -4,6 +4,8 @@ Module.manifest||GHIDRA||||END| README.md||GHIDRA||||END| build.gradle||GHIDRA||||END| +src/main/help/help/TOC_Source.xml||GHIDRA||||END| +src/main/help/help/topics/drgn/drgn.html||GHIDRA||||END| src/main/py/LICENSE||GHIDRA||||END| src/main/py/MANIFEST.in||GHIDRA||||END| src/main/py/README.md||GHIDRA||||END| diff --git a/Ghidra/Debug/Debugger-agent-drgn/data/debugger-launchers/core-drgn.sh b/Ghidra/Debug/Debugger-agent-drgn/data/debugger-launchers/core-drgn.sh index e1bb7a2db0..01e5e31995 100755 --- a/Ghidra/Debug/Debugger-agent-drgn/data/debugger-launchers/core-drgn.sh +++ b/Ghidra/Debug/Debugger-agent-drgn/data/debugger-launchers/core-drgn.sh @@ -24,7 +24,7 @@ #@desc #@menu-group drgn #@icon icon.debugger -#@help TraceRmiLauncherServicePlugin#drgn-core +#@help drgn#core #@env OPT_TARGET_IMG:file!="" "Core dump" "The target core dump" export OPT_TARGET_KIND="coredump" diff --git a/Ghidra/Debug/Debugger-agent-drgn/data/debugger-launchers/kernel-drgn.sh b/Ghidra/Debug/Debugger-agent-drgn/data/debugger-launchers/kernel-drgn.sh index bf751266d4..c32f228633 100755 --- a/Ghidra/Debug/Debugger-agent-drgn/data/debugger-launchers/kernel-drgn.sh +++ b/Ghidra/Debug/Debugger-agent-drgn/data/debugger-launchers/kernel-drgn.sh @@ -24,7 +24,7 @@ #@desc #@menu-group drgn #@icon icon.debugger -#@help TraceRmiLauncherServicePlugin#drgn-kernel +#@help drgn#linux_kernel export OPT_TARGET_KIND="kernel" sudo -E drgn ../support/local-drgn.py diff --git a/Ghidra/Debug/Debugger-agent-drgn/data/debugger-launchers/local-drgn.sh b/Ghidra/Debug/Debugger-agent-drgn/data/debugger-launchers/local-drgn.sh index edf9d0f94e..432f42c7d4 100755 --- a/Ghidra/Debug/Debugger-agent-drgn/data/debugger-launchers/local-drgn.sh +++ b/Ghidra/Debug/Debugger-agent-drgn/data/debugger-launchers/local-drgn.sh @@ -24,7 +24,7 @@ #@desc #@menu-group drgn #@icon icon.debugger -#@help TraceRmiLauncherServicePlugin#drgn +#@help drgn#attach #@env OPT_TARGET_PID:int=44068 "PID" "The target's process id" export OPT_TARGET_KIND="user" diff --git a/Ghidra/Debug/Debugger-agent-drgn/src/main/help/help/TOC_Source.xml b/Ghidra/Debug/Debugger-agent-drgn/src/main/help/help/TOC_Source.xml new file mode 100644 index 0000000000..1213bfe9ad --- /dev/null +++ b/Ghidra/Debug/Debugger-agent-drgn/src/main/help/help/TOC_Source.xml @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + diff --git a/Ghidra/Debug/Debugger-agent-drgn/src/main/help/help/topics/drgn/drgn.html b/Ghidra/Debug/Debugger-agent-drgn/src/main/help/help/topics/drgn/drgn.html new file mode 100644 index 0000000000..a15e5e142c --- /dev/null +++ b/Ghidra/Debug/Debugger-agent-drgn/src/main/help/help/topics/drgn/drgn.html @@ -0,0 +1,78 @@ + + + + + + + Debugger Launchers: drgn + + + + + +

Debugger Launchers: drgn

+ +

The following launchers uses Meta's drgn engine to explore various targets:

+ +

Attach

+ +

The "drgn" launcher attaches to a running process via the Linux "/proc/pid" + interface.

+ +

Setup

+ +

You must have Meta's drgn installed on the local system. The default behavior assumes + you do NOT need root access to attach to a running process, i.e. it assumes you have run the + command:

+ + + +

using root privileges at some point. Alternately, you can prepend "sudo -E" to the drgn + invocation line in "local-drgn.sh"". Note: drgn does not currently support stack + unwinding or register access for user-mode access to running processes.

+ +

Options

+ + + +

Core Dump

+ +

This launcher loads a Linux core dump.

+ +

Setup

+ +

You must have Meta's drgn installed on the local system. No other setup is required. + Note: Core dumps may or may not include memory, so the Dynamic Listing may or may not be + populated.

+ +

Options

+ + + +

Linux Kernel

+ +

This launcher attaches to a Linux kernel via the "/proc/kcore" interface.

+ +

Setup

+ +

You must have Meta's drgn installed on the local system. No other setup is required. + Note: requires root access - you will be prompted for a password in the Terminal.

+ +

Options

+ + + + diff --git a/Ghidra/Debug/Debugger-agent-gdb/build.gradle b/Ghidra/Debug/Debugger-agent-gdb/build.gradle index 7a16fd84d4..0f11da65ab 100644 --- a/Ghidra/Debug/Debugger-agent-gdb/build.gradle +++ b/Ghidra/Debug/Debugger-agent-gdb/build.gradle @@ -13,8 +13,16 @@ * See the License for the specific language governing permissions and * limitations under the License. */ +// Not technically a Java project, but required to be a Help project +apply from: "${rootProject.projectDir}/gradle/javaProject.gradle" +apply from: "${rootProject.projectDir}/gradle/helpProject.gradle" apply from: "$rootProject.projectDir/gradle/distributableGhidraModule.gradle" apply from: "$rootProject.projectDir/gradle/hasPythonPackage.gradle" apply plugin: 'eclipse' eclipse.project.name = 'Debug Debugger-agent-gdb' + +dependencies { + // Only for Help :/ + api project(':Debugger-rmi-trace') +} diff --git a/Ghidra/Debug/Debugger-agent-gdb/certification.manifest b/Ghidra/Debug/Debugger-agent-gdb/certification.manifest index 81acfa0106..d2b12fd54e 100644 --- a/Ghidra/Debug/Debugger-agent-gdb/certification.manifest +++ b/Ghidra/Debug/Debugger-agent-gdb/certification.manifest @@ -11,6 +11,9 @@ data/scripts/fallback_info_proc_mappings.gdb||GHIDRA||||END| data/scripts/fallback_maintenance_info_sections.gdb||GHIDRA||||END| data/scripts/getpid-linux-i386.gdb||GHIDRA||||END| data/scripts/wine32_info_proc_mappings.gdb||GHIDRA||||END| +src/main/help/help/TOC_Source.xml||GHIDRA||||END| +src/main/help/help/topics/gdb/gdb.html||GHIDRA||||END| +src/main/help/help/topics/gdb/images/GdbLauncher.png||GHIDRA||||END| src/main/py/LICENSE||GHIDRA||||END| src/main/py/MANIFEST.in||GHIDRA||||END| src/main/py/README.md||GHIDRA||||END| diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/local-gdb.bat b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/local-gdb.bat index e77eea81dd..71e78a9190 100644 --- a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/local-gdb.bat +++ b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/local-gdb.bat @@ -9,7 +9,7 @@ ::@desc ::@menu-group local ::@icon icon.debugger -::@help TraceRmiLauncherServicePlugin#gdb +::@help gdb#local ::@enum StartCmd:str run start starti ::@enum Endian:str auto big little ::@env OPT_TARGET_IMG:file="" "Image" "The target binary executable image" diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/local-gdb.sh b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/local-gdb.sh index 740b77b6d0..ea68f6f07f 100755 --- a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/local-gdb.sh +++ b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/local-gdb.sh @@ -25,7 +25,7 @@ #@desc #@menu-group local #@icon icon.debugger -#@help TraceRmiLauncherServicePlugin#gdb +#@help gdb#local #@enum StartCmd:str run start starti #@enum Endian:str auto big little #@arg :file "Image" "The target binary executable image, empty for no target" diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/local-rr.sh b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/local-rr.sh index e2774bb28d..f59a18b0a1 100755 --- a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/local-rr.sh +++ b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/local-rr.sh @@ -24,7 +24,7 @@ #@desc #@menu-group local #@icon icon.debugger -#@help TraceRmiLauncherServicePlugin#gdb_rr +#@help gdb#rr #@enum StartCmd:str run start starti #@enum Endian:str auto big little #@arg :file "Trace Dir" "The target trace directory (e.g. .local/share/rr/trace)" diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/qemu-gdb.sh b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/qemu-gdb.sh index 71a53269a9..ca511e0f0d 100755 --- a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/qemu-gdb.sh +++ b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/qemu-gdb.sh @@ -26,7 +26,7 @@ #@desc #@menu-group cross #@icon icon.debugger -#@help TraceRmiLauncherServicePlugin#gdb_qemu +#@help gdb#qemu #@enum Endian:str auto big little #@arg :file! "Image" "The target binary executable image" #@args "Arguments" "Command-line arguments to pass to the target" diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/qemu-sys-gdb.bat b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/qemu-sys-gdb.bat index 21f8e4cbd6..76bde6b38f 100644 --- a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/qemu-sys-gdb.bat +++ b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/qemu-sys-gdb.bat @@ -10,7 +10,7 @@ ::@desc ::@menu-group cross ::@icon icon.debugger -::@help TraceRmiLauncherServicePlugin#gdb_qemu +::@help gdb#qemu ::@enum Endian:str auto big little ::@env OPT_TARGET_IMG:file!="" "Image" "The target binary executable image" ::@env GHIDRA_LANG_EXTTOOL_qemu_system:file="" "QEMU command" "The path to qemu-system for the target architecture." diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/qemu-sys-gdb.sh b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/qemu-sys-gdb.sh index 91d438173e..ae31199b9f 100755 --- a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/qemu-sys-gdb.sh +++ b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/qemu-sys-gdb.sh @@ -26,7 +26,7 @@ #@desc #@menu-group cross #@icon icon.debugger -#@help TraceRmiLauncherServicePlugin#gdb_qemu +#@help gdb#qemu #@enum Endian:str auto big little #@arg :file! "Image" "The target binary executable image" #@env GHIDRA_LANG_EXTTOOL_qemu_system:file="" "QEMU command" "The path to qemu-system for the target architecture." diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/remote-gdb.bat b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/remote-gdb.bat index 20c4778780..c1885e0f10 100644 --- a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/remote-gdb.bat +++ b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/remote-gdb.bat @@ -8,7 +8,7 @@ ::@desc ::@menu-group remote ::@icon icon.debugger -::@help TraceRmiLauncherServicePlugin#gdb_remote +::@help gdb#remote ::@enum TargetType:str remote extended-remote ::@enum Endian:str auto big little ::@env OPT_TARGET_TYPE:TargetType="remote" "Target" "The type of remote target" diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/remote-gdb.sh b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/remote-gdb.sh index 06ee2bcac7..02ec35ec05 100755 --- a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/remote-gdb.sh +++ b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/remote-gdb.sh @@ -24,7 +24,7 @@ #@desc #@menu-group remote #@icon icon.debugger -#@help TraceRmiLauncherServicePlugin#gdb_remote +#@help gdb#remote #@enum TargetType:str remote extended-remote #@enum Endian:str auto big little #@env OPT_TARGET_TYPE:TargetType="remote" "Target" "The type of remote target" diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdb.bat b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdb.bat index ce6f76afb5..58a962a7c5 100644 --- a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdb.bat +++ b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdb.bat @@ -10,7 +10,7 @@ ::@desc ::@menu-group remote ::@icon icon.debugger -::@help TraceRmiLauncherServicePlugin#gdb_ssh +::@help gdb#ssh ::@enum StartCmd:str run start starti ::@enum Endian:str auto big little ::@env OPT_TARGET_IMG:str="" "Image" "The target binary executable image on the remote system" diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdb.sh b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdb.sh index 7a3505b5bb..ede3276821 100755 --- a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdb.sh +++ b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdb.sh @@ -26,7 +26,7 @@ #@desc #@menu-group remote #@icon icon.debugger -#@help TraceRmiLauncherServicePlugin#gdb_ssh +#@help gdb#ssh #@enum StartCmd:str run start starti #@enum Endian:str auto big little #@arg :str "Image" "The target binary executable image on the remote system" diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdbserver.bat b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdbserver.bat index 8859c56aea..d03fb5e6ad 100644 --- a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdbserver.bat +++ b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdbserver.bat @@ -10,7 +10,7 @@ ::@desc ::@menu-group remote ::@icon icon.debugger -::@help TraceRmiLauncherServicePlugin#gdb_gdbserver_ssh +::@help gdb#gdbserver_ssh ::@enum Endian:str auto big little ::@env OPT_TARGET_IMG:str!="" "Image" "The target binary executable image on the remote system" ::@env OPT_TARGET_ARGS:str="" "Arguments" "Command-line arguments to pass to the target" diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdbserver.sh b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdbserver.sh index 809b64e77d..4a38e9c61e 100755 --- a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdbserver.sh +++ b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdbserver.sh @@ -26,7 +26,7 @@ #@desc #@menu-group remote #@icon icon.debugger -#@help TraceRmiLauncherServicePlugin#gdb_gdbserver_ssh +#@help gdb#gdbserver_ssh #@enum Endian:str auto big little #@arg :str! "Image" "The target binary executable image on the remote system" #@args "Arguments" "Command-line arguments to pass to the target" diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/wine-gdb.sh b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/wine-gdb.sh index 762e5d4234..0dd83d75dd 100755 --- a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/wine-gdb.sh +++ b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/wine-gdb.sh @@ -25,7 +25,7 @@ #@desc #@menu-group cross #@icon icon.debugger -#@help TraceRmiLauncherServicePlugin#gdb_wine +#@help gdb#wine #@enum Endian:str auto big little #@arg :file! "Image" "The target binary executable image" #@args "Arguments" "Command-line arguments to pass to the target" diff --git a/Ghidra/Debug/Debugger-agent-gdb/src/main/help/help/TOC_Source.xml b/Ghidra/Debug/Debugger-agent-gdb/src/main/help/help/TOC_Source.xml new file mode 100644 index 0000000000..2bfd57f400 --- /dev/null +++ b/Ghidra/Debug/Debugger-agent-gdb/src/main/help/help/TOC_Source.xml @@ -0,0 +1,31 @@ + + + + + + + + + + + + + + + + + + + + + + + diff --git a/Ghidra/Debug/Debugger-agent-gdb/src/main/help/help/topics/gdb/gdb.html b/Ghidra/Debug/Debugger-agent-gdb/src/main/help/help/topics/gdb/gdb.html new file mode 100644 index 0000000000..045dd98e80 --- /dev/null +++ b/Ghidra/Debug/Debugger-agent-gdb/src/main/help/help/topics/gdb/gdb.html @@ -0,0 +1,439 @@ + + + + + + + Debugger Launchers: GDB + + + + + +

Debugger Launchers: GDB

+ +

Integration with GDB is achieved using a Python-based plugin for GDB. It is well-suited for + debuging Linux user-space targets, many embedded systems, and sometimes Windows user-space + targets. Please note you may need to obtain a properly-configured build of GDB for your target. + If you are working with an embedded system, it is probably safest to install the "multiarch" + build of GDB from your package manager.

+ +

The following launchers based on GDB (GNU Debugger) are included out of the box:

+ +

Local

+ +

The plain "gdb" launch script defaults to launching the current program as a + user-mode process on the local system. If there is no current program, or if you clear the + Image option, this launcher will only start gdb and get it connected to a + Ghidra trace. You may then manually start or connect to your target. Note that this may also + require manual mapping of your program database(s) to the target memory.

+ +

Setup

+ +

You must have GDB installed on the local system, and it must embed the Python 3 interpreter. + If you have access to PyPI, setting up your Python 3 environment is done using Pip. Please note + the version specifier for Protobuf.

+ + + +

If you are offline, or would like to use our provided packages, we still use Pip, but with a + more complicated invocation:

+ + + +

Beware that GDB may embed a different Python interpreter than your system's default. If you + are still getting import errors, check the version that GDB embeds:

+ + + +

Note the version and ensure that you are invoking Pip with that version. Supposing + sys.version indicates 3.10, you should invoke Pip using python3.10 -m + pip.

+ +

Warning: Modern Linux distributions are beginning to adopt PEP 668, which prevents + installation of Python packages outside of a virtual environment (venv) even for non-root + user accounts. Unfortunately, gdb does not seem to honor the currently activated + venv, and so such configurations are not officially supported. You may be able to work around + this by modifying the PYTHONPATH lines of the launcher script, but your mileage may + vary. For now, we recommend using the --break-system-packages argument with Pip.

+ +

Options

+ +
+ +
+ + + +

Once running, you are presented with GDB's command-line interface in Ghidra's Terminal. This + is the bona fide GDB command-line interface, so it has all the functionality you would + expect. If you command GDB from this shell, the plugin will keep Ghidra in sync. The terminal + can also be used to interact with the target application when it is running. The plugin + provides an additional set of commands for managing the connection to Ghidra, as well as + controlling trace synchronization. These are all in the "ghidra" command prefix. You + can use tab completion to enumerate the available commands and GDB's "help" command to + examine their documentation.

+ +

Via SSH

+ +

This works the same as the GDB launcher, but runs gdb on a remote system via + ssh. In contrast to the previous system, which used an SSH library for Java, this + launcher uses the ssh command on the local system. Thus, it should have broader + compatibility with remote systems, and it should use the same configuration files as you are + accustomed to. That said, we developed it using OpenSSH, so your experience will be best if + your copy understands the same command-line arguments.

+ +

Setup

+ +

You must install GDB and an SSH server onto the target host. Your local SSH client must + support remote port forwarding (-R option) and terminal allocation (-t option), and + the remote server must be configured to permit them.

+ +

You will need to manually install the required Python packages on the target host, + comprising our plugin for GDB and its dependencies. Copy all of the Python packages from + Ghidra/Debug/Debugger-rmi-trace/pypkg/dist/ and + Ghidra/Debug/Debugger-agent-gdb/pypkg/dist/ to the remote system. It is easiest to put + them all in one directory, e.g., ~/ghidra-pypgk/. Then install them:

+ + + +

Please see Setup for notes about embedded Python interpreter + versions.

+ +

Options

+ + + +

gdbserver via SSH

+ +

This works similarly to the GDB via SSH launcher, but instead of tunneling the Trace RMI + connection, tunnels the RSP (gdbserver) connection. There is actually a fairly elegant + method of doing this straight from within gdb, which is exactly what this launcher + does:

+ + + +

This has some advantages compared to running gdb on the remote target:

+ +
    +
  1. GDB may not be available on the remote target.
    2. + +
  2. There is no need to install our plugin for GDB on the target.
    3. +
+ +

But, it also has some drawbacks:

+ +
    +
  1. gdbserver must be installed on the remote system, and the local gdb + must be compatible with it.
    2. + +
  2. It may be slightly more annoying to map modules from the remote system, because of the + way GDB reports these modules.
    3. + +
  3. The memory map may be absent. Though this is overcome by creating an entry for the entire + address space, if the map is of interest to your analysis, it may not be available.
    4. +
+ +

Setup

+ +

You must have GDB installed on the local system and a compatible version of + gdbserver installed on the target system. You must have an SSH server installed on the + target system. It may be worth testing your setup manually (outside of Ghidra) to ensure + everything is configured correctly. On the local system, follow the steps given in Setup. There are no additional Python requirements on the target system.

+ +

Options

+ + + +

QEMU

+ +

These launchers orchestrate a QEMU user- or system-mode target and connect to it using our + Python plugin for GDB. Ghidra will inspect the current program and attempt to map its language + to the appropriate QEMU command, but due to subtle errors and/or outright failure, the default + value for the QEMU command option often requires careful inspection.

+ +

There are two separate scripts for QEMU, one for user mode and one for system mode. Note + that QEMU does not support user-mode emulation on Windows, so that script is not available on + Windows hosts.

+ +

Setup

+ +

You must acquire versions of QEMU and GDB that support the target architecture. Aside from + the copy of QEMU required, setup is the same whether for user or system mode. As for GDB, on + many distributions of Linux, you can install gdb-multiarch. Follow the steps given in + Setup.

+ +

Options

+ + + +

Wine

+ +

This launchers runs wine in a gdb session on Linux and directs it to a + target Windows executable. There are other ways to rig a Windows target in GDB on Linux, but + this is the method we have chosen. This may prevent GDB from processing the object file, + because it is a PE file, and most copies of GDB for UNIX will support only ELF. Nevertheless, + Ghidra should recognize the target and map it, giving you symbols and debug info in the front + end, even if not in the GDB CLI.

+ +

Setup

+ +

In addition to the steps given in Setup, you must install Wine on your + system. Prepare for configuration by locating the actual wine executable. These are + often in some library directory and named "wine32" or "wine64." To find them, + either examine the file list of the installed package, or dissect the wrapper wine + script, usually on your path:

+ + + +

The locations are usually given in variables at the top of the script, e.g., + "/usr/lib/wine/wine64". One is for 64-bit Windows targets and another is for 32-bit + Windows targets. Unlike native Windows, Wine does not (yet) implement WoW64 (Windows on Windows + 64). Instead, the 32-bit target is loaded using a 32-bit copy of Wine, and so is serviced by + Linux's 32-bit system calls. NOTE: Careful attention must be given to + select the correct wine executable for the target program's architecture! Even + though the wine executable is smart enough to correct this mistake, it results in + calls to exec, which confuse this launcher. If GDB complains that it cannot place + breakpoints because of memory access, it is probably because of this mistake.

+ +

The launcher loads some additional support packages in our plugin for GDB, e.g., to scan the + memory map for PE files and amend the module list. Thus, Ghidra can display both Windows and + Linux modules, and map them to its program databases accordingly, despite GDB's inability to + process PE files. There are perhaps other configurations of GDB for Linux that can process ELFs + as well as PEs loaded by Wine, but they do not seem to be readily available in any popular + package repositories.

+ +

Options

+ + + +

Remote

+ +

This launcher can target any TCP-based GDB stub that is compatible with a local copy of + gdb. Essentially, it just starts gdb and then enters

+ + + +

into it. It is best to test this command outside of Ghidra to be sure everything is + compatible before using this launcher. This launcher does not require an image, nor does it + create your target. Thus, it can be used without a current program.

+ +

Setup

+ +

On your local system, follow the steps given in Setup. Your version of + GDB must be compatible with the stub (e.g., gdbserver) on the target system. There are + no additional requirements on the target system.

+ +

NOTE: The target program image must match that imported in Ghidra, or else things may + not map or synchronize correctly.

+ +

Options

+ + + +

rr

+ +

This launcher runs rr in a gdb session on Linux for replaying rr-generated + traces.

+ +

Options

+ + + +

Other options are the same as in GDB.

+ + diff --git a/Ghidra/Debug/Debugger-rmi-trace/src/main/help/help/topics/TraceRmiLauncherServicePlugin/images/GdbLauncher.png b/Ghidra/Debug/Debugger-agent-gdb/src/main/help/help/topics/gdb/images/GdbLauncher.png similarity index 100% rename from Ghidra/Debug/Debugger-rmi-trace/src/main/help/help/topics/TraceRmiLauncherServicePlugin/images/GdbLauncher.png rename to Ghidra/Debug/Debugger-agent-gdb/src/main/help/help/topics/gdb/images/GdbLauncher.png diff --git a/Ghidra/Debug/Debugger-agent-lldb/build.gradle b/Ghidra/Debug/Debugger-agent-lldb/build.gradle index 788c285364..fc80abd9f6 100644 --- a/Ghidra/Debug/Debugger-agent-lldb/build.gradle +++ b/Ghidra/Debug/Debugger-agent-lldb/build.gradle @@ -13,8 +13,17 @@ * See the License for the specific language governing permissions and * limitations under the License. */ +// Not technically a Java project, but required to be a Help project +apply from: "${rootProject.projectDir}/gradle/javaProject.gradle" +apply from: "${rootProject.projectDir}/gradle/helpProject.gradle" apply from: "$rootProject.projectDir/gradle/distributableGhidraModule.gradle" apply from: "$rootProject.projectDir/gradle/hasPythonPackage.gradle" apply plugin: 'eclipse' eclipse.project.name = 'Debug Debugger-agent-lldb' + +dependencies { + // Only for Help :/ + api project(':Debugger-rmi-trace') + api project(':Debugger-agent-gdb') +} diff --git a/Ghidra/Debug/Debugger-agent-lldb/certification.manifest b/Ghidra/Debug/Debugger-agent-lldb/certification.manifest index 947c12bf90..bf6c392158 100644 --- a/Ghidra/Debug/Debugger-agent-lldb/certification.manifest +++ b/Ghidra/Debug/Debugger-agent-lldb/certification.manifest @@ -9,6 +9,8 @@ data/debugger-launchers/kernel-lldb.bat||GHIDRA||||END| data/debugger-launchers/local-lldb.bat||GHIDRA||||END| data/debugger-launchers/remote-lldb.bat||GHIDRA||||END| data/debugger-launchers/ssh-lldb.bat||GHIDRA||||END| +src/main/help/help/TOC_Source.xml||GHIDRA||||END| +src/main/help/help/topics/lldb/lldb.html||GHIDRA||||END| src/main/py/LICENSE||GHIDRA||||END| src/main/py/MANIFEST.in||GHIDRA||||END| src/main/py/README.md||GHIDRA||||END| diff --git a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/android-lldb.bat b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/android-lldb.bat index 604d25ab99..b182203c3e 100644 --- a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/android-lldb.bat +++ b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/android-lldb.bat @@ -8,7 +8,7 @@ ::@desc ::@menu-group remote ::@icon icon.debugger -::@help TraceRmiLauncherServicePlugin#lldb_android +::@help lldb#android ::@enum StartCmd:str "process launch" "process launch --stop-at-entry" ::@env OPT_TARGET_IMG:file="" "Image" "The target binary executable image" ::@env OPT_TARGET_ARGS:str="" "Arguments" "Command-line arguments to pass to the target" diff --git a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/android-lldb.sh b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/android-lldb.sh index 14e21b0bf9..47395cff2e 100755 --- a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/android-lldb.sh +++ b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/android-lldb.sh @@ -25,7 +25,7 @@ #@desc #@menu-group remote #@icon icon.debugger -#@help TraceRmiLauncherServicePlugin#lldb_android +#@help lldb#android #@enum StartCmd:str "process launch" "process launch --stop-at-entry" #@arg :file "Image" "The target binary executable image" #@args "Arguments" "Command-line arguments to pass to the target" diff --git a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/kernel-lldb.bat b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/kernel-lldb.bat index c57e3bdd92..6b2605e36c 100644 --- a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/kernel-lldb.bat +++ b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/kernel-lldb.bat @@ -8,7 +8,7 @@ ::@desc ::@menu-group remote ::@icon icon.debugger -::@help TraceRmiLauncherServicePlugin#lldb_kernel +::@help lldb#macos_kernel ::@env OPT_HOST:str="localhost" "Host" "The hostname of the target" ::@env OPT_ARCH:str="" "Architecture" "Target architecture override" ::@env OPT_LLDB_PATH:file="lldb" "lldb command" "The path to lldb on the local system. Omit the full path to resolve using the system PATH." diff --git a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/kernel-lldb.sh b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/kernel-lldb.sh index a3e90855ce..b07320a356 100755 --- a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/kernel-lldb.sh +++ b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/kernel-lldb.sh @@ -24,7 +24,7 @@ #@desc #@menu-group remote #@icon icon.debugger -#@help TraceRmiLauncherServicePlugin#lldb_kernel +#@help lldb#macos_kernel #@env OPT_HOST:str="localhost" "Host" "The hostname of the target" #@env OPT_ARCH:str="" "Architecture" "Target architecture override" #@env OPT_LLDB_PATH:file="lldb" "lldb command" "The path to lldb on the local system. Omit the full path to resolve using the system PATH." diff --git a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/local-lldb.bat b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/local-lldb.bat index 156228ddb2..671b7141db 100644 --- a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/local-lldb.bat +++ b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/local-lldb.bat @@ -9,7 +9,7 @@ ::@desc ::@menu-group local ::@icon icon.debugger -::@help TraceRmiLauncherServicePlugin#lldb +::@help lldb#local ::@enum StartCmd:str "process launch" "process launch --stop-at-entry" ::@env OPT_TARGET_IMG:file="" "Image" "The target binary executable image" ::@env OPT_TARGET_ARGS:str="" "Arguments" "Command-line arguments to pass to the target" diff --git a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/local-lldb.sh b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/local-lldb.sh index dc896644e9..397e0deea9 100755 --- a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/local-lldb.sh +++ b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/local-lldb.sh @@ -25,7 +25,7 @@ #@desc #@menu-group local #@icon icon.debugger -#@help TraceRmiLauncherServicePlugin#lldb +#@help lldb#local #@enum StartCmd:str "process launch" "process launch --stop-at-entry" #@arg :file "Image" "The target binary executable image" #@args "Arguments" "Command-line arguments to pass to the target" diff --git a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/remote-lldb.bat b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/remote-lldb.bat index 1e13203962..c9e283b890 100644 --- a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/remote-lldb.bat +++ b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/remote-lldb.bat @@ -8,7 +8,7 @@ ::@desc ::@menu-group remote ::@icon icon.debugger -::@help TraceRmiLauncherServicePlugin#lldb_remote +::@help lldb#remote ::@env OPT_HOST:str="localhost" "Host" "The hostname of the target" ::@env OPT_PORT:str="9999" "Port" "The host's listening port" ::@env OPT_ARCH:str="" "Architecture" "Target architecture override" diff --git a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/remote-lldb.sh b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/remote-lldb.sh index 170da9afc9..d6c34c6b0c 100755 --- a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/remote-lldb.sh +++ b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/remote-lldb.sh @@ -24,7 +24,7 @@ #@desc #@menu-group remote #@icon icon.debugger -#@help TraceRmiLauncherServicePlugin#lldb_remote +#@help lldb#remote #@env OPT_HOST:str="localhost" "Host" "The hostname of the target" #@env OPT_PORT:str="9999" "Port" "The host's listening port" #@env OPT_ARCH:str="" "Architecture" "Target architecture override" diff --git a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/ssh-lldb.bat b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/ssh-lldb.bat index 083c7e0181..3692ce39cc 100644 --- a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/ssh-lldb.bat +++ b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/ssh-lldb.bat @@ -10,7 +10,7 @@ ::@desc ::@menu-group remote ::@icon icon.debugger -::@help TraceRmiLauncherServicePlugin#lldb_ssh +::@help lldb#ssh ::@enum StartCmd:str "process launch" "process launch --stop-at-entry" ::@enum Endian:str auto big little ::@env OPT_TARGET_IMG:str="" "Image" "The target binary executable image on the remote system" diff --git a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/ssh-lldb.sh b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/ssh-lldb.sh index f24f9f6a8b..05e7724a63 100644 --- a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/ssh-lldb.sh +++ b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/ssh-lldb.sh @@ -26,7 +26,7 @@ #@desc #@menu-group remote #@icon icon.debugger -#@help TraceRmiLauncherServicePlugin#lldb_ssh +#@help lldb#ssh #@enum StartCmd:str "process launch" "process launch --stop-at-entry" #@enum Endian:str auto big little #@arg :str "Image" "The target binary executable image on the remote system" diff --git a/Ghidra/Debug/Debugger-agent-lldb/src/main/help/help/TOC_Source.xml b/Ghidra/Debug/Debugger-agent-lldb/src/main/help/help/TOC_Source.xml new file mode 100644 index 0000000000..1897ae5fa1 --- /dev/null +++ b/Ghidra/Debug/Debugger-agent-lldb/src/main/help/help/TOC_Source.xml @@ -0,0 +1,25 @@ + + + + + + + + + + + + + + + + + + + diff --git a/Ghidra/Debug/Debugger-agent-lldb/src/main/help/help/topics/lldb/lldb.html b/Ghidra/Debug/Debugger-agent-lldb/src/main/help/help/topics/lldb/lldb.html new file mode 100644 index 0000000000..654d58ffe2 --- /dev/null +++ b/Ghidra/Debug/Debugger-agent-lldb/src/main/help/help/topics/lldb/lldb.html @@ -0,0 +1,209 @@ + + + + + + + Debugger Launchers: LLDB + + + + + +

Debugger Launchers: LLDB

+ +

Integration with LLDB is achieved using a plugin for LLDB's Python Scripting Bridge. It is + well-suited for debuging user-space targets on a variety of platforms. It is the de + facto debugger for macOS. It can be obtained by installing Xcode from the App Store. + Though it may require a bit more careful configuration, it can also be obtained from other + repositories like brew.

+ +

The following launchers based on the LLDB Debugger are included out of the box:

+ +

Local

+ +

The plain "lldb" launch script defaults to launching the current program as a + user-mode process on the local system. If there is no current program, or if you clear the + Image option, this launcher will only start lldb and get it connected to a + Ghidra trace. You may then manually start or connect to your target. Note that this may also + require manual mapping of your program database(s) to the target memory.

+ +

Setup

+ +

You must have LLDB installed on the local system, and it must support Python 3 scripting. If + you have access to PyPI, setting up your Python 3 environment is done using Pip. Please note + the version specifier for Protobuf.

+ + + +

If you are offline, or would like to use our provided packages, we still use Pip, but with a + more complicated invocation:

+ + + +

Beware that LLDB may embed a different Python interpreter than your system's default. If you + are still getting import errors, check the version that LLDB embeds:

+ + + +

Note the version and ensure that you are invoking Pip with that version. Supposing + sys.version indicates 3.10, you should invoke Pip using python3.10 -m + pip.

+ +

Options

+ + + +

Once running, you are presented with LLDB's command-line interface in Ghidra's Terminal. + This is the bona fide LLDB command-line interface, so it has all the functionality you + would expect. If you command LLDB from this shell, the plugin will keep Ghidra in sync. The + terminal can be used to interact with the target application when it is running. The plugin + provides an additional set of commands for managing the connection to Ghidra, as well as + controlling trace synchronization. These are all in the "ghidra" category. You can use + tab completion to enumerate the available commands and LLDB's "help" command to + examine their documentation.

+ +

Remote

+ +

This launcher can target any TCP-based GDB stub that is compatible with a local copy of + lldb. Essentially, it just starts lldb and then enters

+ + + +

into it. It is best to test this command outside of Ghidra to be sure everything is + compatible before using this launcher. This launcher does not require an image, nor does it + create your target. Thus, it can be used without a current program.

+ +

Setup

+ +

On your local system, follow the steps given in LLDB Setup. Your + version of LLDB must be compatible with the stub (e.g., gdbserver) on the target + system. There are no additional requirements on the target system.

+ +

NOTE: The target program image must match that imported in Ghidra, or else things may + not map or synchronize correctly.

+ +

Options

+ + + +

macOS Kernel

+ +

This launcher connects to macOS kernels booted in debug-mode using lldb. + Essentially, it just starts lldb and then enters

+ + + +

It is best to test this command outside of Ghidra to be sure everything is compatible before + using this launcher. This launcher does not require an image, nor does it create your target. + Thus, it can be used without a current program.

+ +

Setup

+ +

On your local system, follow the steps given in LLDB Setup. Before + connecting to the target kernel, you must force an NMI on the target to ready the connection. + On actual hardware, this is typically achieved by some button sequence, e.g. L/R-Options + + Power or Command+Option+Control+Shift+Esc. In a VM, you may have to pause the VM and + modify its state. For example, by cd'ing to the VM's container and issuing the command:

+ + + +

Options

+ + + +

Via SSH

+ +

This works the same as the GDB via SSH launcher, + but runs lldb on a remote system via ssh.

+ +

Android

+ +

This has the same options as the LLDB via SSH launcher, which are + necessary for connecting to the Android debugger, but executes via the normal lldb + mechanism.

+ + diff --git a/Ghidra/Debug/Debugger-jpda/build.gradle b/Ghidra/Debug/Debugger-jpda/build.gradle index b35481f97b..5e853bc03f 100644 --- a/Ghidra/Debug/Debugger-jpda/build.gradle +++ b/Ghidra/Debug/Debugger-jpda/build.gradle @@ -14,6 +14,7 @@ * limitations under the License. */ apply from: "${rootProject.projectDir}/gradle/javaProject.gradle" +apply from: "${rootProject.projectDir}/gradle/helpProject.gradle" apply from: "${rootProject.projectDir}/gradle/jacocoProject.gradle" apply from: "${rootProject.projectDir}/gradle/javaTestProject.gradle" apply from: "${rootProject.projectDir}/gradle/distributableGhidraModule.gradle" diff --git a/Ghidra/Debug/Debugger-jpda/certification.manifest b/Ghidra/Debug/Debugger-jpda/certification.manifest index 354784e591..50b606c315 100644 --- a/Ghidra/Debug/Debugger-jpda/certification.manifest +++ b/Ghidra/Debug/Debugger-jpda/certification.manifest @@ -4,4 +4,6 @@ README.md||GHIDRA||||END| data/debugger-launchers/attach-java.jsh||GHIDRA||||END| data/debugger-launchers/bypid-java.jsh||GHIDRA||||END| data/debugger-launchers/local-java.jsh||GHIDRA||||END| +src/main/help/help/TOC_Source.xml||GHIDRA||||END| +src/main/help/help/topics/jpda/jpda.html||GHIDRA||||END| src/main/resources/ghidra/app/plugin/core/debug/client/tracermi/jdi_schema.xml||GHIDRA||||END| diff --git a/Ghidra/Debug/Debugger-jpda/data/debugger-launchers/attach-java.jsh b/Ghidra/Debug/Debugger-jpda/data/debugger-launchers/attach-java.jsh index d4a28213c9..0f54fee825 100755 --- a/Ghidra/Debug/Debugger-jpda/data/debugger-launchers/attach-java.jsh +++ b/Ghidra/Debug/Debugger-jpda/data/debugger-launchers/attach-java.jsh @@ -9,7 +9,7 @@ //@desc //@menu-group attach //@icon icon.debugger -//@help TraceRmiLauncherServicePlugin#java_attach +//@help jpda#attach_port //@enum Arch:str JVM Dalvik //@env OPT_ARCH:Arch="JVM" "Arch" "Target architecture" //@env OPT_HOST:str="localhost" "Host" "The hostname of the target" diff --git a/Ghidra/Debug/Debugger-jpda/data/debugger-launchers/bypid-java.jsh b/Ghidra/Debug/Debugger-jpda/data/debugger-launchers/bypid-java.jsh index 0dd22a5d34..c7165ecc50 100755 --- a/Ghidra/Debug/Debugger-jpda/data/debugger-launchers/bypid-java.jsh +++ b/Ghidra/Debug/Debugger-jpda/data/debugger-launchers/bypid-java.jsh @@ -9,7 +9,7 @@ //@desc //@menu-group attach //@icon icon.debugger -//@help TraceRmiLauncherServicePlugin#java_bypid +//@help jpda#attach_pid //@enum Arch:str JVM Dalvik //@env OPT_ARCH:Arch="JVM" "Arch" "Target architecture" //@env OPT_PID:str="" "Pid" "The target process id" diff --git a/Ghidra/Debug/Debugger-jpda/data/debugger-launchers/local-java.jsh b/Ghidra/Debug/Debugger-jpda/data/debugger-launchers/local-java.jsh index bc8916a257..551c133895 100755 --- a/Ghidra/Debug/Debugger-jpda/data/debugger-launchers/local-java.jsh +++ b/Ghidra/Debug/Debugger-jpda/data/debugger-launchers/local-java.jsh @@ -10,7 +10,7 @@ //@desc //@menu-group local //@icon icon.debugger -//@help TraceRmiLauncherServicePlugin#java +//@help jpda#local //@env OPT_TARGET_CLASS:file="" "Image" "The Main Class to launch (defaults to current program)." //@env OPT_TARGET_CLASSPATH:str="" "ClassPath" "The JVM classpath" //@args "Arguments" "Command-line arguments to pass to the target" diff --git a/Ghidra/Debug/Debugger-jpda/src/main/help/help/TOC_Source.xml b/Ghidra/Debug/Debugger-jpda/src/main/help/help/TOC_Source.xml new file mode 100644 index 0000000000..2d17f55be8 --- /dev/null +++ b/Ghidra/Debug/Debugger-jpda/src/main/help/help/TOC_Source.xml @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + diff --git a/Ghidra/Debug/Debugger-jpda/src/main/help/help/topics/jpda/jpda.html b/Ghidra/Debug/Debugger-jpda/src/main/help/help/topics/jpda/jpda.html new file mode 100644 index 0000000000..796264dfeb --- /dev/null +++ b/Ghidra/Debug/Debugger-jpda/src/main/help/help/topics/jpda/jpda.html @@ -0,0 +1,100 @@ + + + + + + + Debugger Launchers: Java + + + + + +

Debugger Launchers: Java

+ +

Our Java Debugger is implemented using the JDK's built-in JPDA/JDI API. We currently have a + mode which embeds it in a jshell for CLI-based diagnostics. It is well-suited for Java + and Dalvik (Android VM) targets.

+ +

The following launchers based on the Java Debugger are included out of the box:

+ +

Local

+ +

The plain "java" launcher uses the native Java Debug Interface (JDI) to launch the + current .class file locally.

+ +

Setup

+ +

You must have Java installed on the local system. No additional setup is required.

+ +

Options

+ + + +

Attach by JDWP

+ +

This launcher uses the native Java Debug Interface (JDI) to attach to a running java program + launched with an open Java Debug Wire Port (JDWP) over TCP, e.g.:

+ + + +

Setup

+ +

Identical to that for the java launcher.

+ +

Options

+ + + +

Attach by PID

+ +

This launcher uses the native Java Debug Interface (JDI) to attach to a running java program + launched with a Java Debug Wire Port (JDWP) identified by process id.

+ +

Setup

+ +

Identical to that for the java launcher.

+ +

Options

+ + + + diff --git a/Ghidra/Debug/Debugger-rmi-trace/certification.manifest b/Ghidra/Debug/Debugger-rmi-trace/certification.manifest index 3beeb10bb8..24a091504d 100644 --- a/Ghidra/Debug/Debugger-rmi-trace/certification.manifest +++ b/Ghidra/Debug/Debugger-rmi-trace/certification.manifest @@ -10,7 +10,6 @@ src/main/help/help/topics/TraceRmiConnectionManagerPlugin/TraceRmiConnectionMana src/main/help/help/topics/TraceRmiConnectionManagerPlugin/images/ConnectDialog.png||GHIDRA||||END| src/main/help/help/topics/TraceRmiConnectionManagerPlugin/images/TraceRmiConnectionManagerPlugin.png||GHIDRA||||END| src/main/help/help/topics/TraceRmiLauncherServicePlugin/TraceRmiLauncherServicePlugin.html||GHIDRA||||END| -src/main/help/help/topics/TraceRmiLauncherServicePlugin/images/GdbLauncher.png||GHIDRA||||END| src/main/help/help/topics/TraceRmiLauncherServicePlugin/images/GdbTerminal.png||GHIDRA||||END| src/main/py/LICENSE||GHIDRA||||END| src/main/py/README.md||GHIDRA||||END| diff --git a/Ghidra/Debug/Debugger-rmi-trace/src/main/help/help/TOC_Source.xml b/Ghidra/Debug/Debugger-rmi-trace/src/main/help/help/TOC_Source.xml index 3d7af5fccb..f1cf058f62 100644 --- a/Ghidra/Debug/Debugger-rmi-trace/src/main/help/help/TOC_Source.xml +++ b/Ghidra/Debug/Debugger-rmi-trace/src/main/help/help/TOC_Source.xml @@ -1,61 +1,13 @@ - - - - + + - - + + - - + + diff --git a/Ghidra/Debug/Debugger-rmi-trace/src/main/help/help/topics/TraceRmiLauncherServicePlugin/TraceRmiLauncherServicePlugin.html b/Ghidra/Debug/Debugger-rmi-trace/src/main/help/help/topics/TraceRmiLauncherServicePlugin/TraceRmiLauncherServicePlugin.html index a38d8d7d57..1c53fda4d8 100644 --- a/Ghidra/Debug/Debugger-rmi-trace/src/main/help/help/topics/TraceRmiLauncherServicePlugin/TraceRmiLauncherServicePlugin.html +++ b/Ghidra/Debug/Debugger-rmi-trace/src/main/help/help/topics/TraceRmiLauncherServicePlugin/TraceRmiLauncherServicePlugin.html @@ -17,7 +17,8 @@ launchers for our supported platforms are provided out of the box. For Linux, we provide a suite of GDB-based launchers. For macOS, we provide a suite of LLDB-based launchers (though, these work on Linux, too). For Windows, we provide a launcher based on the Windows Debugger - (dbgeng.dll and dbgmodel.dll).

+ (dbgeng.dll and dbgmodel.dll). Help is available for each in its respective + sub-topic.

Each launcher automates the creation of a Trace RMI acceptor, @@ -116,1040 +117,16 @@ Window → Terminals menu. If the session has already been terminated (indicated by an orange border) then closing the window will, in fact, destroy the Terminal.

-

Stock GDB Launchers

- -

The following launchers based on GDB (GNU Debugger) are included out of the box:

- -

GDB

- -

This launcher is a Python plugin for GDB, and so is best suited for debugging Linux - user-space targets as well as many embedded systems. Please note you may need to obtain a - properly-configured build of GDB for your target. If you are working with an embedded system, - it is probably safest to install the "multiarch" build of GDB from your package manager.

- -

The plain "gdb" launch script defaults to launching the current program as a - user-mode process on the local system. If there is no current program, or if you clear the - Image option, this launcher will only start gdb and get it connected to a - Ghidra trace. You may then manually start or connect to your target. Note that this may also - require manual mapping of your program database(s) to the target memory.

- -

Setup

- -

You must have GDB installed on the local system, and it must embed the Python 3 interpreter. - If you have access to PyPI, setting up your Python 3 environment is done using Pip. Please note - the version specifier for Protobuf.

- - - -

If you are offline, or would like to use our provided packages, we still use Pip, but with a - more complicated invocation:

- - - -

Beware that GDB may embed a different Python interpreter than your system's default. If you - are still getting import errors, check the version that GDB embeds:

- - - -

Note the version and ensure that you are invoking Pip with that version. Supposing - sys.version indicates 3.10, you should invoke Pip using python3.10 -m - pip.

- -

Warning: Modern Linux distributions are beginning to adopt PEP 668, which prevents - installation of Python packages outside of a virtual environment (venv) even for non-root - user accounts. Unfortunately, gdb does not seem to honor the currently activated - venv, and so such configurations are not officially supported. You may be able to work around - this by modifying the PYTHONPATH lines of the launcher script, but your mileage may - vary. For now, we recommend using the --break-system-packages argument with Pip.

- -

Options

- -
- -
- - - -

Once running, you are presented with GDB's command-line interface in Ghidra's Terminal. This - is the bona fide GDB command-line interface, so it has all the functionality you would - expect. If you command GDB from this shell, the plugin will keep Ghidra in sync. The terminal - can also be used to interact with the target application when it is running. The plugin - provides an additional set of commands for managing the connection to Ghidra, as well as - controlling trace synchronization. These are all in the "ghidra" command prefix. You - can use tab completion to enumerate the available commands and GDB's "help" command to - examine their documentation.

- -

GDB via SSH

- -

This works the same as the GDB launcher, but runs gdb on a remote system via - ssh. In contrast to the previous system, which used an SSH library for Java, this - launcher uses the ssh command on the local system. Thus, it should have broader - compatibility with remote systems, and it should use the same configuration files as you are - accustomed to. That said, we developed it using OpenSSH, so your experience will be best if - your copy understands the same command-line arguments.

- -

Setup

- -

You must install GDB and an SSH server onto the target host. Your local SSH client must - support remote port forwarding (-R option) and terminal allocation (-t option), and - the remote server must be configured to permit them.

- -

You will need to manually install the required Python packages on the target host, - comprising our plugin for GDB and its dependencies. Copy all of the Python packages from - Ghidra/Debug/Debugger-rmi-trace/pypkg/dist/ and - Ghidra/Debug/Debugger-agent-gdb/pypkg/dist/ to the remote system. It is easiest to put - them all in one directory, e.g., ~/ghidra-pypgk/. Then install them:

- - - -

Please see GDB Setup for notes about embedded Python interpreter - versions.

- -

Options

- - - -

GDB + gdbserver via SSH

- -

This works similarly to the GDB via SSH launcher, but instead of tunneling the Trace RMI - connection, tunnels the RSP (gdbserver) connection. There is actually a fairly elegant - method of doing this straight from within gdb, which is exactly what this launcher - does:

- - - -

This has some advantages compared to running gdb on the remote target:

- -
    -
  1. GDB may not be available on the remote target.
    2. - -
  2. There is no need to install our plugin for GDB on the target.
    3. -
- -

But, it also has some drawbacks:

- -
    -
  1. gdbserver must be installed on the remote system, and the local gdb - must be compatible with it.
    2. - -
  2. It may be slightly more annoying to map modules from the remote system, because of the - way GDB reports these modules.
    3. - -
  3. The memory map may be absent. Though this is overcome by creating an entry for the entire - address space, if the map is of interest to your analysis, it may not be available.
    4. -
- -

Setup

- -

You must have GDB installed on the local system and a compatible version of - gdbserver installed on the target system. You must have an SSH server installed on the - target system. It may be worth testing your setup manually (outside of Ghidra) to ensure - everything is configured correctly. On the local system, follow the steps given in GDB Setup. There are no additional Python requirements on the target - system.

- -

Options

- - - -

QEMU + GDB

- -

These launchers orchestrate a QEMU user- or system-mode target and connect to it using our - Python plugin for GDB. Ghidra will inspect the current program and attempt to map its language - to the appropriate QEMU command, but due to subtle errors and/or outright failure, the default - value for the QEMU command option often requires careful inspection.

- -

There are two separate scripts for QEMU, one for user mode and one for system mode. Note - that QEMU does not support user-mode emulation on Windows, so that script is not available on - Windows hosts.

- -

Setup

- -

You must acquire versions of QEMU and GDB that support the target architecture. Aside from - the copy of QEMU required, setup is the same whether for user or system mode. As for GDB, on - many distributions of Linux, you can install gdb-multiarch. Follow the steps given in - GDB Setup.

- -

Options

- - - -

Wine + GDB

- -

This launchers runs wine in a gdb session on Linux and directs it to a - target Windows executable. There are other ways to rig a Windows target in GDB on Linux, but - this is the method we have chosen. This may prevent GDB from processing the object file, - because it is a PE file, and most copies of GDB for UNIX will support only ELF. Nevertheless, - Ghidra should recognize the target and map it, giving you symbols and debug info in the front - end, even if not in the GDB CLI.

- -

Setup

- -

In addition to the steps given in GDB Setup, you must install Wine - on your system. Prepare for configuration by locating the actual wine executable. - These are often in some library directory and named "wine32" or "wine64." To - find them, either examine the file list of the installed package, or dissect the wrapper - wine script, usually on your path:

- - - -

The locations are usually given in variables at the top of the script, e.g., - "/usr/lib/wine/wine64". One is for 64-bit Windows targets and another is for 32-bit - Windows targets. Unlike native Windows, Wine does not (yet) implement WoW64 (Windows on Windows - 64). Instead, the 32-bit target is loaded using a 32-bit copy of Wine, and so is serviced by - Linux's 32-bit system calls. NOTE: Careful attention must be given to - select the correct wine executable for the target program's architecture! Even - though the wine executable is smart enough to correct this mistake, it results in - calls to exec, which confuse this launcher. If GDB complains that it cannot place - breakpoints because of memory access, it is probably because of this mistake.

- -

The launcher loads some additional support packages in our plugin for GDB, e.g., to scan the - memory map for PE files and amend the module list. Thus, Ghidra can display both Windows and - Linux modules, and map them to its program databases accordingly, despite GDB's inability to - process PE files. There are perhaps other configurations of GDB for Linux that can process ELFs - as well as PEs loaded by Wine, but they do not seem to be readily available in any popular - package repositories.

- -

Options

- - - -

Remote GDB

- -

This launcher can target any TCP-based GDB stub that is compatible with a local copy of - gdb. Essentially, it just starts gdb and then enters

- - - -

into it. It is best to test this command outside of Ghidra to be sure everything is - compatible before using this launcher. This launcher does not require an image, nor does it - create your target. Thus, it can be used without a current program.

- -

Setup

- -

On your local system, follow the steps given in GDB Setup. Your - version of GDB must be compatible with the stub (e.g., gdbserver) on the target - system. There are no additional requirements on the target system.

- -

NOTE: The target program image must match that imported in Ghidra, or else things may - not map or synchronize correctly.

- -

Options

- - - -

rr + GDB

- -

This launcher runs rr in a gdb session on Linux for replaying rr-generated traces.

- - -

Options

- - - -

Stock LLDB Launchers

- -

The following launchers based on the LLDB Debugger are included out of the box:

- -

LLDB

- -

This launcher is a Python plugin for LLDB, and so is well suited for debugging user-space - targets on a variety of platforms. It is the de facto debugger for macOS. It can be - obtained by installing Xcode from the App Store. Though it may require a bit more careful - configuration, it can also be obtained from other repositories like brew.

- -

Setup

- -

You must have LLDB installed on the local system, and it must embed the Python 3 - interpreter. If you have access to PyPI, setting up your Python 3 environment is done using - Pip. Please note the version specifier for Protobuf.

- - - -

If you are offline, or would like to use our provided packages, we still use Pip, but with a - more complicated invocation:

- - - -

Beware that LLDB may embed a different Python interpreter than your system's default. If you - are still getting import errors, check the version that LLDB embeds:

- - - -

Note the version and ensure that you are invoking Pip with that version. Supposing - sys.version indicates 3.10, you should invoke Pip using python3.10 -m - pip.

- -

Options

- - - -

Once running, you are presented with LLDB's command-line interface in Ghidra's Terminal. - This is the bona fide LLDB command-line interface, so it has all the functionality you - would expect. If you command LLDB from this shell, the plugin will keep Ghidra in sync. The - terminal can be used to interact with the target application when it is running. The plugin - provides an additional set of commands for managing the connection to Ghidra, as well as - controlling trace synchronization. These are all in the "ghidra" category. You can use - tab completion to enumerate the available commands and LLDB's "help" command to - examine their documentation.

- -

Remote LLDB

- -

This launcher can target any TCP-based GDB stub that is compatible with a local copy of - lldb. Essentially, it just starts lldb and then enters

- - - -

into it. It is best to test this command outside of Ghidra to be sure everything is - compatible before using this launcher. This launcher does not require an image, nor does it - create your target. Thus, it can be used without a current program.

- -

Setup

- -

On your local system, follow the steps given in LLDB Setup. Your - version of LLDB must be compatible with the stub (e.g., gdbserver) on the target - system. There are no additional requirements on the target system.

- -

NOTE: The target program image must match that imported in Ghidra, or else things may - not map or synchronize correctly.

- -

Options

- - - -

Kernel LLDB

- -

This launcher connects to macos kernels booted in debug-mode using - lldb. Essentially, it just starts lldb and then enters

- - - -

It is best to test this command outside of Ghidra to be sure everything is - compatible before using this launcher. This launcher does not require an image, nor does it - create your target. Thus, it can be used without a current program.

- -

Setup

- -

On your local system, follow the steps given in LLDB Setup. - Before connecting to the target kernel, you must force an NMI on the target to ready the connection. - On actual hardware, this is typically achieved by some button sequence, e.g. L/R-Options + Power - or Command+Option+Control+Shift+Esc. In a VM, you may have to pause the VM and modify its state. - For example, by cd'ing to the VM's container and issuing the command: -

- - - -

Options

- - - -

LLDB via SSH

- -

This works the same as the "GDB via SSH" launcher, but runs lldb on a remote system via ssh. - -

Android LLDB

- -

This has the same options as the "LLDB via SSH" launcher, which are necessary for connecting to the Android debugger, - but executes via the normal lldb mechanism. - -

Stock Windows Debugger (WinDbg) Launchers

- -

The following launchers based on Microsoft's dbgeng.dll are included out of the - box:

- -

dbgeng

- -

This launcher is actually a Python implementation of a console debugger based on - dbgeng.dll. This DLL represents the Microsoft Windows Debugger engine, and so is best - suited for debugging Windows user-space targets. Windows kernel targets are not yet supported. - This DLL also backs WinDbg and several other debuggers on Windows. By default, the launcher - will search for this DLL in an installation of the Windows Debugging Kits version 10. If it - does not find it there, it will probably crash with a message in the Terminal.

- -

Please note on some system configurations, one of the debugger's dependencies - dbghelp.dll may get loaded from the system directory instead of from the WinDbg - installation, usually because a security product has pre-loaded it into the Python process. You - might work around this by copying the affected DLLs from your WinDbg installation into your - Python installation.

- -

Setup

- -

Installing WinDbg is highly recommended. If you wish to forego installing WinDbg, you can - use the DLL provided with Windows, which is substantially less capable, by manually pointing - this connector to C:\Windows\system32. If you do this, some commands, e.g. - .server, will not be available.

- -

If you have access to PyPI, setting up your Python 3 environment is done using Pip. Please - note the version specifier for Protobuf.

- - - -

If you are offline, or would like to use our provided packages, we still use Pip, but with a - more complicated invocation:

- - - -

If you get an import error regarding distutils, it is due to a transitive - dependency on a buggy version of capstone. Work around it by installing - setuptools.

- -

Options

- - - -

Once running, you are presented with a command-line interface in Ghidra's Terminal. This CLI - accepts your usual WinDbg (kd) commands. You can escape from this CLI and enter a Python 3 REPL - by entering ".exit". This is not an actual kd command, but our implementation - understands this to mean exit the kd REPL. From the Python 3 REPL, you can access the - underlying Python-based API pybag. This is an uncommon need, but may be useful for - diagnostics and/or workarounds. To re-enter the kd REPL, enter "repl()". - Alternatively, if you are trying to quit, but typed ".exit", just type - "quit()" to terminate the session.

- -

dbgeng-ext

- -

This launcher extends the base dbgeng launcher adding extra options (a la IDebugClient's - CreateProcess2).

- -

Options

- - - -

dbgeng-attach

- -

This launcher allows the user to attach to a local running process. Options are the same as - those for the base dbgeng, except for ProcessId and AttachFlags

- -

Options

- - - -

dbgeng-remote

- -

This launcher connects to a remote debugger that has opened a port for remote control. -

- -

Options

- - - -

dbgeng-svrcx

- -

This launcher extends the base dbgeng launcher adding an option for connecting through a - remote process server.

- -

Options

- - - -

dbgeng-kernel

- -

This version of the dbgeng should be used for kernel-debugging of a remote machine. Options - are the same as the base dbgeng, except for the connection-string arguments. For remote - debugging, the target machine should be booted with the appropriate options, set using BCDEDIT - or the equivalent, such as:

- - - -

where IP= the address of the machine runing Ghidra.

- -

Options

- - - - - -

EXDI

- -

Setup for EXDI connections is fairly complicated and difficult to get correct. The argument - string typically should be something like:

- - - -

The CLSID here should match the CLSID in the exdiConfigData.xml file in the debugger - architectural directory. If windbg has been run using EXDI at some point, there will also be an - entry in the System Registry for this CLSID. The InprocServer32 subentry for this CLSID in the - Registry should point to a copy of ExdiGdbSrv.dll, typically the one in the same directory. - This DLL must reside somewhere that the debugger has permission to load from, i.e. not in the - WindowsApps directory tree. The exdiConfigData file should be configured for the target - you're using. We heavily recommend using displayCommPackets==yes, as many of the tasks - take considerable time, and this is the only indicator of progress.

- -

The Kd=Guess parameter causes the underlying engine to scan memory for the kernel's - base address, which will probably not be provided by the gdbstub. (Kd=NtBaseAddr is also - a valid option, as is eliminating the parameter, but, currently, we have no idea how to point - the configuration at a correct value. Using this option will cause the load to spin - pointlessly.) If you can, we highly recommend breaking the target near the base address, as the - search proceeds down through memory starting at the current program counter. If the difference - between the PC and the base address is large, the loading process will punt before useful - values are detected. If anyone understand how to extend this search (or knows how to set the - base address to sidestep the scan), we would really love some guidance.

- -

TTD (Time-Travel Debugging)

- -

This is a nascent extension to our launcher for the Windows Debugger. The launcher itself - functions, but lacks full integration. In particular, Ghidra's concept of time is not - mapped directly to the TTD concept of time. TTD uses a major/minor scheme for ordering events, - where the major index changes when TTD must record a change in state. Events, including thread - creation/termination, module loads/unloads, syscalls, and other asynchronous changes, merit - new major indices. When you step forward or backward in a trace, the dbgeng API will increment - and decrement correspondingly. Ghidra, on the other hand, will only increment.

- -

Options

- -

This launcher has basically the same options as the WinDbg launcher, except that arguments - are not included and the DLL path must contain TTDReplay.dll - and the scripts that implement TTD. These are most easily obtained by installing WinDbg Preview or later.

- -

Stock Java Launchers

- -

The following launchers based on the Java Debugger are included out of the box:

- -

java

- -

This launcher uses the native Java Debug Interface (JDI) to launch the current - .class file.

- -

Setup

- -

You must have Java installed on the local system. No additional setup is required.

- -

Options

- - - -

java attach port

- -

This launcher uses the native Java Debug Interface (JDI) to attach to a running java program - launched with an open Java Debug Wire Port (JDWP), e.g.:

- - - -

Setup

- -

Identical to that for the java launcher.

- -

Options

- - - -

java attach PID

- -

This launcher uses the native Java Debug Interface (JDI) to attach to a running java program - launched with a Java Debug Wire Port (JDWP) identified by process id.

- -

Setup

- -

Identical to that for the java launcher.

- -

Options

- - - -

Drgn Launchers

- -

The following launchers uses Meta's drgn engine to explore various targets:

- -

drgn

- -

This launcher attaches to a running process via the Linux "/proc/pid" interface.

- -

Setup

- -

You must have Meta's drgn installed on the local system. The default behavior - assumes you do NOT need root access to attach to a running process, i.e. it assumes you - have run the command:

- - - -

using root privileges at some point. Alternately, you can prepend "sudo -E" - to the drgn invocation line in "local-drgn.sh"". Note: drgn does not currently - support stack unwinding or register access for user-mode access to running processes. -

- -

Options

- - - -

drgn-core

- -

This launcher loads a Linux core dump.

- -

Setup

- -

You must have Meta's drgn installed on the local system. No other setup is required. - Note: Core dumps may or may not include memory, so the Dynamic Listing may or may not be populated. -

- -

Options

- - - -

drgn-kernel

- -

This launcher attaches to a Linux kernel via the "/proc/kcore" interface.

- -

Setup

- -

You must have Meta's drgn installed on the local system. No other setup is required. - Note: requires root access - you will be prompted for a password in the Terminal. -

- -

Options

- - -

Development and Diagnostic Launchers

-

We currently provide one launcher for Trace RMI API exploration and development:

+

We currently provide a launcher for Trace RMI API exploration and + development: The "raw python" launcher runs Python in a Terminal window, connects a + Trace RMI client back to Ghidra, then starts a blank trace. Once running, it presents the + Python interpreter, with the ghidratrace and ghidratrace.client packages + imported into the local namespace. Thus, a developer can explore the API, invoke methods, and + observer how Ghidra reacts.

-

Raw Python

- -

This launcher runs Python in a Terminal window, connects a Trace RMI client back to Ghidra, - then starts a blank trace. Once running, it presents the Python interpreter, with the - ghidratrace and ghidratrace.client packages imported into the local - namespace. Thus, a developer can explore the API, invoke methods, and observer how Ghidra - reacts.

- -

Setup

+

Setup

If you have access to PyPI, setting up your Python 3 environment is done using Pip. Please note the version specifier for Protobuf.

@@ -1175,7 +152,7 @@ python3 -m pip install --no-index -f Debugger-rmi-trace/pypkg/dist protobuf -

Options

+

Options