Alias Analysis Tools

This page documents the command-line tools under tools/alias/. For the underlying algorithms and architecture, see Alias Analysis Components.

SparrowAA (lotus-alias-sparrow-aa)

Inclusion-based points-to analysis (flow-insensitive, field-sensitive, with context-insensitive and k-CFA variants).

Binary: lotus-alias-sparrow-aa Location: tools/alias/lotus-alias-sparrow-aa.cpp

Usage:

./build/bin/lotus-alias-sparrow-aa [options] input.bc

Key Options:

  • --andersen-k-cs=<k> – Select call-site sensitivity (0 <= k <= 32; 0 = context-insensitive, default)

  • --andersen-adaptive-cs – Enable adaptive context sensitivity via HVN feedback

  • --andersen-adaptive-cs-threshold=<score> – Context-need score threshold in [0,1] (default: 0.5)

  • --print-pts – Print points-to information for all pointers

  • --print-globals-only – Print points-to information for global variables only

  • --print-alloc-sites – Print all allocation sites identified

  • --print-alias-queries – Perform and print alias queries between pointers

  • --print-context-need – Print per-function adaptive-CS context-need scores

  • --enable-hvn, --enable-hu, --enable-hcd, --enable-lcd – Constraint optimizations

  • -v – Verbose output

  • -s – Only output statistics

Notes:

  • Flow-insensitive, field-sensitive pointer analysis

  • Supports context-insensitive and context-sensitive (k-CFA) modes

  • No on-the-fly call graph construction

  • Fast baseline for points-to and alias queries

TPA (lotus-alias-tpa)

Flow- and context-sensitive pointer analysis using semi-sparse representation with k-limiting support.

Binary: lotus-alias-tpa Location: tools/alias/lotus-alias-tpa.cpp

Usage:

./build/bin/lotus-alias-tpa [options] input.bc

Key Options (see also TPA: Flow- and Context-Sensitive Pointer Analysis):

  • -ext <file> – External pointer table file for modeling library functions

  • -no-prepass – Skip TPA IR normalization prepasses (GEP expansion, etc.)

  • -prepass-out <file> – Write module after prepass to file (suffix .ll or .bc)

  • -cfg-dot-dir <dir> – Write per-function pointer CFGs as .dot files into directory

  • -print-pts – Print points-to sets for pointers materialized by the analysis

  • -print-indirect-calls – Print resolved targets for each indirect call

Characteristics:

  • Flow-sensitive: tracks control flow within functions

  • Context-sensitive: supports k-limiting and adaptive context strategies

  • Semi-sparse representation: only analyzes def-use chains, not all program points

  • Field-sensitive memory model: models individual struct fields and array elements

Examples:

# Basic analysis
./build/bin/lotus-alias-tpa input.bc

# With external pointer table and output CFG graphs
./build/bin/lotus-alias-tpa -ext ext_table.txt -cfg-dot-dir cfgs/ input.bc

# Print points-to sets and indirect call targets
./build/bin/lotus-alias-tpa -print-pts -print-indirect-calls input.bc

# Skip prepass and save preprocessed IR
./build/bin/lotus-alias-tpa -no-prepass -prepass-out preprocessed.bc input.bc

AserPTA (lotus-alias-aser-aa)

High-performance constraint-based pointer analysis with multiple context sensitivities and solver algorithms.

Binary: lotus-alias-aser-aa Location: tools/alias/lotus-alias-aser-aa.cpp

Usage:

./build/bin/lotus-alias-aser-aa [options] input.bc

Key Options (see also Alias Analysis Components):

  • Analysis mode:

    • -analysis-mode=ci – Context-insensitive (default)

    • -analysis-mode=1-cfa – 1-call-site sensitive

    • -analysis-mode=2-cfa – 2-call-site sensitive

    • -analysis-mode=origin – Origin-sensitive (thread creation)

  • Solver:

    • -solver=basic – PartialUpdateSolver

    • -solver=wave – WavePropagation with SCC detection (default)

    • -solver=deep – DeepPropagation with cycle-aware propagation

  • Other:

    • -field-sensitive[=true|false] – Field-sensitive memory model

    • -dump-stats – Print analysis statistics

    • -consgraph – Dump constraint graph (DOT)

    • -dump-pts – Dump points-to sets

Example:

# 1-CFA with deep solver
./build/bin/lotus-alias-aser-aa -analysis-mode=1-cfa -solver=deep input.bc

FlowSensitivePTA (lotus-alias-fspta)

Flow-sensitive pointer-analysis driver. The fspta and vfspta modes build the Lotus SVFG/MemorySSA from an ICFG and solve sparse memory state. The vfpta mode instead builds a field-insensitive value-flow graph directly from LLVM IR.

Binary: lotus-alias-fspta Location: tools/alias/lotus-alias-fspta.cpp

Usage:

./build/bin/lotus-alias-fspta [options] input.bc

