rules-zig

RISK (CWE-704): @alignCast in ReleaseFast/Small emits no runtime check — a misaligned pointer causes undefined behaviour (silent data corruption or SIGBUS on strict-alignment targets). FIX: Assert the incoming pointer's alignment first with '@alignOf(T)' and '@ptrToInt()' modulo, or use 'std.mem.bytesAsValue' which handles unaligned reads safely; document the invariant that guarantees alignment in a comment directly above the cast.

RISK: Running subprocesses inside build.zig enables arbitrary code execution during compilation (supply-chain vector). FIX: Verify the command is strictly necessary, pin its path, and never pass attacker-controlled data.

RISK: Without 'minimum_zig_version' the package silently builds on unsupported toolchains, masking breaking changes from 0.14/0.15 (Writergate, Managed→Unmanaged). FIX: Add '.minimum_zig_version = "0.15.1"' (or your actual tested version) to build.zig.zon.

RISK: 'catch unreachable' turns any real error into undefined behavior in ReleaseFast/Small and an easy DoS crash elsewhere. FIX: Handle the error explicitly, use 'catch |err| { ... }', or 'try' and propagate.

When spawning threads, ensure that any shared allocators are wrapped in std.heap.ThreadSafeAllocator to prevent data races and heap corruption.

RISK (CWE-401): allocator.create(T) allocates a single heap object; without an immediate 'defer allocator.destroy(ptr)' or 'errdefer allocator.destroy(ptr)' the object leaks on every normal return or on the error path respectively. FIX: Follow each 'const ptr = try allocator.create(T)' with 'defer allocator.destroy(ptr)' on the next line; use errdefer instead when the pointer must be transferred to a long-lived owner but freed on early-exit failure paths.

Never use DefaultPrng for cryptographic purposes. Use std.crypto.random for an OS-backed CSPRNG.

RISK: Managed 'std.ArrayHashMap' is deprecated in 0.14+ and will be removed; carries a hidden allocator field that complicates auditing. FIX: Use 'std.ArrayHashMapUnmanaged' (renamed to 'std.ArrayHashMap' in 0.15) and pass the allocator explicitly.

RISK: 'std.ChildProcess' was renamed; continued use hides real API and will break on 0.14+. FIX: Migrate to 'std.process.Child' and replace '.exec()' with '.run()'.

RISK: Zig 0.15 'Writergate' deprecated generic std.io readers/writers; old pattern silently drops output when buffers are not flushed. FIX: Use 'std.Io.Writer' with an explicit buffer and call '.flush()' before exit.

Blocked deprecated 'std.mem.copy'. Use '@memcpy' for guaranteed non-overlapping memory or '@memmove' for potentially overlapping memory.

Blocked deprecated 'std.mem.set'. Use the built-in '@memset' instead.

RISK: FixedBufferAllocator returns OutOfMemory when exhausted; handling untrusted sizes with it invites easy DoS and subtle aliasing bugs. FIX: Cap input sizes before allocation and use GeneralPurposeAllocator or ArenaAllocator for variable-sized work.

RISK: Absolute-path open APIs bypass the Dir sandbox and let '..' or symlink inputs escape to arbitrary filesystem locations. FIX: Open a base Dir once and use 'dir.openFile' with relative paths plus '.no_follow = true' when handling untrusted input.

RISK: File-scope 'var' declarations in a file that also exports 'export fn' symbols create implicit global mutable state shared across all callers — any concurrent or re-entrant call (e.g. from bun:ffi across threads) races without synchronisation. FIX: Document the non-thread-safe contract explicitly in the export comment (as in engine.zig: 'Not thread-safe — designed for single-threaded bun:ffi calls from main thread'); for thread-safe use, protect globals with a Mutex or migrate state into a caller-allocated context struct passed through the C ABI.

RISK: 'std.mem.eql' short-circuits on first mismatch and leaks byte-level timing info when comparing MACs, tokens, or password hashes. FIX: Use 'std.crypto.timing_safe.eql' for any secret comparison.

RISK (CWE-120/CWE-787): @memcpy with a many-pointer '[*]T' source or destination does not carry a length — if the length argument is not first validated against the actual allocation size (e.g. from a C-ABI rules_len parameter), the copy can read or write past the allocation boundary. FIX: Convert the many-pointer to a bounded slice before passing to @memcpy: 'ptr[0..validated_len]'; never derive the length from an untrusted external field without a prior bounds check against the known allocation.

Directly opening files from cwd() with untrusted input can lead to path traversal. Prefer opening a Dir handle to a sandbox folder and using dir.openFile() to restrict access.

RISK (CWE-78): std.process.Child spawns an OS process; if any element of the argv slice is derived from untrusted or user-controlled input without allow-list validation, an attacker can inject arbitrary shell commands or path traversal sequences. FIX: Treat every argv slot as untrusted — validate against a strict allow-list of known-safe values, pin the executable path to an absolute compile-time constant, and never interpolate user strings into command arguments without explicit sanitization.

