apk-reverse/references/native-tamper-and-suicide.md

# Native Tamper Response — When the Library Kills Its Own Process

Load this when the process dies **without a Java stack trace**, when a build that passed every
static check crashes seconds after launch, or when you are about to neutralise a native check.

This file exists because of one specific, expensive mistake. Read §The rule before you edit a
single byte of a shell's native library.

## The rule

> **Never neutralise a terminate path by making it not return. Make it return.**

A terminate routine is reached from ordinary code paths. If you replace it with something that
**never returns** — an infinite loop, a self-branch, a stub that spins — the caller never resumes,
locks are never released, and every unrelated thread that touches those locks wedges. You have not
suppressed the check; you have frozen the process.

The distinction decides the outcome:

| Neutralisation | Effect on the caller | Result |
|---|---|---|
| `ret` / return a benign value | continues normally | check suppressed, process healthy |
| spin / self-branch / `while(1)` | never resumes | process freezes, watchdog or user kills it, symptom looks unrelated |

**Two failure shapes this produces, both of which have been misread as "the patch did not work":**

- The app hangs with no crash record at all, then disappears. Logs show nothing, because nothing
  crashed — it stopped.
- The watchdog or a system supervisor kills the frozen process, producing
  `Force stopping … from uid 0` or an app-restart loop. The uid-0 killer is a strong tell: an app
  cannot spawn a root-owned killer, so the executioner is **outside** the app, which means the app
  froze rather than failed.

Both are self-inflicted and both are avoided by returning instead of spinning.

### The corollary: do not touch normal-path symbols

A hardening library imports a lot of libc. Some of those symbols are terminate paths; most are not.

**Symbols that must stay untouched** — they are on ordinary code paths and freezing them breaks
everything:

`pthread_exit` · `exit` · `abort` · `android_set_abort_message` · `snprintf` · `closedir` ·
`__cxa_atexit` · `__stack_chk_fail`

A concrete case: a set of hand-made patches rewired five PLT stubs to self-branches on one
architecture and a different five on another. On the first architecture two of the five were
`snprintf` and `closedir` — a string formatter and a directory-close — so the app froze on the
first log line. On the second the five included `pthread_exit`, so every thread that finished
wedged. The patches were meant to suppress a suicide check and instead destroyed the process.

**Before touching a stub, resolve what symbol it belongs to.** Do not infer it from the stub's
position or from a comment. See §Resolving a stub to its symbol.

## How a hardened library terminates the process

Enumerate these before you patch anything. Each has a different signature and a different remedy.

| Mechanism | Log signature | Has tombstone? | How to neutralise |
|---|---|---|---|
| `kill(getpid(), SIGKILL)` | `Process N exited due to signal 9 (Killed)`, **no** exit code, **no** tombstone | no | patch the call site or make the `kill` stub return 0 |
| `exit()` / `_exit()` | process ends with an exit code, no signal | no | find the caller; usually one branch of a check |
| `abort()` | `signal 6 (SIGABRT)` + tombstone | yes | usually a genuine assertion — find what tripped it |
| **Deliberate crash** (see §Deliberate-crash stubs) | `signal 11 (SIGSEGV)`, tiny `fault addr` such as `0x4`, `Cause: null pointer dereference` | yes | nop the faulting store |
| `tgkill` / `raise` | same as kill/abort | varies | often not imported at all — check the import table before assuming |

**Distinguish these before patching.** "The app crashed" is not a diagnosis. The signal number and
the presence or absence of a tombstone split the space in half; getting this wrong sends you to the
wrong layer for hours.

### Deliberate-crash stubs

The most deceptive mechanism: the library does not call anything. It **arranges a fault** so the
death looks like an ordinary bug.

```asm
; arm64 shape observed in the wild
mov  x0, #4          ; load a small constant…
mov  w1, #1
str  w1, [x0]        ; …and use it as a pointer. fault addr = 0x4
```

Runtime shape: `SIGSEGV`, `SEGV_MAPERR`, `fault addr 0x4` (or `0x0`/`0x8`), `Cause: null pointer
dereference`, and — critically — **the register holding that small constant value**.

How to recognise it rather than treating it as a real bug:

1. The faulting address is a **small integer**, not a plausible pointer.
2. Disassembling backwards from the faulting `pc` shows the constant loaded **a few instructions
   earlier, in the same basic block**, with nothing in between that could produce a real pointer.
