SanCOTS is a binary-level ASan check optimization artifact built on top of HexHive Retrowrite, with additional backend adapters for e9patch and Egalito. The goal is not to lift binaries to LLVM IR. SanCOTS selects explicit x86-64 register-derived memory dereference sites, inserts ASan checks, tracks the checked memory location conservatively, and removes redundant checks with sound-first dataflow rules.
The current artifact supports:
- Retrowrite reassemblable-assembly backend for optimized ASan instrumentation.
- e9patch direct binary patching backend using ASan trampoline calls.
- Experimental native Egalito ASan insertion backend.
- CPU2006 and common-binary benchmark scripts plus aggregate result tables.
This repository does not include SPEC CPU2006 itself. SPEC CPU is commercial software; the artifact only includes aggregate result CSV/JSON/Markdown files. To reproduce SPEC experiments, provide your own licensed SPEC CPU2006 media.
rwtools_x64/asan/: SanCOTS x86-64 check-site policy, metadata, check graph, dataflow elimination, and deletion logic for the Retrowrite backend.sancots/: backend-neutral SanCOTS helpers and backend adapters.sancots/backends/e9patch.py: e9patch trampoline backend.sancots/backends/egalito.py: Egalito command/native-pass backend adapter.tools/egalito/: native Egalito ASan pass harness and smoke tests.tools/spec/andtools/spec2006_sancots_full.py: CPU2006 automation.artifacts/results/: aggregate experiment results, with no SPEC CPU source, inputs, binaries, or ISO/ZIP files.docs/asan_opt.md: detailed SanCOTS design and usage notes.
SanCOTS is x86-64 first. The Retrowrite backend currently inherits Retrowrite's x64 input restrictions: binaries should be PIE and non-stripped for reliable symbolization.
Base requirements:
- Linux x86-64.
- Python 3 with
venvsupport. gcc,g++,binutils,make.- libasan from GCC or Clang.
- Python packages from
requirements.txt(pyelftools,capstone, etc.).
Optional backend requirements:
- e9patch backend: a built checkout of
GJDuck/e9patch, especially
e9toolande9compile.sh. - Egalito backend: a built checkout of Egalito plus the compatibility patches
in
tools/egalito/patchesif needed by your toolchain. - SPEC CPU2006 reproduction: a separately licensed SPEC CPU2006 distribution. Do not commit or redistribute SPEC sources, inputs, binaries, or archives.
Create a virtual environment and install the Python dependencies:
git clone <anonymous-artifact-repository-url>
cd SanCOTS
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .Build a small PIE/non-stripped test binary:
cat > /tmp/sancots_smoke.c <<'EOF'
#include <stdlib.h>
#include <stdio.h>
int main(void) {
int *p = malloc(4 * sizeof(int));
p[0] = 1;
p[1] = p[0] + 1;
printf("%d\n", p[1]);
free(p);
return 0;
}
EOF
gcc -O0 -g -fPIE -pie -fno-omit-frame-pointer \
-fno-stack-protector /tmp/sancots_smoke.c -o /tmp/sancots_smokeRun the Retrowrite backend:
python3 ./retrowrite --asan-opt /tmp/sancots_smoke /tmp/sancots_smoke.s
gcc /tmp/sancots_smoke.s -lasan -o /tmp/sancots_smoke.sancots
/tmp/sancots_smoke.sancotsRun a dry run with metadata:
python3 ./retrowrite --asan-opt --asan-opt-dry-run \
--asan-opt-dump-json /tmp/sancots_smoke.opt.json \
/tmp/sancots_smoke /tmp/sancots_smoke.sRun the e9patch backend when e9patch is installed:
python3 ./retrowrite --asan-opt --sancots-backend=e9patch \
--sancots-e9tool=/path/to/e9patch/e9tool \
--sancots-e9compile=/path/to/e9patch/e9compile.sh \
--sancots-workdir=/tmp/sancots_e9_work \
/tmp/sancots_smoke /tmp/sancots_smoke.e9
LD_PRELOAD=$(gcc -print-file-name=libasan.so) /tmp/sancots_smoke.e9Build and smoke-test the Egalito native ASan app:
python3 tools/egalito/run_sancots_asan_smoke.py \
--egalito-root /path/to/egalito \
--sancots-asan /tmp/sancots_asan \
--build-app \
--workdir /tmp/sancots_egalito_smoke \
--iterations 3Common Linux utility experiments can be reproduced with the scripts and command
patterns documented in docs/asan_opt.md. Inputs should be rebuilt from source
as non-stripped PIE binaries for Retrowrite compatibility.
CPU2006 automation is in tools/spec/ and tools/spec2006_sancots_full.py.
Provide your own licensed SPEC CPU2006 archive/media on the evaluation machine.
The repository contains only aggregate results under artifacts/results/.
The current artifact results are in artifacts/results/.
SanCOTS was evaluated on a CPU2006 run using the Retrowrite backend. On the paired rewrite-success subset including the two specrand executables:
- Retrowrite-ASan checks: 1,413,704.
- SanCOTS checks: 188,909.
- Weighted check reduction: 86.64%.
- Paired runtime-success subset: 19/31.
- Retrowrite-ASan average overhead: 3.35x.
- SanCOTS average overhead: 1.42x.
- SanCOTS versus Retrowrite-ASan average speedup: 2.59x.
Compared with ASAN-- on paired CPU2006 benchmarks:
- Weighted check reduction: ASAN-- 33.86%, SanCOTS 86.19%.
- Geometric overhead versus native: ASAN-- 1.74x, SanCOTS 1.32x.
- Geometric speedup versus each tool's ASan baseline: ASAN-- 1.06x, SanCOTS 2.58x.
ASAN-- and SanCOTS operate at different layers, so raw check counts are not directly equivalent. The artifact reports both raw counts and normalized reduction/overhead metrics.
For 31 source-built non-stripped PIE utilities (readelf, bzip2, file,
bsdtar, pngfix, tiff2rgba, tcpdump, bash, curl, find, ls, mv,
ping, wget, and others):
- Retrowrite-ASan checks: 524,708.
- SanCOTS Retrowrite-backend checks: 84,333.
- Weighted check reduction: 83.93%.
- SanCOTS assembly linked for 31/31 utilities.
Backend stress-test results over the same 31 utilities:
- e9patch backend: 31/31 rewrite success, 84,332/84,332 selected sites patched, 28/31 lightweight workloads returned successfully.
- Egalito backend: 31/31 baseline and optimized binaries generated, 510,586 checks reduced to 381,614 checks (25.26% reduction), with 8/31 lightweight workloads currently running successfully.
These common-binary numbers are best read as backend feasibility and robustness results. SPEC CPU2006 provides the stronger current runtime trend.
SanCOTS is based on Retrowrite. The original Retrowrite overview follows.
Retrowrite is a static binary rewriter for x64 and aarch64. It works without heuristics, does not introduce overhead and uses the symbolization technique (also known as reassemblable assembly) to insert instrumentation to binaries without the need for source code.
Please note that the x64 version and the arm64 version use different rewriting algorithms and support a different set of features.
For technical details, see the upstream Retrowrite publication and documentation referenced by the original project.
KRetrowrite is a variant of the x64 version that supports the rewriting of Linux kernel modules.
Retrowrite is implemented in python3 (3.6). It depends on pyelftools and capstone.
To install the dependencies, please run:
pip install -r requirements.txtIt is not recommended to install the dependencies from your distro's package managers, as they might be outdated.
| retrowrite-x64 | retrowrite-aarch64 | |
|---|---|---|
| stripped binaries | ❌ (WIP) | ✅ |
| Non-PIE binaries | ❌ | ✅ |
| Non-standard compilers | ❌ | ✅ |
| Zero overhead | ✅ | ✅ |
| Kernel modules support | ✅ | ❌ |
| AFL-coverage instrumentation | ✅ | ✅ |
| ASan instrumentation | ✅ | ✅ |
| C++ support | ❌ (WIP) | ❌ (WIP) |
(retro) $ retrowrite --help
usage: retrowrite [-h] [-a] [-A] [-m MODULE] [-k] [--kcov] [-c] [--ignore-no-pie] [--ignore-stripped] [-v] bin outfile
positional arguments:
bin Input binary to load
outfile Symbolized ASM output
optional arguments:
-h, --help show this help message and exit
-a, --assemble Assemble instrumented assembly file into instrumented binary
-A, --asan Add binary address sanitizer instrumentation
-m MODULE, --module MODULE
Use specified instrumentation pass/module in rwtools directory
-k, --kernel Instrument a kernel module
--kcov Instrument the kernel module with kcov
-c, --cache Save/load register analysis cache (only used with --asan)
--ignore-no-pie Ignore position-independent-executable check (use with caution)
--ignore-stripped Ignore stripped executable check (use with caution)
-v, --verbose Verbose outputSelect the instrumentation pass you would like to apply with retrowrite -m <pass>
You can find the available instrumentation passes in folders rwtools_x64 and rwtools_arm64.
Available instrumentation passes for x64: - AddressSanitizer - AFL-coverage information
Available instrumentation passes for aarch64: - AddressSanitizer - AFL-coverage information + forkserver - Coarse grained control flow integrity on function entries
retrowrite --asan </path/to/binary/> </path/to/output/binary>
Note: If on x64, make sure that the binary is position-independent and is not stripped.
This can be checked using file command (the output should say ELF shared object).
SanCOTS adds an optimized x86-64 ASan pipeline with redundant check removal:
retrowrite --asan-opt </path/to/binary/> </path/to/output.s>.
SanCOTS instruments register-derived dereference operands such as (%rax) and
8(%rax), skips direct stack/global operands such as -0x20(%rbp) and
global(%rip), emits load or store checks according to operand access, rewrites
supported heap allocator calls to libasan interceptors, and then removes
redundant checks conservatively. See
docs/asan_opt.md for flags, fallback rules, and current limitations. The
Retrowrite backend emits optimized reassemblable assembly, the e9patch backend
emits direct trampoline patching commands, and the Egalito backend provides
patched mirror-generation planning plus an experimental native x86-64 ASan
insertion app.
SanCOTS also includes a Retrowrite x86-64 free-register analysis scalability patch: register read/write transfer functions are computed once per instruction and solved with a predecessor worklist instead of repeated full-function scans. This preserves Retrowrite's conservative free-register semantics while avoiding ASan rewriting timeouts on SPEC CPU binaries.
Example, create an instrumented version of /bin/ls:
retrowrite --asan /bin/ls ls-basan-instrumented.s
This will generate an assembly (.s) file.
To recompile the assembly back into a binary, it depends on the architecture:
The generated assembly can be assembled and linked using any compiler, like:
gcc ls-basan-instrumented.s -lasan -o ls-basan-instrumented
debug in case you get the error undefined reference to `__asan_init_v4' ,
replace "asan_init_v4" by "asan_init" in the assembly file, the following command can help you do that:
sed -i 's/asan_init_v4/asan_init/g' ls-basan-instrumented.s
On aarch64, we also rely on standard compilers to assemble and link but the collection of compiler
flags is slightly more involved and so we provide the -a switch on the main retrowrite
executable to do that for you:
retrowrite -a ls-basan-instrumented.s -lasan -o ls-basan-instrumented
To generate an AFL-instrumented binary, first generate the symbolized assembly
as described above. Then, recompile the symbolized assembly with afl-gcc from
afl++ like this:
$ AFL_AS_FORCE_INSTRUMENT=1 afl-gcc foo.s -o foo
or afl-clang.
To instrument a binary with coverage information, use the coverage instrumentation pass
with retrowrite -m coverage <input file> <output asm>. Re-assemble the binary
with retrowrite -a <output asm> <new binary>.
The binary can now be fuzzed with:
afl-fuzz -i <seed folder> -o <out folder> <new binary>Retrowrite also tries to add instrumentation to act as a forkserver for AFL; in case this
causes problems, you can disable this behaviour by using export AFL_NO_FORKSERVER=1
To generate symbolized assembly that may be modified by hand or post-processed by existing tools, just do not specify any instrumentation pass:
retrowrite </path/to/binary> <path/to/output/asm/files>
The output asm files can be freely edited by hand or by other tools. Post-modification, the asm files may be assembled to working binaries as described above.
While retrowrite is interoperable with other tools, we strongly encourage researchers to use the retrowrite API for their binary instrumentation / modification needs! This saves the additional effort of having to load and parse binaries or assembly files.
The jumparound pass randomizes the order of instructions in a function. It can be found
in folder rwtools_x64/jumparound. To use it, you need to specify the -m option as following:
retrowrite -m jumparound <input file> <output asm>
Run setup.sh:
./setup.sh kernel
Activate the virtualenv (from root of the repository):
source retro/bin/activate
(Bonus) To exit virtualenv when you're done with retrowrite:
deactivate
- Instrument Binary with Binary-Address Sanitizer (BASan) :
retrowrite --asan --kernel </path/to/module.ko> </path/to/output/module_asan.ko> - Generate Symbolized Assembly that may be modified by hand or post-processed by existing tools:
retrowrite </path/to/module.ko> <path/to/output/asm/files>
For fuzzing campaign please see fuzzing/ folder.
In general, librw/ contains the code for loading, disassembly, and
symbolization of binaries and forms the core of all transformations.
Individual transformation passes that build on top this rewriting framework,
such as our binary-only Address Sanitizer (BASan) is contained as individual
tools in rwtools/.
The files and folder starting with k are linked with the kernel retrowrite version.
In the demos/ folder, you will find examples for userspace and kernel retrowrite (demos/user_demo and demos/kernel_demo respectively).
The following publications cover different parts of the upstream RetroWrite project. Full citation metadata is available from the upstream RetroWrite project and the corresponding papers.
-
RetroWrite: Statically Instrumenting COTS Binaries for Fuzzing and Sanitization In Oakland'20: IEEE International Symposium on Security and Privacy, 2020
-
No source, no problem! High speed binary fuzzing In 36c3'19: Chaos Communication Congress, 2019
This repository keeps the upstream Retrowrite MIT license in LICENSE.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.