diff options
| -rw-r--r-- | TODO | 8 | ||||
| -rw-r--r-- | debug-me.1 | 64 | ||||
| -rw-r--r-- | debug-me.cabal | 11 |
3 files changed, 63 insertions, 20 deletions
@@ -20,7 +20,9 @@ Activity Entered as well. This will make it easier when supported multiple developers, as each time a developer gets an Activity Seen, they can update their state to use the Activity Entered that it points - to. + to. (Perhaps not needed now that developers see other developer's + Activity Entered.. But, this does let developers know what the current + accepted line is.) * loadLog should verify the hashes (and signatures) in the log, and refuse to use logs that are not valid proofs of a session. (--replay and --graphvis need this; server's use of loadLog does not) @@ -63,3 +65,7 @@ client only sent to Joey's server and trusted it to replicate to Alice, Joey could break the replication to cover up his nefarious activities in the debug-me session. +* When the user presses control-s, before forwarding it to the terminal, + stop accepting any developer input. Control-s again to resume. +* Make control-backslash immediately end the debug-me session. + @@ -5,48 +5,76 @@ debug-me \- secure remote debugging .SH SYNOPSIS .B debug-me [options] .SH DESCRIPTION -.I debug-me -`debug-me` lets a developer access your computer remotely, to debug a problem, -avoiding a tedious back-and-forth by email. When you start `debug-me`, it -starts a shell, and generates an URL which you can give to the developer -(or developers) to connect them to the session. +Debugging a problem over email is slow, tedious, and hard. The developer +needs to see the your problem to understand it. Debug-me aims to make +debugging fast, fun, and easy, by letting the developer access your +computer remotely, so they can immediately see and interact with the +problem. Making your problem their problem gets it fixed fast. .PP -It's not normally a good idea to let someone run commands in a shell on -your computer. To make this as safe as possible, debug-me uses the -GPG web of trust. Everything the developer sends to debug-me is signed -with their GPG key, in a way that produces a GPG signed proof of what the -developer saw, and what they did in the debug-me session. -If the developer does something Evil, you have the neccessary proof -to adjust their reputation. +A debug-me session is logged and signed with the developer's Gnupg +key, producing a chain of evidence of what they saw and what they did. +So the developer's good reputation is leveraged to make debug-me secure. .PP -.SH OPTIONS +When you start debug-me without any options, it will connect to a debug-me +server, and print out an url that you can give to the developer to get +them connected to you. Then debug-me will show you their Gnupg key and who +has signed it. If the developer has a good reputation, you can proceed +to let them type into your console in a debug-me session. Once the +session is done, the debug-me server will email you the signed +evidence of what the developer did in the session. .PP +It's a good idea to watch the debug-me session. The developer should be +running their buggy program in different ways, perhaps running a debugger, +or looking at configuration files. They should *not* be looking at your +personal files without asking you first in the debug-me chat window. +They should not be downloading or installing other software. If you see +them do anything you don't expect, press Control-S immediately, which +will prevent them from doing anything else. You can also press +Control-Backslash to immediately end the debug-me session. +.PP +If the developer did do something bad, you'd have proof that they cannot +be trusted, which you can share with the world. Knowing that is the case +will keep most developers honest. +.SH USER OPTIONS .IP "-- cmd opts" Normally debug-me will run your login shell. To run some other command, pass the command and any options after "--". -.PP .IP "--gpg-opt=option" debug-me runs gpg to verify the GPG key of a developer. To pass options to gpg, use --gpg-opt with the option to pass. For example: --gpg-opt=--keyserver=pgpkeys.mit.edu This can be done multiple times. +.IP "--control" +debug-me uses a separate window from the one displaying the debug-me +session to control the session. This control window is where debug-me will +show you the Gnupg keys of developers who connect and let you decide if +they should access the session. You can also chat with the developer +in the control window during the session. +.IP +Normally, the control window will be opened when debug-me starts, +by running a terminal emulator (xterm or gnome-terminal, etc). +If debug-me is not being run in a graphical environment, that won't work, +and you'll need to open another shell and run "debug-me --control" to see it. +.SH DEVELOPER OPTIONS .IP "--debug url" Connect to a debug-me session on the specified url. The developer runs debug-me with this option to see and interact with the user's bug. +.IP "--watch url" +Connect to a debug-me session on the specified url and display what +happens in the session. Your keystrokes will not be sent to the session. +.SH LOG FILE OPTIONS .IP "--download url" Download a debug-me log file from the specified url. Note that if the debug-me session is still in progress, this will continue downloading -until the session ends. The proof chain in the log file is verified +until the session ends. The signature chain in the log file is verified as it is downloaded, but developer gpg signatures are not verified. .IP "--replay logfile" Replay a debug-me log file with realistic pauses. -.IP "--watch url" -Connect to a debug-me session on the specified url and display what -happens in the session. Your keystrokes will not be sent to the session. .IP "--graphviz logfile" Uses graphviz to generate a visualization of a debug-me log file. .IP "--show-hashes" Include hashes in the graphviz visualization. +.SH SERVER OPTIONS .IP "--server logdir" Run a debug-me server, logging to the specified directory. .IP "--port N" diff --git a/debug-me.cabal b/debug-me.cabal index a73c919..254590c 100644 --- a/debug-me.cabal +++ b/debug-me.cabal @@ -9,8 +9,17 @@ License: AGPL-3 Homepage: https://debug-me.branchable.com/ Category: Utility Build-Type: Custom -Synopsis: +Synopsis: secure remote debugging Description: + Debugging a problem over email is slow, tedious, and hard. The developer + needs to see your problem to understand it. Debug-me aims to make debugging + fast, fun, and easy, by letting the developer access your computer remotely, + so they can immediately see and interact with the problem. Making your + problem their problem gets it fixed fast. + . + A debug-me session is logged and signed with the developer's Gnupg + key, producing a chain of evidence of what they saw and what they did. + So the developer's good reputation is leveraged to make debug-me secure. License-File: AGPL Extra-Source-Files: CHANGELOG |