Skip to content

Commit

Permalink
Added docs to debug using VSCode (#995)
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
hugsy authored Aug 21, 2023
1 parent 9f79363 commit 5d49c22
Show file tree
Hide file tree
Showing 3 changed files with 61 additions and 3 deletions.
3 changes: 2 additions & 1 deletion .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
54 changes: 52 additions & 2 deletions docs/debugging.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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)

Expand Down Expand Up @@ -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)
7 changes: 7 additions & 0 deletions scripts/vscode_debug.py
Original file line number Diff line number Diff line change
@@ -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")

0 comments on commit 5d49c22

Please sign in to comment.