docs: add classic injection case folder with runnable hook sample

Author: YinMo19

.gitignore

@@ -1 +1,11 @@
 /target
+.DS_Store
+
+# Example workspace outputs
+/examples/**/target/
+/examples/**/Cargo.lock
+
+# classic-tight-headerpad-case runtime artifacts
+/examples/classic-tight-headerpad-case/calc_*
+/examples/classic-tight-headerpad-case/*.dylib
+/examples/classic-tight-headerpad-case/calc_bin

README.cn.md

@@ -48,6 +48,8 @@ insert-dylib [options] <dylib_path> <binary_path> [new_binary_path]
 
 ## 示例
 
+更多案例见 [`examples/`](./examples/README.md)。
+
 注入 dylib，输出到默认文件：
 
 ```bash

README.md

@@ -48,6 +48,8 @@ If `new_binary_path` is omitted (and `--inplace` is not used), output defaults t
 
 ## Examples
 
+More case studies are in [`examples/`](./examples/README.md).
+
 Inject a dylib and write to default output:
 
 ```bash

examples/README.md

@@ -0,0 +1,3 @@
+# Examples
+
+- [Classic case folder: tight headerpad on `calc`](./classic-tight-headerpad-case/)

examples/classic-tight-headerpad-case/README.md

@@ -0,0 +1,106 @@
+# Classic `calc` Injection Case (Tight Headerpad)
+
+This folder is a reproducible failure/success comparison for Mach-O dylib injection:
+
+- The target binary (`calc`) has very limited header padding (about 32 bytes).
+- Injecting a long dylib path can corrupt the binary after re-signing.
+- Injecting a short dylib path with the right flags can persist the hook safely.
+
+## Directory Layout
+
+- `calc/calc.c`: target program source
+- `hook/`: Rust hook payload project (`sighook` based)
+
+## Prerequisites
+
+- macOS aarch64 (Apple Silicon)
+- `codesign` available in your environment
+
+## Build and Run (Step-by-Step)
+
+Run from repository root:
+
+```bash
+# 1) Build insert-dylib
+cargo build --release
+
+# 2) Enter this example folder
+cd examples/classic-tight-headerpad-case
+
+# 3) Build the target binary
+cc -O2 -fno-inline calc/calc.c -o calc_bin
+
+# 4) Build the hook dylib
+cargo build --release --manifest-path hook/Cargo.toml
+```
+
+### Baseline Check (`DYLD_INSERT_LIBRARIES`)
+
+```bash
+DYLD_INSERT_LIBRARIES="$PWD/hook/target/release/libclassic_hook.dylib" ./calc_bin
+```
+
+Expected output:
+
+```text
+[+] hooked: now x0 is 99.
+Result: 99
+```
+
+## Failure Repro (Long Dylib Name)
+
+Use a longer filename such as `libh.dylib`:
+
+```bash
+cp hook/target/release/libclassic_hook.dylib libh.dylib
+../../target/release/insert-dylib libh.dylib calc_bin calc_bad
+codesign -f -s - ./calc_bad
+./calc_bad
+```
+
+Common symptom:
+
+- Process exits unexpectedly and does not print the expected final result line.
+
+## Success Repro (Short Dylib Name)
+
+Use a short filename such as `h.dylib`:
+
+```bash
+cp hook/target/release/libclassic_hook.dylib h.dylib
+../../target/release/insert-dylib --no-strip-codesig h.dylib calc_bin calc_ok
+codesign -f -s - ./calc_ok
+./calc_ok
+```
+
+Expected output:
+
+```text
+[+] hooked: now x0 is 99.
+Result: 99
+```
+
+## Why This Happens
+
+For `LC_LOAD_DYLIB`, command size is:
+
+- `cmdsize = 24 + align8(path_len + 1)`
+
+Where:
+
+- `24` is the fixed size of `struct dylib_command`
+- `path_len + 1` includes the trailing `\0`
+
+In this case:
+
+- available header space is about 32 bytes
+- `libh.dylib` needs 40 bytes (overflow)
+- `h.dylib` needs 32 bytes (fits exactly)
+
+That is why long path injection fails while short path injection succeeds.
+
+## Practical Notes
+
+- When header padding is tight, prefer short install names.
+- In this case, prefer `--no-strip-codesig`.
+- If you can rebuild the target, add `-Wl,-headerpad_max_install_names`.

examples/classic-tight-headerpad-case/calc/calc.c

@@ -0,0 +1,13 @@
+#include <stdio.h>
+
+// no inline
+__attribute__((noinline)) int calculate(int a, int b) {
+  int result = a + b;
+  return result;
+}
+
+int main(void) {
+  int result = calculate(3, 66);
+  printf("Result: %d\n", result);
+  return 0;
+}

examples/classic-tight-headerpad-case/hook/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "classic_hook"
+version = "0.1.0"
+edition = "2024"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+libc = "0.2"
+sighook = "0.4.0"

examples/classic-tight-headerpad-case/hook/src/lib.rs

@@ -0,0 +1,33 @@
+use sighook::{HookContext, instrument_no_original};
+
+const ADD_INSN_OFFSET: u64 = 0;
+const LOG_MSG: &[u8] = b"[+] hooked: now x0 is 99.\n";
+
+extern "C" fn replace_logic(_address: u64, ctx: *mut HookContext) {
+    unsafe {
+        let _ = libc::write(
+            libc::STDERR_FILENO,
+            LOG_MSG.as_ptr() as *const libc::c_void,
+            LOG_MSG.len(),
+        );
+        (*ctx).regs.named.x0 = 99;
+    }
+}
+
+#[used]
+#[unsafe(link_section = "__DATA,__mod_init_func")]
+static INIT_ARRAY: extern "C" fn() = init;
+
+extern "C" fn init() {
+    unsafe {
+        let target_address = {
+            let symbol = libc::dlsym(libc::RTLD_DEFAULT, c"calculate".as_ptr());
+            if symbol.is_null() {
+                return;
+            }
+            symbol as u64 + ADD_INSN_OFFSET
+        };
+
+        let _ = instrument_no_original(target_address, replace_logic);
+    }
+}