C Memory Safety skill for Codex

A memory bug is fixed when a test reproduces it under a sanitizer, the fix makes that test pass, the whole suite is clean under ASan and UBSan, and the pattern that caused it is removed everywhere it appears, not only at the crashing line. “It stopped crashing” is not evidence.

Before changing code

1. Read AGENTS.md, the build files (Makefile, CMake, Meson) and CI config. Note the compilers, the C standard (-std=c11, c17, c23) and existing warning flags.
2. Build as-is and record warnings; many memory bugs are already flagged by -Wall -Wextra.
3. Get a reproduction: failing input, test or command. If the bug only shows in production, ask for a core dump, the input that triggered it, or the sanitizer log.

Workflow

• Build a sanitizer configuration (below) in a separate build directory.
• Reproduce under ASan+UBSan; save the report.
• Read the report: access type, size, the faulting stack, and the allocation and free stacks. Details in references/sanitizer-reports.md; read it when a report is unfamiliar or confusing.
• Write a regression test that triggers the bug (unit test or a saved fuzz input).
• Fix the root cause: ownership, bounds or size computation. Not a NULL check sprinkled near the crash.
• Grep for the same pattern elsewhere (rg -n 'strcpy|sprintf|alloca|\bgets\b', repeated malloc(n * size)).
• Run the full suite under ASan+UBSan, then MSan or Valgrind if uninitialised reads are plausible.
• If the code parses untrusted input, add or extend a fuzz target.

Choosing the tool

Bug class	Tool	Build flags
Overflow, use-after-free, double free, stack bugs	AddressSanitizer	-fsanitize=address -fno-omit-frame-pointer -g -O1
Signed overflow, shifts, misaligned access, bad casts, null deref	UBSan	-fsanitize=undefined -fno-sanitize-recover=all
Reads of uninitialised memory	MemorySanitizer (Clang, Linux only; all code incl. libs must be instrumented) or Valgrind	-fsanitize=memory -fsanitize-memory-track-origins=2
Data races	ThreadSanitizer (not combinable with ASan)	-fsanitize=thread
Leaks	LeakSanitizer (part of ASan on Linux), Valgrind, macOS leaks	ASAN_OPTIONS=detect_leaks=1
No recompile possible	Valgrind memcheck	valgrind --leak-check=full --error-exitcode=1 ./prog
Bugs before running	GCC -fanalyzer, clang scan-build, clang-tidy clang-analyzer-*, cppcheck	static
Unknown inputs	libFuzzer / AFL++ with ASan	-fsanitize=fuzzer,address

CC=clang CFLAGS="-fsanitize=address,undefined -fno-sanitize-recover=all -fno-omit-frame-pointer -g -O1" \
  LDFLAGS="-fsanitize=address,undefined" make clean all check

export ASAN_OPTIONS=abort_on_error=1:halt_on_error=1:detect_stack_use_after_return=1:strict_string_checks=1
export UBSAN_OPTIONS=print_stacktrace=1:halt_on_error=1

Platform notes: LeakSanitizer is not available with Apple’s toolchain on macOS; use leaks --atExit -- ./prog there or run the suite in a Linux container. MSan and Valgrind need Linux; Valgrind does not run on Apple silicon macOS. Installing Valgrind or pulling a container image needs network access and approval.

Safe patterns

Size arithmetic

#include <stdckdint.h>   /* C23; on older compilers use __builtin_mul_overflow */

void *alloc_array(size_t count, size_t elem_size) {
    size_t bytes;
    if (ckd_mul(&bytes, count, elem_size)) {
        errno = EOVERFLOW;
        return NULL;
    }
    return malloc(bytes);
}

calloc(count, size) also checks the multiplication. Never compute malloc(len + 1) where len comes from input without an upper bound check first.

Strings