RISK (CWE-466/CWE-587): @ptrFromInt and @intFromPtr break pointer provenance — the derived pointer is not provably from a live allocation, may be misaligned, and causes undefined behaviour in safe builds and silent corruption in ReleaseFast/Small. FIX: Work exclusively with typed slices and references; confine any FFI address boundary to a single narrowly-scoped wrapper function that documents its alignment guarantee and asserts it with @alignOf before use.

RISK: Setting a TLS client's ca_bundle to '.none' disables certificate verification, permitting trivial MITM against 'std.crypto.tls' / 'std.http.Client'. FIX: Load the system bundle via 'std.crypto.Certificate.Bundle.rescan' or pin a specific root certificate.

RISK (CWE-190/CWE-197): @truncate silently discards the high bits of the source value — if that value originates from untrusted input (e.g. a wire-format length field or an FFI return), the truncated result is a latent integer-overflow or out-of-bounds index vector. FIX: Validate that the value fits in the destination type first (e.g. 'if (value > std.math.maxInt(DestType)) return error.Overflow') or replace with 'std.math.cast(DestType, value) catch return error.Overflow' for a checked, fallible narrowing path.

std.http.Server is intended for testing and can be vulnerable to DoS attacks. Ensure it is behind a robust reverse proxy in production.

Ignoring error returns (e.g. `_ = trySomething()`) can leave the system in an inconsistent or insecure state if an operation fails.

Using page_allocator directly is discouraged for general use. Prefer GeneralPurposeAllocator for development (catches leaks/UAF) or ArenaAllocator.

RISK: ReleaseFast (and ReleaseSmall) strip bounds checks, integer-overflow checks, and 'std.debug.assert', re-enabling classic memory-safety bugs. FIX: Default to ReleaseSafe for network-facing or untrusted-input code; reserve ReleaseFast for hot paths with independent fuzzing.

Using 'undefined' can lead to non-deterministic behavior and information leaks if used improperly. Ensure memory is initialized before read or use secureZero for crypto.

RISK: MD5 and SHA-1 are collision-broken and unsuitable for signatures, certificates, or integrity checks. FIX: Use 'std.crypto.hash.sha2.Sha256' or 'std.crypto.hash.Blake3'; keep MD5/SHA-1 only for legacy interop tests.

RISK (CWE-401): allocator.alloc() without a matching defer allocator.free(buf) or errdefer allocator.free(buf) leaks memory on every success or error path respectively. FIX: Immediately follow every const buf = try allocator.alloc(...) with defer allocator.free(buf); use errdefer when the buffer must outlive the current scope but be freed on failure paths.

RISK (CWE-125/CWE-787): extern C function declarations bypass all Zig safety checks \u2014 the callee can read or write out-of-bounds if pointer or length arguments are not validated before the call. FIX: Wrap every extern fn in a safe Zig function that validates all length parameters against actual slice bounds before forwarding; return an error union or optional rather than passing raw unchecked pointers from untrusted input.

RISK (CWE-190/CWE-197): @intCast truncates silently in ReleaseFast/Small and panics in safe builds \u2014 either path is wrong for attacker-controlled sizes or offsets. FIX: Replace narrowing conversions with std.math.cast(DestType, value) catch ... for a fallible checked path; if the value is provably in-range, document the invariant in a comment directly above the cast.

RISK (CWE-466/CWE-587): @intToPtr and @ptrToInt are Zig 0.12-era names superseded by @ptrFromInt and @intFromPtr in 0.13+; the old names are a compile error on current toolchains. Even with the correct names, raw integer-to-pointer casts break provenance and cause undefined behaviour if the address is misaligned or not from a live allocation. FIX: Work with typed slices throughout; isolate any FFI integer-address boundary in a single narrowly-scoped wrapper that documents alignment and provenance guarantees.

RISK (CWE-704/CWE-843): @ptrCast reinterprets a pointer type with no runtime check \u2014 misaligned or wrong-type casts produce undefined behaviour that Zig cannot catch in ReleaseFast/Small. FIX: Use std.mem.bytesAsValue or std.mem.bytesAsSlice for byte-buffer reinterpretation; pair every @ptrCast with an explicit @alignCast verified against @alignOf, and add a comment explaining the invariant that makes the cast safe.

RISK (CWE-617): A bare unreachable in library or engine code is undefined behaviour in ReleaseFast/Small and an immediate abort in safe builds \u2014 either is a DoS vector if reachable via attacker-controlled input. FIX: Replace with an explicit error return (return error.UnexpectedState) so callers can recover; keep unreachable only inside comptime blocks or switch arms that are formally exhaustive by type.