From 34f91f8129ec37c06f5d0daeffbf6913fd9edc7e Mon Sep 17 00:00:00 2001 From: Felicity Chapman Date: Mon, 13 May 2024 16:23:06 +0100 Subject: [PATCH 1/4] Stop building the CodeQL for VS Code docs --- docs/codeql/conf.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/codeql/conf.py b/docs/codeql/conf.py index fca3f272647b..5bc008b7a10b 100644 --- a/docs/codeql/conf.py +++ b/docs/codeql/conf.py @@ -2,13 +2,13 @@ # # The Sphinx config values used in the CodeQL documentation that is published # at codeql.github.com/docs -# +# # Note that not all possible configuration values are present in this file. # # All configuration values have a default; values that are commented out # serve to show the default. # -# For details of all possible config values, +# For details of all possible config values, # see https://www.sphinx-doc.org/en/master/usage/configuration.html # # -- GENERAL CONFIG VALUES ------------------------------------------------ @@ -53,7 +53,7 @@ def setup(sphinx): - sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) + sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) from qllexer import QLLexer sphinx.add_lexer("ql", QLLexer() if sphinx_mod.version_info[0] <= 3 else QLLexer) @@ -86,7 +86,7 @@ def setup(sphinx): # HTML theme options used to customize the look and feel of the docs. html_theme_options = {'font_size': '16px', - 'body_text': '#333', + 'body_text': '#333', 'link': '#2F1695', 'link_hover': '#2F1695', 'show_powered_by': False, @@ -106,4 +106,4 @@ def setup(sphinx): html_favicon = 'images/site/favicon.ico' # Exclude these paths from being built by Sphinx -exclude_patterns = ['vale*', '_static', '_templates', 'reusables', 'images', 'support', 'ql-training', 'query-help', '_build', '*.py*', 'README.rst'] +exclude_patterns = ['vale*', '_static', '_templates', 'reusables', 'images', 'support', 'ql-training', 'query-help', '_build', '*.py*', 'README.rst', 'codeql-for-visual-studio-code'] From c6ee25497e5f902ca8ea59c66bdcfb05c1503389 Mon Sep 17 00:00:00 2001 From: Felicity Chapman Date: Wed, 15 May 2024 12:07:53 +0100 Subject: [PATCH 2/4] Replace old references to VS Code articles --- .../analyzing-data-flow-in-cpp-new.rst | 2 +- .../analyzing-data-flow-in-cpp.rst | 2 +- .../analyzing-data-flow-in-csharp.rst | 2 +- .../analyzing-data-flow-in-java.rst | 6 ++-- ...data-flow-in-javascript-and-typescript.rst | 6 ++-- .../analyzing-data-flow-in-python.rst | 2 +- .../analyzing-data-flow-in-ruby.rst | 26 ++++++++--------- .../analyzing-data-flow-in-swift.rst | 4 +-- ...ing-library-models-for-java-and-kotlin.rst | 3 +- .../data-flow-cheat-sheet-for-javascript.rst | 4 +-- ...-labels-for-precise-data-flow-analysis.rst | 2 +- docs/codeql/contents.rst | 1 - .../about-codeql-queries.rst | 28 +++++++++---------- .../about-data-flow-analysis.rst | 2 +- .../creating-path-queries.rst | 3 +- 15 files changed, 46 insertions(+), 47 deletions(-) diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-cpp-new.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-cpp-new.rst index 0356b9288172..0232d64b8dee 100644 --- a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-cpp-new.rst +++ b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-cpp-new.rst @@ -408,7 +408,7 @@ Exercise 4 Further reading --------------- -- ":ref:`Exploring data flow with path queries `" +- `Exploring data flow with path queries `__ in the GitHub documentation .. include:: ../reusables/cpp-further-reading.rst diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-cpp.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-cpp.rst index f9ed5af0db8e..a37b3668d08d 100644 --- a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-cpp.rst +++ b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-cpp.rst @@ -380,7 +380,7 @@ Exercise 4 Further reading --------------- -- ":ref:`Exploring data flow with path queries `" +- `Exploring data flow with path queries `__ in the GitHub documentation .. include:: ../reusables/cpp-further-reading.rst diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-csharp.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-csharp.rst index 61eb803bdc9f..5750891774f3 100644 --- a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-csharp.rst +++ b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-csharp.rst @@ -541,7 +541,7 @@ This can be adapted from the ``SystemUriFlow`` class: Further reading --------------- -- ":ref:`Exploring data flow with path queries `" +- `Exploring data flow with path queries `__ in the GitHub documentation .. include:: ../reusables/csharp-further-reading.rst diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-java.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-java.rst index 3a9b84cfcc3e..b71dd43ef74f 100644 --- a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-java.rst +++ b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-java.rst @@ -3,7 +3,7 @@ Analyzing data flow in Java and Kotlin ====================================== -You can use CodeQL to track the flow of data through a Java/Kotlin program to its use. +You can use CodeQL to track the flow of data through a Java/Kotlin program to its use. .. include:: ../reusables/kotlin-beta-note.rst @@ -171,7 +171,7 @@ Global data flow tracks data flow throughout the entire program, and is therefor .. pull-quote:: Note .. include:: ../reusables/path-problem.rst - + Using global data flow ~~~~~~~~~~~~~~~~~~~~~~ @@ -362,7 +362,7 @@ Exercise 4 Further reading --------------- -- ":ref:`Exploring data flow with path queries `" +- `Exploring data flow with path queries `__ in the GitHub documentation .. include:: ../reusables/java-further-reading.rst diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-javascript-and-typescript.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-javascript-and-typescript.rst index 733415729407..dc5956da644b 100644 --- a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-javascript-and-typescript.rst +++ b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-javascript-and-typescript.rst @@ -16,7 +16,7 @@ For a more general introduction to modeling data flow, see ":ref:`About data flo Data flow nodes --------------- -Both local and global data flow, as well as taint tracking, work on a representation of the program known as the :ref:`data flow graph `. +Both local and global data flow, as well as taint tracking, work on a representation of the program known as the :ref:`data flow graph `. Nodes on the data flow flow graph may also correspond to nodes on the abstract syntax tree, but they are not the same. While AST nodes belong to class ``ASTNode`` and its subclasses, data flow nodes belong to class ``DataFlow::Node`` and its subclasses: @@ -557,8 +557,8 @@ Exercise 4 Further reading --------------- -- ":ref:`Exploring data flow with path queries `" +- `Exploring data flow with path queries `__ in the GitHub documentation .. include:: ../reusables/java-further-reading.rst -.. include:: ../reusables/codeql-ref-tools-further-reading.rst \ No newline at end of file +.. include:: ../reusables/codeql-ref-tools-further-reading.rst diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-python.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-python.rst index e93f2df3b733..3aeff566b9c0 100644 --- a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-python.rst +++ b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-python.rst @@ -359,7 +359,7 @@ This data flow configuration tracks data flow from environment variables to open Further reading --------------- -- ":ref:`Exploring data flow with path queries `" +- `Exploring data flow with path queries `__ in the GitHub documentation .. include:: ../reusables/python-further-reading.rst diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-ruby.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-ruby.rst index 95744747cbc2..db2fea67c8a7 100644 --- a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-ruby.rst +++ b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-ruby.rst @@ -111,7 +111,7 @@ This query finds the filename argument passed in each call to ``File.open``: import codeql.ruby.DataFlow import codeql.ruby.ApiGraphs - + from DataFlow::CallNode call where call = API::getTopLevelMember("File").getAMethodCall("open") select call.getArgument(0) @@ -126,7 +126,7 @@ So we use local data flow to find all expressions that flow into the argument: import codeql.ruby.DataFlow import codeql.ruby.ApiGraphs - + from DataFlow::CallNode call, DataFlow::ExprNode expr where call = API::getTopLevelMember("File").getAMethodCall("open") and @@ -143,7 +143,7 @@ We can update the query to specify that ``expr`` is an instance of a ``LocalSour import codeql.ruby.DataFlow import codeql.ruby.ApiGraphs - + from DataFlow::CallNode call, DataFlow::ExprNode expr where call = API::getTopLevelMember("File").getAMethodCall("open") and @@ -158,7 +158,7 @@ That would allow us to use the member predicate ``flowsTo`` on ``LocalSourceNode import codeql.ruby.DataFlow import codeql.ruby.ApiGraphs - + from DataFlow::CallNode call, DataFlow::ExprNode expr where call = API::getTopLevelMember("File").getAMethodCall("open") and @@ -171,7 +171,7 @@ As an alternative, we can ask more directly that ``expr`` is a local source of t import codeql.ruby.DataFlow import codeql.ruby.ApiGraphs - + from DataFlow::CallNode call, DataFlow::ExprNode expr where call = API::getTopLevelMember("File").getAMethodCall("open") and @@ -190,7 +190,7 @@ This query finds instances where a parameter is used as the name when opening a import codeql.ruby.DataFlow import codeql.ruby.ApiGraphs - + from DataFlow::CallNode call, DataFlow::ParameterNode p where call = API::getTopLevelMember("File").getAMethodCall("open") and @@ -206,7 +206,7 @@ This query finds calls to ``File.open`` where the file name is derived from a pa import codeql.ruby.DataFlow import codeql.ruby.TaintTracking import codeql.ruby.ApiGraphs - + from DataFlow::CallNode call, DataFlow::ParameterNode p where call = API::getTopLevelMember("File").getAMethodCall("open") and @@ -327,17 +327,17 @@ The following global taint-tracking query finds path arguments in filesystem acc import codeql.ruby.TaintTracking import codeql.ruby.Concepts import codeql.ruby.dataflow.RemoteFlowSources - + module RemoteToFileConfiguration implements DataFlow::ConfigSig { predicate isSource(DataFlow::Node source) { source instanceof RemoteFlowSource } - + predicate isSink(DataFlow::Node sink) { sink = any(FileSystemAccess fa).getAPathArgument() } } module RemoteToFileFlow = TaintTracking::Global; - + from DataFlow::Node input, DataFlow::Node fileAccess where RemoteToFileFlow::flow(input, fileAccess) select fileAccess, "This file access uses data from $@.", input, "user-controllable input." @@ -352,7 +352,7 @@ The following global data-flow query finds calls to ``File.open`` where the file import codeql.ruby.DataFlow import codeql.ruby.controlflow.CfgNodes import codeql.ruby.ApiGraphs - + module EnvironmentToFileConfiguration implements DataFlow::ConfigSig { predicate isSource(DataFlow::Node source) { exists(ExprNodes::ConstantReadAccessCfgNode env | @@ -367,7 +367,7 @@ The following global data-flow query finds calls to ``File.open`` where the file } module EnvironmentToFileFlow = DataFlow::Global; - + from DataFlow::Node environment, DataFlow::Node fileOpen where EnvironmentToFileFlow::flow(environment, fileOpen) select fileOpen, "This call to 'File.open' uses data from $@.", environment, @@ -376,7 +376,7 @@ The following global data-flow query finds calls to ``File.open`` where the file Further reading --------------- -- ":ref:`Exploring data flow with path queries `" +- `Exploring data flow with path queries `__ in the GitHub documentation .. include:: ../reusables/ruby-further-reading.rst diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-swift.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-swift.rst index 9de7d620abf4..63e4927352c2 100644 --- a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-swift.rst +++ b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-swift.rst @@ -34,7 +34,7 @@ The ``Node`` class has a number of useful subclasses, such as ``ExprNode`` for e Expr asExpr() { ... } /** - * Gets the control flow node that corresponds to this data flow node. + * Gets the control flow node that corresponds to this data flow node. */ ControlFlowNode getCfgNode() { ... } @@ -284,7 +284,7 @@ The following global taint-tracking query finds places where a value from a remo Further reading --------------- -- ":ref:`Exploring data flow with path queries `" +- `Exploring data flow with path queries `__ in the GitHub documentation .. include:: ../reusables/swift-further-reading.rst diff --git a/docs/codeql/codeql-language-guides/customizing-library-models-for-java-and-kotlin.rst b/docs/codeql/codeql-language-guides/customizing-library-models-for-java-and-kotlin.rst index dd7f352f6d01..0b653c1d6122 100644 --- a/docs/codeql/codeql-language-guides/customizing-library-models-for-java-and-kotlin.rst +++ b/docs/codeql/codeql-language-guides/customizing-library-models-for-java-and-kotlin.rst @@ -16,7 +16,8 @@ This article contains reference material about how to define custom models for s The best way to create your own models is using the CodeQL model editor in the CodeQL extension for Visual Studio Code. The model editor automatically guides you through the process of defining models, displaying the properties you need to define and the options available. You can save the resulting models as data extension files in CodeQL model packs and use them without worrying about the syntax. -For more information, see ":ref:`Using the CodeQL model editor `." +For more information, see `Using the CodeQL model editor `__ in the GitHub documentation + About data extensions --------------------- diff --git a/docs/codeql/codeql-language-guides/data-flow-cheat-sheet-for-javascript.rst b/docs/codeql/codeql-language-guides/data-flow-cheat-sheet-for-javascript.rst index 7d9ac42c3d8e..f006e51efe48 100644 --- a/docs/codeql/codeql-language-guides/data-flow-cheat-sheet-for-javascript.rst +++ b/docs/codeql/codeql-language-guides/data-flow-cheat-sheet-for-javascript.rst @@ -254,8 +254,8 @@ Troubleshooting Further reading --------------- -- ":ref:`Exploring data flow with path queries `" +- `Exploring data flow with path queries `__ in the GitHub documentation .. include:: ../reusables/javascript-further-reading.rst -.. include:: ../reusables/codeql-ref-tools-further-reading.rst \ No newline at end of file +.. include:: ../reusables/codeql-ref-tools-further-reading.rst diff --git a/docs/codeql/codeql-language-guides/using-flow-labels-for-precise-data-flow-analysis.rst b/docs/codeql/codeql-language-guides/using-flow-labels-for-precise-data-flow-analysis.rst index 8625d6373668..4ee1ab6719ca 100644 --- a/docs/codeql/codeql-language-guides/using-flow-labels-for-precise-data-flow-analysis.rst +++ b/docs/codeql/codeql-language-guides/using-flow-labels-for-precise-data-flow-analysis.rst @@ -405,7 +405,7 @@ string may be an absolute path and whether it may contain ``..`` components. Further reading --------------- -- ":ref:`Exploring data flow with path queries `" +- `Exploring data flow with path queries `__ in the GitHub documentation .. include:: ../reusables/javascript-further-reading.rst diff --git a/docs/codeql/contents.rst b/docs/codeql/contents.rst index 8ecc0ca73043..a91ff31e0aa8 100644 --- a/docs/codeql/contents.rst +++ b/docs/codeql/contents.rst @@ -6,7 +6,6 @@ CodeQL documentation :maxdepth: 3 codeql-overview/index - codeql-for-visual-studio-code/index writing-codeql-queries/index codeql-language-guides/index ql-language-reference/index diff --git a/docs/codeql/writing-codeql-queries/about-codeql-queries.rst b/docs/codeql/writing-codeql-queries/about-codeql-queries.rst index 0405c0474830..6d263b80303b 100644 --- a/docs/codeql/writing-codeql-queries/about-codeql-queries.rst +++ b/docs/codeql/writing-codeql-queries/about-codeql-queries.rst @@ -26,7 +26,7 @@ Basic query structure .. code-block:: ql /** - * + * * Query metadata * */ @@ -39,18 +39,18 @@ Basic query structure where /* ... logical formula ... */ select /* ... expressions ... */ -The following sections describe the information that is typically included in a query file for alerts. Path queries are discussed in more detail in ":doc:`Creating path queries `." +The following sections describe the information that is typically included in a query file for alerts. Path queries are discussed in more detail in ":doc:`Creating path queries `." Query metadata ============== Query metadata is used to identify your custom queries when they are added to the GitHub repository or used in your analysis. Metadata provides information about the query's purpose, and also specifies how to interpret and display the query results. For a full list of metadata properties, see ":doc:`Metadata for CodeQL queries `." The exact metadata requirement depends on how you are going to run your query: -- If you are contributing a query to the GitHub repository, please read the `query metadata style guide `__. +- If you are contributing a query to the GitHub repository, please read the `query metadata style guide `__. - If you are analyzing a database using the `CodeQL CLI `__, your query metadata must contain ``@kind``. -- If you are running a query with the CodeQL extension for VS Code, metadata is not mandatory. However, if you want your results to be displayed as either an 'alert' or a 'path', you must specify the correct ``@kind`` property, as explained below. For more information, see ":ref:`Analyzing your projects `" in the CodeQL for VS Code help. +- If you are running a query with the CodeQL extension for VS Code, metadata is not mandatory. However, if you want your results to be displayed as either an 'alert' or a 'path', you must specify the correct ``@kind`` property, as explained below. For more information, see `Running CodeQL queries `__ in the GitHub documentation. -.. pull-quote:: +.. pull-quote:: Note @@ -66,8 +66,8 @@ Query metadata is used to identify your custom queries when they are added to th Import statements ================= -Each query generally contains one or more ``import`` statements, which define the :ref:`libraries ` or :ref:`modules ` to import into the query. Libraries and modules provide a way of grouping together related :ref:`types `, :ref:`predicates `, and other modules. The contents of each library or module that you import can then be accessed by the query. -Our `open source repository on GitHub `__ contains the standard CodeQL libraries for each supported language. +Each query generally contains one or more ``import`` statements, which define the :ref:`libraries ` or :ref:`modules ` to import into the query. Libraries and modules provide a way of grouping together related :ref:`types `, :ref:`predicates `, and other modules. The contents of each library or module that you import can then be accessed by the query. +Our `open source repository on GitHub `__ contains the standard CodeQL libraries for each supported language. When writing your own alert queries, you would typically import the standard library for the language of the project that you are querying. For more information about importing the standard CodeQL libraries, see the CodeQL library guides: @@ -87,33 +87,33 @@ You can explore the contents of all the standard libraries in the `CodeQL librar Optional CodeQL classes and predicates -------------------------------------- -You can customize your analysis by defining your own predicates and classes in the query. For further information, see :ref:`Defining a predicate ` and :ref:`Defining a class `. +You can customize your analysis by defining your own predicates and classes in the query. For further information, see :ref:`Defining a predicate ` and :ref:`Defining a class `. From clause =========== -The ``from`` clause declares the variables that are used in the query. Each declaration must be of the form `` ``. +The ``from`` clause declares the variables that are used in the query. Each declaration must be of the form `` ``. For more information on the available :ref:`types `, and to learn how to define your own types using :ref:`classes `, see the :ref:`QL language reference `. Where clause ============ -The ``where`` clause defines the logical conditions to apply to the variables declared in the ``from`` clause to generate your results. This clause uses :ref:`aggregations `, :ref:`predicates `, and logical :ref:`formulas ` to limit the variables of interest to a smaller set, which meet the defined conditions. +The ``where`` clause defines the logical conditions to apply to the variables declared in the ``from`` clause to generate your results. This clause uses :ref:`aggregations `, :ref:`predicates `, and logical :ref:`formulas ` to limit the variables of interest to a smaller set, which meet the defined conditions. The CodeQL libraries group commonly used predicates for specific languages and frameworks. You can also define your own predicates in the body of the query file or in your own custom modules, as described above. Select clause ============= -The ``select`` clause specifies the results to display for the variables that meet the conditions defined in the ``where`` clause. The valid structure for the select clause is defined by the ``@kind`` property specified in the metadata. +The ``select`` clause specifies the results to display for the variables that meet the conditions defined in the ``where`` clause. The valid structure for the select clause is defined by the ``@kind`` property specified in the metadata. Select clauses for alert queries (``@kind problem``) consist of two 'columns', with the following structure:: select element, string - ``element``: a code element that is identified by the query, which defines where the alert is displayed. -- ``string``: a message, which can also include links and placeholders, explaining why the alert was generated. +- ``string``: a message, which can also include links and placeholders, explaining why the alert was generated. -You can modify the alert message defined in the final column of the ``select`` statement to give more detail about the alert or path found by the query using links and placeholders. For more information, see ":doc:`Defining the results of a query `." +You can modify the alert message defined in the final column of the ``select`` statement to give more detail about the alert or path found by the query using links and placeholders. For more information, see ":doc:`Defining the results of a query `." Select clauses for path queries (``@kind path-problem``) are crafted to display both an alert and the source and sink of an associated path graph. For more information, see ":doc:`Creating path queries `." @@ -140,4 +140,4 @@ Query contributions to the open source GitHub repository may also have an accomp Query help files **************** -When you write a custom query, we also recommend that you write a query help file to explain the purpose of the query to other users. For more information, see the `Query help style guide `__ on GitHub, and the ":doc:`Query help files `." +When you write a custom query, we also recommend that you write a query help file to explain the purpose of the query to other users. For more information, see the `Query help style guide `__ on GitHub, and the ":doc:`Query help files `." diff --git a/docs/codeql/writing-codeql-queries/about-data-flow-analysis.rst b/docs/codeql/writing-codeql-queries/about-data-flow-analysis.rst index 1fde2e7ac2f6..98f5cf215e98 100644 --- a/docs/codeql/writing-codeql-queries/about-data-flow-analysis.rst +++ b/docs/codeql/writing-codeql-queries/about-data-flow-analysis.rst @@ -85,4 +85,4 @@ These flow steps are modeled in the taint-tracking library using predicates that Further reading *************** -- ":ref:`Exploring data flow with path queries `" +- `Exploring data flow with path queries `__ in the GitHub documentation diff --git a/docs/codeql/writing-codeql-queries/creating-path-queries.rst b/docs/codeql/writing-codeql-queries/creating-path-queries.rst index 41f0683594cc..3f20a1110be8 100644 --- a/docs/codeql/writing-codeql-queries/creating-path-queries.rst +++ b/docs/codeql/writing-codeql-queries/creating-path-queries.rst @@ -180,6 +180,5 @@ The alert message defined in the final column in the ``select`` statement can be Further reading *************** -- ":ref:`Exploring data flow with path queries `" - +- `Exploring data flow with path queries `__ in the GitHub documentation - `CodeQL repository `__ From 24da489bab9ca8a8959c361945e29aff0b46802e Mon Sep 17 00:00:00 2001 From: Felicity Chapman Date: Wed, 15 May 2024 12:14:10 +0100 Subject: [PATCH 3/4] Replace a few more old references --- docs/codeql/reusables/codespaces-template-note.rst | 5 ++--- docs/codeql/reusables/setup-to-run-tutorials.rst | 2 +- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/codeql/reusables/codespaces-template-note.rst b/docs/codeql/reusables/codespaces-template-note.rst index 1fee34e97342..e3abb1382284 100644 --- a/docs/codeql/reusables/codespaces-template-note.rst +++ b/docs/codeql/reusables/codespaces-template-note.rst @@ -3,6 +3,5 @@ Note You can use the CodeQL template (beta) in `GitHub Codespaces `__ to try out the QL concepts and programming-language-agnostic examples in these tutorials. The template includes a guided introduction to working with QL, and makes it easy to get started. - - When you're ready to run CodeQL queries on actual codebases, you will need to install the CodeQL extension in Visual Studio Code. For instructions, see ":ref:`Setting up CodeQL in Visual Studio Code `." - + + When you're ready to run CodeQL queries on actual codebases, you will need to install the CodeQL extension in Visual Studio Code. For instructions, see `Installing CodeQL for Visual Studio Code `__ in the GitHub documentation. diff --git a/docs/codeql/reusables/setup-to-run-tutorials.rst b/docs/codeql/reusables/setup-to-run-tutorials.rst index de761968d8a1..f6ec959eb9e9 100644 --- a/docs/codeql/reusables/setup-to-run-tutorials.rst +++ b/docs/codeql/reusables/setup-to-run-tutorials.rst @@ -1 +1 @@ -For information about installing the CodeQL extension for Visual Studio code, see ":ref:`Setting up CodeQL in Visual Studio Code `." +For information about installing the CodeQL extension for Visual Studio code, see `Installing CodeQL for Visual Studio Code `__ in the GitHub documentation. From b32fb1d9611f83e87ec32ea4deb59f184fa3e528 Mon Sep 17 00:00:00 2001 From: Felicity Chapman Date: Wed, 15 May 2024 12:43:40 +0100 Subject: [PATCH 4/4] Fix another couple of links --- .../analyzing-data-flow-in-cpp-new.rst | 2 +- .../codeql-language-guides/analyzing-data-flow-in-cpp.rst | 2 +- .../analyzing-data-flow-in-csharp.rst | 2 +- .../analyzing-data-flow-in-java.rst | 2 +- .../analyzing-data-flow-in-javascript-and-typescript.rst | 2 +- .../analyzing-data-flow-in-python.rst | 2 +- .../analyzing-data-flow-in-ruby.rst | 2 +- .../analyzing-data-flow-in-swift.rst | 2 +- .../customizing-library-models-for-java-and-kotlin.rst | 2 +- .../data-flow-cheat-sheet-for-javascript.rst | 2 +- .../using-flow-labels-for-precise-data-flow-analysis.rst | 2 +- docs/codeql/codeql-overview/codeql-glossary.rst | 2 +- .../writing-codeql-queries/about-data-flow-analysis.rst | 2 +- .../writing-codeql-queries/creating-path-queries.rst | 2 +- .../debugging-data-flow-queries-using-partial-flow.rst | 8 ++++---- docs/codeql/writing-codeql-queries/introduction-to-ql.rst | 8 ++++---- 16 files changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-cpp-new.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-cpp-new.rst index 0232d64b8dee..e6575e7488f0 100644 --- a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-cpp-new.rst +++ b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-cpp-new.rst @@ -408,7 +408,7 @@ Exercise 4 Further reading --------------- -- `Exploring data flow with path queries `__ in the GitHub documentation +- `Exploring data flow with path queries `__ in the GitHub documentation. .. include:: ../reusables/cpp-further-reading.rst diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-cpp.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-cpp.rst index a37b3668d08d..2642c84680cd 100644 --- a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-cpp.rst +++ b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-cpp.rst @@ -380,7 +380,7 @@ Exercise 4 Further reading --------------- -- `Exploring data flow with path queries `__ in the GitHub documentation +- `Exploring data flow with path queries `__ in the GitHub documentation. .. include:: ../reusables/cpp-further-reading.rst diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-csharp.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-csharp.rst index 5750891774f3..f6c018c0f868 100644 --- a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-csharp.rst +++ b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-csharp.rst @@ -541,7 +541,7 @@ This can be adapted from the ``SystemUriFlow`` class: Further reading --------------- -- `Exploring data flow with path queries `__ in the GitHub documentation +- `Exploring data flow with path queries `__ in the GitHub documentation. .. include:: ../reusables/csharp-further-reading.rst diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-java.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-java.rst index b71dd43ef74f..1a352d4e4ec6 100644 --- a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-java.rst +++ b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-java.rst @@ -362,7 +362,7 @@ Exercise 4 Further reading --------------- -- `Exploring data flow with path queries `__ in the GitHub documentation +- `Exploring data flow with path queries `__ in the GitHub documentation. .. include:: ../reusables/java-further-reading.rst diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-javascript-and-typescript.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-javascript-and-typescript.rst index dc5956da644b..1dfcd0b713b5 100644 --- a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-javascript-and-typescript.rst +++ b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-javascript-and-typescript.rst @@ -557,7 +557,7 @@ Exercise 4 Further reading --------------- -- `Exploring data flow with path queries `__ in the GitHub documentation +- `Exploring data flow with path queries `__ in the GitHub documentation. .. include:: ../reusables/java-further-reading.rst diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-python.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-python.rst index 3aeff566b9c0..8adbfb09a5ca 100644 --- a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-python.rst +++ b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-python.rst @@ -359,7 +359,7 @@ This data flow configuration tracks data flow from environment variables to open Further reading --------------- -- `Exploring data flow with path queries `__ in the GitHub documentation +- `Exploring data flow with path queries `__ in the GitHub documentation. .. include:: ../reusables/python-further-reading.rst diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-ruby.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-ruby.rst index db2fea67c8a7..444280008755 100644 --- a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-ruby.rst +++ b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-ruby.rst @@ -376,7 +376,7 @@ The following global data-flow query finds calls to ``File.open`` where the file Further reading --------------- -- `Exploring data flow with path queries `__ in the GitHub documentation +- `Exploring data flow with path queries `__ in the GitHub documentation. .. include:: ../reusables/ruby-further-reading.rst diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-swift.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-swift.rst index 63e4927352c2..b1e7a1593e87 100644 --- a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-swift.rst +++ b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-swift.rst @@ -284,7 +284,7 @@ The following global taint-tracking query finds places where a value from a remo Further reading --------------- -- `Exploring data flow with path queries `__ in the GitHub documentation +- `Exploring data flow with path queries `__ in the GitHub documentation. .. include:: ../reusables/swift-further-reading.rst diff --git a/docs/codeql/codeql-language-guides/customizing-library-models-for-java-and-kotlin.rst b/docs/codeql/codeql-language-guides/customizing-library-models-for-java-and-kotlin.rst index 0b653c1d6122..ec396d2932bb 100644 --- a/docs/codeql/codeql-language-guides/customizing-library-models-for-java-and-kotlin.rst +++ b/docs/codeql/codeql-language-guides/customizing-library-models-for-java-and-kotlin.rst @@ -16,7 +16,7 @@ This article contains reference material about how to define custom models for s The best way to create your own models is using the CodeQL model editor in the CodeQL extension for Visual Studio Code. The model editor automatically guides you through the process of defining models, displaying the properties you need to define and the options available. You can save the resulting models as data extension files in CodeQL model packs and use them without worrying about the syntax. -For more information, see `Using the CodeQL model editor `__ in the GitHub documentation +For more information, see `Using the CodeQL model editor `__ in the GitHub documentation. About data extensions diff --git a/docs/codeql/codeql-language-guides/data-flow-cheat-sheet-for-javascript.rst b/docs/codeql/codeql-language-guides/data-flow-cheat-sheet-for-javascript.rst index f006e51efe48..60d66ba1644a 100644 --- a/docs/codeql/codeql-language-guides/data-flow-cheat-sheet-for-javascript.rst +++ b/docs/codeql/codeql-language-guides/data-flow-cheat-sheet-for-javascript.rst @@ -254,7 +254,7 @@ Troubleshooting Further reading --------------- -- `Exploring data flow with path queries `__ in the GitHub documentation +- `Exploring data flow with path queries `__ in the GitHub documentation. .. include:: ../reusables/javascript-further-reading.rst diff --git a/docs/codeql/codeql-language-guides/using-flow-labels-for-precise-data-flow-analysis.rst b/docs/codeql/codeql-language-guides/using-flow-labels-for-precise-data-flow-analysis.rst index 4ee1ab6719ca..8e5d3c4285be 100644 --- a/docs/codeql/codeql-language-guides/using-flow-labels-for-precise-data-flow-analysis.rst +++ b/docs/codeql/codeql-language-guides/using-flow-labels-for-precise-data-flow-analysis.rst @@ -405,7 +405,7 @@ string may be an absolute path and whether it may contain ``..`` components. Further reading --------------- -- `Exploring data flow with path queries `__ in the GitHub documentation +- `Exploring data flow with path queries `__ in the GitHub documentation. .. include:: ../reusables/javascript-further-reading.rst diff --git a/docs/codeql/codeql-overview/codeql-glossary.rst b/docs/codeql/codeql-overview/codeql-glossary.rst index f86b5346e2c2..daf0d9c25324 100644 --- a/docs/codeql/codeql-overview/codeql-glossary.rst +++ b/docs/codeql/codeql-overview/codeql-glossary.rst @@ -61,7 +61,7 @@ The DIL format may change without warning between CLI releases. When you specify the ``--dump-dil`` option for ``codeql query compile``, CodeQL prints DIL to standard output for the queries it compiles. You can also view results in DIL format when you run queries in VS Code. -For more information, see ":ref:`Analyzing your projects `" in the CodeQL for VS Code help. +For more information, see `Running CodeQL queries `__ in the GitHub documentation. .. _extractor: diff --git a/docs/codeql/writing-codeql-queries/about-data-flow-analysis.rst b/docs/codeql/writing-codeql-queries/about-data-flow-analysis.rst index 98f5cf215e98..61290e095b24 100644 --- a/docs/codeql/writing-codeql-queries/about-data-flow-analysis.rst +++ b/docs/codeql/writing-codeql-queries/about-data-flow-analysis.rst @@ -85,4 +85,4 @@ These flow steps are modeled in the taint-tracking library using predicates that Further reading *************** -- `Exploring data flow with path queries `__ in the GitHub documentation +- `Exploring data flow with path queries `__ in the GitHub documentation. diff --git a/docs/codeql/writing-codeql-queries/creating-path-queries.rst b/docs/codeql/writing-codeql-queries/creating-path-queries.rst index 3f20a1110be8..036083d2912c 100644 --- a/docs/codeql/writing-codeql-queries/creating-path-queries.rst +++ b/docs/codeql/writing-codeql-queries/creating-path-queries.rst @@ -180,5 +180,5 @@ The alert message defined in the final column in the ``select`` statement can be Further reading *************** -- `Exploring data flow with path queries `__ in the GitHub documentation +- `Exploring data flow with path queries `__ in the GitHub documentation. - `CodeQL repository `__ diff --git a/docs/codeql/writing-codeql-queries/debugging-data-flow-queries-using-partial-flow.rst b/docs/codeql/writing-codeql-queries/debugging-data-flow-queries-using-partial-flow.rst index 53fe4e46a3ea..477562685a56 100644 --- a/docs/codeql/writing-codeql-queries/debugging-data-flow-queries-using-partial-flow.rst +++ b/docs/codeql/writing-codeql-queries/debugging-data-flow-queries-using-partial-flow.rst @@ -34,12 +34,12 @@ The same query can be slightly simplified by rewriting it without :ref:`path exp select sink, "Sink is reached from $@.", source.getNode(), "here" If a data-flow query that you have written doesn't produce the results you expect it to, there may be a problem with your query. -You can try to debug the potential problem by following the steps described below. +You can try to debug the potential problem by following the steps described below. Checking sources and sinks -------------------------- -Initially, you should make sure that the source and sink definitions contain what you expect. If either the source or sink is empty then there can never be any data flow. The easiest way to check this is using quick evaluation in CodeQL for VS Code. Select the text ``node instanceof MySource``, right-click, and choose "CodeQL: Quick Evaluation". This will evaluate the highlighted text, which in this case means the set of sources. For more information, see :ref:`Analyzing your projects ` in the CodeQL for VS Code help. +Initially, you should make sure that the source and sink definitions contain what you expect. If either the source or sink is empty then there can never be any data flow. The easiest way to check this is using quick evaluation in CodeQL for VS Code. Select the text ``node instanceof MySource``, right-click, and choose "CodeQL: Quick Evaluation". This will evaluate the highlighted text, which in this case means the set of sources. For more information, see `Running CodeQL queries `__ in the GitHub documentation. If both source and sink definitions look good then we will need to look for missing flow steps. @@ -106,9 +106,9 @@ To do quick evaluations of partial flow it is often easiest to add a predicate t If you are focusing on a single source then the ``src`` column is superfluous. You may of course also add other columns of interest based on ``n``, but including the enclosing callable and the distance to the source at the very least is generally recommended, as they can be useful columns to sort on to better inspect the results. -If you see a large number of partial flow results, you can focus them in a couple of ways: +If you see a large number of partial flow results, you can focus them in a couple of ways: -- If flow travels a long distance following an expected path, that can result in a lot of uninteresting flow being included in the exploration radius. To reduce the amount of uninteresting flow, you can replace the source definition with a suitable ``node`` that appears along the path and restart the partial flow exploration from that point. +- If flow travels a long distance following an expected path, that can result in a lot of uninteresting flow being included in the exploration radius. To reduce the amount of uninteresting flow, you can replace the source definition with a suitable ``node`` that appears along the path and restart the partial flow exploration from that point. - Creative use of barriers can be used to cut off flow paths that are uninteresting. This also reduces the number of partial flow results to explore while debugging. Further reading diff --git a/docs/codeql/writing-codeql-queries/introduction-to-ql.rst b/docs/codeql/writing-codeql-queries/introduction-to-ql.rst index 203f590f761e..01de71d49d4d 100644 --- a/docs/codeql/writing-codeql-queries/introduction-to-ql.rst +++ b/docs/codeql/writing-codeql-queries/introduction-to-ql.rst @@ -1,6 +1,6 @@ .. _introduction-to-ql: -Introduction to QL +Introduction to QL ================== Work through some simple exercises and examples to learn about the basics of QL and CodeQL. @@ -109,12 +109,12 @@ Example CodeQL queries ---------------------- The previous examples used the primitive types built in to QL. Although we chose a project to query, we didn't use the information in that project's database. -The following example queries *do* use these databases and give you an idea of how to use CodeQL to analyze projects. +The following example queries *do* use these databases and give you an idea of how to use CodeQL to analyze projects. Queries using the CodeQL libraries can find errors and uncover variants of important security vulnerabilities in codebases. Visit `GitHub Security Lab `__ to read about examples of vulnerabilities that we have recently found in open source projects. -Before you can run the following examples, you will need to install the CodeQL extension for Visual Studio Code. For more information, see :ref:`Setting up CodeQL in Visual Studio Code `. You will also need to import and select a database in the corresponding programming language. For more information about obtaining CodeQL databases, see `Managing CodeQL databases `__ in the CodeQL for VS Code documentation. +Before you can run the following examples, you will need to install the CodeQL extension for Visual Studio Code. For more information, see `Installing CodeQL for Visual Studio Code `__ in the GitHub documentation. You will also need to import and select a database in the corresponding programming language. To import the CodeQL library for a specific programming language, type ``import `` at the start of the query. @@ -166,7 +166,7 @@ Exercise 1 from string s where s = "lgtm" select s.length() - + There is often more than one way to define a query. For example, we can also write the above query in the shorter form: .. code-block:: ql