Analysis Architecture

aurora-lint uses a multi-pass analysis architecture:

Source Files
    |
    v
[Tree-sitter Parser] --> AST (per-file)
    |
    v
[Pre-scan Pass] --> Cross-file context (function defs, summaries, macros,
    |                 struct types, global states, call graph, call-site args)
    v
[CFG Construction] --> Per-function control-flow graphs
    |
    v
[Dataflow Analysis] --> Null state, value range, reaching defs, init state
    |
    v
[Rule Evaluation] --> 307 CERT C rules applied to AST + CFG + context
    |
    v
[Suppression Filter] --> Hash-based + wildcard (glob/prefix) suppression
    |
    v
[Export] --> SARIF, JSON

Analysis Modules

Tree-sitter parsing (src/analyze/mod.rs).

Fast, incremental, error-tolerant C parsing. Each .c file is parsed into an AST; the orchestrator coordinates prescan, CFG construction, dataflow, and per-rule evaluation with optional Rayon parallelism.

Cross-file pre-scan (src/analyze/prescan.rs, context.rs).

Walks the -d directories (or, with no -d, the scan target itself) collecting function definitions, header prototypes, function summaries, call graphs, macro constants/aliases, struct field types, global constants, and global pointer null states. Second pass aggregates call-site argument null states and propagates transitive frees through parameter pass-through chains (max 8 iterations). Results stored in ProjectContext, optionally cached to binary (--save-prescan / --load-prescan). Consumed by 15+ rules.

Function summaries (src/analyze/function_summary.rs).

Lightweight inter-procedural summaries computed during prescan: frees_params, can_return_null, returns_allocation, checks_null_params, modifies_params, dereferences_params, never_returns, callsite_param_null_states (aggregated from all call sites), callsite_param_field_null_states (struct field propagation), callsite_param_pointee_null_states (pointer-to-pointer propagation), return_range (VRA inter-procedural), param_passthroughs (transitive free tracking). Consumed by 7 rules.

Control-flow graphs (src/analyze/cfg.rs).

Per-function CFG with basic blocks, typed edges (Fallthrough, TrueBranch, FalseBranch, BackEdge, Return, Break, Continue, Goto), and condition_range metadata for path-sensitive edge refinement. Optional macro-constant-aware construction for dead-branch elimination. Consumed by 8 rules (INT30/31/32/33/34-C, EXP33/34-C, MEM01-C).

Null state dataflow (src/analyze/null_state.rs).

Forward dataflow on CFG with NullState lattice (Unknown → DefinitelyNull / PossiblyNull / NotNull). Edge refinement on branch conditions supports compound || / && expressions. Seeded from global pointer states, call-site parameter states, and function summaries. Primary consumer: EXP34-C; also used by API00-C.

Value range analysis (src/analyze/value_range.rs).

CFG-based forward value-range dataflow for integer variables. Tracks TypedRange (interval + signedness/bit-width) per variable. Handles sequential assignments, conditional narrowing, loop bounds, and early-return guards. Inter-procedural return ranges from function summaries. Consumed by INT30/31/32/33/34-C.

Constant evaluation (src/analyze/const_eval.rs).

Syntactic constant folding of #define macro constants and arithmetic expressions. Includes built-in C99 <limits.h>/<stdint.h> macros (LP64 model). try_evaluate_range() computes value ranges from constants + variables + loop bounds via ancestor walks. Consumed by 11 rules (INT, ENV, ERR, FIO, FLP, STR families).

Reaching definitions (src/analyze/dataflow.rs).

Standard iterative worklist algorithm computing which definitions (Declaration, Assignment, Parameter, NullAssignment, FreeCall, NullableCall) reach each program point. Supports use-after-free and null dereference queries. Primary consumer: MEM01-C.

Initialization state (src/analyze/init_state.rs).

Forward dataflow tracking initialization status with malloc-aware semantics (Uninitialized, MaybeUninitialized, Initialized, MallocUninitialized, MallocInitialized). Detects partial-init patterns in loops. Primary consumer: EXP33-C.

Macro-expansion engine (src/analyze/macro_expand.rs).