Key Options (see also Flow-Sensitive Pointer Analysis):

  • --analysis=fspta|vfspta|vfpta – Conventional sparse (default), object-versioned, or direct value-flow analysis

  • --points-to-sets=mutable|hash-consed – Points-to set backend for fspta

  • --memory-partition=distinct|intra-disjoint|inter-disjoint – MemorySSA region partition strategy for fspta and vfspta

  • --print-pts – Print top-level points-to results

  • --print-memory – Print non-empty sparse memory facts (fspta and vfspta only)

  • --dump-stats – Print solver statistics (default on)

  • --dump-svfg=<file> – Write the initialized SVFG as a DOT file (fspta and vfspta only)

  • --validate-annotations – Validate __aser_alias__/__aser_no_alias__ calls

Examples:

# Conventional sparse flow-sensitive analysis
./build/bin/lotus-alias-fspta input.bc

# Object-versioned analysis with points-to output
./build/bin/lotus-alias-fspta input.bc --analysis=vfspta --print-pts

# Direct value-flow analysis
./build/bin/lotus-alias-fspta input.bc --analysis=vfpta --print-pts

# Hash-consed points-to sets and SVFG dump
./build/bin/lotus-alias-fspta input.bc --points-to-sets=hash-consed --dump-svfg=fspta.dot

BootstrapAA (lotus-alias-bootstrap)

Bootstrapped flow- and context-sensitive points-to analysis. It combines a Steensgaard coarse partition, thresholded Andersen refinement, dependency slicing, and per-cluster input-state summary tabulation.

Binary: lotus-alias-bootstrap

Usage:

./build/bin/lotus-alias-bootstrap [options] input.bc

Key options:

  • --entry=<function> - Select a defined analysis entry (default main)

  • --all-contexts - Print results joined across reachable contexts

  • --andersen-threshold=<N> - Refine coarse partitions larger than N

  • --adaptive-threshold=<bool> - Enable observed-benefit threshold adaptation

  • --max-andersen-partition=<N> - Bound adaptive refinement input size

  • --max-andersen-work=<N> - Bound partition-by-hierarchy refinement work

  • --parallel-clusters=<bool> - Enable independent cluster workers

  • --threads=<N> - Set worker count; zero uses hardware concurrency

  • --precompute-clusters - Eagerly construct all cluster solvers

  • --max-contexts=<N> - Bound input-state summary contexts per cluster

  • --max-steps=<N> - Bound refinement steps per cluster

  • --detailed-stats - Print partition, cluster, and per-cluster timing data

Without --all-contexts, the tool prints pointer-producing instructions in the entry activation. Resource-limit fallbacks are explicitly marked and make the tool exit with status 2. See BootstrapAA for API and model details.

CclyzerAA (lotus-alias-cclyzer-aa)

Datalog-based pointer analysis frontend backed by the in-tree vendored cclyzer++ engine using Soufflé.

Binary: lotus-alias-cclyzer-aa (requires -DLOTUS_ENABLE_CCLYZER=ON) Location: tools/alias/lotus-alias-cclyzer-aa.cpp

Usage:

./build/bin/lotus-alias-cclyzer-aa [options] input.bc

Key options:

  • -analysis=subset|unification|debug – Analysis kind (default: subset)

  • -context-sensitivity=insensitive|1-cfa|2-cfa|3-cfa|1-caller|2-caller – Context sensitivity mode

  • -print-pts – Print points-to sets for functions and global variables

  • -print-cg – Print resolved indirect call graph edges

  • -print-nulls – Print values identified as null pointers

  • -check-assertions – Verify Datalog consistency assertions

See CclyzerAA for architecture and C++ API details.

Call Graph Construction (lotus-alias-call-graph)

Unified call-graph construction tool that can drive several underlying pointer or call-graph analyses.

Binary: lotus-alias-call-graph Location: tools/alias/lotus-alias-call-graph.cpp

Usage:

./build/bin/lotus-alias-call-graph -cg-type=dyck input.bc
./build/bin/lotus-alias-call-graph -cg-type=lotus -emit-cg-as-json input.bc

Key options:

  • -cg-type=dyck|lotus|fpa-flta|fpa-mlta|fpa-mltadf|fpa-kelp|aserpta-ci|aserpta-1cfa|aserpta-2cfa

  • -emit-cg-as-dot or -emit-cg-as-json

  • -o <file> – output destination

  • -S – compute graph statistics and write them to standard error

DOT is the default when no format option is present. Selecting JSON suppresses that implicit DOT output, so the output remains valid JSON.

DyckAA (lotus-alias-dyck-aa)

Unification-based alias analysis using Dyck-CFL reachability.

Binary: lotus-alias-dyck-aa Location: tools/alias/lotus-alias-dyck-aa.cpp

Usage:

./build/bin/lotus-alias-dyck-aa [options] input.bc

