implemented requested fixes for #2382:

+ gdb.debug port is now also used for qemu
+ GDB Python API is now tested for tubes.process.process a warning for ssh.process and an error for everything else
+ updated docs to use mention that gdbserver ports are randomized by default
+ now using gdbserver_port to check if the correct port was set
+ fixed CHANGELOG.md structure

CHANGELOG.md

@@ -72,7 +72,6 @@ The table below shows which release corresponds to each branch, and what date th
 
 ## 4.14.0 (`dev`)
 
-- [#2382][2382] added optional port, gdb_args and gdbserver_args parameters to gdb.debug()
 - [#2360][2360] Add offline parameter for `search_by_hash` series function
 - [#2356][2356] Add local libc database provider for libcdb
 - [#2374][2374] libcdb.unstrip_libc: debug symbols are fetched only if not present
@@ -83,6 +82,7 @@ The table below shows which release corresponds to each branch, and what date th
 - [#2391][2391] Fix error message when passing invalid kwargs to `xor`
 - [#2376][2376] Return buffered data on first EOF in tube.readline()
 - [#2387][2387] Convert apport_corefile() output from bytes-like object to string
+- [#2382][2382] added optional port, gdb_args and gdbserver_args parameters to gdb.debug()
 
 [2360]: https://github.com/Gallopsled/pwntools/pull/2360
 [2356]: https://github.com/Gallopsled/pwntools/pull/2356
@@ -94,6 +94,7 @@ The table below shows which release corresponds to each branch, and what date th
 [2391]: https://github.com/Gallopsled/pwntools/pull/2391
 [2376]: https://github.com/Gallopsled/pwntools/pull/2376
 [2387]: https://github.com/Gallopsled/pwntools/pull/2387
+[2382]: https://github.com/Gallopsled/pwntools/pull/2382
 
 ## 4.13.0 (`beta`)
 

pwnlib/gdb.py

@@ -292,7 +292,7 @@ def _gdbserver_args(pid=None, path=None, port=0, gdbserver_args=None, args=None,
     Arguments:
         pid(int): Process ID to attach to
         path(str): Process to launch
-        port(int): Port to use for gdbserver
+        port(int): Port to use for gdbserver, default: random
         gdbserver_args(list): List of additional arguments to pass to gdbserver
         args(list): List of arguments to provide on the debugger command line
         which(callaable): Function to find the path of a binary.
@@ -435,7 +435,7 @@ def debug(args, gdbscript=None, gdb_args=None, exe=None, ssh=None, env=None, por
         exe(str): Path to the executable on disk
         env(dict): Environment to start the binary in
         ssh(:class:`.ssh`): Remote ssh session to use to launch the process.
-        port(int): Gdb port to use
+        port(int): Gdb port to use, default: random
         gdbserver_args(list): List of additional arguments to pass to gdbserver
         sysroot(str): Set an alternate system root. The system root is used to
             load absolute shared library symbol files. This is useful to instruct
@@ -626,7 +626,9 @@ def debug(args, gdbscript=None, gdb_args=None, exe=None, ssh=None, env=None, por
     gdbscript = gdbscript or ''
 
     if api and runner is not tubes.process.process:
-        log.warn('GDB Python API is supported only for local processes')
+        if runner is not ssh.process:
+            raise ValueError('GDB Python API is supported only for local processes')
+        log.warn('GDB Python API for ssh processes is not officially tested')
 
     args, env = misc.normalize_argv_env(args, env, log)
     if env:
@@ -652,7 +654,7 @@ def debug(args, gdbscript=None, gdb_args=None, exe=None, ssh=None, env=None, por
             script = _execve_script(args, executable=exe, env=env, ssh=ssh)
             args = _gdbserver_args(gdbserver_args=gdbserver_args, args=args, port=port, which=which, env=env, python_wrapper_script=script)
     else:
-        qemu_port = random.randint(1024, 65535)
+        qemu_port = port if port != 0 else random.randint(1024, 65535)
         qemu_user = qemu.user_path()
         sysroot = sysroot or qemu.ld_prefix(env=env)
         if not qemu_user:
@@ -681,13 +683,13 @@ def debug(args, gdbscript=None, gdb_args=None, exe=None, ssh=None, env=None, por
     # Set the .executable on the process object.
     gdbserver.executable = exe
 
-    # if the port was set manually we won't need to find it
-    if not port:
-        # Find what port we need to connect to
-        if ssh or context.native or (context.os == 'android'):
-            port = _gdbserver_port(gdbserver, ssh)
-        else:
-            port = qemu_port
+    if ssh or context.native or (context.os == 'android'):
+        gdb_port =  _gdbserver_port(gdbserver, ssh)
+        if port != 0 and port != gdb_port:
+            log.error("gdbserver port (%d) doesn't equals set port (%d)" % (gdb_port, port))
+        port = gdb_port
+    else:
+        port = qemu_port
 
     host = '127.0.0.1'
     if not ssh and context.os == 'android':