c-audit

name	c-audit
description	Audit C code for security, safety, and memory management. Use when reviewing or hardening C modules.
user-invocable	true

C Code Audit Skill

Perform comprehensive security, safety, and quality audits on Hull C code.

Target: $ARGUMENTS (default: all src/cap/, src/runtime/, and include/hull/ files)

Usage

/c-audit                              # Audit all source files
/c-audit src/cap/hull_cap_db.c        # Audit a specific file
/c-audit --fix                        # Audit and apply fixes

Audit Categories

1. Memory Safety (Critical)

Issue	Pattern to Find	Severity
Buffer overflow	strcpy, strcat, sprintf, gets, unbounded loops	Critical
Unbounded string ops	strlen, strcmp on untrusted input	Critical
Unsafe integer parsing	atoi, atol, atof (no error detection, no bounds)	High
Integer overflow	malloc(a * b) without overflow check	Critical
Use-after-free	Pointer used after free()	Critical
Double-free	free() called twice on same pointer	Critical
Null dereference	Pointer used without NULL check	High
Uninitialized memory	Variables used before assignment	High
Missing null terminator	String buffer not explicitly terminated	High
Memory leak	malloc without corresponding free	Medium
Stack buffer overflow	Large stack arrays, VLAs	Medium

Safe Replacements:

// Copying
strcpy(dst, src)           -> strncpy(dst, src, sizeof(dst)-1); dst[sizeof(dst)-1] = '\0';
strcat(dst, src)           -> strncat(dst, src, sizeof(dst)-strlen(dst)-1);

// Formatting
sprintf(buf, fmt, ...)     -> snprintf(buf, sizeof(buf), fmt, ...);
gets(buf)                  -> fgets(buf, sizeof(buf), stdin);

// Memory allocation (overflow-safe)
malloc(count * size)       -> calloc(count, size);

// Integer parsing (atoi/atol have no error detection!)
atoi(str)                  -> strtol(str, &end, 10) with validation
atof(str)                  -> strtof(str, &end) with validation

Allocator Discipline:

// Hull uses malloc/free directly (no custom allocator like Keel)
// Verify: every malloc has a matching free
// Verify: every malloc return is checked for NULL
// Verify: calloc used when count*size multiplication is needed

// BAD:
void *p = malloc(count * elem_size);  // overflow risk

// GOOD:
void *p = calloc(count, elem_size);   // overflow-safe
if (!p) return -1;

2. Input Validation

Issue	What to Check
Array bounds	All array indices validated before access
Pointer validity	NULL checks before dereference
Size parameters	Non-negative, within reasonable bounds
String length	Length checked before copy/concat
Numeric ranges	Values within expected domain
SQL parameters	param_count checked before binding in hl_cap_db_*
File paths	Path validation via hl_cap_fs_validate() before any I/O
Env allowlist	Variable name checked against allowlist in hl_cap_env_get()

3. Resource Management

Issue	What to Check
File descriptors	fopen paired with fclose
Memory	malloc/calloc paired with free
SQLite	sqlite3_open paired with sqlite3_close
SQLite statements	sqlite3_prepare_v2 paired with sqlite3_finalize
QuickJS runtime	JS_NewRuntime paired with JS_FreeRuntime
QuickJS context	JS_NewContext paired with JS_FreeContext
Lua state	lua_newstate paired with lua_close
Error paths	Resources freed on all exit paths
I/O return values	fwrite/fread return values checked

Hull Cleanup Pattern:

// Every init must have matching free
hl_js_init()           -> hl_js_free()
hl_lua_init()          -> hl_lua_free()
sqlite3_open()         -> sqlite3_close()
sqlite3_prepare_v2()   -> sqlite3_finalize()
JS_NewRuntime()        -> JS_FreeRuntime()
JS_NewContext()         -> JS_FreeContext()
lua_newstate()         -> lua_close()
fopen()                -> fclose()

4. Integer Overflow

Overflow in size computations can cause undersized allocations and buffer overflows.

// BAD: overflow on 32-bit
int total = count * sizeof(HlColumn);
void *buf = malloc(total);

// GOOD: use size_t + calloc
HlColumn *cols = calloc(count, sizeof(HlColumn));

// GOOD: check before multiply
if (count > 0 && (size_t)count > SIZE_MAX / sizeof(HlColumn)) {
    return -1;  // overflow
}

Key areas in Hull:

• HlColumn array allocation in hl_cap_db_query() row callbacks
• PBKDF2 output buffer sizing
• SQL parameter arrays (HlValue binding arrays)
• Filesystem path buffer construction (base_dir + "/" + relative_path)
• QuickJS/Lua value conversion arrays

5. Capability Boundary Enforcement

Hull's security model depends on the shared hl_cap_* layer. Verify:

