address-sanitizer

# AddressSanitizer (ASan)

AddressSanitizer (ASan) is a widely adopted memory error detection tool used extensively during software testing, particularly fuzzing. It helps detect memory corruption bugs that might otherwise go unnoticed, such as buffer overflows, use-after-free errors, and other memory safety violations.

## Overview

ASan is a standard practice in fuzzing due to its effectiveness in identifying memory vulnerabilities. It instruments code at compile time to track memory allocations and accesses, detecting illegal operations at runtime.

### Key Concepts

| Concept | Description |
|---------|-------------|
| Instrumentation | ASan adds runtime checks to memory operations during compilation |
| Shadow Memory | Maps 20TB of virtual memory to track allocation state |
| Performance Cost | Approximately 2-4x slowdown compared to non-instrumented code |
| Detection Scope | Finds buffer overflows, use-after-free, double-free, and memory leaks |

## When to Apply

**Apply this technique when:**
- Fuzzing C/C++ code for memory safety vulnerabilities
- Testing Rust code with unsafe blocks
- Debugging crashes related to memory corruption
- Running unit tests where memory errors are suspected

**Skip this technique when:**
- Running production code (ASan can reduce security)
- Platform is Windows or macOS (limited ASan support)
- Performance overhead is unacceptable for your use case
- Fuzzing pure safe languages without FFI (e.g., pure Go, pure Java)

## Quick Reference

| Task | Command/Pattern |
|------|-----------------|
| Enable ASan (Clang/GCC) | `-fsanitize=address` |
| Enable verbosity | `ASAN_OPTIONS=verbosity=1` |
| Disable leak detection | `ASAN_OPTIONS=detect_leaks=0` |
| Force abort on error | `ASAN_OPTIONS=abort_on_error=1` |
| Multiple options | `ASAN_OPTIONS=verbosity=1:abort_on_error=1` |

## Step-by-Step

### Step 1: Compile with ASan

Compile and link your code with the `-fsanitize=address` flag:

```bash
clang -fsanitize=address -g -o my_program my_program.c
```

The `-g` flag is recommended to get better stack traces when ASan detects errors.

### Step 2: Configure ASan Options

Set the `ASAN_OPTIONS` environment variable to configure ASan behavior:

```bash
export ASAN_OPTIONS=verbosity=1:abort_on_error=1:detect_leaks=0
```

### Step 3: Run Your Program

Execute the ASan-instrumented binary. When memory errors are detected, ASan will print detailed reports:

```bash
./my_program
```

### Step 4: Adjust Fuzzer Memory Limits

ASan requires approximately 20TB of virtual memory. Disable fuzzer memory restrictions:

- libFuzzer: `-rss_limit_mb=0`
- AFL++: `-m none`

## Common Patterns

### Pattern: Basic ASan Integration

**Use Case:** Standard fuzzing setup with ASan

**Before:**
```bash
clang -o fuzz_target fuzz_target.c
./fuzz_target
```

**After:**
```bash
clang -fsanitize=address -g -o fuzz_target fuzz_target.c
ASAN_OPTIONS=verbosity=1:abort_on_error=1 ./fuzz_target
```

### Pattern: ASan with Unit Tests

**Use Case:** Enable ASan for unit test suite

**Before:**
```bash
gcc -o test_suite test_suite.c -lcheck
./test_suite
```

**After:**
```bash
gcc -fsanitize=address -g -o test_suite test_suite.c -lcheck
ASAN_OPTIONS=detect_leaks=1 ./test_suite
```

## Advanced Usage

### Tips and Tricks

| Tip | Why It Helps |
|-----|--------------|
| Use `-g` flag | Provides detailed stack traces for debugging |
| Set `verbosity=1` | Confirms ASan is enabled before program starts |
| Disable leaks during fuzzing | Leak detection doesn't cause immediate crashes, clutters output |
| Enable `abort_on_error=1` | Some fuzzers require `abort()` instead of `_exit()` |

### Understanding ASan Reports

When ASan detects a memory error, it prints a detailed report including:

- **Error type**: Buffer overflow, use-after-free, etc.
- **Stack trace**: Where the error occurred
- **Allocation/deallocation traces**: Where memory was allocated/freed
- **Memory map**: Shadow memory state around the error

Example ASan report:
```
==12345==ERROR: AddressSanitizer: heap-buffer-overflow on address 0x60300000eff4 at pc 0x00000048e6a3
READ of size 4 at 0x60300000eff4 thread T0
    #0 0x48e6a2 in main /path/to/file.c:42
```

### Combining Sanitizers

ASan can be combined with other sanitizers for comprehensive detection:

```bash
clang -fsanitize=address,undefined -g -o fuzz_target fuzz_target.c
```

### Platform-Specific Considerations

**Linux**: Full ASan support with best performance
**macOS**: Limited support, some features may not work
**Windows**: Experimental support, not recommended for production fuzzing

## Anti-Patterns

| Anti-Pattern | Problem | Correct Approach |
|--------------|---------|------------------|
| Using ASan in production | Can make applications less secure | Use ASan only for testing |
| Not disabling memory limits | Fuzzer may kill process due to 20TB virtual memory | Set `-rss_limit_mb=0` or `-m none` |
| Ignoring leak reports | Memory leaks indicate resource management issues | Review leak reports at end of fuzzing campaign |

## Tool-Specific Guidance

### libFuzzer

Compile with both fuzzer and address sanitizer:

```bash
clang++ -fsanitize=fuzzer,address -g harness.cc -o fuzz
```

Run with unlimited RSS:

```bash
./fuzz -rss_limit_mb=0
```

**Integration tips:**
- Always combine `-fsanitize=fuzzer` with `-fsanitize=address`
- Use `-g` for detailed stack traces in crash reports
- Consider `ASAN_OPTIONS=abort_on_error=1` for better crash handling

See: [libFuzzer: AddressSanitizer](https://github.com/google/fuzzing/blob/master/docs/good-fuzz-target.md#memory-error-detection)

### AFL++

Use the `AFL_USE_ASAN` environment variable:

```bash
AFL_USE_ASAN=1 afl-clang-fast++ -g harness.cc -o fuzz
```

Run with unlimited memory:

```bash
afl-fuzz -m none -i input_dir -o output_dir ./fuzz
```

**Integration tips:**
- `AFL_USE_ASAN=1` automatically adds proper compilation flags
- Use `-m none` to disable AFL++'s memory limit
- Consider `AFL_MAP_SIZE` for programs with larg