Session Control

def start_session(self, target_exe: str = "", cmdline: str = "", current_dir: str = "") -> int:
    """
    Start a new x64dbg session and optionally load an executable into it. If target_exe is not provided,
    the debugger starts without any executable. This is useful for performing configuration before the debuggee is loaded.

    Args:
        target_exe: The path to the target executable (optional)
        cmdline: The command line arguments to pass to the executable (optional)
        current_dir: The current working directory to set for the executable (optional)

    Returns:
        The debug session ID
    """
    if len(target_exe.strip()) == 0 and (len(cmdline) > 0 or len(current_dir) > 0):
        raise ValueError("cmdline and current_dir cannot be provided without target_exe")

    self.proc = subprocess.Popen([self.x64dbg_path], executable=self.x64dbg_path)
    self.session_pid = self.proc.pid
    self.attach_session(self.session_pid)

    if target_exe.strip() != "":
        if not self.load_executable(target_exe.strip(), cmdline, current_dir):
            self.terminate_session()
            raise RuntimeError("Failed to load executable")
        self.wait_cmd_ready()
    return self.session_pid

def start_session_attach(self, pid: int) -> int:
    """
    Start a new x64dbg session and attach to an existing process identified by pid.

    Args:
        pid (int): Process Identifier (PID) of the process to attach to.

    Returns:
        int: The debug session ID (the PID of the x64dbg process).

    Raises:
        RuntimeError: If attaching to the process fails.
    """
    self.proc = subprocess.Popen([self.x64dbg_path], executable=self.x64dbg_path)
    self.session_pid = self.proc.pid
    self.attach_session(self.session_pid)

    if not self.attach(pid):
        self.terminate_session()
        raise RuntimeError("Failed to attach to process")

    self.wait_until_debugging()
    return self.session_pid

def attach_session(self, session_pid: int) -> None:
    """
    Attach to an existing x64dbg session

    Args:
        session_pid: The session ID to attach to (debugger PID)
    """
    session = X64DbgClient.wait_for_session(session_pid)
    self.sess_req_rep_port = session.sess_req_rep_port
    self.sess_pub_sub_port = session.sess_pub_sub_port
    self._init_connection()
    self._assert_connection_compat()

def detach_session(self) -> None:
    """
    Detach from the current x64dbg session, leaving the debugger process running.
    """
    self._close_connection()

def terminate_session(self) -> None:
    """
    End the current x64dbg session, terminating the debugger process.
    """
    sid = self.session_pid
    self._xauto_terminate_session()
    self._close_connection()
    for _ in range(100):
        time.sleep(0.2)
        if sid not in [p.pid for p in self.list_sessions()]:
            return
    raise TimeoutError("Session did not terminate in a reasonable amount of time")

@staticmethod
def list_sessions() -> list[DebugSession]:
    """
    Lists all active x64dbg sessions

    Returns:
        A list of sessions
    """
    sessions: list[DebugSession] = []
    temp_path_cstr = ctypes.create_unicode_buffer(1024)
    if GetTempPathW(1024, temp_path_cstr) == 0:
        temp_path = "c:\\windows\\temp\\"
    else:
        temp_path = temp_path_cstr.value

    locks = glob.glob(f'{temp_path}xauto_session.*.lock')
    for lock in locks:
        while True:
            try:
                with open(lock, 'r') as f:
                    sess_req_rep_port = int(f.readline().strip())
                    sess_pub_sub_port = int(f.readline().strip())

                pid = int(lock.split('.')[-2])
                if psutil.pid_exists(pid):
                    process = psutil.Process(pid)
                    sessions.append(DebugSession(
                        pid=pid,
                        lockfile_path=lock,
                        cmdline=process.cmdline(),
                        cwd=process.cwd(),
                        window_title=X64DbgClient._window_title_for_pid(pid),
                        sess_req_rep_port=sess_req_rep_port,
                        sess_pub_sub_port=sess_pub_sub_port
                    ))
                    break
                else:
                    if time.time() - os.path.getctime(lock) > 10.0:
                        logger.warning(f"Stale lockfile {lock}, removing")
                        os.unlink(lock)
                        break
            except FileNotFoundError:
                # The process exited between the glob and the open
                break

    return sessions

@staticmethod
def wait_for_session(session_pid: int, timeout: int = 10) -> DebugSession:
    """
    Wait for an x64dbg session to start

    Args:
        session_pid: The session ID to wait for (debugger PID)
        timeout: The maximum time to wait in seconds

    Returns:
        The awaited debug session object
    """
    while timeout > 0:
        sessions = X64DbgClient.list_sessions()
        sessions = [s for s in sessions if s.pid == session_pid]
        if session_pid in [s.pid for s in sessions]:
            return sessions[0]
        time.sleep(0.2)
        timeout -= 0.2
    raise TimeoutError("Session did not appear in a reasonable amount of time")