BOASan

BOASan is a research prototype for Binary Object-Aware AddressSanitizer. It targets x86-64 Linux ELF binaries when source code is not available and detects a class of intra-object overflows that ordinary object-boundary AddressSanitizer checks may miss.

Traditional ASan catches accesses that cross allocation, stack, or global object boundaries. BOASan instead recovers sanitizer-oriented field ranges from binary evidence and checks high-confidence field-sensitive accesses, such as an indexed write from one struct field into the next field.

struct Packet {
    char header[16];
    int flag;
};

int main(void) {
    struct Packet *p = malloc(sizeof(struct Packet));
    p->header[20] = 'A';   /* corrupts flag but stays inside Packet */
    free(p);
}

What Is Included

This public repository contains the BOASan prototype, runtime, tests, synthetic/CVE-derived harnesses, exact-replay harnesses, and lightweight result summaries. It intentionally does not include paper drafts or manuscript text.

Main components:

• boasan/: Python binary analysis pipeline and backend generators.
• runtime/: C runtime checks and preload/trap support.
• scripts/: experiment, E9Patch, exact-replay, and helper scripts.
• tests/: unit tests and synthetic intra-object examples.
• datasets/: small CVE-derived and exact-function replay harnesses.
• results/remote-2026-06-11/: lightweight E9Patch v7 result summaries.

Dependencies

Required:

• Linux x86-64 for binary analysis and runtime experiments.
• Python 3.10 or newer.
• capstone
• pyelftools
• networkx
• gcc or clang
• cmake for the C runtime build.

Development/test dependencies:

• pytest

Optional:

• E9Patch / e9tool / e9compile.sh for executable call-helper binary rewriting.
• A Juliet/SARD C/C++ test-suite checkout for Juliet curation experiments.

The most recent remote E9Patch validation used:

• Python 3.14.4
• capstone==5.0.9
• pyelftools==0.33
• networkx==3.6.1
• pytest==9.0.3
• gcc (Ubuntu 15.2.0-16ubuntu1)
• E9Tool 1.0.0

Installation

git clone https://github.com/YunlongXing/BOASan.git
cd BOASan

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements-lock.txt
pip install -e ".[dev]"

Build the runtime:

./scripts/build_runtime.sh

Run unit tests:

./scripts/reproduce_unit.sh

For a self-contained artifact walkthrough, see ARTIFACT.md. The repository also includes a Dockerfile, a pinned requirements-lock.txt, GitHub Actions unit-test CI, summary-result hashes in results/remote-2026-06-11/SHA256SUMS, and reproduction helpers:

• scripts/reproduce_unit.sh
• scripts/reproduce_synthetic.sh
• scripts/reproduce_e9patch_v7_matrix.sh
• scripts/reproduce_target24.sh

Quick Start

Build the synthetic examples:

make -C tests/synthetic

Run the full BOASan analysis pipeline:

boasan analyze tests/synthetic/intra_object_1 --out out/intra_object_1
boasan report out/intra_object_1

Generate an instrumentation plan:

boasan instrument-plan tests/synthetic/intra_object_1 --out out/intra_object_1

Run the synthetic benchmark driver:

boasan run-synthetic

E9Patch Backend

BOASan includes an executable E9Patch call-helper backend. For supported indexed and bulk/string helper sites, BOASan emits address-specific e9tool rules plus helper code compiled by e9compile.sh. The patched binaries run without LD_PRELOAD.

Example exact-replay batch:

bash scripts/run_e9patch_exact_replay_batch.sh \
  /path/to/exact-replay-matrix/runs/o0_nopie_unstripped \
  out/e9patch-o0 \
  --include-bulk

Full matrix driver:

bash scripts/run_e9patch_backend_matrix.sh \
  /path/to/exact-replay-matrix/runs \
  out/e9patch-backend-matrix-v7

Diagnose matrix outcomes:

boasan e9-diagnose \
  --matrix-dir out/e9patch-backend-matrix-v7 \
  --out out/e9patch-diagnosis-v7

Highlight Results

The strongest current executable-backend result is the E9Patch v7 exact-replay matrix over 12 binary configurations:

• Optimization levels: O0, O1, O2
• PIE and non-PIE
• stripped and unstripped
• 15 safe/overflow trigger variants across 7 CVEs
• 180 total case/configuration rows

Matrix	Rows	Supported	Patched	TP	FN	FP	TN
E9Patch v7 exact replay	180	180	180	96	0	0	84

The final root-cause export contains zero non-TP/TN rows, and the final miss-priority export contains zero remaining miss buckets.

The optimized helper-site recovery pass specifically closed the previous 24 unsupported E9Patch rows:

Recovery	Rows	Pos	Neg	Effect
Advanced heap-argument indexed recovery	16	8	8	Recovers optimized PDFium array-of-struct helper sites.
Initialization-based prefix field repair	8	4	4	Recovers optimized OpenSSL bulk-loop field sizes.
Total	24	12	12	Converts all remaining misses into patched TP/TN rows.

The lightweight result summaries are in:

• results/remote-2026-06-11/e9patch-backend-matrix-v7-helper-site/
• results/remote-2026-06-11/e9patch-backend-matrix-v7-helper-site-tight/
• results/remote-2026-06-11/e9patch-target-helper-site-v7/
• results/remote-2026-06-11/e9patch-root-causes-v7-helper-site/
• results/remote-2026-06-11/e9patch-miss-priorities-v7-helper-site/

Scope and Limitations

BOASan is a research prototype, not a complete memory-safety system.

Current scope:

• x86-64 Linux ELF binaries.
• Heap object and field recovery first.
• High-confidence indexed and bulk/string field checks.
• Executable E9Patch call-helper backend for selected recovered helper sites.

Out of scope for this prototype:

• Full C/C++ type reconstruction.
• Complete spatial or temporal memory safety.
• Arbitrary optimized-code recovery.
• Full-product exploit replay for every CVE-derived harness.

The key design choice is to recover only the field ranges needed for sanitizer-oriented checks, rather than reconstructing full source-level types.