Skip to content

Commit e37e3e8

Browse files
sam-f0mike-f0
andauthored
Add draw.io deep links
Add draw.io deep links --------- Co-authored-by: mike-f0 <148759787+mike-f0@users.noreply.github.com>
1 parent 0ca9328 commit e37e3e8

File tree

4 files changed

+163
-108
lines changed

4 files changed

+163
-108
lines changed

README.md

Lines changed: 41 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -3,76 +3,93 @@
33
</p>
44

55
# Ghidra Deep Links
6+
67
A cross-platform plugin for Ghidra that provides deep linking support. This enables the generation of clickable `disas://` links that can be included in 3rd party applications. Example use cases include:
8+
79
* Direct linking from research notes or reports to relevant binary locations.
810
* Sharing an interesting section address with peers over Slack, Discord, Teams etc.
911
* Including links in vulnerability write-ups or tutorials to direct readers to the exact address of an issue.
12+
* Creating draw.io diagrams for documenting program structure with direct links to corresponding locations.
1013

1114
The linking mechanism will work across different project structures and with both shared and non-shared Ghidra projects.
1215

13-
# IDA support
16+
## IDA support
1417

1518
Don't use Ghidra? Not a problem...
1619

17-
We have collaborated with the team behind Heimdallr, a plugin that provides deep linking support for IDA, on a new platform-agnostic URI schema so that links generated in Ghidra Deep Links can be opened by Heimdallr and vice versa. This assumes the exact same binary is loaded on both platforms. This is great as now teams can use their prefered disassembler while being able to use the same external notes and reference links. Check out Heimdallr over at: https://github.com/interruptlabs/heimdallr-ida
20+
We have collaborated with the team behind Heimdallr, a plugin that provides deep linking support for IDA, on a new platform-agnostic URI schema so that links generated in Ghidra Deep Links can be opened by Heimdallr and vice versa. This assumes the exact same binary is loaded on both platforms. This is great as now teams can use their prefered disassembler while being able to use the same external notes and reference links. Check out Heimdallr over at: <https://github.com/interruptlabs/heimdallr-ida>
21+
22+
We invite other developers to adopt the `disas://` schema outlined in [URL format](#-url-format) to enable more cross-application compatibility.
1823

19-
We invite other developers to adopt the `disas://` schema outlined in [URL format](#url-format) to enable more cross-application compatibility.
24+
## ▶️ Usage
2025

21-
# ▶️ Usage
22-
With a CodeBrowser tool open, right click on a line in the listing view which will present a new context menu items, "Copy Deep Link"
26+
With a CodeBrowser tool open, right click on a line in the listing view which will present new context menu items:
2327

24-
![The context menu in a Ghidra code listing containing the new Copy Deep Link item](img/context-menu.png)
28+
![The context menu in a Ghidra code listing containing the new Deep Link items](img/context-menu.png)
2529

26-
Click on this menu item and a `disas://` link will be added to the clipboard. This can be shared by pasting like any normal link.
30+
Click on the *Copy Deep Link* item and a `disas://` link will be added to the clipboard. This can be shared by pasting like any normal link.
2731

2832
When you (or somebody else) clicks on the link the referenced binary will open in a CodeBrowser session and the memory address from the link will be jumped to.
2933

3034
> ⚠️ Currently the link handler does not distinguish between projects, and (on non-linux platforms) it cannot open Ghidra by itself. Therefore you will need to have Ghidra open and the project containing the binary referenced in the link open.
3135
32-
You can use the "Copy Markdown Deep Link" content menu item to copy a fully formatted link, where the symbol name or address is the title of the link and the `disas://` is the target.
36+
You can use the *Copy Markdown Deep Link* context menu item to copy a fully formatted Markdown link, where the symbol name or address is the title of the link and the `disas://` URL is the target.
37+
38+
### Creating draw.io objects
39+
40+
The *Copy draw.io Deep Link* context menu item populates your clipboard with a [draw.io](https://draw.io) object. Pasting this into draw.io will add an object to your diagram, labelled with the symbol name or address of the location where you right-clicked. This object will have both the text and the object as a whole linked with the `disas://` URL to the original binary location. Here's what it will look like when pasted into your draw.io diagram:
41+
42+
![Deep link pasted into draw.io](img/drawio-object.png)
43+
44+
If you save your diagram as an SVG image and open it in a browser, you will now be able to click on this object and Ghidra will navigate to the original location. This makes it easy to create diagrams visually documenting the relationship between important locations in your binary, and allowing easy navigation around them.
45+
46+
Top tip: use draw.io's [Editable SVG image](https://www.drawio.com/blog/xml-in-png) functionality to create an SVG file that you can load directly in draw.io.
47+
48+
## ⚙️ Installation
3349

34-
# ⚙️ Installation
3550
### Linux
36-
1. Download and install the latest release of the ghidra-deep-links extension from https://github.com/foundryzero/ghidra-deep-links/releases
51+
52+
1. Download and install the latest release of the ghidra-deep-links extension from <https://github.com/foundryzero/ghidra-deep-links/releases>
3753

3854
2. Install the `disas://` handler by executing the following:
3955

4056
(Before curling and executing random scripts from the internet it is a good idea to validate they don't do anything malicious. Please review the contents of this script before execution at `install.sh`)
41-
```
57+
58+
```bash
4259
bash -c "$(curl https://raw.githubusercontent.com/foundryzero/ghidra-deep-links/main/install.sh)"
4360
```
4461

4562
3. Alternatively, clone this repo and run `install-offline.sh`.
4663

47-
3. Follow the instructions in [Plugin Activation](#plugin-activation) to complete the install.
48-
64+
4. Follow the instructions in [Plugin Activation](#plugin-activation) to complete the install.
4965

5066
### Windows
5167

52-
1. Download and install the latest release of the ghidra-deep-links extension from https://github.com/foundryzero/ghidra-deep-links/releases
68+
1. Download and install the latest release of the ghidra-deep-links extension from <https://github.com/foundryzero/ghidra-deep-links/releases>
5369

5470
2. Install the `disas://` handler by executing the following in a PowerShell window:
5571

5672
(Before executing random PowerShell scripts from the internet it is a good idea to validate they don't do anything malicious. Please review the contents of this script before execution at `install.ps1`)
57-
```
73+
74+
```ps
5875
Invoke-Expression (Invoke-WebRequest https://raw.githubusercontent.com/foundryzero/ghidra-deep-links/main/install.ps1).Content
5976
```
6077
6178
3. Alternatively, clone this repo and run `install-offline.ps1`.
6279
6380
4. Follow the instructions in [Plugin Activation](#plugin-activation) to complete the install.
6481
65-
6682
### Mac
6783
68-
1. Download and install the latest release of the ghidra-deep-links extension from https://github.com/foundryzero/ghidra-deep-links/releases
84+
1. Download and install the latest release of the ghidra-deep-links extension from <https://github.com/foundryzero/ghidra-deep-links/releases>
6985
7086
2. Additionally download `GhidraDeepLinksHandler.dmg` from the above releases page, mount the dmg and install the handler app as normal (drag to Applications)
7187
7288
3. Run the following to disable Gatekeeper on the handler app.
73-
89+
7490
(This is required as we do not code sign our releases. Please review the code at `os/mac`. This can be compiled from source by following the steps in `.github/workflows/mac_app.yml`)
75-
```
91+
92+
```bash
7693
xattr -d com.apple.quarantine /Applications/GhidraDeepLinksHandler.app
7794
```
7895
@@ -82,11 +99,11 @@ You can use the "Copy Markdown Deep Link" content menu item to copy a fully form
8299
83100
1. From the Ghidra project browser click `File -> Install Extensions`. Click the green `+` button and select the extension downloaded from the releases page (Don't extract the zip archive).
84101

85-
![](img/install.png)
102+
![Extension installation in Ghidra](img/install.png)
86103

87104
2. In the main ghidra window (the one that shows your project files), go to `File -> Configure -> Utility` and enable `ghidra-deep-links`.
88105

89-
![](img/configure.png)
106+
![Extension configuration in the Project window](img/configure.png)
90107

91108
3. In a CodeBrowser window, go to `File -> Configure -> Utility` and enable `DeepLinksToolPlugin`.
92109

@@ -96,12 +113,11 @@ You can use the "Copy Markdown Deep Link" content menu item to copy a fully form
96113

97114
See [BUILDING.md](./BUILDING.md)
98115

99-
100116
# 🔗 URL format
101117

102118
The URLs take the format
103119

104-
```
120+
```raw
105121
disas://<hash>/[?ghidra_path=<path>]&offset=<offset>[&label=<label>]
106122
```
107123

@@ -114,10 +130,10 @@ If `<path>` cannot be found or does not match `<hash>`, the entire project will
114130

115131
Please consider adopting this schema when you want to create links to a location in a binary.
116132

117-
# ⚠️ Caveats & Known Issues
133+
## ⚠️ Caveats & Known Issues
118134

119135
* `disas://` links cannot be opened from Snap applications.
120-
* If multiple instances of ghidra are open, only the first will recieve the link requests.
136+
* If multiple instances of ghidra are open, only the first will receive the link requests.
121137
* Currently the link handler does not distinguish between projects, and (on non-linux platforms) it cannot open Ghidra by itself. Therefore you will need to have Ghidra open and the project containing the binary referenced in the link open.
122138
* When the link handler falls back to lookup by hash links may take a few seconds to open on projects with many (i.e. hundreds of) binaries.
123139
* On Windows a Powershell window may briefly flash open on each link press.

0 commit comments

Comments
 (0)