ConstantGuard is a static analysis research prototype for detecting timing side-channel risks in cryptographic C code. The repository is intended for research, benchmarking, and reproducible evaluation. It is not production-ready security tooling.
ConstantGuard combines five analysis stages:
- Semantic analysis over CFG and AST-derived metadata.
- Forward taint propagation with a three-level lattice (
PUBLIC,SECRET,UNKNOWN). - Pattern-based detection for known timing-leak idioms.
- Optional SMT-based cross-checking with Z3.
- Deduplication plus conservative false-positive filtering when stronger evidence is available.
Detected vulnerability classes:
secret_dependent_branchsecret_dependent_loop_boundcache_timing_leaksecret_dependent_memory_accessvariable_time_operationpotential_spectre_gadget
Latest benchmark run reproduced on March 10, 2026:
- Detection-level precision:
66.67% - Detection-level recall:
69.66% - Detection-level F1:
68.13% - Detection-level counts:
TP=62,FP=31,FN=27 - Function-level accuracy:
92.86% - Function-level false-positive rate:
12.12% - Function-level counts:
TP=49,FP=4,TN=29,FN=2
Generalization checks:
- Naming holdout delta:
0.0 ppF1 - External holdout precision:
100.00% - External holdout recall:
100.00% - External holdout F1:
100.00%
Baseline comparison:
- Full ConstantGuard F1:
68.13% - Rule baseline F1:
56.14% - Improvement:
+11.99 pp
Performance snapshot from the February 27, 2026 reference run:
- Total LOC analyzed:
81,542 - Total analysis time:
31.99s - Average throughput:
2,869 LOC/s - Peak RSS observed:
131.66 MB
See RESULTS.md for the detailed metric breakdown.
ConstantGuard/
analyzer.py
src/
benchmarks/
experiments/
scripts/
README.md
REPRODUCIBILITY.md
RESULTS.md
CONTRIBUTING.md
Notes:
benchmarks/generated/is intentionally ignored from version control. Performance experiments recreate synthetic inputs on demand.experiments/results/keeps curated canonical reports.experiments/plots/keeps the curated public plots generated from those reports.
Full environment:
pip install -r requirements.txtMinimal runtime environment:
pip install -r requirements-min.txtRecommended Python: 3.10+
Analyze one file:
python analyzer.py benchmarks/vulnerable_examples.cExport JSON:
python analyzer.py benchmarks/vulnerable_examples.c --format json --output report.jsonEnable SMT mode:
python analyzer.py benchmarks/vulnerable_examples.c --smtGenerate SARIF:
python analyzer.py benchmarks/vulnerable_examples.c --format sarif --output report.sarif0: analysis completed and no vulnerabilities were reported1: vulnerabilities were reported, or the analysis failed
For CI usage, treat 1 as "findings or failure" and inspect JSON or SARIF output to disambiguate.
Run the full evaluation pipeline:
python experiments/run_all_evaluations.pyOr run steps individually:
python experiments/evaluate_benchmark.py
python experiments/evaluate_holdout_naming.py
python experiments/evaluate_external_holdout.py
python experiments/evaluate_rule_baseline.py
python experiments/analyze_error_attribution.py
python experiments/performance_benchmark.py
python experiments/generate_plots.pySee REPRODUCIBILITY.md for expected outputs and metrics.
CVE-2013-0169(Lucky Thirteen): missedCVE-2016-2107(AES-NI padding oracle): detectedCVE-2016-0702(RSA CRT timing): partial detectionCVE-2017-5715(Spectre v1): partial detectionCVE-2011-1945(ECDSA timing): detected
- Intra-procedural analysis only
- No industrial-strength C front-end
- Secret parameter inference is heuristic
- Pattern components can still generate false positives
- SMT mode is experimental
Recommended:
- research prototypes and empirical studies
- educational use for timing-side-channel patterns
- early-stage security review support with manual validation
Not recommended:
- fully automated production CI gating
- compliance-only evidence without manual review
See CONTRIBUTING.md.
MIT. See LICENSE.