memory-safety

name	memory-safety
description	Run AddressSanitizer and UndefinedBehaviorSanitizer on the Z3 test suite to detect memory errors, undefined behavior, and leaks. Logs each finding to z3agent.db.

Build Z3 with compiler-based sanitizer instrumentation, execute the test suite, and parse the runtime output for memory safety violations. Supported sanitizers are AddressSanitizer (heap and stack buffer overflows, use-after-free, double-free, memory leaks) and UndefinedBehaviorSanitizer (signed integer overflow, null pointer dereference, misaligned access, shift errors). Findings are deduplicated and stored in z3agent.db for triage and longitudinal tracking.

Step 1: Configure and build

Action: Invoke the script with the desired sanitizer flag. The script calls cmake with the appropriate -fsanitize flags and builds the test-z3 target. Each sanitizer uses a separate build directory to avoid flag conflicts.

Expectation: cmake configures successfully and make compiles the instrumented binary. If a prior build exists with matching flags, only incremental compilation runs.

Result: On success: an instrumented test-z3 binary is ready in the build directory. Proceed to Step 2. On failure: verify compiler support for the requested sanitizer flags and review cmake output.

python3 scripts/memory_safety.py --sanitizer asan
python3 scripts/memory_safety.py --sanitizer ubsan
python3 scripts/memory_safety.py --sanitizer both

To reuse an existing build:

python3 scripts/memory_safety.py --sanitizer asan --skip-build --build-dir build/sanitizer-asan

Step 2: Run and collect

Action: Execute the instrumented test binary with halt_on_error=0 so all violations are reported rather than aborting on the first.

Expectation: The script parses AddressSanitizer, UndefinedBehaviorSanitizer, and LeakSanitizer patterns from combined output, extracts source locations, and deduplicates by category/file/line.

Result: On clean: no violations detected. On findings: one or more violations found, each printed with severity, category, message, and source location. On timeout: test suite did not finish; increase timeout or investigate. On error: build or execution failed before sanitizer output.

python3 scripts/memory_safety.py --sanitizer asan --timeout 900 --debug

Step 3: Interpret results

Action: Review printed findings and query z3agent.db for historical comparison.

Expectation: Each finding includes severity, category, message, and source location. The database query returns prior runs for trend analysis.

Result: On clean: no action required; proceed. On findings: triage by severity and category. Compare against prior runs to distinguish new regressions from known issues. On timeout: increase the deadline or investigate a possible infinite loop. On error: inspect build logs before re-running.

Query past runs:

python3 ../../shared/z3db.py runs --skill memory-safety --last 10
python3 ../../shared/z3db.py query "SELECT category, severity, file, line, message FROM findings WHERE run_id IN (SELECT run_id FROM runs WHERE skill='memory-safety') ORDER BY run_id DESC LIMIT 20"

Parameters

Parameter	Type	Required	Default	Description
sanitizer	choice	no	asan	which sanitizer to enable: asan, ubsan, or both
build-dir	path	no	build/sanitizer-{name}	path to the build directory
timeout	int	no	600	seconds before killing the test run
skip-build	flag	no	off	reuse an existing instrumented build
debug	flag	no	off	verbose cmake, make, and test output
db	path	no	.z3-agent/z3agent.db	path to the logging database