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 0356b928817..0232d64b8de 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 f9ed5af0db8..a37b3668d08 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 61eb803bdc9..5750891774f 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 3a9b84cfcc3..b71dd43ef74 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 73341572940..dc5956da644 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 e93f2df3b73..3aeff566b9c 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 95744747cbc..db2fea67c8a 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 9de7d620abf..63e4927352c 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 dd7f352f6d0..0b653c1d612 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 7d9ac42c3d8..f006e51efe4 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 8625d637366..4ee1ab6719c 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 8ecc0ca7304..a91ff31e0aa 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 0405c047483..6d263b80303 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 1fde2e7ac2f..98f5cf215e9 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 41f0683594c..3f20a1110be 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 `__