pai

Process Analyzer and Instrumenter

• Documentation
• Crate

Recommended way to include the crate, even though API is not expected to be stable until version 0.2.0, is:

pai = { version = "0.1", features = ["syscalls"] }

The feature syscalls is only needed if you want to resolve the arguments of system calls. So if you want to resolve the system call number to a name, an argument to strings, etc.

There are some example of use under examples/ more information will be written when the API is more stable.

Standalone tools using pai

• pai-strace - strace-like tool
• pai-inject-so - inject SO-file into process

Compilation

A regular build for native can be compiled with:

cargo build --all-features

Cross-compilation

The recommended way to cross-compile is to use cross

This is setup in Makefile.toml, so you can build for all desired targets with:

cargo make build i686-unknown-linux-gnu x86_64-unknown-linux-gnu ...

Build output from cross will sometimes interfere with build output from cargo so all cross builds will go to directory output/, leaving target/ for regular cargo commands.

Builds will then work as expected, but most test-targets will fail because the testing method used doesn't support ptrace.

To run cross-architecture tests correctly see testing.md

Targets tested

We don't want to test all cross-combination of builds, but try to test all platforms supported and all architectures supported.

• platforms: GNU, Android, Musl
• architectures: x86_64, x86, Aarch64, Aarch32

The Makefile.toml target fulltest is executed before new versions are published.

Known issues

• PTRACE_SINGLESTEP is not working correctly on Aarch32 or Riscv64. This is a deliberate limitation of Aarch32, I'm unsure if the same is the case for Riscv64.
  • As a workaround, we insert a new breakpoint after the instruction to simulate a single-step.
  • This workaround is obviously flawed as the next instruction may be a branch. This is currently not detected and the step would then be missed completely.
  • This bug may appear even if you don't use single-stepping since single-stepping is used internally in those cases we need to redo something on the next instruction, like re-inserting a breakppoint.

Known cross-compilation issues

• mips-unknown-linux-musl
  • Presumably also for other mips targets
  • https://github.com/rust-lang/rust/issues/108835#issuecomment-1636983993
  • Build with: RUSTFLAGS='-C opt-level=1' cargo build -Zbuild-std=std --target mips-unknown-linux-musl