{"id":18894202,"url":"https://github.com/trailofbits/itergator","last_synced_at":"2026-01-27T07:32:40.211Z","repository":{"id":52427206,"uuid":"281758611","full_name":"trailofbits/itergator","owner":"trailofbits","description":"CodeQL library and queries for iterator invalidation","archived":false,"fork":false,"pushed_at":"2021-05-05T02:22:37.000Z","size":22,"stargazers_count":22,"open_issues_count":0,"forks_count":7,"subscribers_count":29,"default_branch":"master","last_synced_at":"2025-06-01T11:59:27.719Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"CodeQL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trailofbits.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-22T18:52:16.000Z","updated_at":"2025-05-20T13:13:45.000Z","dependencies_parsed_at":"2022-08-19T06:30:15.853Z","dependency_job_id":null,"html_url":"https://github.com/trailofbits/itergator","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/trailofbits/itergator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fitergator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fitergator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fitergator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fitergator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trailofbits","download_url":"https://codeload.github.com/trailofbits/itergator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fitergator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28808021,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T07:14:39.408Z","status":"ssl_error","status_checked_at":"2026-01-27T07:14:39.098Z","response_time":168,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T08:19:52.046Z","updated_at":"2026-01-27T07:32:40.198Z","avatar_url":"https://github.com/trailofbits.png","language":"CodeQL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Itergator\n\nA [CodeQL](https://securitylab.github.com/tools/codeql) library for detecting and analyzing iterator invalidation in C++ codebases.\n\n## Getting started\n\nSet 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).\n\nDownload Itergator and [add it to your workspace](https://code.visualstudio.com/docs/editor/multi-root-workspaces#_adding-folders).\n\n```\ngit clone https://github.com/trailofbits/itergator\n```\n\n[Open and run](https://help.semmle.com/codeql/codeql-for-vscode/procedures/using-extension.html#running-a-query) the desired queries.\n\nTo use the classes in your own queries, add Itergator to your `qlpack.yml`:\n\n```yaml\nname: codeql-custom-queries-cpp\nversion: 0.0.0\nlibraryPathDependencies:\n    - codeql-cpp\n    - trailofbits-itergator\n```\n\nThen import the libraries:\n\n```codeql\nimport trailofbits.itergator.iterators\nimport trailofbits.itergator.dataflow\nimport trailofbits.itergator.invalidations.Destructor\nimport trailofbits.itergator.invalidations.STL\n```\n\n## Queries\n\n### `IteratedTypes.ql`\n\nReturns a list of iterated types.\n\nThere may be false positives, such as when an iterator is used in an expression that is assigned to another:\n\n```cpp\niterator __pos = __position._M_const_cast()\n```\n\n### `InvalidationFlows.ql`\n\nReturns a list of potential invalidations.\n\nResults 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.\n\nThis 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).\n\n## Libraries\n\n### `trailofbits.itergator.iterators`\n\nClasses representing iterators and invalidations in the codebase.\n\n\u003ca name=\"Iterator\"\u003e\u003c/a\u003e\n\n```codeql\nclass Iterator extends Variable\n```\n\n\u003e A variable that stores an iterator.\n\n\u003ca name=\"Iterated\"\u003e\u003c/a\u003e\n\n```codeql\nclass Iterated extends VariableAccess\n```\n\n\u003e The access of a container where it is being iterated over, e.g. `vec.begin()`.\n\u003e\n\u003e Member predicate `Iterator iterator()` returns a variable the resulting iterator is stored in.\n\n\u003ca name=\"Invalidator\"\u003e\u003c/a\u003e\n\n```codeql\nclass Invalidator extends InvalidatorT\n```\n\n\u003e A function call within the scope of an iterator that could trigger an invalidation.\n\u003e\n\u003e Member predicate `Iterated iterated()` returns an `Iterated` element in the assignment of an iterator with the same scope as this `Invalidator`.\n\u003e\n\u003e Member predicate `Invalidation invalidation()` returns a function call that could invalidate an iterator in the scope of this invalidator.\n\n\u003ca name=\"Invalidation\"\u003e\u003c/a\u003e\n\n```codeql\nclass Invalidation extends InvalidatorT\n```\n\n\u003e A function call that is a potential invalidation and could be reached from an `Invalidator`.\n\u003e\n\u003e Member predicate `Invalidator invalidator()` returns an `Invalidator` function call within the scope of a correctly typed iterator that this is reachable from.\n\n\u003ca name=\"InvalidatorT\"\u003e\u003c/a\u003e\n\n```codeql\nclass InvalidatorT extends FunctionCallR\n```\n\n\u003e A class of function call that composes the path from an `Invalidator` to an `Invalidation`.\n\u003e\n\u003e 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.\n\n### `trailofbits.itergator.dataflow`\n\n[Global data flow](https://help.semmle.com/QL/learn-ql/cpp/dataflow.html#global-data-flow) configurations for Itergator's classes.\n\n```codeql\nclass IteratorFlow extends DataFlow::Configuration\n```\n\n```codeql\nclass IteratedFlow extends DataFlow::Configuration\n```\n\n```codeql\nclass InvalidationFlow extends DataFlow::Configuration\n```\n\n```codeql\nclass InvalidatorFlow extends DataFlow::Configuration\n```\n\n### `trailofbits.itergator.invalidations`\n\nA framework for designating functions as potentially invalidating.\n\n```codeql\nabstract class PotentialInvalidation extends Function\n```\n\n\u003e This class can be extended to define potential invalidations.\n\u003e\n\u003e Member predicate `invalidates(Iterated i)` holds if a call to the function could invalidate an iterator of the type of the parameter `i`.\n\nTwo potential invalidation definitions are already written:\n\n```codeql\nimport trailofbits.itergator.invalidations.Destructor\n```\n\n\u003e Destructors of the iterated type.\n\n```codeql\nimport trailofbits.itergator.invalidations.STL\n```\n\n\u003e Member functions of STL types based on the C++ specification. This does not include destructors.\n\n[These classes](ql/src/trailofbits/itergator/invalidations) may be used as examples when writing custom invalidation conditions.\n\n## License\n\nItergator 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrailofbits%2Fitergator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrailofbits%2Fitergator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrailofbits%2Fitergator/lists"}