Key Options:

  • -print-cg – Print call graph statistics

  • -v – Verbose output

  • -s – Only output statistics

  • -print-alias-set-info – Print alias sets and relations (DOT)

  • -count-fp – Count possible targets for each function pointer

  • -dot-dyck-callgraph – Generate call graph from alias results

  • -function-type-check-level=<0-4> – Strictness of function type compatibility checking (default 4)

Typical Use:

# Dump alias sets and Dyck-based call graph
./build/bin/lotus-alias-dyck-aa -print-alias-set-info -dot-dyck-callgraph input.bc

LotusAA (lotus-alias-lotus-aa)

Lotus-specific, flow-sensitive and field-sensitive pointer analysis with on-the-fly call graph construction.

Binary: lotus-alias-lotus-aa Location: tools/alias/lotus-alias-lotus-aa.cpp

Usage:

./build/bin/lotus-alias-lotus-aa [options] input.bc

Key Options:

  • -o <file> – Override output filename

  • -S – Write LLVM assembly instead of bitcode

  • -v – Verbose output

  • -s – Only output statistics

  • -lotus-print-pts – Print points-to results

  • -lotus-print-cg – Print call graph results

  • -lotus-cg – Use LotusAA to build call graph

  • -lotus-restrict-cg-iter=<int> – Maximum iterations for call graph construction

  • -lotus-enable-must-kill – Enable must-kill store pruning (default: true)

Characteristics:

  • Flow-sensitive intra-procedural analysis

  • Inter-procedural summarization and iterative call graph refinement

  • Designed for high precision on smaller/medium programs

FPA (Function Pointer Analysis)

Function pointer analysis toolbox (FLTA, MLTA, MLTADF, KELP) for resolving indirect calls. It is exposed through the unified call-graph driver lotus-alias-call-graph (the former standalone lotus-alias-fpa binary was merged into it).

Binary: lotus-alias-call-graph Location: tools/alias/lotus-alias-call-graph.cpp

Usage:

./build/bin/lotus-alias-call-graph -cg-type=<type> [options] input.bc

Key Options:

  • -cg-type=<type>:

    • fpa-flta – FLTA

    • fpa-mlta – MLTA

    • fpa-mltadf – MLTADF

    • fpa-kelp – KELP (USENIX Security’24)

  • -fpa-max-type-layer=<N> – Maximum type layer for MLTA (default: 10)

  • -fpa-debug – Enable debug output

  • -fpa-dump-targets=<path> – Dump resolved targets (use “cout” for stdout)

Example:

# KELP-based function pointer analysis
./build/bin/lotus-alias-call-graph -cg-type=fpa-kelp -fpa-debug input.bc

See FPA — Function Pointer Analyses (FLTA/MLTA/MLTADF/KELP) for the algorithm-level description.

Sea-DSA Tools

Sea-DSA-based memory graph construction and analysis.

Binaries:

  • lotus-alias-sea-dsa-dg – Simple Sea-DSA driver

  • lotus-alias-seadsa-tool – Advanced Sea-DSA analysis tool

Locations:

  • tools/alias/lotus-alias-sea-dsa-dg.cpp

  • tools/alias/lotus-alias-seadsa-tool.cpp

Usage:

# Basic memory graph generation
./build/bin/lotus-alias-sea-dsa-dg --sea-dsa-dot input.bc

# Advanced analysis with DOT output directory
./build/bin/lotus-alias-seadsa-tool --sea-dsa-dot --outdir=results/ input.bc

Key Options:

  • --sea-dsa-dot – Generate DOT memory graphs

  • --sea-dsa-callgraph-dot – Generate call graph DOT (if enabled)

  • --outdir <DIR> – Output directory for generated artifacts

DynAA (Dynamic Alias Analysis)

Dynamic checker that validates static alias analyses against runtime behavior.

Binaries:

  • dynaa – Driver for running dynamic alias checking workflows

  • dynaa-instrument – Instrument program to log pointer behavior

  • dynaa-check – Compare runtime logs against static AA

  • dynaa-log-dump – Dump binary logs to readable format

Location: tools/alias/dynaa/

Typical Workflow:

# 1. Compile to LLVM bitcode
clang -emit-llvm -c example.cpp -o example.bc

# 2. Instrument the bitcode
./build/bin/dynaa-instrument example.bc -o example.inst.bc

# 3. Build and run the instrumented binary
clang example.inst.bc build/libRuntime.a -o example.inst
LOG_DIR=logs/ ./example.inst

# 4. Check static analysis (e.g., basic-aa) against runtime log
./build/bin/dynaa-check example.bc logs/pts.log basic-aa

# 5. Optionally dump the log
./build/bin/dynaa-log-dump logs/pts.log

Use Cases:

  • Validate soundness/precision of a static alias analysis

  • Investigate mismatches between static and dynamic behavior

  • Support research on alias analysis accuracy

See also the detailed description in tools/alias/dynaa/README.md.