hohn/codeql
1
0
Fork 0
mirror of https://github.com/github/codeql.git synced 2025-12-21 03:06:31 +01:00
Code Issues Packages Projects Releases Wiki Activity

Apply suggestions from code review

Browse Source
This commit is contained in:
Andrew Eisenberg
2022-08-23 17:07:56 -07:00
parent a40b7ef81c
commit 5fe06abc24
4 changed files with 54 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/codeql/codeql-cli/about-codeql-packs.rst
View File

@@ -258,10 +258,10 @@ databases. You may also wish to specify the ``tests`` property.
For more information about running tests, see ":doc:`Testing custom queries For more information about running tests, see ":doc:`Testing custom queries
<testing-custom-queries>`." <testing-custom-queries>`."
.. _standard-ql-packs: .. _standard-codeql-packs:
Examples of CodeQL packs in the CodeQL repository Examples of CodeQL packs in the CodeQL repository
---------------------------------------------~~~~ -------------------------------------------------
Each of the languages in the CodeQL repository has four main CodeQL packs: Each of the languages in the CodeQL repository has four main CodeQL packs:
@@ -292,6 +292,7 @@ Some extra notes on the following properties:
- ``library``: Indicates that this is a library pack with no executable queries. It is only meant to be used as a dependency for other packs. - ``library``: Indicates that this is a library pack with no executable queries. It is only meant to be used as a dependency for other packs.
- ``dbscheme`` and ``upgrades``: These properties are internal to the CodeQL CLI and should only be defined in the core QL pack for a language. - ``dbscheme`` and ``upgrades``: These properties are internal to the CodeQL CLI and should only be defined in the core QL pack for a language.
.. _standard-codeql-query-packs:
Core query pack Core query pack
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~

78
docs/codeql/codeql-cli/analyzing-databases-with-the-codeql-cli.rst
View File