Registry-based, name-independent modeling of function-like macro bodies — not a per-macro name allowlist. collect_function_macros + FunctionMacro back a growing set of shape predicates regardless of the macro’s name (as of this writing: output-param writes, the “safe free” free+null idiom, generic writes, forwarding to another macro, plain frees, clears, and callee-released-parameter detection — see the file’s own pub fn list for the current, authoritative set rather than trusting a count here). Consumed by 24 rules: ARR30-C, DCL13-C, DCL16-C, DCL18-C, DCL31-C, DCL41-C, EXP10-C, EXP33-C, EXP34-C, EXP36-C, INT32-C, INT34-C, MEM03-C, MEM12-C, MEM30-C, MEM31-C, MSC13-C, MSC37-C, PRE05-C, PRE30-C, PRE31-C, PRE32-C, SIG30-C, and WIN05-C. Before adding a name-heuristic workaround for a macro-opacity false positive, check whether this engine already covers it — see docs/design/macro-expansion.md for the full design rationale and a per-rule disposition table.

Standard function database (src/utility/cert_c/std_functions.rs).

~370 C11, POSIX, and Windows API functions recognized to suppress false positives on standard library calls (DCL31-C, DCL07-C).

Call-role classification (src/utility/cert_c/call_roles.rs).

Single-source-of-truth predicates layered on top of the standard function database for “what role does this call play” (is_allocator_call, is_heap_allocator, is_printf_family, is_scanf_family, is_sizeof_text), replacing 7+ independently reinvented, disagreeing per-rule lists found by a ruleset-wide duplication sweep.

Arithmetic-overflow-detection helpers (src/utility/cert_c/overflow_helpers.rs).

Shared type-map-building and identifier/operand-extraction primitives for INT30-C/INT32-C (and one primitive each for INT10-C), replacing ~20 identically-named private helpers duplicated across those two ~2800-line files — the largest duplicated surface found by that same sweep. The overflow-guard-detection logic itself (has_overflow_check_*) stays rule-local: it only looks duplicated: INT30-C’s is unsigned-wraparound-focused and INT32-C’s is signed-overflow-focused.

Floating-point type inference (src/utility/cert_c/float_typing.rs).

Word-boundary-aware float classification of type spellings and literals (is_float_type, is_float_literal) and the collect_variable_types name map, shared by the FLP rule family; and expr_is_float, which types an expression by declaration through expr_type and is the floating test of INT30-C, INT32-C and INT33-C. A follow-up migrated 3 of the 9 flagged rules (FLP02-C, FLP34-C, FLP37-C); the other 6 turned out to check genuinely different concepts (format specifiers, long double specifically, a more comprehensive extended-float set) and correctly stay rule-local.

Internal capability catalog (docs/design/internal-capability-catalog.md).

