mirror of
https://github.com/github/codeql.git
synced 2026-02-01 07:42:57 +01:00
Apply suggestions from code review
Co-authored-by: Felicity Chapman <felicitymay@github.com> Co-authored-by: James Fletcher <42464962+jf205@users.noreply.github.com>
This commit is contained in:
Andrew Eisenberg
@@ -16,7 +16,7 @@ You can use the package management commands in the CodeQL CLI to create CodeQL p
|
||||
|
||||
|
||||
The standard CodeQL packages for all supported languages are published in the `GitHub Container registry <https://github.com/orgs/codeql/packages>`__.
|
||||
The `CodeQL repository <https://github.com/github/codeql>`__ contains sources for the standard CodeQL packs for all supported languages.
|
||||
The `CodeQL repository <https://github.com/github/codeql>`__ contains source files for the standard CodeQL packs for all supported languages.
|
||||
|
||||
.. _codeql-pack-structure:
|
||||
|
||||
@@ -38,13 +38,13 @@ When executing query-related commands, CodeQL first looks in siblings of the ins
|
||||
Then it checks the package cache for CodeQL packs which have been downloaded. This means that when you are developing queries locally, the local packages
|
||||
in the installation directory override packages of the same name in the package cache, so that you can test your local changes.
|
||||
|
||||
The metadata in each `qlpack.yml`` file tells
|
||||
The metadata in each ``qlpack.yml`` file tells
|
||||
CodeQL how to compile any queries in the pack, what libraries the pack depends on, and where to
|
||||
find query suite definitions.
|
||||
|
||||
The contents of the CodeQL pack (queries or libraries used in CodeQL analysis) is included in the same directory as ``qlpack.yml``, or its subdirectories.
|
||||
|
||||
The directory containing the ``qlpack.yml`` file serves as the root directory for the content of the CodeQL pack. That is, for all ``.ql`` and ``.qll`` files in the pack, CodeQL will resolve all import statements relative to the directory containing ``qlpack.yml`` at the pack's root.
|
||||
The directory containing the ``qlpack.yml`` file serves as the root directory for the content of the CodeQL pack. That is, for all ``.ql`` and ``.qll`` files in the pack, CodeQL will resolve all import statements relative to the directory containing the ``qlpack.yml`` file at the pack's root.
|
||||
|
||||
.. _codeqlpack-yml-properties:
|
||||
|
||||
@@ -141,7 +141,7 @@ The following properties are supported in ``qlpack.yml`` files.
|
||||
upgrades: .
|
||||
|
||||
- Core language packs only
|
||||
- The path to a directory within the pack that contains database upgrade scripts, defined relative to the pack directory. Database upgrades are used internally to ensure a database created with a different version of the CodeQL CLI is compatible with the current version.
|
||||
- The path to a directory within the pack that contains database upgrade scripts, defined relative to the pack directory. Database upgrades are used internally to ensure that a database created with a different version of the CodeQL CLI is compatible with the current version of the CLI.
|
||||
* - ``authors``
|
||||
- .. code-block:: yaml
|
||||
|
||||
@@ -212,7 +212,7 @@ In most cases, the ``codeql-pack.lock.yml`` file is only relevant for query pack
|
||||
Examples of custom CodeQL packs
|
||||
-------------------------------
|
||||
|
||||
When you write custom queries or tests, you should save them in custom CodeQL packs. For simplicity, try to organize each pack logically. For more information, see ""`CodeQL pack structure <#codeql-pack-structure>`__." Save files for queries and tests in separate packs and, where possible, organize custom packs into specific folders for each target language. This is particuarly useful if you intend to publish your CodeQL packs so they can be shared with others or used in GitHub `Code scanning <https://docs.github.com/en/code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning>`__.
|
||||
When you write custom queries or tests, you should save them in custom CodeQL packs. For simplicity, try to organize each pack logically. For more information, see "`CodeQL pack structure <#codeql-pack-structure>`__." Save files for queries and tests in separate packs and, where possible, organize custom packs into specific folders for each target language. This is particuarly useful if you intend to publish your CodeQL packs so they can be shared with others or used in GitHub `Code scanning <https://docs.github.com/en/code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning>`__.
|
||||
|
||||
CodeQL packs for custom libraries
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@@ -58,8 +58,8 @@ You can also specify:
|
||||
- a path to a directory containing query files
|
||||
- a path to a query suite file
|
||||
- the name of a CodeQL query pack
|
||||
- with an optional version range
|
||||
- with an optional path to a query, directory, or query suite inside the pack
|
||||
- with an optional version range
|
||||
- with an optional path to a query, directory, or query suite inside the pack
|
||||
|
||||
If omitted, the default query suite for the language of the database being analyzed will be used. For more information, see the :ref:`examples <database-analyze-examples>` below.
|
||||
|
||||
@@ -166,12 +166,6 @@ For example, to execute all Python queries contained in the ``Functions`` direct
|
||||
|
||||
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.
|
||||
|
||||
@@ -39,7 +39,7 @@ Example
|
||||
A query reference file to test a JavaScript alert query:
|
||||
`DeadAngularJSEventListener.qlref <https://github.com/github/codeql/blob/main/javascript/ql/test/query-tests/AngularJS/DeadAngularJSEventListener/DeadAngularJSEventListener.qlref>`__
|
||||
|
||||
The `CodeQL pack <https://github.com/github/codeql/blob/main/javascript/ql/test/qlpack.yml>`__
|
||||
The ```qlpack.yml`` file <https://github.com/github/codeql/blob/main/javascript/ql/test/qlpack.yml>`__
|
||||
for the CodeQL pack at ``javascript/ql/test`` defines ``codeql/javascript-queries`` as
|
||||
a dependency. So the query reference file defines the location of the query relative
|
||||
to the ``codeql/javascript-queries`` CodeQL pack::
|
||||
|
||||
@@ -64,7 +64,7 @@ library files, query suites, and important metadata. Their root directory must
|
||||
contain a file named ``qlpack.yml``. Your custom queries should be saved in the
|
||||
CodeQL pack root, or its subdirectories.
|
||||
|
||||
For each CodeQL pack, the ``qlpack.yml`` file includes information that tells CodeQL
|
||||
For each CodeQL pack, the ``qlpack.yml`` file includes information that tells the CodeQL CLI
|
||||
how to compile the queries, which other CodeQL packs and libraries the pack
|
||||
depends on, and where to find query suite definitions. For more information
|
||||
about what to include in this file, see ":ref:`About CodeQL packs <codeqlpack-yml-properties>`."
|
||||
|
||||
Reference in New Issue
Block a user