# `pwnlib.protocols.adb` — Protocol implementations

Implementation of the Android Debug Bridge (ADB) protocol.

Documentation is available here.

class pwnlib.protocols.adb.AdbClient(level=None)

  ADB Client

  __init__(level=None)
  _autoclose()

    Decorator which automatically closes the connection to the ADB server after calling the decorated function.

  _sync()

    Decorator which enters ‘sync:’ mode to the selected transport, then invokes the decorated funciton.

  _with_transport()

    Decorator which automatically selects a device transport before calling the decorated function, and closes the connection afterward.

  devices(long=False)
    Parameters:

      long (bool) – If `True`, fetch the long-format listing.

    Returns:

      String representation of all available devices.

  execute(argv)

    Executes a program on the device.

    Returns:

      A `pwnlib.tubes.tube.tube` which is connected to the process.

    Examples:

         >>> pwnlib.protocols.adb.AdbClient().execute(['echo','hello']).recvall()
         b'hello\n'

  kill()

    Kills the remote ADB server”

         >>> c=pwnlib.protocols.adb.AdbClient()
         >>> c.kill()

    The server is automatically re-started on the next request, if the default host/port are used.

         >>> c.version() > (4,0)
         True
         >>> c.wait_for_device() # ensure doctests alive

  list(path)

    Execute the `LIST` command of the `SYNC` API.

    Parameters:

      path (str) – Path of the directory to list.

    Returns:

      A dictionary, where the keys are relative filenames, and the values are a dictionary containing the same values as `stat()` supplies.

    Note

    In recent releases of Android (e.g. 7.0), the domain that adbd executes from does not have access to everything that the shell user does.

    Because of this, while the shell user can get listings of e.g. the root directory (‘/’), adbd cannot.

    The SYNC APIs are executed within the adbd context, not the shell user context.

    This issue is not a problem if the phone is rooted via ‘adb root’, since adbd then runs in the `su` domain.

    Examples:

         >>> _ = AdbClient().root()
         >>> AdbClient().wait_for_device()
         >>> pprint(AdbClient().list('/data/user'))
         {'0': {'mode': 41471, 'size': 10, 'time': ...}}
         >>> AdbClient().list('/does/not/exist')
         Traceback (most recent call last):
         ...
         PwnlibException: Cannot list directory '/does/not/exist': Does not exist

  read(path, filesize=0, callback=<function AdbClient.<lambda>>)

    Execute the `READ` command of the `SYNC` API.

    Parameters:

      - path (str) – Path to the file to read

      - filesize (int) – Size of the file, in bytes. Optional.

      - callback (callable) –

        Callback function invoked as data becomes available. Arguments provided are:

        - File path

        - All data

        - Expected size of all data

        - Current chunk

        - Expected size of chunk

    Returns:

      The data received as a string.

  recvl()

    Receives a length-prefixed data buffer from the ADB server

  send(*a, **kw)

    Sends data to the ADB server

  stat(path)

    Execute the STAT command of the SYNC API.

    Parameters:

      path (str) – Path to the file to stat.

    Returns:

      On success, a dictionary mapping the values returned. If the file cannot be stat() ed, None is returned.

    Example:

         >>> expected = {'mode': 16749, 'size': 0, 'time': 0}
         >>> pwnlib.protocols.adb.AdbClient().stat('/proc')           == expected
         True
         >>> pwnlib.protocols.adb.AdbClient().stat('/does/not/exist') is None
         True

  track_devices()
    Returns:

      Generator which returns a short-format listing of available devices each time a device state changes.

  transport(serial=None, try_again=True)

    Sets the Transport on the remote device.

    Examples:

         >>> pwnlib.protocols.adb.AdbClient().transport()

  unpack(*a, **kw)

    Receives a hex-ascii packed integer from the ADB server

  version()
    Returns:

      Tuple containing the `(major, minor)` version from the ADB server

    Example:

         >>> pwnlib.protocols.adb.AdbClient().version()
         (4, 36)

  write(path, data, mode=493, timestamp=None, callback=None)

    Execute the `WRITE` command of the `SYNC` API.

    Parameters:

      - path (str) – Path to the file to write

      - data (str) – Data to write to the file

      - mode (int) – File mode to set (e.g. `0o755`)

      - timestamp (int) – Unix timestamp to set the file date to

      - callback (callable) –

        Callback function invoked as data is written. Arguments provided are:

        - File path

        - All data

        - Expected size of all data

        - Current chunk

        - Expected size of chunk

  property c

    AdbClient’s connection to the ADB server

class pwnlib.protocols.adb.Connection(host, port, level=None, *a, **kw)

  Connection to the ADB server

  __init__(host, port, level=None, *a, **kw)
  close()

    Closes the tube.

class pwnlib.protocols.adb.Message(string)

  An ADB hex-length-prefixed message

  __init__(string)
  __str__()

    Return str(self).

  __weakref__

    list of weak references to the object

class pwnlib.protocols.adb.Process(host, port, level=None, *a, **kw)

  Duck-typed `tubes.remote` object to add properties of a `tubes.process`

pwnlib.protocols.adb.proxy(port=9999)

  Starts an ADB proxy on the specified port, for debugging purposes.