3. The block sits immediately before a function epilogue (canary check + `ret`), i.e. the normal
   exit is right there and this store is bolted on in front of it.
4. There is often a **delay loop just above it** — `sleep`/`usleep` repeated N times — because this
   is a *watchdog*: wait a while, then die if the condition still holds. That delay is why the crash
   is always "a little while after launch" rather than immediate.

**Neutralise it by nop-ing the faulting store**, leaving the surrounding arithmetic alone. The
thread then falls through into the epilogue and returns normally. Do not remove the whole block:
the two `mov`s are harmless and keeping them makes the diff minimal and reviewable.

**This is why patching `kill` alone is not enough.** A deliberate crash uses no imported symbol at
all, so every PLT-level fix — including a correctly implemented one — leaves it untouched.

### Find every instance, not the first one

Search the binary for the **byte pattern**, not with a linear disassembler. The exact encoding is
architecture-specific and must be derived from the crash you already have, then searched as bytes:

- Take the faulting `pc`, read the instruction bytes backwards until you have the full constant-then-
  store sequence.
- Search the whole file for that byte sequence.
- If the search returns more than one hit, patch each; if it returns exactly one, you have the
  complete set — record that fact, it is a real result.

A linear disassembler is the wrong tool here for a reason covered in §Scanner traps.

## Resolving a stub to its symbol

When a stub's target is a PLT entry, the symbol comes from the relocation table, **not** from the
stub's bytes or its neighbours. Two architectures encode this differently:

- **x86_64** — the stub is `jmp qword ptr [rip+disp32]` (6 bytes). The target address is
  `stub_addr + 6 + disp32`; look that address up in the PLT relocation map.
- **aarch64** — the stub is **four instructions / 16 bytes** (`adrp` → `ldr` → `add` → `br`). The
  GOT address is `page(adrp) + add_imm`. Do not assume a 4-byte stub: a 16-byte stub leaves room
  for a **two-instruction replacement** (`mov x0, #0` + `ret`), which is exactly what you need, and
  assuming 4 bytes pushes you into borrowing the neighbouring slot — which belongs to a different
  symbol and breaks it.

`scripts/elf_plt.py` does both architectures, including the relocation lookup.

**Never splice in a neighbouring stub's bytes.** Stubs are laid out back to back; the next one
along is a different function, and corrupting it produces a second, unrelated failure that you will
then spend hours attributing.

## Patching a terminate path correctly

Work in this order.

1. **Confirm the mechanism first.** Get the tombstone or the signal number. Do not patch on a
   guess about *how* it dies.
2. **Decide between call-site and stub.** Call sites are precise but you must find all of them.
   A stub covers every caller at once, including ones your scan missed — but it changes behaviour
   for every symbol user, so it is only safe when that symbol means "terminate" and nothing else.
3. **For a stub, return success, not failure.** Callers commonly inspect the return value. Returning
   **0** (success) lets the caller take its "already handled" branch; returning **-1** pushes it
   into an error path that may try a different termination method. Make the stub *succeed*.
4. **Preserve every byte you did not intend to change.** Record the original bytes so the patch is
   reversible and auditable.
5. **Re-verify the file after patching.** Length unchanged, only the intended offsets differ, and
   the normal-path symbols are byte-identical to the original. `scripts/elf_plt.py --diff` prints
   exactly that.

### What "faithful suppression" looks like

A library that decides "tampered" and then cannot terminate has an inconsistent state — it believes
it has killed the process and continues. That is **acceptable and usually harmless**, because the
terminate path is the end of the check; nothing downstream re-reads "did I die". But verify it
rather than assuming: after a successful suppression the app must reach its **normal UI and stay
there**, not loop through half-initialised states.

## ELF hardening you will meet in these targets

Hardening libraries are not normal ELF files. Assume the following until measured otherwise.

### Forged section headers

A shell may ship a library whose section header table is deliberately wrong — `.text` sized to a
handful of bytes, `.dynsym` truncated, sections overlapping. Tools that walk sections therefore
produce **confidently wrong** answers (a symbol list with one entry, an import table that is empty).

**Work from the program headers instead.** `PT_LOAD` gives you the real mapped segments and their
permissions; `PT_DYNAMIC` gives you the pointers you need, walked by hand:

