sanitizers

サニタイザー

目的

メモリエラー、未定義動作、データ競合、メモリリークを見つけるために、コンパイラーのランタイムサニタイザーの選択、有効化、結果の解釈をエージェントに案内します。

トリガー

• 「プログラムでメモリエラーが発生しています。どのサニタイザーを使えばよいですか？」
• 「ASan を有効にするにはどうすればよいですか？」
• 「ASan／UBSan／TSan のレポートはどう解釈すればよいですか？」
• 「ASan に heap-buffer-overflow と表示されます。これはどういう意味ですか？」
• 「サニタイザーの誤検知を抑制するにはどうすればよいですか？」
• 「CI でサニタイザーを使用できますか？」

ワークフロー

1. 判断ツリー：どのサニタイザーを使うか？

Bug class?
├── Memory OOB, use-after-free, double-free → AddressSanitizer (ASan)
├── Stack OOB, global OOB → ASan (all three covered)
├── Uninitialised reads → MemorySanitizer (MSan, Clang only, requires all-clang build)
├── Undefined behaviour (int overflow, null deref, bad cast) → UBSan
├── Data races (multi-thread) → ThreadSanitizer (TSan)
├── Memory leaks only → LeakSanitizer (LSan, standalone or via ASan)
└── Multiple classes → ASan + UBSan (common combo); cannot combine with TSan or MSan

2. AddressSanitizer（ASan）

# GCC or Clang
gcc -fsanitize=address -fno-omit-frame-pointer -g -O1 -o prog main.c
# Or
clang -fsanitize=address -fno-omit-frame-pointer -g -O1 -o prog main.c

ランタイムオプション（ASAN_OPTIONS 経由）：

ASAN_OPTIONS=detect_leaks=1:abort_on_error=1:log_path=/tmp/asan.log ./prog

ASAN_OPTIONS のキー	効果
detect_leaks=0/1	LeakSanitizer を有効にします（Linux ではデフォルトで 1）
abort_on_error=1	_exit() の代わりに abort() を呼び出します（コアダンプ用）
log_path=path	レポートをファイルに書き込みます
symbolize=1	アドレスをシンボル化します（PATH に llvm-symbolizer が必要です）
fast_unwind_on_malloc=0	より正確なスタックを取得します（低速になります）
quarantine_size_mb=256	解放済みメモリの再利用を遅らせます

ASan 出力の解釈：

==12345==ERROR: AddressSanitizer: heap-buffer-overflow on address 0x602000000050
READ of size 4 at 0x602000000050 thread T0
    #0 0x401234 in foo /home/user/src/main.c:15
    #1 0x401567 in main /home/user/src/main.c:42

0x602000000050 is located 0 bytes after a 40-byte region
[0x602000000028, 0x602000000050) allocated at:
    #0 0x7f12345 in malloc ...
    #1 0x401234 in main /home/user/src/main.c:10

読み方：WRITE/READ の最上位フレームはアクセス箇所です。allocated at のスタックには割り当て箇所が表示されます。この領域は [start, end) の 40 バイトで、アクセス位置は end、つまり末尾から 1 バイト先です（典型的なオフバイワンエラー）。

3. UndefinedBehaviorSanitizer（UBSan）

gcc -fsanitize=undefined -g -O1 -o prog main.c
# More complete: add specific checks
gcc -fsanitize=undefined,integer -g -O1 -o prog main.c

一般的な UBSan のチェック：

• signed-integer-overflow
• unsigned-integer-overflow（デフォルトでは undefined に含まれません）
• null — null ポインターの参照外し
• bounds — 配列インデックスの範囲外アクセス（コンパイル時に範囲が判明している場合）
• alignment — アラインメントが不正なポインターアクセス
• float-cast-overflow — 浮動小数点数から整数への変換時のオーバーフロー
• vptr — C++ の vtable 型の不一致
• shift-exponent — ビット幅以上のシフト

# Enable everything including integer overflow
gcc -fsanitize=undefined \
    -fsanitize=signed-integer-overflow,unsigned-integer-overflow,float-cast-overflow \
    -fno-sanitize-recover=all \   # abort instead of continue
    -g -O1 -o prog main.c

-fno-sanitize-recover=all：UBSan が最初のエラーで異常終了するようにします（CI で重要です）。

UBSan 出力の解釈：

src/main.c:15:12: runtime error: signed integer overflow: 2147483647 + 1 cannot be represented in type 'int'

4. ThreadSanitizer（TSan）

# Clang or GCC (GCC ≥ 4.8)
clang -fsanitize=thread -g -O1 -o prog main.c

# TSan is incompatible with ASan and MSan

TSan 出力の解釈：

WARNING: ThreadSanitizer: data race (pid=12345)
  Write of size 4 at 0x7f... by thread T2:
    #0 increment /home/user/src/counter.c:8
  Previous read of size 4 at 0x7f... by thread T1:
    #0 read_counter /home/user/src/counter.c:3