Avoid	Use
strcpy, strcat, sprintf, gets	snprintf with return-value check; memcpy with an explicit, checked length
strncpy (may not NUL-terminate, pads)	snprintf(dst, sizeof dst, "%s", src) or strlcpy where available (glibc 2.38+, BSD, macOS)
printf(user_str)	printf("%s", user_str)
atoi	strtol with errno, end-pointer and range checks

int n = snprintf(buf, sizeof buf, "%s/%s", dir, name);
if (n < 0 || (size_t)n >= sizeof buf) {
    return ERR_PATH_TOO_LONG;          /* truncated: treat as an error, not a success */
}

sizeof buf is only the buffer size when buf is an array in scope; for a pointer parameter it is the pointer size. Pass lengths explicitly alongside pointers.

Ownership and cleanup

• Document ownership in the header: who allocates, who frees, and whether a returned pointer is borrowed.
• One exit path for cleanup with goto:

int load(const char *path, struct config *out) {
    int rc = -1;
    FILE *f = NULL;
    char *buf = NULL;

    f = fopen(path, "rb");
    if (!f) goto done;
    buf = malloc(MAX_CONFIG);
    if (!buf) goto done;
    /* ... parse ... */
    rc = 0;
done:
    free(buf);
    if (f) fclose(f);
    return rc;
}

• After free(p), set p = NULL when the pointer remains reachable (struct fields, globals); it turns a later use-after-free into a deterministic NULL crash and makes double free harmless.
• realloc into a temporary: tmp = realloc(p, n); if (!tmp) { /* p still valid */ }.
• Initialise every local at declaration; for structs use = {0}.

Integer pitfalls

• Signed overflow is undefined; do size and index math in size_t and check bounds before converting from signed input.
• Comparisons between int and size_t convert the int to unsigned: -1 < sizeof x is false. -Wsign-compare catches these.
• Shifts by >= the width or of negative values are UB; UBSan reports them.

Hardening flags for release builds

-Wall -Wextra -Wformat=2 -Wformat-security -Wconversion -Wsign-conversion -Wshadow
-Wimplicit-fallthrough -Werror=implicit-function-declaration
-D_FORTIFY_SOURCE=3 -O2           # FORTIFY needs optimisation; =3 on GCC 12+/Clang 16+, else =2
-fstack-protector-strong -fstack-clash-protection
-ftrivial-auto-var-init=zero      # GCC 12+/Clang 16+: defangs uninitialised stack reads
-fPIE -pie -Wl,-z,relro,-z,now    # Linux ELF

Hardening reduces exploitability; it does not replace fixing the bug. Add flags in the build system per target, check each with every CI compiler, and do not ship sanitizer builds to production.

Fuzzing an input parser

#include <stddef.h>
#include <stdint.h>
#include "parser.h"

int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
    struct message msg;
    if (parse_message(data, size, &msg) == 0) {
        message_free(&msg);
    }
    return 0;
}

clang -g -O1 -fsanitize=fuzzer,address,undefined fuzz_parser.c parser.c -o fuzz_parser
mkdir -p corpus && cp tests/fixtures/*.bin corpus/
./fuzz_parser corpus/ -max_total_time=300

Crashes are written as crash-<hash> files; add each as a regression test before fixing.

Verification

• The regression test fails before the fix and passes after, under ASan+UBSan.
• Full test suite clean under ASan+UBSan with halt_on_error=1.
• No new warnings with the flags above.
• Static analyser run on changed files (gcc -fanalyzer or scan-build make).
• Fuzz target (if added) runs for at least a few minutes with no findings.

Report template

## Memory bug: <one-line summary>
**Class:** heap-buffer-overflow | use-after-free | double-free | leak | uninit read | UB
**Trigger:** <input or test>   **Introduced:** <commit if known>
**Root cause:** <ownership/bounds/size reasoning, with file:line>
**Fix:** <what changed and why it removes the class of bug>
**Same pattern elsewhere:** <locations fixed or left, with reason>
**Evidence:** sanitizer report before, clean run after, regression test name