Python: add new shared-SSA-backed SSA adapter (additive) by yoff · Pull Request #21923 · github/codeql

yoff · 2026-06-01T12:04:29Z

Summary

Adds a Python SSA adapter built on the shared CFG and the shared codeql.ssa library. The adapter is additive: existing production analysis continues to use legacy ESSA until the dataflow switch-over in #21925.

The adapter also preserves synthetic normal-exit uses for module-level phi definitions, ensuring that values conditionally assigned at module scope remain visible to module exports and downstream analysis.

Library addition

semmle.python.dataflow.new.internal.SsaImpl instantiates codeql.ssa.Ssa::Make<Location, Cfg, Input> using Python CFG basic-block positions as variable references.
SourceVariable maps to Py::Variable; reads, writes, and deletes are provided by the shared-CFG facade.
Implicit entry definitions cover non-local, captured, global, builtin, and parameter reads where required.
EssaVariable.getAUse() accepts generic SSA definitions, allowing phi definitions to retain synthetic module normal-exit uses.

Tests

library-tests/dataflow-new-ssa/ covers representative definition/use chains and module-exit phi uses.
library-tests/dataflow-new-ssa-vs-legacy/ compares the new SSA with legacy ESSA and reports semantic divergence.

Production impact

None until #21925 enables the adapter in the dataflow library. The legacy ESSA implementation remains the production default in this PR.

Verification

All 367 lib/, src/, and consistency-queries/ queries compile cleanly.
All 641 ControlFlow, PointsTo, dataflow, ESSA, and consistency library tests pass.
Both dataflow-new-ssa test packs pass.
The focused module-exit phi regression test and QL formatting checks pass.

Notes for reviewers

SsaImpl.qll is the only non-test addition. The vs-legacy test provides the most direct view of any semantic differences between the implementations.

Copilot

Pull request overview

Adds an additive, shared-SSA-backed SSA adapter for Python on top of the new shared CFG facade, along with library test packs to validate the new SSA in isolation and against legacy ESSA as preparation for the upcoming dataflow migration.

Changes:

Introduce semmle.python.dataflow.new.internal.SsaImpl (shared-SSA instantiation + ESSA-shaped adapter surface).
Add a new inline-expectations SSA test pack (dataflow-new-ssa) and a “vs legacy ESSA” comparison pack (dataflow-new-ssa-vs-legacy).
Add a Python library change note documenting the new adapter.

Show a summary per file

File	Description
python/ql/test/library-tests/dataflow-new-ssa/test.py	New Python corpus for inline SSA def/use/phi expectations.
python/ql/test/library-tests/dataflow-new-ssa/SsaTest.ql	Inline-expectations driver query for the new SSA adapter.
python/ql/test/library-tests/dataflow-new-ssa/SsaTest.expected	Snapshot of current inline-expectations outcomes.
python/ql/test/library-tests/dataflow-new-ssa-vs-legacy/test.py	Shared corpus used to compare new SSA vs legacy ESSA.
python/ql/test/library-tests/dataflow-new-ssa-vs-legacy/CmpTest.ql	Query comparing def signatures between new SSA and legacy ESSA.
python/ql/test/library-tests/dataflow-new-ssa-vs-legacy/CmpTest.expected	Snapshot of current “def-only-old/new” diffs.
python/ql/lib/semmle/python/dataflow/new/internal/SsaImpl.qll	New shared-SSA-backed SSA adapter and ESSA-shaped compatibility layer.
python/ql/lib/change-notes/2026-05-19-add-shared-ssa.md	Change note entry for the new SSA adapter.

Copilot's findings

Files reviewed: 8/8 changed files
Comments generated: 3

+---
+category: minorAnalysis
+---