5. MemorySanitizer（MSan）

MSan は初期化されていないメモリの読み取りを検出します。Clang 専用です。すべてのコードをインストルメントするビルドが必要です（MSan オブジェクトと非 MSan オブジェクトを混在させることはできません）。

clang -fsanitize=memory -fno-omit-frame-pointer -g -O1 -o prog main.c
# With origin tracking (slower but shows where uninit value came from)
clang -fsanitize=memory -fsanitize-memory-track-origins=2 -g -O1 -o prog main.c

システムライブラリは MSan を使って再ビルドするか、MSan でインストルメントされたラッパーに置き換える必要があります。LLVM の msan-libs ツールチェーンを使用してください。

6. ASan と UBSan の併用

gcc -fsanitize=address,undefined -fno-sanitize-recover=all \
    -fno-omit-frame-pointer -g -O1 -o prog main.c

TSan や MSan とは併用しないでください。

7. 抑制

# ASan suppression file
cat > asan.supp << 'EOF'
# Suppress leaks from OpenSSL init
leak:CRYPTO_malloc
EOF

LSAN_OPTIONS=suppressions=asan.supp ./prog

# UBSan suppression
cat > ubsan.supp << 'EOF'
signed-integer-overflow:third_party/fast_math.c
EOF
UBSAN_OPTIONS=suppressions=ubsan.supp:print_stacktrace=1 ./prog

8. CMake との統合

option(SANITIZE "Enable sanitizers" OFF)
if(SANITIZE)
    set(san_flags -fsanitize=address,undefined -fno-sanitize-recover=all
                  -fno-omit-frame-pointer -g -O1)
    add_compile_options(${san_flags})
    add_link_options(${san_flags})
endif()

9. CI との統合

# GitHub Actions example
- name: Build with ASan+UBSan
  run: |
    cmake -S . -B build -DSANITIZE=ON
    cmake --build build -j$(nproc)

- name: Run tests under sanitizers
  run: |
    ASAN_OPTIONS=abort_on_error=1:detect_leaks=1 \
    UBSAN_OPTIONS=print_stacktrace=1:halt_on_error=1 \
    ctest --test-dir build -j$(nproc) --output-on-failure

10. HWASan（ハードウェア支援 AddressSanitizer）

TBI（Top Byte Ignore）または MTE を備えた対応 ARM64 ハードウェアでは、ASan よりオーバーヘッドが小さくなります。

# Clang/LLVM HWASan (userspace)
clang -fsanitize=hwaddress -g -O1 -o app app.c

# Requires ARM64 with TBI (most Android/arm64 servers) or HWASan tagging support
# Cannot combine with ASan on same build

サニタイザー	オーバーヘッド	プラットフォーム
ASan	約 2 倍	x86、arm64
HWASan	約 1.2～1.5 倍	TBI／MTE を備えた arm64
MSan	約 3 倍	LLVM のみ

11. MemTagSanitizer（ARM MTE）

ARM Memory Tagging Extension のハードウェアタグを使用して、ヒープ／スタック／メモリーの安全性を確保します。

# Experimental — LLVM with MTE-capable hardware (arm64)
clang -fsanitize=memtag -g -O1 -o app app.c

# Kernel MTE (separate from userspace MemTagSanitizer)
# CONFIG_ARM64_MTE=y — hardware tagging in kernel allocator

12. GWP-ASan（本番環境でのサンプリング）

本番環境に適した、サンプリング方式のガードページ ASan です（Android で使用されています。upstream glibc との統合は進行中です）。

# LLVM GWP-ASan (link-time, sampled allocations)
clang -fsanitize=gwp-asan -O2 -o app app.c

# Android: enabled in some system components for sampled crash detection
# glibc: experimental GWP-ASan allocator integration (check distro release notes)

定常状態のオーバーヘッドをほぼゼロに抑えながら、ヒープの OOB／UAF を確率的に検出します。

13. カーネルモジュール向け KASAN

# Build test kernel with KASAN
# CONFIG_KASAN=y CONFIG_KASAN_INLINE=y or CONFIG_KASAN_OUTLINE=y

# Boot KASAN kernel in QEMU for module development
qemu-system-x86_64 -kernel bzImage -append "kasan=on" ...

# Load module — KASAN reports appear in dmesg
sudo insmod mymod.ko
dmesg | tail -30

KASAN での KUnit テストには skills/kernel/kernel-testing を併用してください。KASAN レポートのトリアージについては skills/security/kernel-security を参照してください。

フラグのクイックリファレンスについては、references/flags.md を参照してください。 レポートの解釈例については、references/reports.md を参照してください。

関連スキル

• ASan が利用できない場合は、Memcheck に skills/profilers/valgrind を使用します
• サニタイザーエラーを引き起こす入力を自動生成するには、skills/runtimes/fuzzing を使用します
• ビルドフラグの詳細については、skills/compilers/gcc または skills/compilers/clang を使用します