mirror of
https://github.com/github/codeql.git
synced 2026-04-30 19:26:02 +02:00
Apply suggestions from @hubwriter's code review
Co-authored-by: Alistair Christie <54933897+hubwriter@users.noreply.github.com>
This commit is contained in:
James Fletcher
@@ -10,7 +10,7 @@ This topic offers some simple tips on how to avoid common problems that can affe
|
||||
Before reading the tips below, it is worth reiterating a few important points about CodeQL and the QL language:
|
||||
|
||||
- CodeQL `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ and `classes <https://help.semmle.com/QL/ql-handbook/types.html#classes>`__ are evaluated to database `tables <https://en.wikipedia.org/wiki/Table_(database)>`__. Large predicates generate large tables with many rows, and are therefore expensive to compute.
|
||||
- The QL language is implemented using standard database operations and `relational algebra <https://en.wikipedia.org/wiki/Relational_algebra>`__ (such as join, projection, and union). For further information about query languages and databases, see `About the QL language <https://help.semmle.com/QL/learn-ql/about-ql.html>`__.
|
||||
- The QL language is implemented using standard database operations and `relational algebra <https://en.wikipedia.org/wiki/Relational_algebra>`__ (such as join, projection, and union). For more information about query languages and databases, see `About the QL language <https://help.semmle.com/QL/learn-ql/about-ql.html>`__.
|
||||
- Queries are evaluated *bottom-up*, which means that a predicate is not evaluated until *all* of the predicates that it depends on are evaluated. For more information on query evaluation, see "`Evaluation of QL programs <https://help.semmle.com/QL/ql-handbook/evaluation.html>`__."
|
||||
|
||||
Performance tips
|
||||
|
||||
@@ -106,7 +106,7 @@ Select clauses for alert queries (``@kind problem``) consist of two 'columns', w
|
||||
- ``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.
|
||||
|
||||
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 further information, see ":doc:`Defining the results of a query <select-statement>`."
|
||||
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-statement>`."
|
||||
|
||||
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 <path-queries>`."
|
||||
|
||||
|
||||
@@ -149,11 +149,11 @@ The configuration class is accessed by importing the data flow library. This cla
|
||||
- ``isSource()`` defines where data may flow from.
|
||||
- ``isSink()`` defines where data may flow to.
|
||||
|
||||
For further information on using the configuration class in your analysis see the sections on global data flow in ":doc:`Analyzing data flow in C/C++ <../cpp/dataflow>`"
|
||||
For more information on using the configuration class in your analysis see the sections on global data flow in ":doc:`Analyzing data flow in C/C++ <../cpp/dataflow>`"
|
||||
and ":doc:`Analyzing data flow in C# <../csharp/dataflow>`."
|
||||
|
||||
You can also create a configuration for different frameworks and environments by extending the ``Configuration`` class.
|
||||
For further information, see `defining a class <https://help.semmle.com/QL/ql-handbook/types.html#defining-a-class>`__.
|
||||
For more information, see `defining a class <https://help.semmle.com/QL/ql-handbook/types.html#defining-a-class>`__.
|
||||
|
||||
If you are querying Python code (and you have used ``import semmle.python.security.Paths`` in your query) you should declare ``TaintedPathSource source, TaintedPathSink sink`` in your ``from`` statement. You do not need to declare a ``Configuration`` class as the definitions of the ``TaintedPathSource`` and ``TaintedPathSink`` contain all of the type information that is required::
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ About query metadata
|
||||
|
||||
Any query that is run as part of an analysis includes a number of properties, known as query metadata. Metadata is included at the top of each query file as the content of a `QLDoc <https://help.semmle.com/QL/ql-spec/qldoc.html>`__ comment.
|
||||
This metadata tells LGTM and the CodeQL `extension for VS Code <https://help.semmle.com/codeql/codeql-for-vscode.html>`__ how to handle the query and display its results correctly.
|
||||
It also gives other users information about what the query results mean. For further information on query metadata, see the `query metadata style guide <https://github.com/github/codeql/blob/master/docs/query-metadata-style-guide.md>`__ in our `open source repository <https://github.com/github/codeql>`__ on GitHub.
|
||||
It also gives other users information about what the query results mean. For more information on query metadata, see the `query metadata style guide <https://github.com/github/codeql/blob/master/docs/query-metadata-style-guide.md>`__ in our `open source repository <https://github.com/github/codeql>`__ on GitHub.
|
||||
|
||||
.. pull-quote::
|
||||
|
||||
@@ -28,7 +28,7 @@ The following properties are supported by all query files:
|
||||
+-----------------------+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| ``@id`` | ``<text>`` | A sequence of words composed of lowercase letters or digits, delimited by ``/`` or ``-``, identifying and classifying the query. Each query must have a **unique** ID. To ensure this, it may be helpful to use a fixed structure for each ID. For example, the standard LGTM queries have the following format: ``<language>/<brief-description>``. |
|
||||
+-----------------------+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| ``@kind`` | | ``problem`` | Identifies the query is an alert (``@kind problem``) or a path (``@kind path-problem``). For further information on these query types, see ":doc:`About CodeQL queries <introduction-to-queries>`." |
|
||||
| ``@kind`` | | ``problem`` | Identifies the query is an alert (``@kind problem``) or a path (``@kind path-problem``). For more information on these query types, see ":doc:`About CodeQL queries <introduction-to-queries>`." |
|
||||
| | | ``path-problem`` | |
|
||||
+-----------------------+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| ``@name`` | ``<text>`` | A statement that defines the label of the query. The name is written in plain text, and uses single quotes (``'``) to enclose code elements. |
|
||||
|
||||
@@ -15,7 +15,7 @@ This topic explains how to write your select statement to generate helpful analy
|
||||
Overview
|
||||
--------
|
||||
|
||||
Alert queries must have the property ``@kind problem`` defined in their metadata. For further information, see ":doc:`Metadata for CodeQL queries <query-metadata>`."
|
||||
Alert queries must have the property ``@kind problem`` defined in their metadata. For more information, see ":doc:`Metadata for CodeQL queries <query-metadata>`."
|
||||
In their most basic form, the ``select`` statement must select two 'columns':
|
||||
|
||||
- **Element**—a code element that's identified by the query. This defines the location of the alert.
|
||||
@@ -109,4 +109,4 @@ The new elements added here don't need to be clickable, so we added them directl
|
||||
Further reading
|
||||
---------------
|
||||
|
||||
- `CodeQL repository <https://github.com/github/codeql>`__
|
||||
- `CodeQL repository <https://github.com/github/codeql>`__
|
||||
|
||||
Reference in New Issue
Block a user