Skip to content

Commit e5ee476

Browse files
asgerfasgerf
committed
JS: Add migration guide and change note
1 parent 7e4fbe2 commit e5ee476

File tree

3 files changed

+305
-0
lines changed

3 files changed

+305
-0
lines changed

‎docs/codeql/codeql-language-guides/migrating-javascript-dataflow-queries.rst‎

Lines changed: 294 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,294 @@
1+
.. _migrating-javascript-dataflow-queries:
2+
3+
Migrating JavaScript Dataflow Queries
4+
=====================================
5+
6+
The JavaScript analysis used to have its own data flow library, which differed from the shared data flow
7+
library used by other languages. This library has now been deprecated in favor of the shared library.
8+
9+
This article explains how to migrate JavaScript data flow queries to use the shared data flow library,
10+
and some important differences to be aware of. Note that the article on :ref:`analyzing data flow in JavaScript and TypeScript <analyzing-data-flow-in-javascript-and-typescript>`
11+
provides a general guide to new data flow library, whereas this article aims to help with migrating existing queries from the old data flow library.
12+
13+
Note that the ``DataFlow::Configuration`` class is still backed by the original data flow library, but has been marked as deprecated.
14+
This means data flow queries using this class will continue work, albeit with deprecation warnings, until the 1-year deprecation period expires in early 2026.
15+
It is recommended that all custom queries are migrated before this time, to ensure they continue to work in the future.
16+
17+
Data flow queries should be migrated to use ``DataFlow::ConfigSig``-style modules instead of the ``DataFlow::Configuration`` class.
18+
This is identical to the interface found in other languages.
19+
When making this switch, the query will become backed by the shared data flow library instead. That is, data flow queries will only work
20+
with the shared data flow library when they have been migrated to ``ConfigSig``-style, as shown in the following table:
21+
22+
+--------------------------------+---------------------------------------------------------+
23+
| API | Implementation |
24+
|--------------------------------|---------------------------------------------------------|
25+
| ``DataFlow::Configuration`` | Old library (deprecated, to be removed in early 2026) |
26+
| ``DataFlow::ConfigSig`` | Shared library |
27+
+--------------------------------+---------------------------------------------------------+
28+
29+
A straight-forward translation to ``DataFlow::ConfigSig``-style is usually possible, although there are some complications
30+
that may cause the query to behave differently.
31+
We'll first cover some straight-forward migration examples, and then go over some of the complications that may arise.
32+
33+
Simple migration example
34+
------------------------
35+
36+
A simple example of a query using the old data flow library is shown below:
37+
38+
.. code-block:: ql
39+
40+
/** @kind path-problem */
41+
import javascript
42+
import DataFlow::PathGraph
43+
44+
class MyConfig extends DataFlow::Configuration {
45+
MyConfig() { this = "MyConfig" }
46+
47+
override predicate isSource(DataFlow::Node node) { ... }
48+
49+
override predicate isSink(DataFlow::Node node) { ... }
50+
}
51+
52+
from MyConfig cfg, DataFlow::PathNode source, DataFlow::PathNode sink
53+
where cfg.hasFlowPath(source, sink)
54+
select sink, source, sink, "Flow found"
55+
56+
With the new style this would look like this:
57+
58+
.. code-block:: ql
59+
60+
/** @kind path-problem */
61+
import javascript
62+
63+
module MyConfig implements DataFlow::ConfigSig {
64+
predicate isSource(DataFlow::Node node) { ... }
65+
66+
predicate isSink(DataFlow::Node node) { ... }
67+
}
68+
69+
module MyFlow = DataFlow::Global<MyConfig>;
70+
71+
import MyFlow::PathGraph
72+
73+
from MyFlow::PathNode source, MyFlow::PathNode sink
74+
where MyFlow::flowPath(source, sink)
75+
select sink, source, sink, "Flow found"
76+
77+
The changes can be summarised as:
78+
79+
- The ``DataFlow::Configuration`` class was replaced with a module implementing ``DataFlow::ConfigSig``.
80+
- The characteristic predicate was removed (modules have no characteristic predicates)
81+
- Predicates such as ``isSource`` no longer have the ``override`` keyword (as they are defined in a module now).
82+
- The configuration module is being passed to ``DataFlow::Global``, resulting in a new module, called ``MyFlow`` in this example.
83+
- The query imports ``MyFlow::PathGraph`` instead of ``DataFlow::PathGraph``.
84+
- The ``MyConfig cfg`` variable was removed from the ``from`` clause.
85+
- The ``hasFlowPath`` call was replaced with ``MyFlow::flowPath``.
86+
- The type ``DataFlow::PathNode`` was replaced with ``MyFlow::PathNode``.
87+
88+
With these changes, we have produced an equivalent query that is backed by the new data flow library.
89+
90+
Taint tracking
91+
--------------
92+
93+
For configuration classes extending ``TaintTracking::Configuration``, the migration is similar but with few differences:
94+
95+
- The ``TaintTracking::Global`` module should be used instead of ``DataFlow::Global``.
96+
- The ``isSanitizer`` predicate should be renamed to ``isBarrier``.
97+
- The ``isAdditionalTaintStep`` predicate should be renamed to ``isAdditionalFlowStep``.
98+
99+
Note that there is no such thing as ``TaintTracking::ConfigSig``. The ``DataFlow::ConfigSig`` interface is used for both data flow and taint tracking.
100+
101+
For example:
102+
103+
.. code-block:: ql
104+
105+
class MyConfig extends TaintTracking::Configuration {
106+
predicate isSanitizer(DataFlow::Node node) { ... }
107+
predicate isAdditionalTaintStep(DataFlow::Node node1, DataFlow::Node node2) { ... }
108+
...
109+
}
110+
111+
The above configuration can be migrated to the shared data flow library as follows:
112+
113+
.. code-block:: ql
114+
115+
module MyConfig implements DataFlow::ConfigSig {
116+
predicate isBarrier(DataFlow::Node node) { ... }
117+
predicate isAdditionalFlowStep(DataFlow::Node node1, DataFlow::Node node2) { ... }
118+
...
119+
}
120+
121+
module MyFlow = TaintTracking::Global<MyConfig>;
122+
123+
124+
Flow labels and flow states
125+
---------------------------
126+
127+
The ``DataFlow::FlowLabel`` class has been deprecated. Queries that relied on flow labels should use the new `flow state` concept instead.
128+
This is done by implementing ``DataFlow::StateConfigSig`` instead of ``DataFlow::ConfigSig``, and passing the module to ``DataFlow::GlobalWithState``
129+
or ``TaintTracking::GlobalWithState``. See :ref:`using flow state <using-flow-labels-for-precise-data-flow-analysis>` for more details about flow state.
130+
131+
Some changes to be aware of:
132+
133+
- The 4-argument version of ``isAdditionalFlowStep`` now takes parameter in a different order.
134+
It now takes ``node1, state1, node2, state2`` instead of ``node1, node2, state1, state2``.
135+
- Taint steps apply to all flow states, not just the ``taint`` flow label. See more details further down in this article.
136+
137+
Barrier guards
138+
--------------
139+
140+
The predicates ``isBarrierGuard`` and ``isSanitizerGuard`` have been removed.
141+
142+
Instead, the ``isBarrier`` predicate must used to define all barriers. To do this, barrier guards can be reduced to a set of barrier nodes using the ``DataFlow::MakeBarrierGuard`` module.
143+
144+
For example, consider this data flow configuration using a barrier guard:
145+
146+
.. code-block:: ql
147+
148+
class MyConfig extends DataFlow::Configuration {
149+
override predicate isBarrierGuard(DataFlow::BarrierGuardNode node) {
150+
node instanceof MyBarrierGuard
151+
}
152+
..
153+
}
154+
155+
class MyBarrierGuard extends DataFlow::BarrierGuardNode {
156+
MyBarrierGuard() { ... }
157+
158+
override predicate blocks(Expr e, boolean outcome) { ... }
159+
}
160+
161+
This can be migrated to the shared data flow library as follows:
162+
163+
.. code-block:: ql
164+
165+
module MyConfig implements DataFlow::ConfigSig {
166+
predicate isBarrier(DataFlow::Node node) {
167+
node = DataFlow::MakeBarrierGuard<MyBarrierGuard>::getABarrierNode()
168+
}
169+
..
170+
}
171+
172+
class MyBarrierGuard extends DataFlow::Node {
173+
MyBarrierGuard() { ... }
174+
175+
predicate blocksExpr(Expr e, boolean outcome) { ... }
176+
}
177+
178+
The changes can be summarised as:
179+
- The contents of ``isBarrierGuard`` have been moved to ``isBarrier``.
180+
- The ``node instanceof MyBarrierGuard`` check was replaced with ``node = DataFlow::MakeBarrierGuard<MyBarrierGuard>::getABarrierNode()``.
181+
- The ``MyBarrierGuard`` class no longer has ``DataFlow::BarrierGuardNode`` as a base class. We simply use ``DataFlow::Node`` instead.
182+
- The ``blocks`` predicate has been renamed to ``blocksExpr`` and no longer has the ``override`` keyword.
183+
184+
See :ref:`using flow state <using-flow-labels-for-precise-data-flow-analysis>` for examples of how to use barrier guards with flow state.
185+
186+
Query-specific load and store steps
187+
-----------------------------------
188+
189+
The predicates ``isAdditionalLoadStep``, ``isAdditionalStoreStep``, and ``isAdditionalLoadStoreStep`` have been removed. There is no way to emulate the original behaviour.
190+
191+
Library models can still contribute such steps, but they will be applicable to all queries. Also see the section on jump steps further down.
192+
193+
Changes in behaviour
194+
--------------------
195+
196+
When the query has been migrated to the new interface, it may seem to behave differently due to some technical differences in the internals of
197+
the two data flow libraries. The most significant changes are described below.
198+
199+
Taint steps now propagate all flow states
200+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
201+
202+
There's an important change from the old data flow library when using flow state and taint-tracking together.
203+
204+
When using when using ``TaintTracking::GlobalWithState``, all flow states can propagate along taint steps.
205+
In the old data flow library, only the ``taint`` flow label could propagate along taint steps.
206+
A straight-forward translation of such a query may therefore result in new flow paths being found, which might be unexpected.
207+
208+
To emulate the old behaviour, use ``DataFlow::GlobalWithState`` instead of ``TaintTracking::GlobalWithState``,
209+
and manually add taint steps using ``isAdditionalFlowStep``. The predicate ``TaintTracking::defaultTaintStep`` can be used to access to the set of taint steps.
210+
211+
For example:
212+
213+
.. code-block:: ql
214+
215+
module MyConfig implements DataFlow::StateConfigSig {
216+
class FlowState extends string {
217+
FlowState() { this = ["taint", "foo"] }
218+
}
219+
220+
predicate isAdditionalFlowStep(DataFlow::Node node1, FlowState state1, DataFlow::Node node2, FlowState state2) {
221+
// Allow taint steps to propagate the "taint" flow state
222+
TaintTracking::defaultTaintStep(node1, node2) and
223+
state1 = "taint" and
224+
state2 = state
225+
}
226+
227+
...
228+
}
229+
230+
module MyFlow = DataFlow::GlobalWithState<MyConfig>;
231+
232+
233+
Jump steps across function boundaries
234+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
235+
236+
When a flow step crosses a function boundary, that is, it starts and ends in two different functions, it will now be classified as a "jump" step.
237+
238+
Jump steps can be problematic in some cases. Roughly speaking, the data flow library will "forget" which call site it came from when following a jump step.
239+
This can lead to spurious flow paths that go into a function through one call site, and back out of a different call site.
240+
241+
If the step was generated by a library model, that is, the step is applicable to all queries, this is best mitigated by converting the step to a flow summary.
242+
For example, the following library model adds a taint step from ``x`` to ``y`` in ``foo.bar(x, y => {})``:
243+
244+
.. code-block:: ql
245+
246+
class MyStep extends TaintTracking::SharedTaintStep {
247+
override predicate step(DataFlow::Node node1, DataFlow::Node node2) {
248+
exists(DataFlow::CallNode call |
249+
call = DataFlow::moduleMember("foo", "bar").getACall() and
250+
node1 = call.getArgument(0) and
251+
node2 = call.getCallback(1).getParameter(0)
252+
)
253+
}
254+
}
255+
256+
Because this step crosses a function boundary, it becomes a jump step. This can be avoided by converting it to a flow summary as follows:
257+
258+
.. code-block:: ql
259+
260+
class MySummary extends DataFlow::SummarizedCallable {
261+
MySummary() { this = "MySummary" }
262+
263+
override DataFlow::CallNode getACall() { result = DataFlow::moduleMember("foo", "bar").getACall() }
264+
265+
override predicate propagatesFlow(string input, string output, boolean preservesValue) {
266+
input = "Argument[this]" and
267+
output = "Argument[1].Parameter[0]" and
268+
preservesValue = false // taint step
269+
}
270+
}
271+
272+
See :ref:`customizing library models for JavaScript <customizing-library-models-for-javascript>` for details about the format of the ``input`` and ``output`` strings.
273+
The aforementioned article also provides guidance on how to store the flow summary in a data extension.
274+
275+
For query-specific steps that cross function boundaries, that is, steps added with ``isAdditionalFlowStep``, there is currently no way to emulate the original behaviour.
276+
A possible workaround is to convert the query-specific step to a flow summary. In this case it should be stored in a data extension to avoid performance issues, although this also means
277+
that all other queries will be able to use the flow summary.
278+
279+
Barriers block all flows
280+
~~~~~~~~~~~~~~~~~~~~~~~~
281+
282+
In the shared data flow library, a barrier blocks all flows, even if the tracked value is inside a content.
283+
284+
In the old data flow library, only barriers specific to the ``data`` flow label blocked flows when the tracked value was inside a content.
285+
286+
This rarely has significant impact, but some users may observe some result changes because of this.
287+
288+
There is currently no way to emulate the original behavour.
289+
290+
Further reading
291+
---------------
292+
293+
- :ref:`Analyzing data flow in JavaScript and TypeScript <analyzing-data-flow-in-javascript-and-typescript>` provides a general guide to the new data flow library.
294+
- :ref:`Using flow state for precise data flow analysis <using-flow-labels-for-precise-data-flow-analysis>` provides a general guide on using flow state.

‎javascript/ql/lib/change-notes/2025-01-07-dataflow-deprecation.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
category: deprecation
3+
---
4+
* Custom data flow queries will need to be migrated in order to use the shared data flow library. Until migrated, such queries will compile with deprecation warnings and run with a
5+
deprecated copy of the old data flow library. The deprecation layer will be removed in early 2026, after which any unmigrated queries will stop working.
6+
See more information in the [migration guide](https://codeql.github.com/docs/codeql-language-guides/migrating-javascript-dataflow-queries).

‎javascript/ql/lib/change-notes/2025-01-07-dataflow.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
category: majorAnalysis
3+
---
4+
* All data flow queries are now using the same underlying data flow library as the other languages analyses, replacing the old one written specifically for JavaScript/TypeScript.
5+
This is a significant change and users may consequently observe differences in the alerts generated by the analysis.

0 commit comments

Comments
 (0)