Unicorn Emulator Debug Server - Written in Rust, with bindings of C, Go, Java and Python

Last update: Dec 27, 2022

Overview

udbserver - Unicorn Emulator Debug Server

When you do emulation with Unicorn Engine, do you want to inspect the inner state during every step?

udbserver is a plugin for Unicorn, provides a debug server which implements GDB Remote Serial Protocol. You can connect it by a GDB client and do debugging as what you do on real program.

udbserver can be used as a crate by Rust program, but it also provides a C library and bindings for other languages. You can use it inside most Unicorn based projects!

Features

Architectures support

i386
x86_64
ARM
AArch64
MIPS
PowerPC

Usage

API

udbserver only provides one API:

void udbserver(void* handle, uint16_t port, uint64_t start_addr);

The handle should be the raw handle of a Unicorn instance, port is the port to be listened, start_addr is the address which when Unicorn runs at the debug server will start and wait to be connected. if start_addr is provided with 0, the debug server will start instantly.

You can call this API inside a Unicorn hook, so you can integrate udbserver inside other Unicorn based project easily.

Used in Rust

You can use udbserver as a crate in Rust.

You can check the example on how to use it.

And you can try it by:

$ cargo run --example server

Then you can connect it with a GDB client.

Installation

udbserver provides a C-compatible set of library, header and pkg-config files, which help you to use it with other languages.

To build and install it you need to use cargo-c:

