mirror of
https://github.com/github/codeql.git
synced 2026-04-26 09:15:12 +02:00
Merge pull request #16496 from github/felicitymay/sphinx-config
Stop building the CodeQL for VS Code docs now they've been migrated
This commit is contained in:
Felicity Chapman
@@ -408,7 +408,7 @@ Exercise 4
|
||||
Further reading
|
||||
---------------
|
||||
|
||||
- ":ref:`Exploring data flow with path queries <exploring-data-flow-with-path-queries>`"
|
||||
- `Exploring data flow with path queries <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries>`__ in the GitHub documentation.
|
||||
|
||||
|
||||
.. include:: ../reusables/cpp-further-reading.rst
|
||||
|
||||
@@ -380,7 +380,7 @@ Exercise 4
|
||||
Further reading
|
||||
---------------
|
||||
|
||||
- ":ref:`Exploring data flow with path queries <exploring-data-flow-with-path-queries>`"
|
||||
- `Exploring data flow with path queries <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries>`__ in the GitHub documentation.
|
||||
|
||||
|
||||
.. include:: ../reusables/cpp-further-reading.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>`"
|
||||
- `Exploring data flow with path queries <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries>`__ in the GitHub documentation.
|
||||
|
||||
|
||||
.. include:: ../reusables/csharp-further-reading.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>`"
|
||||
- `Exploring data flow with path queries <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries>`__ in the GitHub documentation.
|
||||
|
||||
|
||||
.. include:: ../reusables/java-further-reading.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 <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 <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>`"
|
||||
- `Exploring data flow with path queries <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries>`__ in the GitHub documentation.
|
||||
|
||||
|
||||
.. include:: ../reusables/java-further-reading.rst
|
||||
.. include:: ../reusables/codeql-ref-tools-further-reading.rst
|
||||
.. include:: ../reusables/codeql-ref-tools-further-reading.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>`"
|
||||
- `Exploring data flow with path queries <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries>`__ in the GitHub documentation.
|
||||
|
||||
|
||||
.. include:: ../reusables/python-further-reading.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<RemoteToFileConfiguration>;
|
||||
|
||||
|
||||
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<EnvironmentToFileConfiguration>;
|
||||
|
||||
|
||||
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>`"
|
||||
- `Exploring data flow with path queries <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries>`__ in the GitHub documentation.
|
||||
|
||||
|
||||
.. include:: ../reusables/ruby-further-reading.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>`"
|
||||
- `Exploring data flow with path queries <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries>`__ in the GitHub documentation.
|
||||
|
||||
|
||||
.. include:: ../reusables/swift-further-reading.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 <using-the-codeql-model-editor>`."
|
||||
For more information, see `Using the CodeQL model editor <https://docs.github.com/en/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/using-the-codeql-model-editor>`__ in the GitHub documentation.
|
||||
|
||||
|
||||
About data extensions
|
||||
---------------------
|
||||
|
||||
@@ -254,8 +254,8 @@ Troubleshooting
|
||||
Further reading
|
||||
---------------
|
||||
|
||||
- ":ref:`Exploring data flow with path queries <exploring-data-flow-with-path-queries>`"
|
||||
- `Exploring data flow with path queries <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries>`__ in the GitHub documentation.
|
||||
|
||||
|
||||
.. include:: ../reusables/javascript-further-reading.rst
|
||||
.. include:: ../reusables/codeql-ref-tools-further-reading.rst
|
||||
.. include:: ../reusables/codeql-ref-tools-further-reading.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>`"
|
||||
- `Exploring data flow with path queries <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries>`__ in the GitHub documentation.
|
||||
|
||||
|
||||
.. include:: ../reusables/javascript-further-reading.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 <viewing-query-results>`" in the CodeQL for VS Code help.
|
||||
For more information, see `Running CodeQL queries <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries#understanding-your-query-results>`__ in the GitHub documentation.
|
||||
|
||||
.. _extractor:
|
||||
|
||||
|
||||
@@ -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 @@ import sphinx as sphinx_mod
|
||||
|
||||
|
||||
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 @@ html_theme = 'alabaster'
|
||||
|
||||
# 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 @@ html_extra_path = ['index.html']
|
||||
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']
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -3,6 +3,5 @@
|
||||
Note
|
||||
|
||||
You can use the CodeQL template (beta) in `GitHub Codespaces <https://github.com/codespaces/new?template_repository=github/codespaces-codeql>`__ 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 <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 <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/installing-codeql-for-vs-code>`__ in the GitHub documentation.
|
||||
|
||||
@@ -1 +1 @@
|
||||
For information about installing the CodeQL extension for Visual Studio code, see ":ref:`Setting up CodeQL in Visual Studio Code <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 <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/installing-codeql-for-vs-code>`__ in the GitHub documentation.
|
||||
|
||||
@@ -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 <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 <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 <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 <https://github.com/github/codeql/blob/main/docs/query-metadata-style-guide.md>`__.
|
||||
- If you are contributing a query to the GitHub repository, please read the `query metadata style guide <https://github.com/github/codeql/blob/main/docs/query-metadata-style-guide.md>`__.
|
||||
- If you are analyzing a database using the `CodeQL CLI <https://docs.github.com/en/code-security/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 <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 <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/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 <library-modules>` or :ref:`modules <modules>` to import into the query. Libraries and modules provide a way of grouping together related :ref:`types <types>`, :ref:`predicates <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 <https://github.com/github/codeql>`__ contains the standard CodeQL libraries for each supported language.
|
||||
Each query generally contains one or more ``import`` statements, which define the :ref:`libraries <library-modules>` or :ref:`modules <modules>` to import into the query. Libraries and modules provide a way of grouping together related :ref:`types <types>`, :ref:`predicates <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 <https://github.com/github/codeql>`__ 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 <defining-a-predicate>` and :ref:`Defining a class <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 <defining-a-predicate>` and :ref:`Defining a class <defining-a-class>`.
|
||||
|
||||
From clause
|
||||
===========
|
||||
|
||||
The ``from`` clause declares the variables that are used in the query. Each declaration must be of the form ``<type> <variable name>``.
|
||||
The ``from`` clause declares the variables that are used in the query. Each declaration must be of the form ``<type> <variable name>``.
|
||||
For more information on the available :ref:`types <types>`, and to learn how to define your own types using :ref:`classes <classes>`, see the :ref:`QL language reference <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 <aggregations>`, :ref:`predicates <predicates>`, and logical :ref:`formulas <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 <aggregations>`, :ref:`predicates <predicates>`, and logical :ref:`formulas <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 <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 <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 <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 <https://github.com/github/codeql/blob/main/docs/query-help-style-guide.md>`__ on GitHub, and the ":doc:`Query help files <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 <https://github.com/github/codeql/blob/main/docs/query-help-style-guide.md>`__ on GitHub, and the ":doc:`Query help files <query-help-files>`."
|
||||
|
||||
@@ -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>`"
|
||||
- `Exploring data flow with path queries <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries>`__ in the GitHub documentation.
|
||||
|
||||
@@ -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>`"
|
||||
|
||||
- `Exploring data flow with path queries <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries>`__ in the GitHub documentation.
|
||||
- `CodeQL repository <https://github.com/github/codeql>`__
|
||||
|
||||
@@ -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 <running-a-specific-part-of-a-query-or-library>` 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 <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries#running-a-specific-part-of-a-query-or-library>`__ 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
|
||||
|
||||
@@ -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 <https://securitylab.github.com/>`__ 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 <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 <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/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 <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/installing-codeql-for-vs-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 <language>`` 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
|
||||
|
||||
Reference in New Issue
Block a user