├── .codeqlmanifest.json
├── .gitignore
├── LICENSE
├── README.md
└── ql
├── examples
├── LLVMPath.ql
└── qlpack.yml
└── src
├── InvalidationFlows.ql
├── IteratedTypes.ql
├── qlpack.yml
└── trailofbits
└── itergator
├── dataflow.qll
├── invalidations.qll
├── invalidations
├── Destructor.qll
└── STL.qll
└── iterators.qll
/.codeqlmanifest.json:
--------------------------------------------------------------------------------
1 | {"provide": ["ql/src/qlpack.yml", "ql/examples/qlpack.yml"]}
2 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | .cache
2 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | Attribution-NonCommercial-ShareAlike 4.0 International
2 |
3 | =======================================================================
4 |
5 | Creative Commons Corporation ("Creative Commons") is not a law firm and
6 | does not provide legal services or legal advice. Distribution of
7 | Creative Commons public licenses does not create a lawyer-client or
8 | other relationship. Creative Commons makes its licenses and related
9 | information available on an "as-is" basis. Creative Commons gives no
10 | warranties regarding its licenses, any material licensed under their
11 | terms and conditions, or any related information. Creative Commons
12 | disclaims all liability for damages resulting from their use to the
13 | fullest extent possible.
14 |
15 | Using Creative Commons Public Licenses
16 |
17 | Creative Commons public licenses provide a standard set of terms and
18 | conditions that creators and other rights holders may use to share
19 | original works of authorship and other material subject to copyright
20 | and certain other rights specified in the public license below. The
21 | following considerations are for informational purposes only, are not
22 | exhaustive, and do not form part of our licenses.
23 |
24 | Considerations for licensors: Our public licenses are
25 | intended for use by those authorized to give the public
26 | permission to use material in ways otherwise restricted by
27 | copyright and certain other rights. Our licenses are
28 | irrevocable. Licensors should read and understand the terms
29 | and conditions of the license they choose before applying it.
30 | Licensors should also secure all rights necessary before
31 | applying our licenses so that the public can reuse the
32 | material as expected. Licensors should clearly mark any
33 | material not subject to the license. This includes other CC-
34 | licensed material, or material used under an exception or
35 | limitation to copyright. More considerations for licensors:
36 | wiki.creativecommons.org/Considerations_for_licensors
37 |
38 | Considerations for the public: By using one of our public
39 | licenses, a licensor grants the public permission to use the
40 | licensed material under specified terms and conditions. If
41 | the licensor's permission is not necessary for any reason--for
42 | example, because of any applicable exception or limitation to
43 | copyright--then that use is not regulated by the license. Our
44 | licenses grant only permissions under copyright and certain
45 | other rights that a licensor has authority to grant. Use of
46 | the licensed material may still be restricted for other
47 | reasons, including because others have copyright or other
48 | rights in the material. A licensor may make special requests,
49 | such as asking that all changes be marked or described.
50 | Although not required by our licenses, you are encouraged to
51 | respect those requests where reasonable. More considerations
52 | for the public:
53 | wiki.creativecommons.org/Considerations_for_licensees
54 |
55 | =======================================================================
56 |
57 | Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International
58 | Public License
59 |
60 | By exercising the Licensed Rights (defined below), You accept and agree
61 | to be bound by the terms and conditions of this Creative Commons
62 | Attribution-NonCommercial-ShareAlike 4.0 International Public License
63 | ("Public License"). To the extent this Public License may be
64 | interpreted as a contract, You are granted the Licensed Rights in
65 | consideration of Your acceptance of these terms and conditions, and the
66 | Licensor grants You such rights in consideration of benefits the
67 | Licensor receives from making the Licensed Material available under
68 | these terms and conditions.
69 |
70 |
71 | Section 1 -- Definitions.
72 |
73 | a. Adapted Material means material subject to Copyright and Similar
74 | Rights that is derived from or based upon the Licensed Material
75 | and in which the Licensed Material is translated, altered,
76 | arranged, transformed, or otherwise modified in a manner requiring
77 | permission under the Copyright and Similar Rights held by the
78 | Licensor. For purposes of this Public License, where the Licensed
79 | Material is a musical work, performance, or sound recording,
80 | Adapted Material is always produced where the Licensed Material is
81 | synched in timed relation with a moving image.
82 |
83 | b. Adapter's License means the license You apply to Your Copyright
84 | and Similar Rights in Your contributions to Adapted Material in
85 | accordance with the terms and conditions of this Public License.
86 |
87 | c. BY-NC-SA Compatible License means a license listed at
88 | creativecommons.org/compatiblelicenses, approved by Creative
89 | Commons as essentially the equivalent of this Public License.
90 |
91 | d. Copyright and Similar Rights means copyright and/or similar rights
92 | closely related to copyright including, without limitation,
93 | performance, broadcast, sound recording, and Sui Generis Database
94 | Rights, without regard to how the rights are labeled or
95 | categorized. For purposes of this Public License, the rights
96 | specified in Section 2(b)(1)-(2) are not Copyright and Similar
97 | Rights.
98 |
99 | e. Effective Technological Measures means those measures that, in the
100 | absence of proper authority, may not be circumvented under laws
101 | fulfilling obligations under Article 11 of the WIPO Copyright
102 | Treaty adopted on December 20, 1996, and/or similar international
103 | agreements.
104 |
105 | f. Exceptions and Limitations means fair use, fair dealing, and/or
106 | any other exception or limitation to Copyright and Similar Rights
107 | that applies to Your use of the Licensed Material.
108 |
109 | g. License Elements means the license attributes listed in the name
110 | of a Creative Commons Public License. The License Elements of this
111 | Public License are Attribution, NonCommercial, and ShareAlike.
112 |
113 | h. Licensed Material means the artistic or literary work, database,
114 | or other material to which the Licensor applied this Public
115 | License.
116 |
117 | i. Licensed Rights means the rights granted to You subject to the
118 | terms and conditions of this Public License, which are limited to
119 | all Copyright and Similar Rights that apply to Your use of the
120 | Licensed Material and that the Licensor has authority to license.
121 |
122 | j. Licensor means the individual(s) or entity(ies) granting rights
123 | under this Public License.
124 |
125 | k. NonCommercial means not primarily intended for or directed towards
126 | commercial advantage or monetary compensation. For purposes of
127 | this Public License, the exchange of the Licensed Material for
128 | other material subject to Copyright and Similar Rights by digital
129 | file-sharing or similar means is NonCommercial provided there is
130 | no payment of monetary compensation in connection with the
131 | exchange.
132 |
133 | l. Share means to provide material to the public by any means or
134 | process that requires permission under the Licensed Rights, such
135 | as reproduction, public display, public performance, distribution,
136 | dissemination, communication, or importation, and to make material
137 | available to the public including in ways that members of the
138 | public may access the material from a place and at a time
139 | individually chosen by them.
140 |
141 | m. Sui Generis Database Rights means rights other than copyright
142 | resulting from Directive 96/9/EC of the European Parliament and of
143 | the Council of 11 March 1996 on the legal protection of databases,
144 | as amended and/or succeeded, as well as other essentially
145 | equivalent rights anywhere in the world.
146 |
147 | n. You means the individual or entity exercising the Licensed Rights
148 | under this Public License. Your has a corresponding meaning.
149 |
150 |
151 | Section 2 -- Scope.
152 |
153 | a. License grant.
154 |
155 | 1. Subject to the terms and conditions of this Public License,
156 | the Licensor hereby grants You a worldwide, royalty-free,
157 | non-sublicensable, non-exclusive, irrevocable license to
158 | exercise the Licensed Rights in the Licensed Material to:
159 |
160 | a. reproduce and Share the Licensed Material, in whole or
161 | in part, for NonCommercial purposes only; and
162 |
163 | b. produce, reproduce, and Share Adapted Material for
164 | NonCommercial purposes only.
165 |
166 | 2. Exceptions and Limitations. For the avoidance of doubt, where
167 | Exceptions and Limitations apply to Your use, this Public
168 | License does not apply, and You do not need to comply with
169 | its terms and conditions.
170 |
171 | 3. Term. The term of this Public License is specified in Section
172 | 6(a).
173 |
174 | 4. Media and formats; technical modifications allowed. The
175 | Licensor authorizes You to exercise the Licensed Rights in
176 | all media and formats whether now known or hereafter created,
177 | and to make technical modifications necessary to do so. The
178 | Licensor waives and/or agrees not to assert any right or
179 | authority to forbid You from making technical modifications
180 | necessary to exercise the Licensed Rights, including
181 | technical modifications necessary to circumvent Effective
182 | Technological Measures. For purposes of this Public License,
183 | simply making modifications authorized by this Section 2(a)
184 | (4) never produces Adapted Material.
185 |
186 | 5. Downstream recipients.
187 |
188 | a. Offer from the Licensor -- Licensed Material. Every
189 | recipient of the Licensed Material automatically
190 | receives an offer from the Licensor to exercise the
191 | Licensed Rights under the terms and conditions of this
192 | Public License.
193 |
194 | b. Additional offer from the Licensor -- Adapted Material.
195 | Every recipient of Adapted Material from You
196 | automatically receives an offer from the Licensor to
197 | exercise the Licensed Rights in the Adapted Material
198 | under the conditions of the Adapter's License You apply.
199 |
200 | c. No downstream restrictions. You may not offer or impose
201 | any additional or different terms or conditions on, or
202 | apply any Effective Technological Measures to, the
203 | Licensed Material if doing so restricts exercise of the
204 | Licensed Rights by any recipient of the Licensed
205 | Material.
206 |
207 | 6. No endorsement. Nothing in this Public License constitutes or
208 | may be construed as permission to assert or imply that You
209 | are, or that Your use of the Licensed Material is, connected
210 | with, or sponsored, endorsed, or granted official status by,
211 | the Licensor or others designated to receive attribution as
212 | provided in Section 3(a)(1)(A)(i).
213 |
214 | b. Other rights.
215 |
216 | 1. Moral rights, such as the right of integrity, are not
217 | licensed under this Public License, nor are publicity,
218 | privacy, and/or other similar personality rights; however, to
219 | the extent possible, the Licensor waives and/or agrees not to
220 | assert any such rights held by the Licensor to the limited
221 | extent necessary to allow You to exercise the Licensed
222 | Rights, but not otherwise.
223 |
224 | 2. Patent and trademark rights are not licensed under this
225 | Public License.
226 |
227 | 3. To the extent possible, the Licensor waives any right to
228 | collect royalties from You for the exercise of the Licensed
229 | Rights, whether directly or through a collecting society
230 | under any voluntary or waivable statutory or compulsory
231 | licensing scheme. In all other cases the Licensor expressly
232 | reserves any right to collect such royalties, including when
233 | the Licensed Material is used other than for NonCommercial
234 | purposes.
235 |
236 |
237 | Section 3 -- License Conditions.
238 |
239 | Your exercise of the Licensed Rights is expressly made subject to the
240 | following conditions.
241 |
242 | a. Attribution.
243 |
244 | 1. If You Share the Licensed Material (including in modified
245 | form), You must:
246 |
247 | a. retain the following if it is supplied by the Licensor
248 | with the Licensed Material:
249 |
250 | i. identification of the creator(s) of the Licensed
251 | Material and any others designated to receive
252 | attribution, in any reasonable manner requested by
253 | the Licensor (including by pseudonym if
254 | designated);
255 |
256 | ii. a copyright notice;
257 |
258 | iii. a notice that refers to this Public License;
259 |
260 | iv. a notice that refers to the disclaimer of
261 | warranties;
262 |
263 | v. a URI or hyperlink to the Licensed Material to the
264 | extent reasonably practicable;
265 |
266 | b. indicate if You modified the Licensed Material and
267 | retain an indication of any previous modifications; and
268 |
269 | c. indicate the Licensed Material is licensed under this
270 | Public License, and include the text of, or the URI or
271 | hyperlink to, this Public License.
272 |
273 | 2. You may satisfy the conditions in Section 3(a)(1) in any
274 | reasonable manner based on the medium, means, and context in
275 | which You Share the Licensed Material. For example, it may be
276 | reasonable to satisfy the conditions by providing a URI or
277 | hyperlink to a resource that includes the required
278 | information.
279 | 3. If requested by the Licensor, You must remove any of the
280 | information required by Section 3(a)(1)(A) to the extent
281 | reasonably practicable.
282 |
283 | b. ShareAlike.
284 |
285 | In addition to the conditions in Section 3(a), if You Share
286 | Adapted Material You produce, the following conditions also apply.
287 |
288 | 1. The Adapter's License You apply must be a Creative Commons
289 | license with the same License Elements, this version or
290 | later, or a BY-NC-SA Compatible License.
291 |
292 | 2. You must include the text of, or the URI or hyperlink to, the
293 | Adapter's License You apply. You may satisfy this condition
294 | in any reasonable manner based on the medium, means, and
295 | context in which You Share Adapted Material.
296 |
297 | 3. You may not offer or impose any additional or different terms
298 | or conditions on, or apply any Effective Technological
299 | Measures to, Adapted Material that restrict exercise of the
300 | rights granted under the Adapter's License You apply.
301 |
302 |
303 | Section 4 -- Sui Generis Database Rights.
304 |
305 | Where the Licensed Rights include Sui Generis Database Rights that
306 | apply to Your use of the Licensed Material:
307 |
308 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right
309 | to extract, reuse, reproduce, and Share all or a substantial
310 | portion of the contents of the database for NonCommercial purposes
311 | only;
312 |
313 | b. if You include all or a substantial portion of the database
314 | contents in a database in which You have Sui Generis Database
315 | Rights, then the database in which You have Sui Generis Database
316 | Rights (but not its individual contents) is Adapted Material,
317 | including for purposes of Section 3(b); and
318 |
319 | c. You must comply with the conditions in Section 3(a) if You Share
320 | all or a substantial portion of the contents of the database.
321 |
322 | For the avoidance of doubt, this Section 4 supplements and does not
323 | replace Your obligations under this Public License where the Licensed
324 | Rights include other Copyright and Similar Rights.
325 |
326 |
327 | Section 5 -- Disclaimer of Warranties and Limitation of Liability.
328 |
329 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
330 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
331 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
332 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
333 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
334 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
335 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
336 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
337 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
338 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
339 |
340 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
341 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
342 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
343 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
344 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
345 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
346 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
347 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
348 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
349 |
350 | c. The disclaimer of warranties and limitation of liability provided
351 | above shall be interpreted in a manner that, to the extent
352 | possible, most closely approximates an absolute disclaimer and
353 | waiver of all liability.
354 |
355 |
356 | Section 6 -- Term and Termination.
357 |
358 | a. This Public License applies for the term of the Copyright and
359 | Similar Rights licensed here. However, if You fail to comply with
360 | this Public License, then Your rights under this Public License
361 | terminate automatically.
362 |
363 | b. Where Your right to use the Licensed Material has terminated under
364 | Section 6(a), it reinstates:
365 |
366 | 1. automatically as of the date the violation is cured, provided
367 | it is cured within 30 days of Your discovery of the
368 | violation; or
369 |
370 | 2. upon express reinstatement by the Licensor.
371 |
372 | For the avoidance of doubt, this Section 6(b) does not affect any
373 | right the Licensor may have to seek remedies for Your violations
374 | of this Public License.
375 |
376 | c. For the avoidance of doubt, the Licensor may also offer the
377 | Licensed Material under separate terms or conditions or stop
378 | distributing the Licensed Material at any time; however, doing so
379 | will not terminate this Public License.
380 |
381 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
382 | License.
383 |
384 |
385 | Section 7 -- Other Terms and Conditions.
386 |
387 | a. The Licensor shall not be bound by any additional or different
388 | terms or conditions communicated by You unless expressly agreed.
389 |
390 | b. Any arrangements, understandings, or agreements regarding the
391 | Licensed Material not stated herein are separate from and
392 | independent of the terms and conditions of this Public License.
393 |
394 |
395 | Section 8 -- Interpretation.
396 |
397 | a. For the avoidance of doubt, this Public License does not, and
398 | shall not be interpreted to, reduce, limit, restrict, or impose
399 | conditions on any use of the Licensed Material that could lawfully
400 | be made without permission under this Public License.
401 |
402 | b. To the extent possible, if any provision of this Public License is
403 | deemed unenforceable, it shall be automatically reformed to the
404 | minimum extent necessary to make it enforceable. If the provision
405 | cannot be reformed, it shall be severed from this Public License
406 | without affecting the enforceability of the remaining terms and
407 | conditions.
408 |
409 | c. No term or condition of this Public License will be waived and no
410 | failure to comply consented to unless expressly agreed to by the
411 | Licensor.
412 |
413 | d. Nothing in this Public License constitutes or may be interpreted
414 | as a limitation upon, or waiver of, any privileges and immunities
415 | that apply to the Licensor or You, including from the legal
416 | processes of any jurisdiction or authority.
417 |
418 | =======================================================================
419 |
420 | Creative Commons is not a party to its public
421 | licenses. Notwithstanding, Creative Commons may elect to apply one of
422 | its public licenses to material it publishes and in those instances
423 | will be considered the “Licensor.” The text of the Creative Commons
424 | public licenses is dedicated to the public domain under the CC0 Public
425 | Domain Dedication. Except for the limited purpose of indicating that
426 | material is shared under a Creative Commons public license or as
427 | otherwise permitted by the Creative Commons policies published at
428 | creativecommons.org/policies, Creative Commons does not authorize the
429 | use of the trademark "Creative Commons" or any other trademark or logo
430 | of Creative Commons without its prior written consent including,
431 | without limitation, in connection with any unauthorized modifications
432 | to any of its public licenses or any other arrangements,
433 | understandings, or agreements concerning use of licensed material. For
434 | the avoidance of doubt, this paragraph does not form part of the
435 | public licenses.
436 |
437 | Creative Commons may be contacted at creativecommons.org.
438 |
439 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Itergator
2 |
3 | A [CodeQL](https://securitylab.github.com/tools/codeql) library for detecting and analyzing iterator invalidation in C++ codebases.
4 |
5 | ## Getting started
6 |
7 | Set up CodeQL in Visual Studio Code. We recommend using the [starter workspace](https://help.semmle.com/codeql/codeql-for-vscode/procedures/setting-up.html#using-the-starter-workspace).
8 |
9 | Download Itergator and [add it to your workspace](https://code.visualstudio.com/docs/editor/multi-root-workspaces#_adding-folders).
10 |
11 | ```
12 | git clone https://github.com/trailofbits/itergator
13 | ```
14 |
15 | [Open and run](https://help.semmle.com/codeql/codeql-for-vscode/procedures/using-extension.html#running-a-query) the desired queries.
16 |
17 | To use the classes in your own queries, add Itergator to your `qlpack.yml`:
18 |
19 | ```yaml
20 | name: codeql-custom-queries-cpp
21 | version: 0.0.0
22 | libraryPathDependencies:
23 | - codeql-cpp
24 | - trailofbits-itergator
25 | ```
26 |
27 | Then import the libraries:
28 |
29 | ```codeql
30 | import trailofbits.itergator.iterators
31 | import trailofbits.itergator.dataflow
32 | import trailofbits.itergator.invalidations.Destructor
33 | import trailofbits.itergator.invalidations.STL
34 | ```
35 |
36 | ## Queries
37 |
38 | ### `IteratedTypes.ql`
39 |
40 | Returns a list of iterated types.
41 |
42 | There may be false positives, such as when an iterator is used in an expression that is assigned to another:
43 |
44 | ```cpp
45 | iterator __pos = __position._M_const_cast()
46 | ```
47 |
48 | ### `InvalidationFlows.ql`
49 |
50 | Returns a list of potential invalidations.
51 |
52 | Results contain the [iterator](#Iterator) that may be invalidated, the [access](#Iterated) of the iterated variable, the top-level potentially invalidating [function call](#Invalidator), and the [method call](#Invalidation) on the iterated variable. There is also an integer column `significance`. Lower values are expected to have less noise in their results.
53 |
54 | This query has a high false positive rate. Analyzing the path of the function calls is useful to confirm a potential invalidation. An example of a path query can be seen in [examples/LLVMPath.ql](ql/examples/LLVMPath.ql).
55 |
56 | ## Libraries
57 |
58 | ### `trailofbits.itergator.iterators`
59 |
60 | Classes representing iterators and invalidations in the codebase.
61 |
62 |
63 |
64 | ```codeql
65 | class Iterator extends Variable
66 | ```
67 |
68 | > A variable that stores an iterator.
69 |
70 |
71 |
72 | ```codeql
73 | class Iterated extends VariableAccess
74 | ```
75 |
76 | > The access of a container where it is being iterated over, e.g. `vec.begin()`.
77 | >
78 | > Member predicate `Iterator iterator()` returns a variable the resulting iterator is stored in.
79 |
80 |
81 |
82 | ```codeql
83 | class Invalidator extends InvalidatorT
84 | ```
85 |
86 | > A function call within the scope of an iterator that could trigger an invalidation.
87 | >
88 | > Member predicate `Iterated iterated()` returns an `Iterated` element in the assignment of an iterator with the same scope as this `Invalidator`.
89 | >
90 | > Member predicate `Invalidation invalidation()` returns a function call that could invalidate an iterator in the scope of this invalidator.
91 |
92 |
93 |
94 | ```codeql
95 | class Invalidation extends InvalidatorT
96 | ```
97 |
98 | > A function call that is a potential invalidation and could be reached from an `Invalidator`.
99 | >
100 | > Member predicate `Invalidator invalidator()` returns an `Invalidator` function call within the scope of a correctly typed iterator that this is reachable from.
101 |
102 |
103 |
104 | ```codeql
105 | class InvalidatorT extends FunctionCallR
106 | ```
107 |
108 | > A class of function call that composes the path from an `Invalidator` to an `Invalidation`.
109 | >
110 | > This is primarily an internal class, but it may be useful in some queries. View the [implementation](ql/src/trailofbits/itergator/iterators.qll#L47) for details.
111 |
112 | ### `trailofbits.itergator.dataflow`
113 |
114 | [Global data flow](https://help.semmle.com/QL/learn-ql/cpp/dataflow.html#global-data-flow) configurations for Itergator's classes.
115 |
116 | ```codeql
117 | class IteratorFlow extends DataFlow::Configuration
118 | ```
119 |
120 | ```codeql
121 | class IteratedFlow extends DataFlow::Configuration
122 | ```
123 |
124 | ```codeql
125 | class InvalidationFlow extends DataFlow::Configuration
126 | ```
127 |
128 | ```codeql
129 | class InvalidatorFlow extends DataFlow::Configuration
130 | ```
131 |
132 | ### `trailofbits.itergator.invalidations`
133 |
134 | A framework for designating functions as potentially invalidating.
135 |
136 | ```codeql
137 | abstract class PotentialInvalidation extends Function
138 | ```
139 |
140 | > This class can be extended to define potential invalidations.
141 | >
142 | > Member predicate `invalidates(Iterated i)` holds if a call to the function could invalidate an iterator of the type of the parameter `i`.
143 |
144 | Two potential invalidation definitions are already written:
145 |
146 | ```codeql
147 | import trailofbits.itergator.invalidations.Destructor
148 | ```
149 |
150 | > Destructors of the iterated type.
151 |
152 | ```codeql
153 | import trailofbits.itergator.invalidations.STL
154 | ```
155 |
156 | > Member functions of STL types based on the C++ specification. This does not include destructors.
157 |
158 | [These classes](ql/src/trailofbits/itergator/invalidations) may be used as examples when writing custom invalidation conditions.
159 |
160 | ## License
161 |
162 | Itergator is licensed and distributed under the [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) license. [Contact us](mailto:opensource@trailofbits.com) if you're looking for an exception to the terms.
163 |
--------------------------------------------------------------------------------
/ql/examples/LLVMPath.ql:
--------------------------------------------------------------------------------
1 | // used against https://github.com/apple/llvm-project/tree/b73bab42a101a29a1e178d618bb8448d9a423b6e
2 | // to investigate and confirm a potential invalidation in lld
3 |
4 | import cpp
5 | import trailofbits.itergator.iterators
6 | import trailofbits.itergator.invalidations.Destructor
7 | import trailofbits.itergator.invalidations.STL
8 |
9 | from Invalidator i, InvalidatorT i1, InvalidatorT i2, InvalidatorT i3, InvalidatorT i4, InvalidatorT i5, InvalidatorT i6, InvalidatorT i7, InvalidatorT i8, InvalidatorT i9, InvalidatorT i10, InvalidatorT i11, Invalidation inv
10 | where i.getTarget().hasName("handleUndefined")
11 | and i.child() = i1 and i1.child() = i2 and i2.child() = i3 and i3.child() = i4 and i4.child() = i5 and i5.child() = i6 and i6.child() = i7 and i7.child() = i8 and i8.child() = i9 and i9.child() = i10 and i10.child() = i11
12 | and inv.getTarget().hasName("push_back")
13 | and inv.getLocation().toString().matches("%ScriptParser.cpp%329%")
14 | and (inv = i or inv = i1 or inv = i2 or inv = i3 or inv = i4 or inv = i5 or inv = i6 or inv = i7 or inv = i8 or inv = i9 or inv = i10 or inv = i11)
15 | and i.getLocation().toString().matches("%Driver.cpp%1782%")
16 | select i, i1, i2, i3, i4, i5, i6, i7, i8, i9, i10, i11, inv
17 |
--------------------------------------------------------------------------------
/ql/examples/qlpack.yml:
--------------------------------------------------------------------------------
1 | name: trailofbits-itergator-examples
2 | version: 0.0.0
3 | libraryPathDependencies: trailofbits-itergator
4 |
--------------------------------------------------------------------------------
/ql/src/InvalidationFlows.ql:
--------------------------------------------------------------------------------
1 | import cpp
2 |
3 | import trailofbits.itergator.iterators
4 | import trailofbits.itergator.dataflow
5 | import trailofbits.itergator.invalidations.STL
6 | import trailofbits.itergator.invalidations.Destructor
7 |
8 | class NotStackVariable extends Variable {
9 | NotStackVariable() {
10 | not this instanceof StackVariable
11 | }
12 | }
13 |
14 | Variable nodeToVariable(DataFlow::Node node) {
15 | result = node.asExpr().(VariableAccess).getTarget()
16 | }
17 |
18 | predicate falsePositive(Iterator it, Invalidator inv) {
19 | forex (ControlFlowNode n | n = inv.getASuccessor() |
20 | n.(BreakStmt).getBreakable().(Loop) = it.getParentScope()
21 | or n.(ReturnStmt).getEnclosingFunction() = it.getParentScope+()
22 | or exists (ExitBasicBlock b |
23 | b = n.getBasicBlock() and b.getEnclosingFunction() = it.getParentScope+()
24 | and not b.contains(it.getAnAccess())
25 | )
26 | )
27 | or inv = it.getAnAssignedValue()
28 | }
29 |
30 | predicate invalidatesChild(Invalidation invd, Expr container) {
31 | invd.getTarget().(PotentialInvalidation).invalidatedChild(invd) = container
32 | }
33 |
34 | from IteratedFlow f1, InvalidatorFlow f2, InvalidationFlow f3, int significance,
35 | DataFlow::Node source, DataFlow::Node invalidationNode, DataFlow::Node iteratedNode, DataFlow::Node invalidatorNode,
36 | Invalidator inv, Iterated itd, Iterator it, Invalidation invd
37 | // set up variables (iterator, iterated, invalidation, and invalidator)
38 | where itd = iteratedNode.asExpr()
39 | and itd = inv.iterated()
40 | and it = itd.iterator()
41 | and inv = invalidatorNode.asExpr().getEnclosingElement()
42 | and invalidatesChild(inv.invalidation(), invalidationNode.asExpr())
43 | and invd = invalidationNode.asExpr().getEnclosingElement()
44 | // make sure the actions can operate on the same values
45 | and (
46 | // the same value flows to the iterator, the invalidator, and the invalidation
47 | (f1.hasFlow(source, iteratedNode)
48 | and f2.hasFlow(source, invalidatorNode)
49 | and f3.hasFlow(source, invalidationNode)
50 | and f3.hasFlow(invalidatorNode, invalidationNode)
51 | and significance = 0)
52 | // or some access of the iterated variable flows to the invalidation
53 | or (exists (DataFlow::Node source2 |
54 | f1.hasFlow(source, iteratedNode)
55 | and f3.hasFlow(source2, invalidationNode)
56 | // stack variables should have sequential flow (caught by above)
57 | and nodeToVariable(source).(NotStackVariable) = nodeToVariable(source2).(NotStackVariable)
58 | and (
59 | nodeToVariable(source) instanceof GlobalOrNamespaceVariable and significance = 1
60 | or not nodeToVariable(source) instanceof GlobalOrNamespaceVariable and significance = 2
61 | )
62 | ))
63 | )
64 | and not falsePositive(it, inv)
65 | select it, itd, inv, invd, significance order by significance
66 |
--------------------------------------------------------------------------------
/ql/src/IteratedTypes.ql:
--------------------------------------------------------------------------------
1 | import cpp
2 | import trailofbits.itergator.iterators
3 |
4 | from Iterated i
5 | select i.getType().stripType().getName().regexpCapture("(.*?)<.*", 1)
6 |
--------------------------------------------------------------------------------
/ql/src/qlpack.yml:
--------------------------------------------------------------------------------
1 | name: trailofbits-itergator
2 | version: 0.0.0
3 | libraryPathDependencies: codeql-cpp
4 |
--------------------------------------------------------------------------------
/ql/src/trailofbits/itergator/dataflow.qll:
--------------------------------------------------------------------------------
1 | private import cpp
2 | private import trailofbits.itergator.iterators
3 |
4 | import semmle.code.cpp.dataflow.DataFlow
5 |
6 | class IteratorFlow extends DataFlow::Configuration {
7 | IteratorFlow() { this = "IteratorFlow" }
8 |
9 | override predicate isSource(DataFlow::Node source) {
10 | source.asExpr() instanceof Access
11 | or exists (source.asParameter())
12 | }
13 |
14 | override predicate isSink(DataFlow::Node sink) {
15 | sink.asExpr().(Access).getTarget() instanceof Iterator
16 | }
17 |
18 | override predicate isBarrier(DataFlow::Node node) {
19 | node.asExpr().(FunctionCall).getTarget() instanceof CopyConstructor
20 | }
21 | }
22 |
23 | class IteratedFlow extends DataFlow::Configuration {
24 | IteratedFlow() { this = "IteratedFlow" }
25 |
26 | override predicate isSource(DataFlow::Node source) {
27 | source.asExpr() instanceof Access
28 | or exists (source.asParameter())
29 | }
30 |
31 | override predicate isSink(DataFlow::Node sink) {
32 | sink.asExpr() instanceof Iterated
33 | }
34 |
35 | override predicate isBarrier(DataFlow::Node node) {
36 | node.asExpr().(FunctionCall).getTarget() instanceof CopyConstructor
37 | }
38 | }
39 |
40 | class InvalidationFlow extends DataFlow::Configuration {
41 | InvalidationFlow() { this = "InvalidationFlow" }
42 |
43 | override predicate isSource(DataFlow::Node source) {
44 | exists (Access a | a = source.asExpr())
45 | or exists (source.asParameter())
46 | }
47 |
48 | override predicate isSink(DataFlow::Node sink) {
49 | exists (Invalidation i | sink.asExpr() = i.getAChild())
50 | }
51 |
52 | override predicate isBarrier(DataFlow::Node node) {
53 | node.asExpr().(FunctionCall).getTarget() instanceof CopyConstructor
54 | }
55 | }
56 |
57 | class InvalidatorFlow extends DataFlow::Configuration {
58 | InvalidatorFlow() { this = "InvalidatorFlow" }
59 |
60 | override predicate isSource(DataFlow::Node source) {
61 | exists(source)
62 | }
63 |
64 | override predicate isSink(DataFlow::Node sink) {
65 | sink.asExpr().getEnclosingElement() instanceof Invalidator
66 | }
67 |
68 | override predicate isBarrier(DataFlow::Node node) {
69 | node.asExpr().(FunctionCall).getTarget() instanceof CopyConstructor
70 | }
71 | }
72 |
--------------------------------------------------------------------------------
/ql/src/trailofbits/itergator/invalidations.qll:
--------------------------------------------------------------------------------
1 | private import cpp
2 | private import trailofbits.itergator.iterators
3 |
4 | abstract class PotentialInvalidation extends Function {
5 | cached abstract predicate invalidates(Iterated i);
6 |
7 | Expr invalidatedChild(Invalidation invd) {
8 | // by default, invalidates object method is called on
9 | result = invd.getQualifier()
10 | }
11 | }
12 |
--------------------------------------------------------------------------------
/ql/src/trailofbits/itergator/invalidations/Destructor.qll:
--------------------------------------------------------------------------------
1 | private import trailofbits.itergator.iterators
2 | private import cpp
3 |
4 | import trailofbits.itergator.invalidations
5 |
6 | class PotentialInvalidationDestructor extends PotentialInvalidation {
7 | PotentialInvalidationDestructor() {
8 | this instanceof MemberFunction and this.getName().matches("~%")
9 | }
10 |
11 | override predicate invalidates(Iterated i) {
12 | i.getType().refersTo(this.getParentScope())
13 | }
14 | }
15 |
--------------------------------------------------------------------------------
/ql/src/trailofbits/itergator/invalidations/STL.qll:
--------------------------------------------------------------------------------
1 | private import trailofbits.itergator.iterators
2 | private import cpp
3 |
4 | import trailofbits.itergator.invalidations
5 |
6 | private string typeName(Iterated i) {
7 | result = i.getTarget().getType().stripType().getName()
8 | }
9 |
10 | class PotentialInvalidationSTL extends PotentialInvalidation {
11 | PotentialInvalidationSTL() {
12 | this instanceof MemberFunction
13 | }
14 |
15 | override Expr invalidatedChild(Invalidation invd) {
16 | result = super.invalidatedChild(invd)
17 | // swap can also invalidate the first argument
18 | or this.hasName("swap") and result = invd.getArgument(0)
19 | }
20 |
21 | override predicate invalidates(Iterated i) {
22 | i.getType().refersTo(this.getParentScope())
23 | and (
24 | typeName(i).matches("vector<%") and this.vectorInvalidation()
25 | or typeName(i).matches("deque<%") and this.dequeInvalidation()
26 | or typeName(i).regexpMatch("unordered_(set|multiset)<.*") and this.setInvalidation()
27 | )
28 | }
29 |
30 | predicate vectorInvalidation() {
31 | this.hasName("push_back")
32 | or this.hasName("reserve")
33 | or this.hasName("insert")
34 | or this.hasName("emplace_back")
35 | or this.hasName("emplace")
36 | or this.hasName("erase")
37 | or this.hasName("pop_back")
38 | or this.hasName("resize")
39 | or this.hasName("shrink_to_fit")
40 | or this.hasName("clear")
41 | or this.hasName("swap")
42 | }
43 |
44 | predicate dequeInvalidation() {
45 | this.hasName("push_back")
46 | or this.hasName("push_front")
47 | or this.hasName("pop_back")
48 | or this.hasName("pop_front")
49 | or this.hasName("insert")
50 | or this.hasName("erase")
51 | or this.hasName("emplace")
52 | or this.hasName("emplace_front")
53 | or this.hasName("emplace_back")
54 | or this.hasName("resize")
55 | or this.hasName("clear")
56 | or this.hasName("shrink_to_fit")
57 | or this.hasName("swap")
58 | }
59 |
60 | predicate setInvalidation() {
61 | this.hasName("emplace")
62 | or this.hasName("emplace_hint")
63 | or this.hasName("insert")
64 | or this.hasName("clear")
65 | }
66 | }
67 |
--------------------------------------------------------------------------------
/ql/src/trailofbits/itergator/iterators.qll:
--------------------------------------------------------------------------------
1 | private import cpp
2 | private import trailofbits.itergator.invalidations
3 |
4 | class Iterator extends Variable {
5 | Iterator() {
6 | this.getUnderlyingType().getName().matches("%iterator%")
7 | // getType is inconsistent
8 | or this.getAnAssignedValue().(FunctionCall).getTarget().(MemberFunction).getName().regexpMatch("c?r?begin")
9 | or this.getAnAssignedValue().(FunctionCall).getTarget().(MemberFunction).getName().regexpMatch("c?r?end")
10 | or this.getAnAssignedValue().(FunctionCall).getTarget().hasName("find")
11 | }
12 | }
13 |
14 | // the location where a variable is being iterated over
15 | class Iterated extends VariableAccess {
16 | Iterator iterator;
17 |
18 | Iterated() {
19 | iterator.getAnAssignedValue().getChild(-1) = this and not this.getTarget().isCompilerGenerated()
20 | // show the iterable assigned to __range in ranged based for loops
21 | or (iterator.getAnAssignedValue().getChild(-1).(VariableAccess).getTarget().isCompilerGenerated()
22 | and this = iterator.getAnAssignedValue().getChild(-1).(VariableAccess).getTarget().getAnAssignedValue())
23 | }
24 |
25 | Iterator iterator() {
26 | result = iterator
27 | }
28 | }
29 |
30 | // function call with utility predicates
31 | private class FunctionCallR extends FunctionCall {
32 | predicate containedBy(Stmt other) {
33 | (other.getASuccessor*() = this
34 | and other.getAChild*() = this)
35 | // for destructors
36 | or exists (Function f | f.getBlock() = other and this.getEnclosingFunction() = f)
37 | }
38 |
39 | predicate callsPotentialInvalidation() {
40 | this.getTarget().(PotentialInvalidation).invalidates(any (Iterated i))
41 | }
42 |
43 | predicate callsPotentialInvalidation(Iterated i) {
44 | this.getTarget().(PotentialInvalidation).invalidates(i)
45 | }
46 | }
47 |
48 | // a call to any function that could call a PotentialInvalidation
49 | class InvalidatorT extends FunctionCallR {
50 | InvalidatorT() {
51 | this.callsPotentialInvalidation() or
52 | exists (InvalidatorT i |
53 | i.containedBy(this.getTarget().getBlock())
54 | )
55 | }
56 |
57 | InvalidatorT child() {
58 | result = this.getTarget().getBlock().getAChild+().(InvalidatorT)
59 | or exists (DestructorCall d | d.getEnclosingFunction() = this.getTarget() and d.(InvalidatorT) = result)
60 | }
61 |
62 | Iterated iterated_() {
63 | this.callsPotentialInvalidation(result)
64 | or result = this.child().iterated_()
65 | }
66 |
67 | InvalidatorT potentialInvalidation() {
68 | this.callsPotentialInvalidation(this.iterated_()) and result = this
69 | or result = this.child().potentialInvalidation()
70 | }
71 | }
72 |
73 | // calls that actually perform the invalidation
74 | class Invalidation extends InvalidatorT {
75 | Invalidator invalidator;
76 |
77 | Invalidation() {
78 | this = invalidator.potentialInvalidation() and invalidator.iterated() = this.iterated_()
79 | }
80 |
81 | Invalidator invalidator() {
82 | result = invalidator
83 | }
84 | }
85 |
86 | // the top level invalidation calls (directly inside loop bodies)
87 | class Invalidator extends InvalidatorT {
88 | Iterated iterated;
89 |
90 | Invalidator() {
91 | iterated = this.iterated_() and
92 | this.containedBy(iterated.iterator().getParentScope())
93 | }
94 |
95 | Iterated iterated() {
96 | result = iterated
97 | }
98 |
99 | Invalidation invalidation() {
100 | result = any (Invalidation i | i.invalidator() = this)
101 | }
102 | }
103 |
--------------------------------------------------------------------------------