mirror of
https://github.com/github/codeql.git
synced 2026-04-25 16:55:19 +02:00
Apply suggestions from code review
Co-authored-by: Ben Ahmady <32935794+subatoi@users.noreply.github.com>
This commit is contained in:
@@ -25,7 +25,7 @@ The model editor has two different modes:
|
||||
Displaying the CodeQL model editor
|
||||
----------------------------------
|
||||
|
||||
#. Open your CodeQL workspace in VS Code, for example, the vscode-codeql-starter workspace.
|
||||
#. Open your CodeQL workspace in VS Code, for example, the ``vscode-codeql-starter`` workspace.
|
||||
If you haven't updated the ``ql`` submodule for a while, update it from ``main`` to ensure that you have the queries used to gather data for the model editor.
|
||||
#. Open the CodeQL extension and select the CodeQL database that you want to model from the "Databases" section of the left side pane.
|
||||
#. Use the command palette to run the “CodeQL: Open Model Editor (Beta)” command.
|
||||
@@ -35,7 +35,7 @@ Displaying the CodeQL model editor
|
||||
Modeling the calls your codebase makes to external APIs
|
||||
-------------------------------------------------------
|
||||
|
||||
You typically use this approach when you are looking at a specific codebase where you want to improve the precision of CodeQL results. This is usually when the codebase uses frameworks or libraries that are not supported by CodeQL and if the source code of the framework or library is not included in the analysis..
|
||||
You typically use this approach when you are looking at a specific codebase where you want to improve the precision of CodeQL results. This is usually when the codebase uses frameworks or libraries that are not supported by CodeQL and if the source code of the framework or library is not included in the analysis.
|
||||
|
||||
#. Select the CodeQL database that you want to improve CodeQL coverage for.
|
||||
#. Display the CodeQL model editor. By default the editor runs in application mode, so the list of external APIs used by the selected codebase is shown.
|
||||
@@ -59,7 +59,7 @@ You typically use this approach when you are looking at a specific codebase wher
|
||||
- **Flow summary**: choose the **Input** and **Output** elements to model.
|
||||
|
||||
#. Define the **Kind** of dataflow for the model.
|
||||
#. When you have finished modeling, click **Save all** or **Save** (shown at the bottom right of each expanded list of calls). The percentage of calls modeled in the editor is updated.
|
||||
#. When you have finished modeling, click **Save all** or **Save** (shown at the bottom right of each expanded list of calls). The percentage of calls modeled in the editor is updated.
|
||||
|
||||
The models are stored in your workspace at ``.github/codeql/extensions/<codeql-model-pack>``, where ``<codeql-model-pack>`` is the name of the CodeQL database that you selected. That is, the name of the repository, hyphen, the language analyzed by CodeQL.
|
||||
|
||||
@@ -99,7 +99,7 @@ You typically use this method when you want to model a framework or library that
|
||||
- **Flow summary**: choose the **Input** and **Output** elements to model.
|
||||
|
||||
#. Define the **Kind** of dataflow for the model.
|
||||
#. When you have finished modeling, click **Save all** or **Save** (shown at the bottom right of each expanded list of calls). The percentage of calls modeled in the editor is updated.
|
||||
#. When you have finished modeling, click **Save all** or **Save** (shown at the bottom right of each expanded list of calls). The percentage of calls modeled in the editor is updated.
|
||||
|
||||
The models are stored in your workspace at ``.github/codeql/extensions/<codeql-model-pack>``, where ``<codeql-model-pack>`` is the name of the CodeQL database that you selected. That is, the name of the repository, hyphen, the language analyzed by CodeQL.
|
||||
|
||||
|
||||
@@ -28,7 +28,7 @@ You can write and run query packs that depend on the CodeQL standard libraries,
|
||||
Working with CodeQL query packs
|
||||
-------------------------------
|
||||
|
||||
One of the main benefits of working with a CodeQL query pack is that all dependecies are resolved, not just those defined within the query and standard libraries.
|
||||
One of the main benefits of working with a CodeQL query pack is that all dependencies are resolved, not just those defined within the query and standard libraries.
|
||||
|
||||
Creating and editing CodeQL query packs
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@@ -21,7 +21,7 @@ For more information, see ":ref:`Using the CodeQL model editor <using-the-codeql
|
||||
About data extensions
|
||||
---------------------
|
||||
|
||||
You can customize analysis by defining models (summaries, sinks, and sources) of your code's dependencies in data extension files. Each model defines the behavior of one or more elements of your library or framework, such as a methods and callables. When you run dataflow analysis, these models expand the potential sources and sinks tracked by data flow analysis and improve the precision of results.
|
||||
You can customize analysis by defining models (summaries, sinks, and sources) of your code's dependencies in data extension files. Each model defines the behavior of one or more elements of your library or framework, such as methods and callables. When you run dataflow analysis, these models expand the potential sources and sinks tracked by data flow analysis and improve the precision of results.
|
||||
|
||||
Most of the security queries search for paths from a source of untrusted input to a sink that represents a vulnerability. This is known as taint tracking. Each source is a starting point for dataflow analysis to track tainted data and each sink is an end point.
|
||||
|
||||
@@ -64,7 +64,7 @@ The CodeQL library for Java and Kotlin analysis exposes the following extensible
|
||||
- ``sourceModel(package, type, subtypes, name, signature, ext, output, kind, provenance)``. This is used to model sources of potentially tainted data.
|
||||
- ``sinkModel(package, type, subtypes, name, signature, ext, input, kind, provenance)``. This is used to model sinks where tainted data maybe used in a way that makes the code vulnerable.
|
||||
- ``summaryModel(package, type, subtypes, name, signature, ext, input, output, kind, provenance)``. This is used to model flow through elements.
|
||||
- ``neutralModel(package, type, name, signature, kind, provenance)``. This is similar to a summary model but used to model the flow of values that have only a minor impact on the data flow analysis.
|
||||
- ``neutralModel(package, type, name, signature, kind, provenance)``. This is similar to a summary model but used to model the flow of values that have only a minor impact on the dataflow analysis.
|
||||
|
||||
The extensible predicates are populated using data extensions specified in YAML files. For more information about extensible predicates, see ":doc:`extensible-predicates`."
|
||||
|
||||
@@ -258,7 +258,7 @@ For the remaining values for both rows:
|
||||
- The ninth value ``value`` is the kind of the flow. ``value`` means that the value is preserved.
|
||||
- The tenth value ``manual`` is the provenance of the summary, which is used to identify the origin of the summary.
|
||||
|
||||
That is, the first row specifies that values can flow from the elements of the qualifier stream into the first argument of the function provided to ``map``. The second row sepcifies that values can flow from the return value of the function to the elements of the stream returned from ``map``.
|
||||
That is, the first row specifies that values can flow from the elements of the qualifier stream into the first argument of the function provided to ``map``. The second row specifies that values can flow from the return value of the function to the elements of the stream returned from ``map``.
|
||||
|
||||
Example: Add a ``neutral`` method
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@@ -124,7 +124,7 @@ neutralModel(package, type, name, signature, kind, provenance)
|
||||
|
||||
This extensible predicate is not typically needed externally, but is included here for completeness.
|
||||
It has limited impact on dataflow analysis.
|
||||
Manual neutrals are considered high-confidence dispatch call targets and can reduce the number of dispatch call targets during data flow analysis (a performance optimization).
|
||||
Manual neutrals are considered high-confidence dispatch call targets and can reduce the number of dispatch call targets during dataflow analysis (a performance optimization).
|
||||
|
||||
- ``kind``: Kind of the neutral. For neutrals the kind can be ``summary``, ``source``, or ``sink`` to indicate that the callable is neutral with respect to flow (no summary), source (is not a source) or sink (is not a sink).
|
||||
|
||||
@@ -162,14 +162,14 @@ The following values are supported.
|
||||
|
||||
- ``manual``: The model was manually created and added to the extensible predicate.
|
||||
|
||||
Values can also take the form`ORIGIN-VERIFICATION`, where `ORIGIN` is one of:
|
||||
Values can also take the form ``ORIGIN-VERIFICATION``, where ``ORIGIN`` is one of:
|
||||
|
||||
- ``ai``: The model was generated by artificial intelligence (AI).
|
||||
- ``df``: The model was generated by the dataflow model generator.
|
||||
- ``tb``: The model was generated by the type based model generator.
|
||||
- ``hq``: The model was generated using a heuristic query.
|
||||
|
||||
And `VERIFICATION` is one of:
|
||||
And ``VERIFICATION`` is one of:
|
||||
|
||||
- ``manual``: The model was verified by a human.
|
||||
- ``generated``: The model was generated, but not verified by a human.
|
||||
|
||||
Reference in New Issue
Block a user