From 5d49c227da1088e434e651d50f9264e6a14cd630 Mon Sep 17 00:00:00 2001
From: crazy hugsy <hugsy@users.noreply.github.com>
Date: Sun, 20 Aug 2023 19:06:41 -0700
Subject: [PATCH] Added docs to debug using VSCode (#995)

This PR adds the documentation to use VSCode as a source debugging
platform for GEF.

It also fixes the PR template MD file, which had a non-terminated HTML
comment tag.
---
 .github/PULL_REQUEST_TEMPLATE.md |  3 +-
 docs/debugging.md                | 54 ++++++++++++++++++++++++++++++--
 scripts/vscode_debug.py          |  7 +++++
 3 files changed, 61 insertions(+), 3 deletions(-)
 create mode 100644 scripts/vscode_debug.py

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index e3b0184c1..c15ff7cb5 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -8,7 +8,8 @@
 
 <!-- How does this look? Add a screenshot if you can -->
 
-<!-- Annotate your PR with label proper labels (architecture impacted, type of improvement, etc.)
+<!-- Annotate your PR with label proper labels (architecture impacted, type of improvement,
+etc.) ->
 
 ## Checklist
 
diff --git a/docs/debugging.md b/docs/debugging.md
index 203d9ca3b..78217da6c 100644
--- a/docs/debugging.md
+++ b/docs/debugging.md
@@ -2,7 +2,7 @@
 
 Debugging GEF has a trick, let's see some examples
 
-## Debugging a command execution with pdb
+## Debugging with pdb
 
 Open gef.py
 
@@ -32,7 +32,7 @@ gef➤  nop
 
 Learn more about [pdb](https://docs.python.org/3/library/pdb.html)
 
-## Debugging a command execution with pycharm
+## Debugging with PyCharm
 
 Install [pycharm](https://www.jetbrains.com/help/pycharm/installation-guide.html)
 
@@ -79,3 +79,53 @@ Open a gdb session -> start -> nop
 Done!
 
 ![pycharm9](https://github.com/hugsy/gef/assets/9882181/b22ec431-57e7-442a-835e-5817bdac7687)
+
+
+## Debugging with VSCode
+
+The approach to debug GEF with VSCode is relatively similar to that of PyCharm. Make sure to
+install the [Python extension for
+VSCode](https://marketplace.visualstudio.com/items?itemName=ms-python.python). This will install
+`debugpy`, a remote debugger that you can connect to from VSCode and debug anything in GEF from
+your session (breakpoints, watchpoints, etc.). Debugging a Python app from VSCode is [extensively
+ covered in the official docs](https://code.visualstudio.com/docs/python/debugging) to refer to
+ them if you're not sure how it works.
+
+To start a debugging session in GEF, manually run the following Python commands
+
+```python
+gef> pi import debugpy; debugpy.listen(5678); pi debugpy.wait_for_client()
+```
+
+Alternatively a convenience script named `vscode_debug.py` can also be found in the `scripts`
+folder, which you can invoke easily simply using the GDB `source` command:
+
+```text
+gef> source /path/to/gef/scripts/vscode_debug.py
+```
+
+GEF will be suspended, waiting for a client to connect to the debugger to resume the execution.
+Then from your VSCode, edit or create `/path/to/gef/.vscode/launch.json`, and add a debug
+configuration to attach to GEF, by specifying the IP address and port (on `localhost` in the
+example below, but the remote server can be anywhere):
+
+```json
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python: Attach to GEF",
+            "type": "python",
+            "request": "attach",
+            "connect": {
+                "host": "localhost",
+                "port": 5678
+            }
+        }
+    ]
+}
+```
+
+Everything is ready to attach to GEF. By default, you can simply hit F5 on VSCode (Start Debugging)
+
+![vscode-dbg](https://user-images.githubusercontent.com/590234/260521923-b730e2b1-8a17-423d-914c-2be0a1abfed4.png)
diff --git a/scripts/vscode_debug.py b/scripts/vscode_debug.py
new file mode 100644
index 000000000..6c48c03ab
--- /dev/null
+++ b/scripts/vscode_debug.py
@@ -0,0 +1,7 @@
+import debugpy
+
+DEBUGPY_PORT = 5678
+debugpy.listen(DEBUGPY_PORT)
+print("Waiting for debugger attach")
+debugpy.wait_for_client()
+print("Client connected, resuming session")