```
DT_STRTAB(5)  DT_SYMTAB(6)  DT_STRSZ(10)  DT_SYMENT(11)
DT_JMPREL(23) DT_PLTRELSZ(2) DT_PLTREL(20) DT_PLTGOT(3)
```

Then translate any virtual address to a file offset through the `PT_LOAD` that contains it. A
library with forged sections that yields a full import list this way is a good sign; one that
still yields almost nothing means the hardening is deeper and you should say so rather than
reporting the truncated result as the truth.

### Function boundaries come from `PT_GNU_EH_FRAME`, not from prologue guessing

You will need "where does this function start". Two bad answers and one good one:

- **Reverse-decoding backwards from a call site does not work on aarch64.** Almost any 4-byte
  window decodes as *some* instruction, so a naive scanner reports hundreds of "function starts"
  that are all fiction.
- **Guessing at prologues** (`sub sp, sp, #imm` + `stp`) produces a plausible set with no guarantee
  of completeness.
- **`PT_GNU_EH_FRAME` is authoritative.** If the segment survives (it usually does, because
  unwinding is needed at runtime), parsing it yields the real function entry table — every entry,
  exactly. It is several lines of code and it removes an entire class of wrong conclusions.

**Check for it first.** If it is present, use it; if it is absent, say your boundary list is
heuristic.

### A function's entry is not where its logic is

Callers reach a routine through several routes: a direct branch, a cached table slot, or a function
pointer in writable data. Rewriting the entry point only covers the first. If a call resolves
through a cached pointer, your entry-point change is invisible to it — so before patching an entry,
scan for the other routes (`scripts/elf_plt.py`, or a byte-pattern scan for the address).

## Scanner traps

**A linear disassembler can stop silently.** Given a buffer whose start is not code, a decoder may
return a handful of instructions and then nothing, with no error. Concluding "there are no such
call sites in this library" from that output is a false negative with real consequences.

Guards, in order of preference:

1. **Byte-pattern search** for a sequence you already know (from a crash or a known call site).
   Fast, exhaustive, no decoder involved.
2. **Fixed-bit-pattern scans** for instruction classes whose encoding is regular — the branch
   instructions are the useful ones here (`BL`/`B` on aarch64, `call rel32` on x86_64). This finds
   every call site without depending on linear decoding.
3. **Resynchronising scan** — decode, and on failure advance by one instruction unit (4 bytes on
   fixed-width aarch64, 1 byte on x86_64) and retry. Slower, but it does not stop early.

Whichever you use, **state which one you used and what it can miss**. "No hits" from a scan whose
coverage you cannot describe is not evidence.

## Deciding whether a dynamic-resolution path matters

Hardening libraries frequently build a table of function pointers with `dlopen` + `dlsym` — often
40+ symbols including terminate calls. This raises an obvious worry: *a call through that table
bypasses the PLT stub, so my stub patch does nothing.*

**Measure it instead of assuming either way.** For each symbol of interest, find whether its table
slot is ever **read**:

- Locate the slot's address (the store from the `dlsym` return, or the table base + index).
- Search the code for instructions that load from that address (`adrp`+`add`+`ldr` on aarch64).
- **Zero readers means the entry is written and never used.** The table is a redundant fast path,
  not a bypass, and PLT-level patching is complete.

Real outcome from a hardened target: the `kill` slot had **zero** readers while the `exit` slot had
exactly one, inside a routine that was already suppressed — so no dynamic-resolution bypass existed
at all, and the expensive "patch `dlsym` itself" plan would have broken 40 unrelated symbols for
nothing.

**Do not blanket-patch a symbol resolver.** It feeds `open`, `read`, `mmap`, `dlopen` and more.
Changing its behaviour to reach one terminate symbol is a large blast radius for a problem you may
not have.

## Verification

A native suppression earns no credit until:

1. The process **survives the window in which it used to die** — and that window must be measured,
   not guessed. If the observed death was ~40 s after launch, a 30-second test proves nothing.
2. It then **keeps surviving** through real interaction, not just idling.
3. `crash`/`tombstone` buffers are clean, **and** the process id never changed (a restart with a new
   pid is a death even when nothing logged a crash).
4. The normal-path symbols are byte-identical to the original build.
5. A **control build** — same pipeline, no native patch — still dies the same way. Without the
   control you cannot tell suppression from an unrelated change in timing.

**Record the observed time-to-death before patching.** It is the only thing that later tells you
whether your patch worked or merely moved the window.