@@ -123,6 +123,14 @@ You can also run your own custom queries with the ``database analyze`` command.
For more information about preparing your queries to use with the CodeQL CLI, For more information about preparing your queries to use with the CodeQL CLI,
see ":doc:`Using custom queries with the CodeQL CLI <using-custom-queries-with-the-codeql-cli>`." see ":doc:`Using custom queries with the CodeQL CLI <using-custom-queries-with-the-codeql-cli>`."
If you do not have the CodeQL repository checked out, you can execute the same queries by specifying the query pack name and the path to the queries::
codeql database analyze --download <javascript-database> codeql/javascript-queries:Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv
Use the ``--download`` flag to download the query pack if it isn't yet available locally.
.. _run-query-pack:
Running a CodeQL pack Running a CodeQL pack
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
@@ -136,6 +144,40 @@ pack names and use the ``--download`` flag::
The ``analyze`` command above runs the default suite from ``microsoft/coding-standards v1.0.0`` and the latest version of ``github/security-queries`` on the specified database. The ``analyze`` command above runs the default suite from ``microsoft/coding-standards v1.0.0`` and the latest version of ``github/security-queries`` on the specified database.
For further information about default suites, see ":ref:`Publishing and using CodeQL packs <publishing-and-using-codeql-packs>`". For further information about default suites, see ":ref:`Publishing and using CodeQL packs <publishing-and-using-codeql-packs>`".
Running all queries in a directory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can run all the queries located in a directory by providing the directory
path, rather than listing all the individual query files. Paths are searched
recursively, so any queries contained in subfolders will also be executed.
.. pull-quote::
Important
You should avoid specifying the root of a :ref:`core CodeQL query pack
<standard-codeql-query-packs>` when executing ``database analyze``
as it might contain some special queries that aren't designed to be used with
the command. Rather, :ref:`run the query pack <run-query-pack>` to include the
pack's default queries in the analysis, or run one of the
code scanning query suites.
For example, to execute all Python queries contained in the ``Functions`` directory you would run::
codeql database analyze <python-database> ../ql/python/ql/src/Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif
If you do not have the CodeQL repository checked out, you can execute the same queries by specifying the query pack name and the path to the queries::
codeql database analyze --download <python-database> codeql/python-queries:Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif
Use the ``--download`` flag to download the query pack if it isn't yet available locally.
When the analysis has finished, a SARIF results file is generated. Specifying ``--format=sarif-latest`` ensures
that the results are formatted according to the most recent SARIF specification
supported by CodeQL.
.. _including-query-help-for-custom-codeql-queries-in-sarif-files:
Running a subset of queries in a CodeQL pack Running a subset of queries in a CodeQL pack
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -196,7 +238,7 @@ CodeQL query suites are ``.qls`` files that use directives to select queries to
based on certain metadata properties. The standard CodeQL packs have metadata that specify based on certain metadata properties. The standard CodeQL packs have metadata that specify
the location of the query suites used by code scanning, so the CodeQL CLI knows where to find these the location of the query suites used by code scanning, so the CodeQL CLI knows where to find these
suite files automatically, and you don't have to specify the full path on the command line. suite files automatically, and you don't have to specify the full path on the command line.
For more information, see ":ref:`About CodeQL packs <standard-ql-packs>`." For more information, see ":ref:`About CodeQL packs <standard-codeql-packs>`."
The standard query suites are stored at the following paths in The standard query suites are stored at the following paths in
the CodeQL repository:: the CodeQL repository::
@@ -228,40 +270,6 @@ Integrating a CodeQL pack into a code scanning workflow in GitHub
You can use CodeQL query packs in your code scanning setup. This allows you to select query packs published by various sources and use them to analyze your code. You can use CodeQL query packs in your code scanning setup. This allows you to select query packs published by various sources and use them to analyze your code.
For more information, see "`Using CodeQL query packs in the CodeQL action <https://docs.github.com/en/code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-codeql-query-packs/>`_" or "`Downloading and using CodeQL query packs in your CI system <https://docs.github.com/en/code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system#downloading-and-using-codeql-query-packs>`_." For more information, see "`Using CodeQL query packs in the CodeQL action <https://docs.github.com/en/code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-codeql-query-packs/>`_" or "`Downloading and using CodeQL query packs in your CI system <https://docs.github.com/en/code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system#downloading-and-using-codeql-query-packs>`_."
Running all queries in a directory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can run all the queries located in a directory by providing the directory
path, rather than listing all the individual query files. Paths are searched
recursively, so any queries contained in subfolders will also be executed.
.. pull-quote::
Important
You shouldn't specify the root of a :doc:`CodeQL pack
<about-codeql-packs>` when executing ``database analyze``
as it contains some special queries that aren't designed to be used with
the command. Rather, to run a wide range of useful queries, run one of the
LGTM.com query suites.
For example, to execute all Python queries contained in the ``Functions`` directory you would run::
codeql database analyze <python-database> ../ql/python/ql/src/Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif
If you do not have the CodeQL repository checked out, you can execute the same queries by specifying the query pack name and the path to the queries:
codeql database analyze --download <python-database> codeql/python-queries:Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif
Use the ``--download`` flag to download the query pack if it isn't yet available locally.
After evaluating, a SARIF results file is generated. Specifying ``--format=sarif-latest`` ensures
that the results are formatted according to the most recent SARIF specification
supported by CodeQL.
.. _including-query-help-for-custom-codeql-queries-in-sarif-files:
Including query help for custom CodeQL queries in SARIF files Including query help for custom CodeQL queries in SARIF files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

8
docs/codeql/codeql-cli/creating-and-working-with-codeql-packs.rst
View File

@@ -34,14 +34,14 @@ You must specify:
The ``codeql pack init`` command creates the directory structure and configuration files for a CodeQL pack. By default, the command creates a query pack. If you want to create a library pack, you must edit the ``qlpack.yml`` file to explicitly declare the file as a library pack by including the ``library:true`` property. The ``codeql pack init`` command creates the directory structure and configuration files for a CodeQL pack. By default, the command creates a query pack. If you want to create a library pack, you must edit the ``qlpack.yml`` file to explicitly declare the file as a library pack by including the ``library:true`` property.
Modifying an existing legacy CodeQL pack to create a CodeQL pack Modifying an existing legacy QL pack to create a CodeQL pack
---------------------------------------------------------------- ------------------------------------------------------------
If you already have a ``qlpack.yml`` file, you can edit it manually to convert it into a CodeQL pack. If you already have a ``qlpack.yml`` file, you can edit it manually to convert it into a CodeQL pack.
#. Edit the ``name`` property so that it matches the format ``<scope>/<name>``, where ``<scope>`` is the name of the GitHub organization or user account that you will publish to. #. Edit the ``name`` property so that it matches the format ``<scope>/<name>``, where ``<scope>`` is the name of the GitHub organization or user account that you will publish to.
#. In the ``qlpack.yml`` file, include a ``version`` property with a semver identifier, as well as an optional ``dependencies`` block. #. In the ``qlpack.yml`` file, include a ``version`` property with a semver identifier, as well as an optional ``dependencies`` block.
#. Migrate the list of dependencies in ``libraryPathDependencies`` to the ``dependencies`` block. Specify the version range for each dependency. If the range is unimportant, or you are unsure of compatibility, you can specify ``"*"``, which indicates that any version is acceptable and will default to the latest version when ``codeql pack install`` is run. #. Migrate the list of dependencies in ``libraryPathDependencies`` to the ``dependencies`` block. Specify the version range for each dependency. If the range is unimportant, or you are unsure of compatibility, you can specify ``"*"``, which indicates that any version is acceptable and will default to the latest version when you run ``codeql pack install``.
For more information about the properties, see ":ref:`About CodeQL packs <about-codeql-packs>`." For more information about the properties, see ":ref:`About CodeQL packs <about-codeql-packs>`."
@@ -53,7 +53,7 @@ You can add dependencies on CodeQL packs using the command ``codeql pack add``.
codeql pack add <scope>/<name>@x.x.x <scope>/<other-name> codeql pack add <scope>/<name>@x.x.x <scope>/<other-name>
If you leave off the version range, the latest version will be added. Otherwise, the latest version that satisfies the requested range will be added. If you don't specify a version range, the latest version will be added. Otherwise, the latest version that satisfies the requested range will be added.
This command updates the ``qlpack.yml`` file with the requested dependencies and downloads them into the package cache. Please note that this command will reformat the file and remove all comments. This command updates the ``qlpack.yml`` file with the requested dependencies and downloads them into the package cache. Please note that this command will reformat the file and remove all comments.

8
docs/codeql/codeql-cli/creating-codeql-query-suites.rst
View File

@@ -18,7 +18,7 @@ suite definition have been executed, the result is a set of selected queries.
.. pull-quote:: Note .. pull-quote:: Note
Any custom queries that you want to add to a query suite must be in a :doc:`QL Any custom queries that you want to add to a query suite must be in a :doc:`CodeQL
pack <about-codeql-packs>` and contain the correct query metadata. pack <about-codeql-packs>` and contain the correct query metadata.
For more information, see For more information, see
":doc:`Using custom queries with the CodeQL CLI <using-custom-queries-with-the-codeql-cli>`." ":doc:`Using custom queries with the CodeQL CLI <using-custom-queries-with-the-codeql-cli>`."
@@ -52,7 +52,7 @@ queries using:
version: ^x.y.z version: ^x.y.z
The ``version`` field is optional and specifies a range of compatible versions of this CodeQL pack. The ``version`` field is optional and specifies a range of compatible versions of this CodeQL pack.
If the version is excluded, then the most recent version of the pack is used. If you don't specify a version, then the most recent version of the pack is used.
- A ``qlpack`` instruction---tells CodeQL to resolve queries in the default suite of the - A ``qlpack`` instruction---tells CodeQL to resolve queries in the default suite of the
named CodeQL pack:: named CodeQL pack::
@@ -65,7 +65,7 @@ queries using:
define a default suite, the `qlpack` instruction will resolve to all of the queries within the pack. define a default suite, the `qlpack` instruction will resolve to all of the queries within the pack.
The ``version`` field is optional and specifies a range of compatible versions of this CodeQL pack. The ``version`` field is optional and specifies a range of compatible versions of this CodeQL pack.
If the version is excluded, then the most recent version of the pack is used. If you don't specify a version, then the most recent version of the pack is used.
.. pull-quote:: Note .. pull-quote:: Note
@@ -191,7 +191,7 @@ Existing query suite definitions can be reused by specifying:
version: ^x.y.z version: ^x.y.z
The ``version`` field is optional and specifies a range of compatible versions of this CodeQL pack. The ``version`` field is optional and specifies a range of compatible versions of this CodeQL pack.
If the version is excluded, then the most recent version of the pack is used. If you don't specify a version, then the most recent version of the pack is used.
Queries added using an ``import`` instruction can be filtered using subsequent Queries added using an ``import`` instruction can be filtered using subsequent
``exclude`` instructions. ``exclude`` instructions.