Flips the Python dataflow trunk from the legacy CFG (semmle/python/Flow.qll) and legacy ESSA SSA (semmle/python/essa/*) to the new shared CFG facade (semmle.python.controlflow.internal.Cfg) and the new SSA adapter (semmle.python.dataflow.new.internal.SsaImpl), both introduced additively in the preceding PRs in this stack. This is the trunk-flip equivalent of the original draft PR #21894 (kept around as documentation), rebased on top of the four preparatory PRs: P1: Remove AstNode.getAFlowNode() and rewrite callers (#21919). P2: Qualify Flow.qll's AST references with Py:: prefix (#21920). P3: Add new shared-CFG-backed control flow graph (#21921). P4: Add new shared-SSA-backed SSA adapter (#21923). The Python dataflow library (semmle/python/dataflow/new/) now imports the new CFG facade and SSA adapter. All CFG-typed predicates (ControlFlowNode, CallNode, BasicBlock, NameNode, AttrNode, ...) are qualified with the Cfg:: prefix; SSA references switch from EssaVariable/EssaDefinition to SsaImpl::Definition/SourceVariable. GuardNode is redesigned to use the new CFG's outcome-node model (isAfterTrue / isAfterFalse) instead of the legacy ConditionBlock + flipped indirection. Only BarrierGuard<...> is preserved as public API. Framework files (Bottle, FastApi, Django, Tornado, Pyramid, Stdlib, ...) are updated to take CFG nodes from the new facade. A handful of dataflow consistency tweaks for the new CFG: - Augmented-assignment targets are treated as both load and store. - 'from X import *' produces uncertain SSA writes for unknown names. - CFG nodes are canonicalised so dataflow does not see equivalent pre/post-order pairs as distinct nodes. Two AST tweaks for the new CFG: - AstNodeImpl: omit PEP 695 type-parameter names from FunctionDefExpr / ClassDefExpr children. - ImportResolution: drop the legacy essa import. Test churn (~175 files): reblessed library- and query-test .expected files reflect slightly different CFG granularity, different toString output, and a handful of true alert deltas in security queries. Verification: all 367 lib + src + consistency-queries compile clean. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

aschackmull · 2026-07-08T10:42:15Z

+ *   - `WriteDefinition`, `UncertainWriteDefinition`, `PhiNode`
+ *   - the standard SSA predicates (`getAUse`, `getAnUltimateDefinition`, ...).
+ */
+module Ssa = SsaImplCommon::Make<Py::Location, CfgForSsa, SsaImplInput>;


This instantiation provides just the basic SSA construction where most functionality is in raw uncached top-level predicates. If you further instantiate Ssa::MakeSsa then you also get a nice class hierarchy where caching has been handled such that all the member predicates reference cached predicates. The result is intended to provide the public SSA class hierarchy, which can then be exposed as the python SSA.

I made an attempt to do this in d723cb4.

yoff · 2026-07-28T09:13:44Z

(force pushed to rebase on 21921)

yoff · 2026-07-28T14:52:18Z

(Force pushed to now be based on main -- I should start using stacks)

Preparatory refactor for the shared-CFG dataflow migration. Adds the new Python SSA adapter additively, without changing any production behaviour. Library additions: - semmle.python.dataflow.new.internal.SsaImpl — Python SSA implementation built on the new (shared) CFG. Mirrors the Java SSA adapter (java/ql/lib/semmle/code/java/dataflow/internal/SsaImpl.qll): an InputSig is defined in terms of positional (BasicBlock, int) variable references, and the shared codeql.ssa.Ssa::Make<Location, Cfg, Input> module is then instantiated. SourceVariable is the AST-level Py::Variable. Variable references are looked up via the new CFG facade's NameNode.defines/uses/deletes predicates (added in the preceding PR), which themselves are one-line bridges to AST-level Name.defines/uses/deletes. Implicit-entry definitions are inserted for non-local/global/builtin reads, captured variables, and (when needed) parameters. Test additions: - library-tests/dataflow-new-ssa/ — exercises the new SSA over a representative test corpus and checks expected def/use chains. - library-tests/dataflow-new-ssa-vs-legacy/ — runs both new SSA and legacy ESSA over the same corpus and diffs the results, so any semantic divergence shows up as a test failure. Production impact: None. The new SSA adapter has zero callers in lib/ and src/ — the legacy ESSA SSA (semmle/python/essa/*) remains the default. The dataflow library is not migrated yet; that lands in a follow-up PR. Verified by: - All 367 lib + src + consistency-queries compile clean. - All 641 ControlFlow + PointsTo + dataflow + essa + consistency library-tests pass. - Both new dataflow-new-ssa[/vs-legacy] test packs pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- part of the ESSA adapter layer still refers to the raw SSA (now called Impl)

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings June 1, 2026 12:04

yoff requested a review from a team as a code owner June 1, 2026 12:04

github-actions Bot added documentation Python labels Jun 1, 2026

Copilot started reviewing on behalf of yoff June 1, 2026 12:04 View session

Copilot AI reviewed Jun 1, 2026

View reviewed changes

This was referenced Jun 1, 2026

Python: switch dataflow library to new (shared) CFG + SSA #21925

Open

Yoff/python use shared cfg for dataflow #21894

Draft

yoff force-pushed the yoff/python-add-new-cfg-library branch from b547f1b to 370dc98 Compare June 1, 2026 13:27

yoff requested a review from a team as a code owner June 1, 2026 13:27

yoff force-pushed the yoff/python-add-new-ssa branch from 28062e1 to 4d4b916 Compare June 1, 2026 13:28

yoff mentioned this pull request Jun 1, 2026

Python: simplify decorator-detection predicates to pure AST match #21926

Merged

yoff force-pushed the yoff/python-add-new-cfg-library branch from 370dc98 to 0ca4cab Compare June 1, 2026 14:05

yoff force-pushed the yoff/python-add-new-ssa branch from 4d4b916 to 6313e70 Compare June 1, 2026 14:05

yoff marked this pull request as draft June 2, 2026 07:49

yoff force-pushed the yoff/python-add-new-cfg-library branch from 0ca4cab to 99bcded Compare June 2, 2026 08:30

yoff force-pushed the yoff/python-add-new-ssa branch from 6313e70 to e3b9611 Compare June 2, 2026 08:30

yoff force-pushed the yoff/python-add-new-cfg-library branch from 99bcded to 45fef35 Compare June 2, 2026 08:47

yoff force-pushed the yoff/python-add-new-ssa branch from e3b9611 to 9be5c62 Compare June 2, 2026 08:47

yoff force-pushed the yoff/python-add-new-ssa branch from 9be5c62 to 944d56e Compare June 2, 2026 13:48

yoff force-pushed the yoff/python-add-new-cfg-library branch 2 times, most recently from 8ef008e to 57a5cad Compare June 2, 2026 13:56

yoff force-pushed the yoff/python-add-new-ssa branch from b3f1d94 to e51acdc Compare June 24, 2026 08:46

yoff force-pushed the yoff/python-add-new-cfg-library branch from c95c3fe to 4c8e6e3 Compare June 25, 2026 22:20

yoff force-pushed the yoff/python-add-new-ssa branch from e51acdc to 0389e01 Compare June 25, 2026 22:20

yoff force-pushed the yoff/python-add-new-ssa branch from 0389e01 to 6c6af73 Compare June 25, 2026 23:08

yoff force-pushed the yoff/python-add-new-cfg-library branch 2 times, most recently from 05aae21 to eccaccf Compare June 29, 2026 13:25

yoff force-pushed the yoff/python-add-new-ssa branch from 6c6af73 to 7afd645 Compare June 29, 2026 13:25

yoff force-pushed the yoff/python-add-new-cfg-library branch from d68784a to 30c56a8 Compare June 29, 2026 18:05

yoff force-pushed the yoff/python-add-new-ssa branch from 7afd645 to d059bf6 Compare June 29, 2026 18:05

aschackmull reviewed Jul 8, 2026

View reviewed changes

Comment thread python/ql/lib/change-notes/2026-05-19-add-shared-ssa.md Outdated

aschackmull reviewed Jul 8, 2026

View reviewed changes

Comment thread python/ql/lib/semmle/python/dataflow/new/internal/SsaImpl.qll Outdated

aschackmull reviewed Jul 8, 2026

View reviewed changes

github-advanced-security Bot found potential problems Jul 28, 2026

View reviewed changes

yoff mentioned this pull request Aug 19, 2026

Python: fix shared CFG exception-handler reachability #22380

Open

Copilot AI and others added 11 commits August 20, 2026 08:59

Python: remove unnecessary change note

4b0e8f5

Python: remove superflous module

c9c4eef

Python: attempt at instantiating MakeSsa

11d4b52

- part of the ESSA adapter layer still refers to the raw SSA (now called Impl)

Python: fix compilation of test

6a1af0f

Potential fix for pull request finding

16337c7

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

0816aed

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Python: address bot reviews

5a09f3c

Python: exclude constants from being SSA variables

e89e5ca

Python: test phi definitions at module exit

2fef764

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Python: preserve phi uses at module exit

f49429a

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Navigation Menu

Uh oh!

Python: add new shared-SSA-backed SSA adapter (additive) - #21923

Python: add new shared-SSA-backed SSA adapter (additive)#21923
yoff wants to merge 11 commits into
yoff-fix-shared-cfg-ssa-regressionsfrom
yoff/python-add-new-ssa

yoff commented Jun 1, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aschackmull Jul 8, 2026

Uh oh!

yoff Jul 30, 2026

Uh oh!

yoff commented Jul 28, 2026

Uh oh!

yoff commented Jul 28, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

yoff commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Library addition

Tests

Production impact

Verification

Notes for reviewers

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aschackmull Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

yoff Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

yoff commented Jul 28, 2026

Uh oh!

yoff commented Jul 28, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

yoff commented Jun 1, 2026 •

edited

Loading