Issue	Severity	What to Check
Direct SQLite calls	Critical	JS/Lua bindings never call sqlite3_* directly
Direct file I/O	Critical	JS/Lua bindings never call fopen/fread/fwrite directly
Path traversal	Critical	hl_cap_fs_validate() called before every file operation
SQL injection	Critical	All SQL uses parameterized binding via hl_cap_db_*
Env leakage	High	All env access through hl_cap_env_get() with allowlist
Sandbox escape	Critical	eval() removed, io/os libs not loaded, loadfile/dofile removed

5b. Sealed runtime tables (read-only memory protection)

Hull defends boot-built security policy via two mechanisms (see docs/security.md §4b):

• .rodata for compile-time constants (static const tables — automatic OS read-only via the linker).
• hl_seal_arena (page-backed mmap RW → mprotect RO) for data that can't be static const because it's built at boot from app input (manifest, configuration, capability resolution).

When auditing C runtime changes, look for these patterns:

Issue	Severity	What to check
Boot-built mutable security policy not sealed. A new C-level structure that's (a) built once at boot from app input, (b) read on every request by the capability/sandbox layer, (c) influences security policy (allowlists, dispatch, trust anchors), and DOESN'T flow through hl_seal_arena.	Critical	Find the boot-init site; verify it calls hl_seal_arena_alloc / _strdup / _memdup and seals before the resolver/sandbox runs. Example pattern: HlManifest in src/hull/serve.c::hl_serve_wire_caps.
xxd -i generated table without const. Default xxd output emits unsigned char foo[] (writable). Any new embedded asset (CA bundle, signed manifest, embedded key, vendored binary) that lands in writable .data instead of read-only .rodata.	High	Grep the Makefile for xxd -i invocations; verify each is followed by the XXD_CONST_SEAL (sed post-process) or XXD_CONST_PIPE macro defined near the top of the Makefile.
Function-pointer table not const. A new dispatch vtable, registry, or callback array declared as plain static T table[] instead of static const T table[]. A writable function-pointer table in .data is a direct ROP/JOP pivot — a single arbitrary-write primitive turns into RCE by overwriting one slot.	Critical	Every HlRuntimeVtable, HlDbBackend, HlAsyncBackend, HlNetBackend, HlGpuBackend, HlCompilerVtable, etc. instance must be const-qualified. Same for HlModuleSpec arrays, command-dispatch tables, luaL_Reg[], QuickJS JSCFunctionListEntry[]. The compile-time const lands the table in .rodata, which is RO-mapped by the linker — same protection level as the sealed arena, for free.
__attribute__((constructor)) mutating dispatch state. A new boot-time constructor that initialises a function-pointer table or capability config. Constructors run before main, BEFORE the sandbox/seal phases — anything they touch is implicitly trusted boot state.	High	Avoid constructors for security policy; do init explicitly in the boot phase where the order is auditable. If a constructor IS necessary (e.g. WAMR's own globals), document why and verify it only touches its own static state, never Hull's.
Long-lived C struct holding secret material. Any new struct { char key[N]; ... } or static uint8_t shared_secret[N] that survives past the immediate operation. Hull's convention is Lua/JS-side _state tables + per-call stack-local uint8_t key[128] with secure_zero on return.	Critical	If C must cache secret material (e.g. parsed mbedTLS key context held across requests), seal it via hl_seal_arena or zero it on every use. Document the lifetime.
Sealing failure not fatal. A call to hl_seal_arena_seal whose return code isn't checked, or where -1 is logged-and-continued. The whole point is to fail closed; shipping with unsealed policy silently weakens the hardening guarantee.	Critical	Sealing failure must propagate up the boot-error path (return -1 from the boot phase → process exits). The only acceptable test-only path is documented + gated.
Writable alias retained after seal. A pointer to the to-be-sealed memory cached elsewhere (e.g. in a HlRuntime field) without being updated to the in-arena address. After sealing, the alias still points at the now-freed source.	High	Verify all consumers receive the sealed-copy pointer, not the source. The hl_manifest_seal pattern is to value-copy the struct, so consumers reading &s->manifest see the new pointers automatically.
Sealed arena destroyed before aliasing consumer. A teardown path that calls hl_seal_arena_destroy before every consumer that holds aliased pointers into it (cap configs, TLS contexts, runtime tables) has been freed. The arena must be destroyed LAST in cleanup.	High	Audit both success and failure cleanup paths (hl_serve_teardown_after_serve, hl_serve_cleanup, hl_serve_undo_caps). The pattern is documented in src/hull/serve.c — destroy arena AFTER hl_app_context_free, WASM/GPU caches, TLS contexts.
Allocation after seal. Code that tries to extend a sealed arena later (hl_seal_arena_alloc post-seal returns NULL — easy to miss in error paths if you assume alloc always succeeds).	Medium	Bump-arena alloc-after-seal is a programming bug; the call site should never reach that branch in production. Add an assertion.
Casting away const on a sealed/rodata table. T *mut = (T *)((uintptr_t)CONST_TABLE); or similar laundering to write into a read-only mapping. Will fault at runtime (SIGSEGV/SIGBUS) but the intent indicates a design mistake.	High	Reject the cast. If the table genuinely needs to mutate, it shouldn't be sealed — surface the lifecycle to the audit and decide on a per-case basis.

Cross-platform guard. hl_seal_arena is POSIX (mmap/mprotect/ sysconf). Cosmopolitan provides the POSIX shim transparently. If you ever add a native MSVC build, the arena needs a #ifdef _WIN32 branch using VirtualAlloc / VirtualProtect — same API contract.

Death tests are non-negotiable. Any new sealed surface needs a fork+SIGSEGV test that writes to a sealed page from a child process and asserts the child died with SIGSEGV/SIGBUS. Without it, a no-op mprotect would silently pass every other test. Pattern in tests/hull/test_seal_arena.c::write_after_seal_faults.

6. Defensive Macros

Check for and suggest these patterns:

#define ARRAY_LEN(a) (sizeof(a) / sizeof((a)[0]))
#define SAFE_FREE(p) do { free(p); (p) = NULL; } while(0)
#define CLAMP(x, lo, hi) ((x) < (lo) ? (lo) : ((x) > (hi) ? (hi) : (x)))

7. Test Coverage

Check test files (tests/test_*.c) for:

• Basic functionality tests
• Edge cases (empty input, max values, NULL)
• Error path tests (what happens when things fail)
• Bounds checking tests
• All public API functions have at least one test
• Path traversal rejection tested
• SQL parameterization tested
• Env allowlist enforcement tested
• Sandbox restrictions tested (both JS and Lua)

8. Dead Code Detection

Pattern	Issue	Fix
if (0) { ... }	Dead branch	Remove
return; code_after;	Unreachable code	Remove
#if 0 ... #endif	Disabled code	Remove or document
Unused #define	Dead macro	Remove
Unused static function	Dead function	Remove

Compile with -Wunused flags to detect automatically.

9. Build hardening + ROP/JOP resistance

Hull ships a probe-based compiler/linker hardening layer (Makefile ~lines 69-180, full reference in docs/security.md §4c). The verifier at scripts/check_hardening.sh runs on every CI build and every release native target; the release fails if a required protection drops.

9.1. Verify the build flags are still applied

The baseline (unconditional on non-COSMO):

-fstack-protector-strong  -fPIE  [-pie on Linux]
-D_FORTIFY_SOURCE=3  (release only)
-Wl,-z,relro -Wl,-z,now -Wl,-z,noexecstack  (Linux only)

The probed set (added if the toolchain accepts each — older toolchains reject some; the probe at hl_have_cflag / hl_have_ldflag handles fallback cleanly):

CFLAGS:   -fstack-clash-protection
          -fno-plt  -fno-common
          -ftrivial-auto-var-init=zero
          -fzero-call-used-regs=used-gpr
          -fcf-protection=full         (x86_64 only)
          -mbranch-protection=standard (arm64 only)
LDFLAGS:  -Wl,-z,separate-code  (Linux only)
          -Wl,--as-needed       (universal where supported)

Sanity checks for any audit touching the Makefile:

• make hardening runs without error and reports the expected flags for the host toolchain.
• make check-hardening passes on macOS and Linux (skips everything on cosmo, expected).
• Existing -fstack-protector-strong / -fPIE / FORTIFY / RELRO baseline still present.
• If a new flag is added: probe it via hl_have_cflag rather than hard-applying — must not break older toolchains.
• HULL_DISABLE_HARDENING=1 opt-out still works for local debugging (and CI's check-hardening step still fails on release if it was set).

9.2. C-level patterns that DEFEAT the hardening

The hardening flags raise the cost of exploitation; specific C patterns can undo it in a single line. When auditing new code, flag these:

Pattern	Severity	Why it defeats hardening
mmap(..., PROT_WRITE | PROT_EXEC, ...) or mmap(..., PROT_EXEC, ...) followed by writes / mprotect(... PROT_WRITE | PROT_EXEC ...).	Critical	Direct W^X violation. Hull's design ban on RWX memory (no JIT, no runtime codegen) is the precondition every other hardening flag assumes. The sealed-arena pattern is RW → RO; the reverse direction has no legitimate use case.
dlopen / dlsym / dlmopen / dladdr introduced in any Hull TU.	Critical	Forces lazy binding (defeats BIND_NOW), expands DT_NEEDED surface (defeats -Wl,--as-needed shrinkage), and gives runtime symbol resolution which is a classic ROP gadget pivot. Hull's manifest.allow_dynamic_libraries is the app-side opt-in; the C side should not initiate dlopen from its own code.
New global function-pointer table without static const.	Critical	Lands in writable .data; one arbitrary-write primitive overwrites a slot → control-flow hijack. See §5b above.
Unbounded alloca(n) / VLA with data-derived size.	High	Defeats -fstack-clash-protection by jumping the guard page in one allocation. If the size is bounded (alloca(SMALL_CONSTANT)) it's fine; if it's alloca(strlen(input)) it's a stack-pivot primitive. Hull's convention is #pragma GCC diagnostic doesn't suppress -Wvla — VLAs should be replaced by malloc + size check.
setjmp / longjmp straddling a sandbox or seal boundary.	High	Linux CET shadow stack (SHSTK) tracks frames; non-local jumps via standard setjmp/longjmp cooperate via glibc shims, but a custom setjmp-like macro or hand-rolled context switch loses the protection. If absolutely needed, use sigsetjmp with savesigs=1 only when documented.
Hardcoded executable address literals (0x[0-9a-f]{6,} that smell like a pointer).	High	Defeats ASLR — implies the code expects a known layout. Common sources: ported exploit PoCs, fixed-address mmap, hand-rolled JIT trampolines. Reject unless there's a documented platform reason (e.g. a kernel-defined vDSO address).
__attribute__((no_stack_protector)) on a non-leaf function.	High	Disables the canary on functions that might have a stack buffer. Only acceptable on tiny leaf helpers that demonstrably never take &local of a stack object. Document the reason inline.
__attribute__((interrupt)), __attribute__((naked)), or custom calling conventions.	High	Bypasses -fzero-call-used-regs and the standard return-address tagging. No legitimate use case in Hull.
Inline asm (__asm__ / asm volatile) clobbering registers -fzero-call-used-regs would zero.	Medium	Mostly fine if it doesn't escape — but inline asm in a function that's later inlined into a security-sensitive caller can leak register state. Review the clobber list and the calling context.
Casting a function pointer through void * (e.g. via dlsym return, generic registry lookup) and calling without IBT/BTI marker check.	High	Defeats CET IBT / arm64 BTI: the target function must start with endbr64 / bti for the indirect-branch landing to be legal. Functions reached via dlsym aren't compiled with CET markers by default. If Hull must call a dynamically-resolved function pointer, the resolver must verify the target's start instruction. (Status today: Hull has no dlsym; this check is forward-looking.)
__builtin_return_address(N) for N > 0.	Medium	Walks the call stack manually — works against the frame pointer (which release builds may omit) and against the shadow stack (which intentionally hides return addresses from userspace). Almost always a sign of a hack; prefer explicit context passing.
New vendor library imported without applying hardening CFLAGS.	Medium	New vendor TU's CFLAGS := … -w … clobbers the global set; gadgets in its text segment are reachable. Add hardening to that TU's CFLAGS array OR document the deferral in the per-library _CFLAGS block.
Adding -rdynamic or -Wl,-export-dynamic to LDFLAGS.	High	Exports every symbol — makes the binary trivially introspectable for gadget search. Hull is a static executable; no symbols should be exported.

9.3. Sanitizer / debug-mode hygiene

Pattern	Severity	Why
make debug build doesn't actually instrument new code.	High	If a new TU sets its own CFLAGS := … (no +=) it clobbers the inherited -fsanitize=address,undefined. The TU compiles, the linker fails on ASan runtime symbols. Verify any new vendor *_CFLAGS block inherits sanitizer flags from $(CFLAGS) (or has an explicit -fsanitize=… block under ifdef DEBUG).
make msan doesn't instrument the vendor TU.	High	MSan requires every TU on the read-path to be instrumented; an uninstrumented mbedtls_sha256() call makes the caller's read of the output buffer flag as use-of-uninitialized-value. See the existing MBEDTLS_CFLAGS block under ifdef MSAN for the pattern.
New death test (fork + write to sealed page + assert WIFSIGNALED) lacks the signal(SIGSEGV, SIG_DFL); signal(SIGBUS, SIG_DFL); reset in the child.	High	Sanitizer runtimes install their own SEGV handler that prints a diagnostic and _exit(1). The child then dies "cleanly" instead of by signal, and WIFSIGNALED returns false → test fails. Reset SIG_DFL in the child immediately after fork(). Pattern: tests/hull/test_seal_arena.c::write_after_seal_faults.
All tests pass under sanitizers (make check).	High	Required for CI. ASan + UBSan must be green; MSan + UBSan must be green on Linux.

9.4. Expected commands

• make debug — ASan + UBSan + -O0 -g -fno-omit-frame-pointer.
• make msan — MSan + UBSan (Linux clang only).
• make check — clean + ASan build + test + e2e.
• make hardening — print resolved hardening flag list.
• make check-hardening — run post-build verifier on build/hull.
• scripts/check_hardening.sh [BINARY] — same, on any binary.

Audit checklist for §9:

• No new RWX-introducing patterns (mmap+PROT_EXEC|PROT_WRITE, mprotect to W+X).
• No new dlopen/dlsym in Hull TUs.
• No new global function-pointer tables missing static const.
• No new unbounded alloca / VLAs.
• No new __attribute__((constructor)) touching dispatch state.
• make hardening reports the expected flag set.
• make check-hardening passes on macOS + Linux + cosmo.
• Sanitizer builds still build and pass.

10. Lifetime classes & arena discipline

Hull's trusted core avoids most use-after-free / double-free / lifetime bugs by construction: security-sensitive code does not individually free() objects, it lets an arena's destroy point free everything at once. When auditing allocation, classify every site by lifetime class and check it uses the right ownership model.

Lifetime class	What	Allocator / owner	Destroy point
boot arena	tables/config built once at init, then validated + sealed read-only	sh_seal_arena (RW→mprotect RO)	destroyed LAST in teardown, after every aliasing consumer (see §5b)
module arena	lifetime tied to one module / runtime instance (WASM module cache, GPU device caches)	per-instance struct + its own mutex	instance _free() / _destroy()
request arena	lifetime tied to ONE operation / call / RPC / tool invocation	sh_arena (bump), reset per request	one sh_arena_reset / _destroy per op
scratch arena	transient parse/serialize workspace	sh_arena mark/rewind (hl_arena_mark/_rewind in src/hull/utils/alloc.c)	rewind at end of the local scope
third-party glue	malloc/free required by an external API (SQLite, mbedTLS, QuickJS, Lua, WAMR, wgpu)	that library's allocator	that library's free; Hull must not cross allocators

Patterns to flag:

Issue	Severity	What to check
Scattered request-temporary malloc/free in a security path where an arena's lifetime would remove the manual free entirely. The danger is a luaL_error/longjmp or early-return path that skips the free.	High	Prefer arena-backed scratch (the request/scratch arena is freed wholesale regardless of how the function exits). Hull's mod_db.c/mod_crypto.c/mod_http_client.c already do this — new request-scoped scratch should too.
free() outside allocator/arena internals in core runtime code.	Medium	Strongly discouraged. Every free is a UAF/double-free surface. Confirm the object isn't arena-owned (freeing an arena sub-allocation is a bug). shared/ and utils/ should approach zero raw free.
More than one owner / more than one destroy point for an arena.	Critical	Each arena has exactly ONE owner and ONE destroy call. Two destroys = double-free of the whole region.
Pointer retained into an arena after the arena is reset/destroyed.	Critical	A cached pointer into request/scratch memory used after reset is a UAF. Verify no long-lived struct field aliases arena memory across a reset. The seal pattern value-copies structs precisely to avoid this.
realloc() that may invalidate a pointer/iterator held across the call.	High	Every realloc must reassign into the owning field and NO previously-obtained element pointer or loop cursor may survive the call. Re-derive the pointer after the realloc (e.g. row = &r->values[i] after db_result_grow). See §10.1.
Crossing allocators — e.g. free()-ing a pointer that came from a codec/library allocator, or vice versa.	High	Free with the matching allocator. Image-codec output, mbedTLS buffers, SQLite strings each have their own free contract.
Missing debug poisoning after arena reset/destroy.	Low	Under make debug, poison freed region so stale reads trap (sh_arena already ASan-poisons on create/reset). New arenas should match.

10.1. realloc / internal-mutable-pointer hazards

Two specific sub-checks that catch the subtle lifetime bugs:

• Dangling-after-realloc. Grep every realloc. For each, confirm the result is stored back into the owning struct and that the code does not hold a pointer/iterator obtained before the realloc. Growable buffers (tui out_buf, worker_db value array, tool result array, agent line buffers, poll timer/watcher/completion arrays) are the usual sites. A bounded-size check (SIZE_MAX/2) must precede the doubling.
• API returning a pointer into mutable internal storage. A public hl_* getter must return either a const pointer into immutable .rodata/sealed memory (e.g. hl_vfs_find → const HlEntry *), a freshly-allocated string with a documented caller-frees contract, or a stable handle the caller is meant to drive. Flag any getter that hands back a non-const pointer into a buffer a later call could realloc/free (a latent dangling reference), or a write-through into sealed security policy.

11. Iterator invalidation

The dangerous shape is iterate a mutable container while it can be mutated during the walk. The mutation almost always arrives through a callback invoked inside the loop body that re-enters Hull and adds/removes/grows the very container being walked.

Issue	Severity	What to check
Callback-driven loop over a mutable container (broadcast over a connection list, timer fire over a timer array, pool drain, cache eviction, per-row DB callback) where the callback can re-enter and mutate the container.	Critical/High	The callback must run in a context that cannot re-enter and mutate (sandbox/driver boundary), OR the loop must snapshot first, OR teardown must be deferred. Document the non-reentrancy invariant at the cb() call site (the WS-broadcast comment is the template).
Element pointer held across an add that may realloc/grow.	High	Use index-based iteration that re-reads count, not a cached &arr[i].
LRU/cache eviction nested inside iteration over the same cache.	High	The prepared-statement cache is the canonical hazard: evicting (finalizing) the in-flight entry mid-loop is a UAF. Keep an explicit "in-use entry is pinned against eviction" rule.

Safe patterns to require: snapshot array (copy the elements/handles before the loop), index-based iteration with explicit mutation rules (append-only + re-read count), two-phase update/delete queue (mark in phase 1, apply after the loop), or sealed immutable array (registries that are static const — confirm they're never mutated at runtime). Document, per container, whether mutation during iteration is allowed. Do not expose raw container storage if growth/realloc can occur.

12. Generational handles for long-lived objects

For long-lived runtime objects currently referenced by raw pointers across an API boundary (script → C), prefer a generational handle over a raw pointer so a stale reference fails validation instead of dereferencing freed memory:

typedef struct { uint32_t index; uint32_t generation; } HullHandle;

The backing table slot carries generation + an alive bit; lookup validates slot.generation == handle.generation and returns NULL on mismatch. Apply this ONLY where it improves safety without broad churn:

When to recommend	When NOT to
A script-visible object that outlives a single call, can be destroyed by app code while another reference exists, and is reached by raw pointer (the classic dangling-userdata risk).	Objects already protected by an index+generation pool, a per-call stack local, a static const table, or a monotonic ID under a lock (Hull's CFI/typed-handle work already covers the vtables — don't re-handle those).
Connection / instance / buffer registries where "destroyed by name while a handle is held" is reachable.	Boot/sealed config (immutable — no stale-handle risk).

Today Hull's binding layer mostly uses the "null the userdata's opaque pointer on close/destroy, methods fail closed" pattern — an acceptable hand-rolled equivalent. Flag any binding where close/destroy frees the underlying struct but a suspended/async continuation can still resume against it (that's where the fail-closed null is insufficient).

13. Aliasing & single-owner mutation

Issue	Severity	What to check
Sealed/boot-built security state exposed as non-const after init.	High	Configuration, policy, dispatch, vtable, capability, and manifest-derived tables must be reachable only as const once initialized (see §5b).
API exposing a mutable internal pointer instead of mutating through the owner.	High	Prefer hl_x_set(owner, ...) over handing out &owner->field. See §10.1.
Two live aliases to the same object with unclear ownership, one of which may free/realloc.	High	Establish a single explicit owner; others hold a borrow (read-only) or a handle. Document ownership transfer at the boundary.
Unclear borrow-vs-owned at a binding boundary — handing app code a long-lived object that borrows a buffer the app can free/GC (the *_from_buffer / borrowed-view → long-lived-handle constructor pattern).	Critical	The long-lived object must PIN its source (dup/ref the backing buffer, or copy). A borrow that outlives its source is a UAF.

Recommended naming discipline in comments/types: borrow / read-only view (caller must not free; valid only for the call), owned object (caller frees), arena-owned (freed by the arena's destroy, never individually), handle reference (validated each use, may be stale).

14. Data races & thread affinity

Hull's model: a single event-loop thread owns all core policy / security state; a worker thread pool runs db.async / compute.async / gpu.async jobs on deep-copied inputs; Keel returns each job's done_fn/cancel_fn to the event-loop thread.

Issue	Severity	What to check
Concurrent mutation of capability policy, dispatch/vtables, runtime config, or manifest-derived security state.	Critical	These must be static const, sealed (sh_seal_arena), or mutated ONLY on the event loop. Never written from a worker.
Shared mutable cache touched by both the loop and a worker without a lock (WASM module cache / instance pool, GPU device buffer/texture/pipeline caches, shared-data segments).	Critical	Must be under the owning mutex (pool_mutex, mod->mutex, dev->mutex) across the whole critical section, including the backend submit/poll. Mutation-while-async-in-flight needs an explicit reservation (the inflight_async counter pattern).
Event-loop-only mutation site missing a thread-affinity assertion.	Medium	hl_assert_on_event_loop() (gated on HL_THREAD_AFFINITY_CHECKS) should guard each loop-only mutation of security state (segment load, async submit, GPU compile).
Event-loop thread never marked / log not made thread-safe in a build flavor that still spawns the worker pool.	High	Every entry point that creates the worker pool must call BOTH hl_event_loop_mark_current() (so the affinity asserts are live, not silently inert) AND hl_log_make_threadsafe() (so log.c's callback list + stream write is locked) BEFORE pool_create. Check every flavor (serve.c AND serve_cli.c / CLI-flavor HL_ENABLE_HTTP_SERVER=0), not just the default.
Unsynchronized writes to a shared output stream from multiple threads (audit JSONL / log to stderr emitted from worker work_fns).	Medium	Per-token fwrite from a worker can interleave byte-wise with an event-loop line, corrupting the JSONL. Hold a process lock around the whole record, or build the line in a buffer and emit with one fwrite.
Globals mutated without a lock, or _Atomic/memory-ordering misuse at a boundary.	High	Init-before-threads globals are fine if written once before pool_create; anything written later from >1 thread needs an atomic or lock.

Prefer, in order: single-threaded event loop for policy state → immutable sealed shared config → message passing (deep-copied inputs to workers) → explicit atomic queues only at the boundary. Document thread affinity for security-sensitive state. TSan CI (make tsan) must cover the worker-pool paths for each build flavor that ships a pool.

15. Debug-build defensive checks

Under make debug (and TSAN/MSAN where relevant), the trusted core should carry lightweight, compiled-out-in-release checks. When auditing new code in a security path, expect (or recommend) these:

• arena owner / lifetime asserts (alloc-after-destroy, alloc-after-seal both return NULL / assert — the bump arena already does)
• ASan poisoning of freed/reset arena regions (stale read traps)
• stale-handle detection (generation mismatch → NULL)
• mutation-during-iteration asserts (e.g. a dispatch_depth/iterating flag that aborts on re-entrant mutation)
• thread-affinity asserts for security-sensitive state (hl_assert_on_event_loop())

These are the runtime tripwires that turn a latent lifetime/race bug into a loud test failure under the sanitizer matrix.

Audit Procedure

When /c-audit is invoked:

1. Locate Files

   src/cap/*.c                 # Shared capability layer
   src/runtime/js/*.c          # QuickJS runtime integration
   src/runtime/lua/*.c         # Lua 5.4 runtime integration
   src/main.c                  # Entry point
   include/hull/*.h            # Public headers
   tests/test_*.c              # Test files
   Makefile                    # Build configuration
   

2. Scan for Critical Issues

   • Search for unsafe functions: strcpy, sprintf, gets, strcat
   • Search for unsafe integer parsing: atoi, atol, atof
   • Search for unchecked allocations: malloc/calloc without NULL check
   • Search for integer overflow in size calculations
   • Search for missing bounds checks on array access
   • Search for unchecked fwrite()/fread() return values
   • Search for direct SQLite/file I/O calls in runtime bindings (bypass of hl_cap_*)
   • Search for ROP/JOP defeats (§9.2):
     • mmap.*PROT_EXEC.*PROT_WRITE / mprotect.*PROT_EXEC.*PROT_WRITE (RWX)
     • dlopen / dlsym / dlmopen (runtime symbol resolution)
     • alloca( with data-derived size (stack-clash defeat)
     • new global function-pointer arrays missing static const
     • __attribute__((constructor)) (pre-main mutation)
     • __attribute__((no_stack_protector)) / ((naked)) / ((interrupt))
     • hardcoded executable address literals (0x[0-9a-f]{6,})
     • -rdynamic / -Wl,-export-dynamic in any Makefile change
   • Search for lifetime / aliasing / race hazards (§§10-14):
     • every realloc( → does any pointer/iterator held across it dangle? (§10.1)
     • free( in shared/ or utils/ or any security path (should be ~zero; §10)
     • callback invocations inside a loop over a mutable container (§11)
     • *_from_buffer / borrowed-view constructors returning a long-lived handle without pinning the source (§13)
     • public hl_* getters returning a non-const pointer into a buffer a later call can realloc/free (§10.1, §13)
     • worker work_fn (db/wasm/gpu async) reads/writes of a shared cache, global, or output stream without the owning mutex/lock (§14)
     • every entry point that calls pool_create → does it FIRST call hl_event_loop_mark_current() AND hl_log_make_threadsafe()? Check serve.c AND serve_cli.c (CLI flavor) (§14)

3. Review Public API

   • Check all public functions in headers (hl_* prefix)
   • Verify NULL checks on pointer parameters
   • Verify bounds checks on size parameters

4. Check Resource Management

   • Every _init()/_create() has matching _free()/_close()
   • Error paths free allocated resources
   • No memory leaks on early returns
   • SQLite statements finalized on error paths
   • QuickJS/Lua contexts cleaned up on error paths

5. Check Capability Boundaries

   • JS/Lua bindings only access resources through hl_cap_* functions
   • Path validation enforced before every filesystem operation
   • SQL always parameterized
   • Sandbox restrictions in place (no eval, no io/os libs)

6. Detect Dead Code

   • Compile with -Wunused flags
   • Find unused static functions
   • Find unused variables and parameters
   • Flag commented-out or #if 0 code blocks

7. Check Build Hardening (§9)

   • Probe-based flag set still applied (make hardening reports the expected list for this toolchain).
   • Verifier passes (make check-hardening, or scripts/check_hardening.sh build/hull directly).
   • No new C pattern from the §9.2 defeat list landed in this change (RWX, dlsym, unbounded alloca, naked attribute, etc.).
   • Sanitizer builds (make debug, make msan) still build and pass — if a new vendor TU was added, its *_CFLAGS block must inherit / re-add the sanitizer flags under ifdef DEBUG / ifdef MSAN.

8. Check Sealed Runtime Tables (§5b)

   • Any new boot-built mutable security policy flows through hl_seal_arena and is sealed before the resolver/sandbox runs.
   • Any new global function-pointer table (vtable, registry, callback array) is static const.
   • Any new xxd -i Makefile invocation uses XXD_CONST_SEAL or XXD_CONST_PIPE to land in .rodata.
   • Sealed-arena destroy stays LAST in every cleanup path.

9. Check Lifetime, Iteration & Concurrency (§§10-15)

   • Classify each allocation cluster by lifetime class (boot / module / request / scratch / third-party); flag scattered request-temporary malloc/free an arena would make leak-proof (§10).
   • One owner + one destroy per arena; no pointer retained past a reset (§10).
   • Every realloc re-derives held pointers; no getter returns a mutable internal pointer a later call can invalidate (§10.1).
   • No callback-driven loop mutates the container it walks; registries iterated are static const (§11).
   • Long-lived script-visible objects that app code can destroy while a reference (esp. a suspended/async continuation) lives: handle or fail-closed, never a bare dangling pointer (§12).
   • Sealed/policy state exposed const; single-owner mutation; borrowed buffers pinned by the long-lived objects that reference them (§13).
   • No off-event-loop mutation of policy/dispatch/manifest state; shared worker-touched caches under the owning mutex; every pool_create entry point marks the loop thread + makes log thread-safe first; audit/log stream writes from workers are lock-wrapped (§14).
   • For a large audit, fan out §10/§11/§14 to parallel subagents (one per dimension over cap/ + runtime/ + the worker files), then reconcile against known prior hardening before reporting.

10. Generate Report Format as markdown table with findings, severity, file:line, and suggested fix.

Report Format

## C Audit Report: Hull

**Date:** YYYY-MM-DD
**Files Scanned:** N
**Issues Found:** N (Critical: N, High: N, Medium: N, Low: N)

### Critical Issues

| # | File:Line | Issue | Current Code | Suggested Fix |
|---|-----------|-------|--------------|---------------|
| C1 | src/cap/hull_cap_db.c:42 | Buffer overflow | `strcpy(buf, src)` | `snprintf(buf, sizeof(buf), "%s", src)` |

### High Issues
...

### Medium Issues
...

### Low Issues
...

### Lifetime / ownership / concurrency summary (§§10-14)
For a lifetime/race-focused audit, ALSO report these dimensions explicitly
(state "CLEAN" where there is nothing — coverage matters):
- Risky allocation / `free` sites (by lifetime class).
- `realloc` / iterator-invalidation risks found.
- Raw-pointer lifetime / borrow-outlives-source risks found.
- Shared mutable state / data-race risks found (per build flavor).
- Changes made vs. cases intentionally left unchanged.
- Larger architectural changes recommended but NOT implemented.
- Remaining residual risks.

### Recommendations
1. ...

Fix Mode (--fix)

When --fix is specified:

1. Generate the audit report first
2. For each fixable issue, apply the transformation
3. Rebuild (make)
4. Re-run tests (make test)
5. Report any test failures or new warnings

Auto-fixable Issues:

• strcpy -> snprintf with buffer size
• sprintf -> snprintf with buffer size
• atoi -> strtol with validation
• Missing NULL checks (add early return)
• Missing malloc return check (add NULL check)
• Integer overflow in size calc -> calloc or overflow check
• Missing size_t casts in size calculations
• Unused local variables (remove)
• Unused static functions (remove)
• static T table[] for dispatch / vtable / registry → add const (§5b)
• New xxd -i Makefile rule missing const post-process → add XXD_CONST_SEAL / XXD_CONST_PIPE (§5b)
• Bounded alloca(SMALL_CONSTANT) left as-is; data-derived alloca(n) → flag, propose malloc + size check (§9.2, not auto-fix)

NOT Auto-fixable (require manual review):

• Logic errors
• Resource leaks in complex control flow
• Capability boundary violations
• Sandbox escape paths
• Architectural changes
• New W^X primitives (mmap/mprotect with PROT_WRITE|PROT_EXEC)
• New dlopen / dlsym introduced in C
• Sealed-arena destroy reordering — must trace every aliasing consumer's lifetime
• New __attribute__((constructor)) — needs design review of init order
• Probe regressions: if make hardening reports fewer flags than before on the same toolchain, the probe macro or surrounding ifdef was likely broken — manual investigation