$ cargo install cargo-c
$ mkdir build
$ cargo cinstall --release --prefix=/usr --destdir build
$ sudo cp -a build/* /

Language bindings

After install the udbserver library, you can use udbserver in other languages.

You could check the examples on how to use udbserver by different languages:

Comments

[help] Please provide instructions to install on Windows

Hello,

I've been trying to install this server following the instructions.

But while installing I'm getting:

--- stderr
  thread 'main' panicked at 'Could not find system unicorn2: Could not run `"pkg-config" "--libs" "--cflags" "unicorn" "unicorn >= 2"`
  The pkg-config command could not be found.
  Most likely, you need to install a pkg-config package for your OS.
  If you've already installed it, ensure the pkg-config command is one of the
  directories in the PATH environment variable.
  If you did not expect this build to link to a pre-installed system library,
  then check documentation of the unicorn-engine crate for an option to
  build the library from source, or disable features or dependencies
  that require pkg-config.', C:\Users\runneradmin\.cargo\registry\src\github.com-1ecc6299db9ec823\unicorn-engine-2.0.0-rc7\bindings/rust/build.rs:115:14
  note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
warning: build failed, waiting for other jobs to finish...
Error: CliError { error: Some(1 job failed), exit_code: 101 }

How do I install unicorn engine for pkg-config?

opened by CypherpunkSamurai 22

Example panicking due to UnexpectedEof error

Hello,

Thank you very much for open sourcing this project, which I believe has the potential to radically improve the emulation experience with Unicorn. I followed all the provided steps to compile it (with the exception of removing "use_system_unicorn" from Cargo.toml, because I wanted a fresh installation). Unfortunately, when trying to connect to the example, it crashes as you can see below.

Steps to reproduce:

install udbserver without using the local installation of Unicorn
RUST_BACKTRACE=1 cargo run --example server
on another terminal, run gdb and then target remote :1234

On the first terminal, I see the following:

$ RUST_BACKTRACE=1 cargo run --example server
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
     Running `target/debug/examples/server`
Waiting for a GDB connection on "127.0.0.1:1234"...
Debugger connected from 127.0.0.1:37154
thread 'main' panicked at 'Failed to start udbserver: Error { kind: UnexpectedEof, message: "failed to fill whole buffer" }', src/lib.rs:46:60
stack backtrace:
   0: rust_begin_unwind
             at /rustc/a8314ef7d0ec7b75c336af2c9857bfaf43002bfc/library/std/src/panicking.rs:584:5
   1: core::panicking::panic_fmt
             at /rustc/a8314ef7d0ec7b75c336af2c9857bfaf43002bfc/library/core/src/panicking.rs:142:14
   2: core::result::unwrap_failed
             at /rustc/a8314ef7d0ec7b75c336af2c9857bfaf43002bfc/library/core/src/result.rs:1785:5
   3: core::result::Result<T,E>::expect
             at /rustc/a8314ef7d0ec7b75c336af2c9857bfaf43002bfc/library/core/src/result.rs:1035:23
   4: udbserver::udbserver::{{closure}}
             at ./src/lib.rs:46:13
   5: unicorn_engine::ffi::code_hook_proxy
             at /home/damiano/.cargo/registry/src/github.com-1ecc6299db9ec823/unicorn-engine-2.0.0-rc7/bindings/rust/src/ffi.rs:137:5
   6: helper_uc_tracecode
             at /home/damiano/.cargo/registry/src/github.com-1ecc6299db9ec823/unicorn-engine-2.0.0-rc7/uc.c:1718:14
   7: <unknown>
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.
fatal runtime error: failed to initiate panic, error 5
[1]    929611 abort (core dumped)  RUST_BACKTRACE=1 cargo run --example server

In gdb instead I get this:

$ target remote :1234
Remote debugging using :1234
warning: while parsing target description (at line 3): Target description specified unknown architecture "arm"
warning: Could not load XML target description; ignoring
warning: No executable has been specified and target does not support
determining executable automatically.  Try using the "file" command.
Truncated register 16 in remote 'g' packet

Am I doing anything wrong? I successfully reproduced the same issue following these steps in a VM with a fresh Linux installation, but let me know if I can provide anything further to help you debug this.

Thanks!

opened by dmell 5

Unable to build, error[E0658]

Trying to build a GDB server for use with Unicorn yields (on Ubuntu 22.04 x86_64): error[E0658]: use of unstable library feature 'scoped_threads'

$ rustc --explain E0658

If you're using a stable or a beta version of rustc, you won't be able to use
any unstable features. In order to do so, please switch to a nightly version of
rustc (by using [rustup]).

done. (I think)

If you're using a nightly version of rustc, just add the corresponding feature
to be able to use it:

#![feature(repr128)]
#[repr(u128)] // ok!
enum Foo {
    Bar(u64),
}

That's very nice but in what file does one do that, Cargo.toml? I gather I paste something, but not sure what. ...and yes, I'm trying to do this w/o becoming a Rust expert (at least not now).

Tried pasting this in to Cargo.toml (in the udbserver dir) but that didn't work (or I didn't paste it right).

Full result of "cargo install cargo-c" bellow:

tallen@timmy:~/Projects/udbserver$ cargo install cargo-c
    Updating crates.io index
  Installing cargo-c v0.9.14+cargo-0.66
   Compiling libc v0.2.137
   Compiling pkg-config v0.3.26
   Compiling proc-macro2 v1.0.47
   Compiling quote v1.0.21
   Compiling unicode-ident v1.0.5
   Compiling autocfg v1.1.0
   Compiling syn v1.0.103
   Compiling cfg-if v1.0.0
   Compiling serde_derive v1.0.147
   Compiling version_check v0.9.4
   Compiling serde v1.0.147
   Compiling log v0.4.17
   Compiling memchr v2.5.0
   Compiling crc32fast v1.3.2
   Compiling once_cell v1.16.0
   Compiling tinyvec_macros v0.1.0
   Compiling bitflags v1.3.2
   Compiling percent-encoding v2.2.0
   Compiling serde_json v1.0.87
   Compiling anyhow v1.0.66
   Compiling typenum v1.15.0
   Compiling unicode-bidi v0.3.8
   Compiling openssl-probe v0.1.5
   Compiling curl v0.4.44
   Compiling lazy_static v1.4.0
   Compiling hashbrown v0.12.3
   Compiling ryu v1.0.11
   Compiling openssl v0.10.42
   Compiling itoa v1.0.4
   Compiling regex-syntax v0.6.28
   Compiling regex-automata v0.1.10
   Compiling foreign-types-shared v0.1.1
   Compiling crossbeam-utils v0.8.12
   Compiling termcolor v1.1.3
   Compiling remove_dir_all v0.5.3
   Compiling heck v0.4.0
   Compiling fastrand v1.8.0
   Compiling os_str_bytes v6.4.0
   Compiling same-file v1.0.6
   Compiling fnv v1.0.7
   Compiling utf8parse v0.2.0
   Compiling semver v1.0.14
   Compiling rand_core v0.6.4
   Compiling static_assertions v1.1.0
   Compiling bytes v1.2.1
   Compiling strsim v0.10.0
   Compiling hex v0.3.2
   Compiling either v1.8.0
   Compiling textwrap v0.16.0
   Compiling arrayvec v0.5.2
   Compiling cbindgen v0.24.3
   Compiling shell-escape v0.1.5
   Compiling humantime v2.1.0
   Compiling hex v0.4.3
   Compiling pathdiff v0.2.1
   Compiling glob v0.3.0
   Compiling unicode-xid v0.2.4
   Compiling home v0.5.4
   Compiling rustc-workspace-hack v1.0.0
   Compiling bytesize v1.1.0
   Compiling unicode-width v0.1.10
   Compiling lazycell v1.3.0
   Compiling cc v1.0.76
   Compiling indexmap v1.9.1
   Compiling tinyvec v1.6.0
   Compiling proc-macro-error-attr v1.0.4
   Compiling proc-macro-error v1.0.4
   Compiling im-rc v15.1.0
   Compiling thread_local v1.1.4
   Compiling form_urlencoded v1.1.0
   Compiling foreign-types v0.3.2
   Compiling walkdir v2.3.2
   Compiling clap_lex v0.2.4
   Compiling kstring v2.0.0
   Compiling rand_xoshiro v0.6.0
   Compiling itertools v0.10.5
   Compiling unicode-normalization v0.1.22
   Compiling jobserver v0.1.25
   Compiling filetime v0.2.18
   Compiling socket2 v0.4.7
   Compiling atty v0.2.14
   Compiling tempfile v3.3.0
   Compiling aho-corasick v0.7.19
   Compiling bstr v0.2.17
   Compiling combine v4.6.6
   Compiling idna v0.3.0
   Compiling bitmaps v2.1.0
   Compiling tar v0.4.38
   Compiling vte_generate_state_changes v0.1.1
   Compiling regex v1.7.0
   Compiling opener v0.5.0
   Compiling url v2.3.1
   Compiling openssl-sys v0.9.77
   Compiling libz-sys v1.1.8
   Compiling libnghttp2-sys v0.1.7+1.45.0
   Compiling curl-sys v0.4.59+curl-7.86.0
   Compiling libssh2-sys v0.2.23
   Compiling libgit2-sys v0.14.0+1.5.0
   Compiling sized-chunks v0.6.5
   Compiling vte v0.10.1
   Compiling globset v0.4.9
   Compiling env_logger v0.9.3
   Compiling ignore v0.4.18
   Compiling strip-ansi-escapes v0.1.1
   Compiling flate2 v1.0.24
   Compiling openssl-macros v0.1.0
   Compiling clap_derive v3.2.18
   Compiling cargo v0.66.0
   Compiling clap v3.2.23
   Compiling crypto-hash v0.3.4
   Compiling cargo-util v0.2.2
   Compiling cargo-platform v0.1.2
   Compiling toml_edit v0.14.4
   Compiling toml v0.5.9
   Compiling os_info v3.5.1
   Compiling serde_ignored v0.1.5
   Compiling rustfix v0.6.1
   Compiling crates-io v0.34.0
   Compiling git2 v0.15.0
   Compiling git2-curl v0.16.0
error[E0658]: use of unstable library feature 'scoped_threads'
  --> /home/tallen/.cargo/registry/src/github.com-1ecc6299db9ec823/cargo-0.66.0/src/cargo/core/compiler/job_queue.rs:58:25
   |
58 | use std::thread::{self, Scope};
   |                         ^^^^^
   |
   = note: see issue #93203 <https://github.com/rust-lang/rust/issues/93203> for more information

error[E0658]: use of unstable library feature 'scoped_threads'
   --> /home/tallen/.cargo/registry/src/github.com-1ecc6299db9ec823/cargo-0.66.0/src/cargo/core/compiler/job_queue.rs:559:9
    |
559 |         thread::scope(
    |         ^^^^^^^^^^^^^
    |
    = note: see issue #93203 <https://github.com/rust-lang/rust/issues/93203> for more information

error[E0658]: use of unstable library feature 'scoped_threads'
   --> /home/tallen/.cargo/registry/src/github.com-1ecc6299db9ec823/cargo-0.66.0/src/cargo/core/compiler/job_queue.rs:573:20
    |
573 |         scope: &'s Scope<'s, '_>,
    |                    ^^^^^^^^^^^^^
    |
    = note: see issue #93203 <https://github.com/rust-lang/rust/issues/93203> for more information

error[E0658]: use of unstable library feature 'scoped_threads'
   --> /home/tallen/.cargo/registry/src/github.com-1ecc6299db9ec823/cargo-0.66.0/src/cargo/core/compiler/job_queue.rs:824:20
    |
824 |         scope: &'s Scope<'s, '_>,
    |                    ^^^^^^^^^^^^^
    |
    = note: see issue #93203 <https://github.com/rust-lang/rust/issues/93203> for more information

error[E0658]: use of unstable library feature 'scoped_threads'
    --> /home/tallen/.cargo/registry/src/github.com-1ecc6299db9ec823/cargo-0.66.0/src/cargo/core/compiler/job_queue.rs:1010:83
     |
1010 |     fn run<'s>(&mut self, unit: &Unit, job: Job, cx: &Context<'_, '_>, scope: &'s Scope<'s, '_>) {
     |                                                                                   ^^^^^^^^^^^^^
     |
     = note: see issue #93203 <https://github.com/rust-lang/rust/issues/93203> for more information

error[E0658]: use of unstable library feature 'scoped_threads'
    --> /home/tallen/.cargo/registry/src/github.com-1ecc6299db9ec823/cargo-0.66.0/src/cargo/core/compiler/job_queue.rs:1085:23
     |
1085 |                 scope.spawn(move || {
     |                       ^^^^^
     |
     = note: see issue #93203 <https://github.com/rust-lang/rust/issues/93203> for more information

For more information about this error, try `rustc --explain E0658`.
error: could not compile `cargo` due to 6 previous errors
warning: build failed, waiting for other jobs to finish...
error: failed to compile `cargo-c v0.9.14+cargo-0.66`, intermediate artifacts can be found at `/tmp/cargo-installMVsUot`

opened by tallenintegsys 2

Python binding: Segfault on Windows due to type mismatch

I compiled this library with mingw64 and it's segfaulting. unsigned long is 4 bytes on Windows, causing libpython to overwrite adjacent bytes on the stack when specifying K. I recommend using inttypes and uint64_t.

opened by Hendi48 1
java调用时提示错误

Exception in thread "main" java.lang.UnsatisfiedLinkError: udbserver.Udbserver.udbserver(JSJ)V at udbserver.Udbserver.udbserver(Native Method) at udbserver.Udbserver.Udbserver(Udbserver.java:12) at com.github.udbserver.Example.main(Example.java:19)

opened by heckerstone 0

[bug] Python Crashes when attaching udb to AndroidNativeEmu

So, I'm trying to use udbserver with AndroidNativeEmu (androidemu) on Windows, with Python 3.7.

I have the following code:

import logging
import posixpath
import sys

from unicorn import UcError, UC_HOOK_MEM_UNMAPPED, UC_HOOK_CODE, UC_HOOK_MEM_READ, UC_HOOK_MEM_WRITE
from unicorn.arm_const import *


import sys
sys.path.append("emulator") # Adds higher directory to python modules path.
# for loading changed module

from androidemu.emulator import Emulator
from androidemu.java.java_class_def import JavaClassDef
from androidemu.java.java_method_def import java_method_def

from udbserver import udbserver

# .............................. Code here ..................................

emulator.uc.hook_add(UC_HOOK_MEM_UNMAPPED, debug_utils.hook_unmapped)

# Register Java class.
emulator.java_classloader.add_class(EncryptorUtil)

# Load all libraries.
emulator.load_library("emulator/libdl.so")
emulator.load_library("emulator/libc.so")
emulator.load_library("emulator/libstdc++.so")
emulator.load_library("emulator/libm.so")

lib_module = emulator.load_library("emulator/libEncryptor.so")

# ......................... Code Here ........................
udbserver(emulator.uc, 1337, 0xcbbd2dec)

and Python crashes and stops working as soon as line udbserver(emulator.uc, 1337, 0xcbbd2dec) is run.

Is there any reason for this? also, what is 0xcbbd2dec here, am i supposed to use it according to my library?

opened by CypherpunkSamurai 9

mac m1下使用有问题

编译完成后执行sudo cp -a build/* / 失败，因为mac的新版本系统没有那个权限。然后我复制到了/usr/local/include 和 /usr/local/lib中。最后测试的时候报下面的错误 ImportError: dlopen(/Users/king/Library/Python/3.8/lib/python/site-packages/udbserver.cpython-38-darwin.so, 0x0002): symbol not found in flat namespace '_udbserver'
bug help wanted

opened by dqzg12300 3