https://github.com/woodruffw/upgrayedd

Ergonomic function interposition in Rust
https://github.com/woodruffw/upgrayedd

instrumentation ld-preload

Last synced: about 1 month ago
JSON representation

Ergonomic function interposition in Rust

• Host: GitHub
• URL: https://github.com/woodruffw/upgrayedd
• Owner: woodruffw
• Created: 2023-11-12T21:30:19.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2024-03-11T21:17:27.000Z (11 months ago)
• Last Synced: 2025-01-05T11:31:27.626Z (about 1 month ago)
• Topics: instrumentation, ld-preload
• Language: Rust
• Homepage: https://crates.io/crates/upgrayedd
• Size: 22.5 KB
• Stars: 15
• Watchers: 3
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# upgrayedd

[*"Two Ds for a double dose of debugging."*](https://www.youtube.com/watch?v=Gf9i23KPGKk)

[![CI](https://github.com/woodruffw/upgrayedd/actions/workflows/ci.yml/badge.svg)](https://github.com/woodruffw/upgrayedd/actions/workflows/ci.yml)

[![Crates.io](https://img.shields.io/crates/v/upgrayedd)](https://crates.io/crates/upgrayedd)

> [!WARNING]

> You do not need this library. Do not use this library, especially in production

> systems. It is **not safe**, *even if* you only use safe Rust with it.

> It **cannot** be made safe.

`upgrayedd` is a convenience proc macro for building function interposition

tools in Rust. When used in a shared library build (which is the only

way you should be using it), it makes `LD_PRELOAD`-style interposition

look like (relatively) idiomatic Rust.

## Usage

Interposing on an OpenSSL API:

```rust,no_run

use upgrayedd::upgrayedd;

#[upgrayedd]

fn X509_VERIFY_PARAM_set_auth_level(param: *mut std::ffi::c_void, level: std::ffi::c_int) {

    eprintln!("before!");

    unsafe { upgrayedd(param, level) };

    eprintln!("after!");

}

```

Rewriting parameters:

```rust

use upgrayedd::upgrayedd;

#[upgrayedd]

fn frobulate(size: libc::size_t) {

    unsafe { upgrayedd(size + 42) };

}

```

Stubbing functions out:

```rust

use upgrayedd::upgrayedd;

#[upgrayedd]

fn verify_cert(cert: *mut std::ffi::c_void) -> libc::c_int {

    // nothing to see here

    1

}

```

See the [docs] for more usage examples.

[docs]: https://docs.rs/upgrayedd

## Limitations

* Fundamentally unsafe. Again: please do not use this for anything serious.

* Hooking "basic" routines (like `malloc` and `free`) may or may not work,

  depending on what you put in your hook. In particular, if you accidentally

  recurse while holding a lock (which is easy to do when hooking `malloc`

  and calling `println!`), you'll probably end up deadlocking.

* Bad things will definitely happen if you try to pass Rust types into

  wrapped C functions, which `upgrayedd` will happily let you do.

* Bad things will definitely happen if you supply the wrong function

  signature, which `upgrayedd` will happily let you do.

* Only C functions can currently be wrapped; C++ would probably work with small

  tweaks.

* Currently Linux only. Other OSes would probably work with small tweaks.