A browsable-by-concept catalog of every reusable primitive in src/utility/cert_c/*.rs and src/analyze/*.rs (macro detection, declarator resolution, lvalue/aliasing, constant folding/VRA, CFG, function summaries, suppression, cross-file ProjectContext). Skim it before writing any new AST/text heuristic in a rule file – filed after a near-duplication of DCL40-C’s macro-detection helpers in MSC12-C.

Suppression system (src/analyze/suppression.rs).

Inline // AURORA-SUPPRESS comments and suppress.toml files (the pre-rename SQC-SUPPRESS / .sqc-suppress.toml spellings still parse). SHA-256 hash-based point suppressions and glob/prefix wildcard suppressions.

Current Capabilities

Capability

Implementation

Local variable/type inference

Per-function collect_variable_types

Preprocessor block traversal

preproc_* node recursion

Standard function database

~370 C11/POSIX/Windows functions

Cross-file function scanning

-d flag pre-scan with binary cache

CFG construction

Per-function with condition_range metadata

Reaching definitions

Iterative worklist dataflow (MEM01-C)

Inter-procedural summaries

Null returns, freed params, no-return, return ranges, dereferences, pass-throughs

CFG-based null state dataflow

Forward dataflow with NullState lattice, compound condition support, global/call-site seeding

Value range analysis

CFG-based forward dataflow, inter-procedural return ranges, type-aware intervals

Initialization state analysis

Forward dataflow with malloc-aware semantics

Constant evaluation

Macro resolution, built-in limits, sizeof types

Macro-expansion engine (registry)

Name-independent free+null and output-param macro body modeling (MEM30/31-C, EXP33-C, DCL31-C)

Call-site null propagation

Aggregated argument states across all callers

Transitive free propagation

Parameter pass-through chains + field-sensitive custom-deallocator credit (MEM31-C)

Global pointer null state

Cross-file extern pointer tracking (EXP34-C)

Struct field type resolution

Prescan-collected struct definitions

Taint tracking

Intra-function (FIO30-C, STR02-C)

Dead-branch elimination

Macro-constant-aware CFG construction

Known Limitations

Gap

Impact

No general macro expansion

Arbitrary macro bodies are not expanded. A registry-based engine (macro_expand.rs, see above) name-independently recognizes a growing set of shapes for 24 rules; outside those shapes macros are still opaque function calls, partially mitigated by collect_macro_aliases for constant-valued macros

No alias analysis

Pointer aliasing unresolved; field-scoped alias collection causes cross-function issues

No symbolic execution

Complex path conditions not evaluated

No SSA form

No use-def chains beyond reaching definitions

VRA intra-procedural only

Inter-procedural argument ranges and field-sensitive VRA not implemented; return ranges available

Limited taint tracking

Intra-function only (STR02-C, FIO30-C); cross-function taint for injection CWEs planned

Struct field tracking limited

Prescan-visible structs only (INT32-C/INT30-C); no field-level free or null tracking

No ownership model

Same-function ownership transfer (allocate + custom deallocator) is credited, but parameter-owned vs. locally-owned struct lifetimes are not distinguished; dominant remaining MEM31-C real-world FP source

Known departures from the labeling ADRs. Where detection still contradicts ADR-0005 (misfires), ADR-0006 (resolve identifiers, not spelling), ADR-0010 (every compilable configuration counts) or ADR-0011 (what counts as proof), the place is listed in docs/design/adr-conformance.md: the code, the shortcut, and whether a fix adds or removes findings. A published per-rule figure for a rule with an open row there carries that caveat.

No build input is required. The gaps above are what analyzing source alone costs, and the tool accepts that cost rather than depending on a build. A compile database, -I/-D flags and declared environment facts only refine results. With none of them, each rule takes its strict reading of the source as found, and gives no credit the source alone can’t prove. ADR-0015 Decision 3 (docs/adr/0015-default-and-strict-profiles.md) states the principle and the tests that keep it true.

Architectural Ceiling

Current TP rate: 83.8% (Juliet, v0.4.116, 74 CWEs; up from 67.5% at v0.3.119). CWE-190/191 (integer overflow) and CWE-476 (null dereference) have since moved substantially with VRA and null-state work; the remaining gaps are concentrated in a smaller set of CWEs still requiring deeper analysis:

  • CWE-190 (integer overflow): 100.0% — resolved via value-range analysis.

  • CWE-191 (integer underflow): 98.5% (was 55.3%) — same VRA work.

  • CWE-476 (null dereference): 67.9% (was 61.9%) vs clang-tidy 94.3%. Requires deeper inter-procedural null propagation and alias analysis.

  • CWE-121 (stack buffer overflow): 71.0% (was 57.5%) vs clang-tidy 86.6%. Requires symbolic buffer size tracking across assignments.

  • CWE-369 (divide by zero): 57.8% (was 56.0%) vs clang-tidy 94.7%. Requires stronger zero-value tracking through assignments; largely unmoved despite the VRA/alias investment that lifted 190/191/476/121.

Alias analysis and field-sensitive value tracking remain the two capabilities most likely to close the remaining gap, particularly for CWE-369 and the residual CWE-121/476 share tied to pointer aliasing.

Competitor Landscape

5-tool comparison on 15 overlapping Juliet CWEs (28,488 files):

Tool

Detection Rate

FP Rate

Analysis Depth

Price

clang-tidy

91.6%

0.8%

AST + path-sensitive

Free

aurora-lint

67.5%

32.5%

AST + CFG + inter-procedural

–

Frama-C

61.0%

39.0%

Abstract interpretation

Free

Infer

43.6%

56.4%

Separation logic

Free

cppcheck

36.4%

63.6%

Data-flow

Free

aurora-lint row is from the v0.3.119 Juliet benchmark, held fixed here because the other four tools were not re-run at v0.4.116 — this table is a frozen snapshot of a one-time comparative study, not a continuously re-measured figure. aurora-lint’s own overall TP rate has since risen to 83.8% (see above); it is not directly comparable to the 67.5% row without re-running the other four tools on the same 15-CWE, 28,488-file slice.

aurora-lint achieved 100% precision (zero FP) on 48 of 74 benchmarked CWEs as of v0.4.116 (a frozen figure from this study, not re-measured since; see README.md’s Benchmark Highlights for the current 100%-precision-CWE count), including CWE-690, CWE-761, CWE-78, and CWE-190. Broadest CWE coverage (74+ CWEs benchmarked vs clang-tidy’s 15 in the frozen study above).

Key context: on real-world vulnerabilities, even the best single C analyzer studied misses between 47% and 80%, depending on the evaluation scenario (Lipp2022); in another study, 27% of C/C++ vulnerabilities were missed by all three commercial tools tested (Goseva2015). From a developer survey, Christakis and Bird recommend that analysis designers aim for a false-positive rate no higher than 15–20%; only 24% of respondents accepted 20% (Christakis2016). See Bibliography for full references.