KASAN(9)

💅 KASAN(9) — the Kernel Address SANitizer, explained by your local Unix bestie

okay so this whole page is from the Kernel Developer's Manual, and it's literally the glow-up guide for KASAN — the Kernel Address SANitizer. she catches the kernel doing crimes against memory, and honestly? iconic.

---

✨ NAME ✨

KASAN — Kernel Address SANitizer 🕵️‍♀️

---

🌸 SYNOPSIS 🌸

so there's two ways to get her in. option one: the GENERIC-KASAN kernel configuration — you use that to compile a KASAN-enabled kernel, and it uses GENERIC as the base configuration. easy.

alternately (option two, the DIY route), to compile KASAN into the kernel, you place this line in your kernel configuration file:

options KASAN

and don't forget the include, bestie:

#include <sys/asan.h>

also here's the function signature, keep it exact:

void
kasan_mark(const void *addr, size_t size, size_t redzsize,
      uint8_t code);

---

🦋 DESCRIPTION 🦋

KASAN is a whole subsystem that leverages compiler instrumentation to detect invalid memory accesses in the kernel 👀. currently it's implemented on the amd64 and arm64 platforms — so yes, she's platform-picky, we respect it.

when KASAN is compiled into the kernel, the compiler is configured to emit function calls upon every memory access. those functions are implemented by KASAN, and they permit run-time detection of several types of bugs, including:

• use-after-frees
• double frees and frees of invalid pointers
• out-of-bounds accesses

these protections apply to memory allocated by uma(9), malloc(9) and related functions, and kmem_malloc() and related functions — plus global variables and kernel stacks. so basically the whole squad gets watched 💖.

but real talk: KASAN is conservative and will not detect all instances of these types of bugs. she's not omniscient, she's just thorough. memory accesses through the kernel map are sanitized, but accesses via the direct map are not. when KASAN is configured, the kernel aims to minimize its use of the direct map — like, no cap, she's actively avoiding the sketchy shortcut.

---

🎀 IMPLEMENTATION NOTES 🎀

KASAN is implemented using compiler instrumentation and a kernel runtime. when a kernel is built with the KASAN option enabled, the compiler inserts function calls before most memory accesses in the generated code. the runtime implements the corresponding functions, which decide whether a given access is valid. if it's not valid, the runtime prints a warning or panics the kernel — depending on the value of the debug.kasan.panic_on_violation sysctl/tunable. so like… she either yells at you or she full-on faints 💀.

the KASAN runtime in a KASAN-configured kernel can be disabled by setting the loader tunable debug.kasan.disable=1. off switch: located.

the KASAN runtime works by maintaining a shadow map for the kernel map. there exists a linear mapping between addresses in the kernel map and addresses in the shadow map. the shadow map is used to store information about the current state of allocations from the kernel map. for example, when a buffer is returned by malloc(9), the corresponding region of the shadow map is marked to indicate that the buffer is valid ✅. when it is freed, the shadow map is updated to mark the buffer as invalid ❌. accesses to the buffer are intercepted by the KASAN runtime and validated using the contents of the shadow map. it's giving surveillance but make it fair.

upon booting, all kernel memory is marked as valid. kernel allocators must mark cached but free buffers as invalid, and must mark them valid before freeing the kernel virtual address range. this slightly reduces the effectiveness of KASAN, but it simplifies its maintenance and integration into the kernel — a little trade-off, we stan a pragmatic queen.

updates to the shadow map are performed by calling kasan_mark(). let's break down the parameters, because you know she has lore:

• addr — the address of the buffer whose shadow is to be updated.
• size — the usable size of the buffer.
• redzsize — the full size of the buffer allocated from lower layers of the system. redzsize must be greater than or equal to size.
• code — lets the caller specify an identifier used when marking a buffer as invalid. this identifier is included in any reports generated by KASAN and helps identify the source of the invalid access.

in some cases kernel allocators will return a buffer larger than that requested by the consumer; the unused space at the end is referred to as a red zone, and it is always marked as invalid. periodt.

for instance, when an item is freed to a uma(9) zone, the item is marked with KASAN_UMA_FREED. see <sys/asan.h> for the available identifiers. and if the entire buffer is to be marked valid — i.e., size and redzsize are equal — code should be 0.

---

🔥 SEE ALSO 🔥

build(7), KMSAN(9), malloc(9), memguard(9), redzone(9), uma(9)

(a whole friend group, honestly 🫶)

---

👑 HISTORY 👑

KASAN was ported from NetBSD and first appeared in FreeBSD 13.1. so she's got range, she's got lineage, she's a transplant success story 🌈.

---

💀 BUGS 💀

okay, the fine print, because we love honesty:

• accesses to kernel memory outside of the kernel map are ignored by the KASAN runtime. when KASAN is configured, the kernel memory allocators are configured to use the kernel map, but some uses of the direct map remain. for example, on amd64 and arm64, accesses to page table pages are not tracked. not me finding the loophole 😭.
• some kernel memory allocators explicitly permit accesses after an object has been freed. these cannot be sanitized by KASAN. for example, memory from all uma(9) zones initialized with the UMA_ZONE_NOFREE flag are not sanitized. so like… she literally can't, and that's on the allocator.

---

💖 reminder bestie: no cap, KASAN catches a lot of bugs, but "conservative" means she will not catch all of them. don't get cocky just because the vibe check passed.

---

anyway, that's the page 🎀 this lil doc came from Debian land and is dated October 13, 2023 — so go forth, mark your buffers, and remember: the shadow map is always watching 🦋✨💜