hohn/codeql
1
0
Fork 0
mirror of https://github.com/github/codeql.git synced 2026-01-07 03:30:24 +01:00
Code Issues Packages Projects Releases Wiki Activity

lots of changes

Browse Source
This commit is contained in:
james
2020-11-11 13:50:29 +00:00
parent 3d9efa1dc2
commit 12c6009895
365 changed files with 60 additions and 731 deletions
Download Patch File Download Diff File Expand all files Collapse all files

231
docs/codeql/codeql-cli/codeql-cli-reference/about-ql-packs.rst Normal file
View File

@@ -0,0 +1,231 @@
.. _about-ql-packs:
About QL packs
==============
QL packs are used to organize the files used in CodeQL analysis. They
contain queries, library files, query suites, and important metadata.
The `CodeQL repository <https://github.com/github/codeql>`__ contains QL packs for
C/C++, C#, Java, JavaScript, and Python. The `CodeQL for Go
<https://github.com/github/codeql-go/>`__ repository contains a QL pack for Go
analysis. You can also make custom QL packs to contain your own queries and
libraries.
QL pack structure
-----------------
A QL pack must contain a file called ``qlpack.yml`` in its root directory. The other
files and directories within the pack should be logically organized. For example, typically:
- Queries are organized into directories for specific categories.
- Queries for specific products, libraries, and frameworks are organized into
their own top-level directories.
- There is a top-level directory named ``<owner>/<ql-language-specification>`` for query library
(``.qll``) files. Within this directory, ``.qll`` files should be organized into
subdirectories for specific categories.
About ``qlpack.yml`` files
--------------------------
When executing commands, CodeQL scans siblings of the installation directory (and
their subdirectories) for ``qlpack.yml`` files. The metadata in the file tells
CodeQL how to compile queries, what libraries the pack depends on, and where to
find query suite definitions.
The content of the QL pack (queries and libraries used in CodeQL analysis) is
included in the same directory as ``qlpack.yml``, or its subdirectories.
The location of ``qlpack.yml`` defines the library path for the content
of the QL pack. That is, for all ``.ql`` and ``.qll`` files in the QL pack,
CodeQL will resolve all import statements relative to the ``qlpack.yml`` at the
pack's root.
For example, in a QL pack with the following contents, you can import ``CustomSinks.qll``
from any location in the pack by declaring ``import mycompany.java.CustomSinks``.
.. code-block:: none
qlpack.yml
mycompany/
java/
security/
CustomSinks.qll
Security/
CustomQuery.ql
For more information, see ":ref:`Importing modules <importing-modules>`"
in the QL language reference.
``qlpack.yml`` properties
~~~~~~~~~~~~~~~~~~~~~~~~~
The following properties are supported in ``qlpack.yml`` files.
.. list-table::
:header-rows: 1
:widths: auto
* - Property
- Example
- Required
- Purpose
* - ``name``
- ``org-queries``
- All packs
- The name of the QL pack defined using alphanumeric characters, hyphens, and periods. It must be unique as CodeQL cannot differentiate between QL packs with identical names. If you intend to distribute the pack, prefix the name with your (or your organization's) name followed by a hyphen. Use the pack name to specify queries to run using ``database analyze`` and to define dependencies between QL packs (see examples below).- '
* - ``version``
- ``0.0.0``
- All packs
- A version number for this QL pack. This field is not currently used by any commands, but may be required by future releases of CodeQL.
* - ``libraryPathDependencies``
- ``codeql-javascript``
- Optional
- The names of any QL packs that this QL pack depends on, as a sequence. This gives the pack access to any libraries, database schema, and query suites defined in the dependency.
* - ``suites``
- ``suites``
- Optional
- The path to a directory that contains the "well-known" query suites in the pack, defined relative to the pack directory. You can run "well-known" suites stored in this directory by specifying the pack name, without providing their full path. To use query suites stored in other directories in the pack, you must provide their full path. For more information about query suites, see ":doc:`Creating CodeQL query suites <../using-the-codeql-cli/creating-codeql-query-suites>`."
* - ``extractor``
- ``javascript``
- All test packs
- The CodeQL language extractor to use when the CLI creates a database from test files in the pack. For more information about testing queries, see ":doc:`Testing custom queries <../using-the-codeql-cli/testing-custom-queries>`."
* - ``tests``
- ``.``
- Optional for test packs
- Supported from release 2.1.0 onwards. The path to a directory within the pack that contains tests, defined relative to the pack directory. Use ``.`` to specify the whole pack. Any queries in this directory are run as tests when ``test run`` is run with the ``--strict-test-discovery`` option. These queries are ignored by query suite definitions that use ``queries`` or ``qlpack`` instructions to ask for all queries in a particular pack.
* - ``dbscheme``
- ``semmlecode.python.dbscheme``
- Core language pack only
- The path to the :ref:`database schema <codeql-database-schema>` for all libraries and queries written for this CodeQL language (see example below).
* - ``upgrades``
- ``.``
- Packs with upgrades
- The path to a directory within the pack that contains upgrade scripts, defined relative to the pack directory. The ``database upgrade`` action uses these scripts to update databases that were created by an older version of an extractor so they're compatible with the current extractor (see `Upgrade scripts for a language <upgrade-scripts-for-a-language>`__ below.)
.. _custom-ql-packs:
Examples of custom QL packs
---------------------------
When you write custom queries or tests, you should save them in
custom QL packs. For simplicity, try to organize each pack logically. For more
information, see `QL pack structure <#ql-pack-structure>`__. Save files for queries
and tests in separate packs and, where possible, organize custom packs into specific
folders for each target language.
QL packs for custom queries
~~~~~~~~~~~~~~~~~~~~~~~~~~~
A custom QL pack for queries must include a ``qlpack.yml`` file at
the pack root, containing ``name``, ``version``,
and ``libraryPathDependencies`` properties. If the pack contains query suites, you can
use the ``suites`` property to define their location. Query suites defined
here are called "well-known" suites, and can be used on the command line by referring to
their name only, rather than their full path.
For more information about query suites, see ":doc:`Creating CodeQL query suites <../using-the-codeql-cli/creating-codeql-query-suites>`."
For example, a ``qlpack.yml`` file for a QL pack featuring custom C++ queries
and libraries may contain:
.. code-block:: yaml
name: my-custom-queries
version: 0.0.0
libraryPathDependencies: codeql-cpp
suites: my-custom-suites
where ``codeql-cpp`` is the name of the QL pack for C/C++ analysis included in
the CodeQL repository.
.. pull-quote::
Note
When you create a custom QL pack, it's usually a good idea to add it to the search path in your CodeQL configuration.
This will ensure that any libraries the pack contains are available to the CodeQL CLI.
For more information, see ":doc:`Specifying command options in a CodeQL configuration file <../codeql-cli-reference/specifying-command-options-in-a-codeql-configuration-file>`."
QL packs for custom test files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For custom QL packs containing test files, you also need to include an
``extractor`` property so that the ``test run`` command knows how to create test
databases. You may also wish to specify the ``tests`` property.
.. include:: ../../reusables/test-qlpack.rst
For more information about running tests, see ":doc:`Testing custom queries
<../using-the-codeql-cli/testing-custom-queries>`."
.. _standard-ql-packs:
Examples of QL packs in the CodeQL repository
---------------------------------------------
Each of the languages in the CodeQL repository has three main QL packs:
- Core QL pack for the language, with the :ref:`database schema <codeql-database-schema>`
used by the language, CodeQL libraries, and queries at ``ql/<language>/ql/src``
- Tests for the core language libraries and queries pack at ``ql/<language>/ql/test``
- Upgrade scripts for the language at ``ql/<language>/upgrades``
Core QL pack
~~~~~~~~~~~~
The ``qlpack.yml`` file for a core QL pack uses the following properties:
``name``, ``version``, ``dbscheme``, and ``suites``.
The ``dbscheme`` property should only be defined in the core QL
pack for a language.
For example, the ``qlpack.yml`` file for `C/C++ analysis
<https://github.com/github/codeql/blob/main/cpp/ql/src/qlpack.yml>`__
contains:
.. code-block:: yaml
name: codeql-cpp
version: 0.0.0
dbscheme: semmlecode.cpp.dbscheme
suites: codeql-suites
Tests for the core QL pack
~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``qlpack.yml`` file for the tests for the core QL packs use the following
properties: ``name``, ``version``, and ``libraryPathDependencies``.
The ``libraryPathDependencies`` always specifies the core QL pack.
For example, the ``qlpack.yml`` file for `C/C++ analysis tests
<https://github.com/github/codeql/blob/main/cpp/ql/test/qlpack.yml>`__
contains:
.. code-block:: yaml
name: codeql-cpp-tests
version: 0.0.0
libraryPathDependencies: codeql-cpp
Notice that, unlike the example QL pack for custom tests, this file does not define
an ``extractor`` or ``tests`` property. These properties have been added to
the QL pack file since the release of CodeQL CLI 2.0.1.
They haven't been added yet to ensure compatibility for LGTM Enterprise users.
After the next release of LGTM Enterprise, these files can be updated.
.. _upgrade-ql-packs:
Upgrade scripts for a language
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``qlpack.yml`` file for a QL pack that contains only upgrade scripts
uses the following properties: ``name`` and ``upgrades``.
For example, the ``qlpack.yml`` file for `C/C++ upgrades
<https://github.com/github/codeql/blob/main/cpp/upgrades/qlpack.yml>`__
contains:
.. code-block:: yaml
name: codeql-cpp-upgrades
upgrades: .

74
docs/codeql/codeql-cli/codeql-cli-reference/exit-codes.rst Normal file
View File

@@ -0,0 +1,74 @@
.. _exit-codes:
Exit codes
==========
The CodeQL CLI reports the status of each command it runs as an exit code.
This exit code provides information for subsequent commands or for other tools that rely on the CodeQL CLI.
0
---
Success, normal termination.
1
---
The command successfully determined that the answer to your question is "no".
This exit code is only used by a few commands, such as `codeql test run <../codeql-cli-manual/test-run.html>`__, `codeql database check <../codeql-cli-manual/dataset-check.html>`__, `codeql query format <../codeql-cli-manual/query-format.html>`__,and `codeql resolve extractor <../codeql-cli-manual/resolve-extractor.html>`__.
For more details, see the documentation for those commands.
2
---
Something went wrong.
The CLI writes a human-readable error message to stderr.
This includes cases where an extractor fails with an internal error, because the ``codeql`` driver can't distinguish between internal and user-facing errors in extractor behavior.
3
---
The launcher was unable to find the CodeQL installation directory.
In this case, the launcher can't start the Java code for the CodeQL CLI at all. This should only happen when something is severely wrong with the CodeQL installation.
32
---
The extractor didn't find any code to analyze when running `codeql database create <../codeql-cli-manual/database-create.html>`__ or `codeql database finalize <../codeql-cli-manual/database-finalize.html>`__.
33
---
One or more query evaluations timed out.
It's possible that some queries that were evaluated in parallel didn't time out. The results for those queries are produced as usual.
98
---
Evaluation was explicitly canceled.
99
---
The CodeQL CLI ran out of memory.
This doesn't necessarily mean that all the machine's physical RAM has been used.
If you don't use the ``--ram`` option to set a limit explicitly, the JVM decides on a default limit at startup.
100
---
A fatal internal error occurred.
This should be considered a bug. The CLI usually writes an abbreviated error description to stderr.
If you can reproduce the bug, it's helpful to use ``--logdir`` and send the log files to GitHub in a bug report.
Other
-----
In the case of really severe problems within the JVM that runs ``codeql``, it might return a nonzero exit code of its own choosing.
This should only happen if something is severely wrong with the CodeQL installation.

35
docs/codeql/codeql-cli/codeql-cli-reference/index.rst Normal file
View File

@@ -0,0 +1,35 @@
.. _codeql-cli-reference:
CodeQL CLI reference
====================
Find detailed information about the CodeQL commands, as well the files you can
use or generate when executing CodeQL processes.
.. toctree::
:titlesonly:
:hidden:
about-ql-packs
query-reference-files
sarif-output
specifying-command-options-in-a-codeql-configuration-file
exit-codes
- :doc:`About QL packs <about-ql-packs>`: QL packs are used to organize the files used in CodeQL analysis. They
contain queries, library files, query suites, and important metadata.
- :doc:`Query reference files <query-reference-files>`: A query reference file is text file that defines the location of one query to test.
- :doc:`SARIF output <sarif-output>`: CodeQL supports SARIF as an output format for sharing static analysis results.
- :doc:`Specifying command options in a CodeQL configuration file <specifying-command-options-in-a-codeql-configuration-file>`:
You can save default or frequently used options for your commands in a per-user configuration file.
- :doc:`Exit codes <exit-codes>`: The CodeQL CLI reports the status of each command it runs as an exit code.
This exit code provides information for subsequent commands or for other tools that rely on the CodeQL CLI.
.. _cli-commands:
CodeQL CLI commands
-------------------
To view provide detailed information about each CodeQL CLI command,
including its usage and options, visit the "`CodeQL CLI manual <../codeql-cli-manual>`__."

47
docs/codeql/codeql-cli/codeql-cli-reference/query-reference-files.rst Normal file
View File

@@ -0,0 +1,47 @@
.. _query-reference-files:
Query reference files
=====================
A query reference file is text file that defines the location of one query to test.
You use a query reference file when you want to tell the ``test run`` subcommand
to run a query that's not part of a test directory.
There are two ways to specify queries that you want to run as tests:
#. Use a query reference file to specify the location of a query to test.
This is useful when you create tests for alert and path queries that
are intended to identify problems in real codebases. You might create
several directories of test code, each focusing on different
aspects of the query. Then you would add a query reference file to
each directory of test code, to specify the query to test.
#. Add the query directly to a directory of tests.
These is typically useful when you're writing queries explicitly to test the behavior
of QL libraries. Often these queries contain just a few calls to library predicates,
wrapping them in a ``select`` statement so their output can be tested.
Defining a query reference file
-------------------------------
Each query reference file, ``.qlref``, contains a single line that defines
where to find one query. The location must be defined relative
to the root of the QL pack that contains the query.
Usually, this is a QL pack specified by the ``libraryPathDependencies`` for the test pack.
You should use forward slashes in the path on all operating
systems to ensure compatibility between systems.
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 `QL pack <https://github.com/github/codeql/blob/main/javascript/ql/test/qlpack.yml>`__
for the ``javascript/ql/test`` directory defines the ``codeql-javascript`` queries as
a dependency. So the query reference file defines the location of the query relative
to the ``codeql-javascript`` QL pack:
AngularJS/DeadAngularJSEventListener.ql
For another example, see `Testing custom queries <../using-the-codeql-cli/test-queries.html#example>`__.

292
docs/codeql/codeql-cli/codeql-cli-reference/sarif-output.rst Normal file
View File

@@ -0,0 +1,292 @@
.. _sarif-output:
SARIF output
============
CodeQL supports SARIF as an output format for sharing static analysis results.
SARIF is designed to represent the output of a broad range of static analysis
tools, and there are many features in the SARIF specification that are
considered "optional". This document details the output produced when using the
format type ``sarifv2.1.0``, which corresponds to the SARIF v2.1.0.csd1
specification.
For more information on selecting a file format for your analysis results, see
the `database analyze reference <../codeql-cli-manual/database-analyze.html>`__.
SARIF specification and schema
------------------------------
This topic is intended to be read alongside the detailed SARIF specification.
For more information on the specification and the SARIF schema, see the `SARIF
specification documentation
<https://github.com/oasis-tcs/sarif-spec/tree/master/Documents/CommitteeSpecificationDrafts/>`__
on GitHub.
Change notes
------------
Changes between versions
~~~~~~~~~~~~~~~~~~~~~~~~
+----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------+
| CodeQL version | Format type | Changes |
+================+=================+=============================================================================================================================+
| 2.0.0 | ``sarifv2.1.0`` | First version of this format. |
+----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------+
Future changes to the output
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The output produced for a given specific format type (for example
``sarifv2.1.0``) may change in future CodeQL releases. We will endeavor to
maintain backwards compatibility with consumers of the generated SARIF by
ensuring that:
- No field which is marked as “Always” being generated will be removed.
- The circumstances under which “Optional” fields are generated may change.
Consumers of the CodeQL SARIF output should be robust to the presence or absence
of these fields.
New output fields may be added in future releases under the same format
type–these are not considered to break backwards compatibility, and consumers
should be robust to the presence of newly added fields.
New format argument types may be added in future versions of CodeQL---for example,
to support new versions of SARIF. These have no guarantee of backwards
compatibility, unless explicitly documented.
Generated SARIF objects
-----------------------
This details each SARIF component that may be generated, along with any specific
circumstances. We omit any properties that are never generated.
``sarifLog`` object
~~~~~~~~~~~~~~~~~~~
+------------------------+-----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| JSON property name | When is this generated? | Notes |
+========================+=============================+===========================================================================================================================================+
| ``$schema`` | Always | Provides a link to the `SARIF schema <https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json>`__. |
+------------------------+-----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| ``version`` | Always | The version of the SARIF used to generate the output. |
+------------------------+-----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| ``runs`` | Always | An array containing a single run object, for one language. |
+------------------------+-----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
``run`` object
~~~~~~~~~~~~~~
+------------------------+-----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| JSON property name | When is this generated? | Notes |
+========================+=============================+===========================================================================================================================================================================================================================================================================================+
| ``tool`` | Always | – |
+------------------------+-----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``originalUriBaseIds`` | Always | A dictionary of ``uriBaseIds`` to artifactLocations representing the original locations on the analysis machine. At a minimum, this will contain the ``%SRCROOT%`` ``uriBaseId``, which represents the root location on the analysis machine of the source code for the analyzed project. |
| | | Each ``artifactLocation`` will contain the ``uri`` and ``description`` properties. |
+------------------------+-----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``artifacts`` | Always | An array containing at least one artifact object for every file referenced in a result. |
+------------------------+-----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``results`` | Always | – |
+------------------------+-----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``newLineSequences`` | Always | – |
+------------------------+-----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``columnKind`` | Always | – |
+------------------------+-----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``properties`` | Always | The properties dictionary will contain the ``semmle.formatSpecifier``, which identifies the format specifier passed to the CodeQL CLI. |
+------------------------+-----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
``tool`` object
~~~~~~~~~~~~~~~
+------------------------+-----------------------------+-----------+
| JSON property name | When is this generated? | Notes |
+========================+=============================+===========+
| ``driver`` | Always | – |
+------------------------+-----------------------------+-----------+
``toolComponent`` object
~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------+-----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| JSON property name | When is this generated? | Notes |
+========================+=============================+==========================================================================================================================================================================================================================================================================================+
| ``name`` | Always | Set to “CodeQL command-line toolchain” for output from the CodeQL CLI tools. Note, if the output was generated using a different tool a different ``name`` is reported, and the format may not be as described here. |
+------------------------+-----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``organization`` | Always | Set to “GitHub”. |
+------------------------+-----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``version`` | Always | Set to the CodeQL release version e.g. “2.0.0”. |
+------------------------+-----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``rules`` | Always | An array of ``reportingDescriptor`` objects that represent rules. This array will contain, at a minimum, all the rules that were run during this analysis, but may contain rules which were available but not run. For more detail about enabling queries, see ``defaultConfiguration``. |
+------------------------+-----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
``reportingDescriptor`` object (for rule)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``reportingDescriptor`` objects may be used in multiple places in the SARIF specification. When a ``reportingDescriptor`` is included in the rules array of a ``toolComponent`` object it has the following properties.
+------------------------------------------------------------------+--------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| JSON property name | When is this generated? | Notes |
+==================================================================+================================+====================================================================================================================================================================================================================================================================================+
| ``id`` | Always | Will contain the ``@id`` property specified in the query that defines the rule, which is usually of the format ``language/rule-name`` (for example ``cpp/unsafe-format-string``). If your organization defines the ``@opaqueid`` property in the query it will be used instead. |
+------------------------------------------------------------------+--------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``name`` | Always | Will contain the ``@id`` property specified in the query. See the ``id`` property above for an example. |
+------------------------------------------------------------------+--------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``shortDescription`` | Always | Will contain the ``@name`` property specified in the query that defines the rule. |
+------------------------------------------------------------------+--------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``fullDescription`` | Always | Will contain the ``@description`` property specified in the query that defines the rule. |
+------------------------------------------------------------------+--------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``defaultConfiguration`` | Always | A ``reportingConfiguration`` object, with the enabled property set to true or false, and a level property set according to the ``@severity`` property specified in the query that defines the rule. Omitted if the ``@severity`` property was not specified. |
+------------------------------------------------------------------+--------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
``artifact`` object
~~~~~~~~~~~~~~~~~~~
+------------------------+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| JSON property name | When is this generated? | Notes |
+========================+=============================+=================================================================================================================================================================================================================================================================+
| ``location`` | Always | An ``artifactLocation`` object. |
+------------------------+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``index`` | Always | The index of the ``artifact`` object. |
+------------------------+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``contents`` | Optionally | If results are generated using the ``--sarif-add-file-contents`` flag, and the source code is available at the time the SARIF file is generated, then the ``contents`` property is populated with an ``artifactContent`` object, with the ``text`` property set.|
+------------------------+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
``artifactLocation`` object
~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| JSON property name | When is this generated? | Notes |
+========================+=============================+======================================================================================================================================+
| ``uri`` | Always | – |
+------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| ``index`` | Always | – |
+------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| ``uriBaseId`` | Optionally | If the file is relative to some known abstract location, such as the root source location on the analysis machine, this will be set. |
+------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
``result`` object
~~~~~~~~~~~~~~~~~
The composition of the results is dependent on the options provided to CodeQL.
By default, the results are grouped by unique message format string and
primary location. Thus, two results that occur at the same location with the
same underlying message, will appear as a single result in the output. This
behavior can be disabled by using the flag ``--ungroup-results``, in which case
no results are grouped.
+-------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| JSON property name | When is this generated? | Notes |
+=========================+=============================+=========================================================================================================================================================================================================================================================================================================+
| ``ruleId`` | Always | See the description of the ``id`` property in ``reportingDescriptor`` object (for rule) . |
+-------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``ruleIndex`` | Always | – |
+-------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``message`` | Always | A message describing the problem(s) occurring at this location. This message may be a SARIF “Message with placeholder”, containing links that refer to locations in the ``relatedLocations`` property. |
+-------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``locations`` | Always | An array containing a single ``location`` object. |
+-------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``partialFingerprints`` | Always | A dictionary from named fingerprint types to the fingerprint. This will contain, at a minimum, a value for the ``primaryLocationLineHash``, which provides a fingerprint based on the context of the primary location. |
+-------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``codeFlows`` | Optionally | This array may be populated with one or more ``codeFlow`` objects if the query that defines the rule for this result is of ``@kind path-problem``. |
+-------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``relatedLocations`` | Optionally | This array will be populated if the query that defines the rule for this result has a message with placeholder options. Each unique location is included once. |
+-------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``suppressions`` | Optionally | If the result is suppressed, then this will contain a single ``suppression`` object, with the ``@kind`` property set to ``IN_SOURCE``. If this result is not suppressed, but there is at least one result that has a suppression, then this will be set to an empty array, otherwise it will not be set.|
+-------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
``location`` object
~~~~~~~~~~~~~~~~~~~
+------------------------+-----------------------------+----------------------------------------------------------------------------------------------------------------------------+
| JSON property name | When is this generated? | Notes |
+========================+=============================+============================================================================================================================+
| ``physicalLocation`` | Always | – |
+------------------------+-----------------------------+----------------------------------------------------------------------------------------------------------------------------+
| ``id`` | Optionally | ``location`` objects that appear in the ``relatedLocations`` array of a ``result`` object may contain the ``id`` property. |
+------------------------+-----------------------------+----------------------------------------------------------------------------------------------------------------------------+
| ``message`` | Optionally | ``location`` objects may contain the ``message`` property if: |
| | | |
| | | - They appear in the ``relatedLocations`` array of a ``result`` object may contain the ``message`` property. |
| | | - They appear in the ``threadFlowLocation.location`` property. |
+------------------------+-----------------------------+----------------------------------------------------------------------------------------------------------------------------+
``physicalLocation`` object
~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| JSON property name | When is this generated? | Notes |
+========================+=============================+===================================================================================================================================+
| ``artifactLocation`` | Always | – |
+------------------------+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| ``region`` | Optionally | If the given ``physicalLocation`` exists in a text file, such as a source code file, then the ``region`` property may be present. |
+------------------------+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| ``contextRegion`` | Optionally | May be present if this location has an associated ``snippet``. |
+------------------------+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
``region`` object
~~~~~~~~~~~~~~~~~
There are two types of ``region`` object produced by CodeQL:
- Line/column offset regions
- Character offset and length regions
Any region produced by CodeQL may be specified in either format, and consumers
should robustly handle either type.
For line/column offset regions, the following properties will be set:
+------------------------+-----------------------------+----------------------------------------------------------------------------------------------+
| JSON property name | When is this generated? | Notes |
+========================+=============================+==============================================================================================+
| ``startLine`` | Always | – |
+------------------------+-----------------------------+----------------------------------------------------------------------------------------------+
| ``startColumn`` | Optionally | Not included if equal to the default value of 1. |
+------------------------+-----------------------------+----------------------------------------------------------------------------------------------+
| ``endLine`` | Optionally | Not included if identical to ``startLine``. |
+------------------------+-----------------------------+----------------------------------------------------------------------------------------------+
| ``endColumn`` | Always | – |
+------------------------+-----------------------------+----------------------------------------------------------------------------------------------+
| ``snippet`` | Optionally | – |
+------------------------+-----------------------------+----------------------------------------------------------------------------------------------+
For character offset and length regions, the following properties will be set:
+------------------------+-----------------------------+----------------------------------------------------------------------------------------------+
| JSON property name | When is this generated? | Notes |
+========================+=============================+==============================================================================================+
| ``charOffset`` | Optionally | Provided if ``startLine``, ``startColumn``, ``endLine``, and ``endColumn`` are not populated.|
+------------------------+-----------------------------+----------------------------------------------------------------------------------------------+
| ``charLength`` | Optionally | Provided if ``startLine``, ``startColumn``, ``endLine``, and ``endColumn`` are not populated.|
+------------------------+-----------------------------+----------------------------------------------------------------------------------------------+
| ``snippet`` | Optionally | – |
+------------------------+-----------------------------+----------------------------------------------------------------------------------------------+
``codeFlow`` object
~~~~~~~~~~~~~~~~~~~
+------------------------+-----------------------------+-----------+
| JSON property name | When is this generated? | Notes |
+========================+=============================+===========+
| ``threadFlows`` | Always | – |
+------------------------+-----------------------------+-----------+
``threadFlow`` object
~~~~~~~~~~~~~~~~~~~~~
+------------------------+-----------------------------+-----------+
| JSON property name | When is this generated? | Notes |
+========================+=============================+===========+
| ``locations`` | Always | – |
+------------------------+-----------------------------+-----------+
``threadFlowLocation`` object
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------+-----------------------------+-----------+
| JSON property name | When is this generated? | Notes |
+========================+=============================+===========+
| ``location`` | Always | – |
+------------------------+-----------------------------+-----------+

72
docs/codeql/codeql-cli/codeql-cli-reference/specifying-command-options-in-a-codeql-configuration-file.rst Normal file
View File

@@ -0,0 +1,72 @@
.. _specifying-command-options-in-a-codeql-configuration-file:
Specifying command options in a CodeQL configuration file
=========================================================
You can save default or frequently used options for your commands in a per-user
configuration file.
You can specify CodeQL CLI command options in two ways:
- Directly in the command line, using the appropriate flag.
- In a configuration (or ``config``) file that CodeQL scans for relevant
options each time a command is executed.
For options that are likely to change each time you execute a command,
specifying the value on the command line is the most convenient way of passing
the information to CodeQL. Saving options in a ``config`` file is a good way to
specify options you use frequently.
It's also a good way to add custom QL packs that you use regularly to your search path.
Using a CodeQL configuration file
---------------------------------
You need to save the ``config`` file under your home (Linux and macOS) or user profile
(Windows) directory in the ``.config/codeql/`` subdirectory.
For example, ``$HOME/.config/codeql/config``.
The syntax for specifying options is as follows::
<command> <subcommand> <option> <value>
To apply the same options to more than one command you can:
- Omit the ``<subcommand>``, which will specify the option for every
``<subcommand>`` to which it's relevant.
- Omit both ``<command>`` and ``<subcommand>``, which will globally specify the
option for every ``<command>`` and ``<subcommand>`` to which it's relevant.
.. pull-quote::
Note
- ``config`` files only accept spaces between between option flags and
values---CodeQL will throw an error if you use ``=`` to specify an option value.
- If you specify an option in the command line, this overrides the ``config``
value defined for that option.
- If you want to specify more than one option for a ``<command>``,
``<subcommand>`` or globally, use one line per option.
Examples
~~~~~~~~
- To output all analysis results generated by ``codeql database analyze`` as
CSV format, you would specify::
database analyze --format csv
Here, you have to specify the command and subcommand to prevent any of the
low-level commands that are executed during ``database analyze`` being passed
the same ``--format`` option.
- To define the RAM (4096 MB) and number of threads (4) to use when running
CodeQL commands, specify the following, on separate lines::
--ram 4096
--threads 4
- To globally specify a directory for CodeQL to scan for QL packs (which is not a
sibling of the installation directory), use::
--search-path <path-to-directory>

21
docs/codeql/codeql-cli/index.rst Normal file
View File

@@ -0,0 +1,21 @@
.. _codeql-cli:
CodeQL CLI
==========
.. include:: ../reusables/codeql-cli-overview.rst
See the following links to learn how to get set up and run CodeQL commands:
- :ref:`Using the CodeQL CLI <using-the-codeql-cli>`: Software
developers and security researchers can secure their code using the CodeQL CLI.
- :ref:`CodeQL CLI reference <codeql-cli-reference>`."
.. toctree::
:titlesonly:
:hidden:
using-the-codeql-cli/index
codeql-cli-reference/index

29
docs/codeql/codeql-cli/using-the-codeql-cli/about-the-codeql-cli.rst Normal file
View File

@@ -0,0 +1,29 @@
.. _about-the-codeql-cli:
About the CodeQL CLI
====================
Software developers and security researchers can secure their code
using the CodeQL CLI.
The CodeQL CLI is a command-line tool used to run CodeQL processes locally on
open source software projects. You can use the CodeQL CLI to:
- Run CodeQL analyses using queries provided by GitHub engineers and the open
source community
- Create CodeQL databases to use in the CodeQL for Visual Studio Code
- Develop and test custom CodeQL queries to use in your own analyses
For more information about how to use the CodeQL CLI, see
":ref:`CodeQL CLI <codeql-cli>`."
CodeQL CLI commands
-------------------
The CodeQL CLI includes commands to create and analyze CodeQL databases from the
command line. To run a command, use::
codeql [command] [subcommand]
To view the reference documentation for a command, add the ``--help`` flag, or visit the
"`CodeQL CLI manual <../codeql-cli-manual>`__."

228
docs/codeql/codeql-cli/using-the-codeql-cli/analyzing-databases-with-the-codeql-cli.rst Normal file
View File

@@ -0,0 +1,228 @@
.. _analyzing-databases-with-the-codeql-cli:
Analyzing databases with the CodeQL CLI
=======================================
To analyze a codebase, you run queries against a CodeQL
database extracted from the code.
CodeQL analyses produce :ref:`interpreted results
<interpret-query-results>` that can be displayed as alerts or paths in source code.
For information about writing queries to run with ``database analyze``, see
":doc:`Using custom queries with the CodeQL CLI <using-custom-queries-with-the-codeql-cli>`."
.. include:: ../../reusables/advanced-query-execution.rst
Before starting an analysis you must:
- :doc:`Set up the CodeQL CLI <getting-started-with-the-codeql-cli>` so that it can find the queries
and libraries included in the CodeQL repository.
- :doc:`Create a CodeQL database <creating-codeql-databases>` for the source
code you want to analyze.
Running ``codeql database analyze``
------------------------------------
When you run ``database analyze``, it does two things:
#. Executes one or more query files, by running them over a CodeQL database.
#. Interprets the results, based on certain query metadata, so that alerts can be
displayed in the correct location in the source code.
You can analyze a database by running the following command::
codeql database analyze <database> <queries> --format=<format> --output=<output>
You must specify:
- ``<database>``: the path to the CodeQL database you want to analyze.
- ``<queries>``: the queries to run over your database. You can
list one or more individual query files, specify a directory that will be
searched recursively for query files, or name a query suite that defines a
particular set of queries. For more information, see the :ref:`examples
<database-analyze-examples>` below.
- ``--format``: the format of the results file generated during analysis. A
number of different formats are supported, including CSV, :ref:`SARIF
<sarif-file>`, and graph formats. For more information about CSV and SARIF,
see `Results <#results>`__. To find out which other results formats are
supported, see the `database analyze reference
<../codeql-cli-manual/database-analyze.html>`__.
- ``--output``: the output path of the results file generated during analysis.
You can also specify:
- .. include:: ../../reusables/threads-query-execution.rst
.. pull-quote::
Upgrading databases
If the CodeQL queries you want to use are newer than the
extractor used to create the database, then you may see a message telling you
that your database needs to be upgraded when you run ``database analyze``.
You can quickly upgrade a database by running the ``database upgrade``
command. For more information, see ":doc:`Upgrading CodeQL databases
<upgrading-codeql-databases>`."
For full details of all the options you can use when analyzing databases, see
the `database analyze reference documentation <../codeql-cli-manual/database-analyze.html>`__.
.. _database-analyze-examples:
Examples
--------
The following examples assume your CodeQL databases have been created in a
directory that is a sibling of your local copies of the CodeQL and CodeQL for Go
repositories.
Running a single query
~~~~~~~~~~~~~~~~~~~~~~
To run a single query over a JavaScript codebase, you could use the following
command from the directory containing your database::
codeql database analyze <javascript-database> ../ql/javascript/ql/src/Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv
This command runs a simple query that finds potential bugs related to unused
variables, imports, functions, or classes---it is one of the JavaScript
queries included in the CodeQL repository. You could run more than one query by
specifying a space-separated list of similar paths.
The analysis generates a CSV file (``js-results.csv``) in a new directory
(``js-analysis``).
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,
see ":doc:`Using custom queries with the CodeQL CLI <using-custom-queries-with-the-codeql-cli>`."
Running LGTM.com query suites
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The CodeQL repository also includes query suites, which can be run over your
code as part of a broader code review. CodeQL query suites are ``.qls`` files
that use directives to select queries to run based on certain metadata
properties.
The query suites included in the CodeQL repository select the same set of
queries that are run by default on `LGTM.com <https://lgtm.com>`__. The queries
are selected to highlight the most relevant and useful results for each
language.
The language-specific LGTM query suites are located at the following paths in
the CodeQL repository::
ql/<language>/ql/src/codeql-suites/<language>-lgtm.qls
and at the following path in the CodeQL for Go repository::
ql/src/codeql-suites/go-lgtm.qls
These locations are specified in the metadata included in the standard QL packs.
This means that CodeQL knows where to find the suite files automatically, and
you don't have to specify the full path on the command line when running an
analysis. For more information, see ":ref:`About QL packs <standard-ql-packs>`."
For example, to run the LGTM.com query suite on a C++ codebase (generating
results in the latest SARIF format), you would run::
codeql database analyze <cpp-database> cpp-lgtm.qls --format=sarif-latest --output=cpp-analysis/cpp-results.sarif
For information about creating custom query suites, see ":doc:`Creating
CodeQL query suites <creating-codeql-query-suites>`."
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:`QL pack
<../codeql-cli-reference/about-ql-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
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.
Results
-------
You can save analysis results in a number of different formats, including SARIF
and CSV.
The SARIF format is designed to represent the output of a broad range of static
analysis tools. For more information, see :doc:`SARIF output <../codeql-cli-reference/sarif-output>`.
If you choose to generate results in CSV format, then each line in the output file
corresponds to an alert. Each line is a comma-separated list with the following information:
.. list-table::
:header-rows: 1
:widths: 20 40 40
* - Property
- Description
- Example
* - Name
- Name of the query that identified the result.
- ``Inefficient regular expression``
* - Description
- Description of the query.
- ``A regular expression that requires exponential time to match certain
inputs can be a performance bottleneck, and may be vulnerable to
denial-of-service attacks.``
* - Severity
- Severity of the query.
- ``error``
* - Message
- Alert message.
- ``This part of the regular expression may cause exponential backtracking
on strings containing many repetitions of '\\\\'.``
* - Path
- Path of the file containing the alert.
- ``/vendor/codemirror/markdown.js``
* - Start line
- Line of the file where the code that triggered the alert begins.
- ``617``
* - Start column
- Column of the start line that marks the start of the alert code. Not
included when equal to 1.
- ``32``
* - End line
- Line of the file where the code that triggered the alert ends. Not
included when the same value as the start line.
- ``64``
* - End column
- Where available, the column of the end line that marks the end of the
alert code. Otherwise the end line is repeated.
- ``617``
Results files can be integrated into your own code-review or debugging
infrastructure. For example, SARIF file output can be used to highlight alerts
in the correct location in your source code using a SARIF viewer plugin for your
IDE.
Further reading
---------------
- ":ref:`Analyzing your projects in CodeQL for VS Code <analyzing-your-projects>`"

226
docs/codeql/codeql-cli/using-the-codeql-cli/creating-codeql-databases.rst Normal file
View File

@@ -0,0 +1,226 @@
.. _creating-codeql-databases:
Creating CodeQL databases
=========================
Before you analyze your code using CodeQL, you need to create a CodeQL
database containing all the data required to run queries on your code.
CodeQL analysis relies on extracting relational data from your code, and
using it to build a :ref:`CodeQL database <codeql-database>`. CodeQL
databases contain all of the important information about a codebase, which can
be analyzed by executing CodeQL queries against it.
Before you generate a CodeQL database, you need to:
- Install and set up the CodeQL CLI. For more information, see
":doc:`Getting started with the CodeQL CLI <getting-started-with-the-codeql-cli>`."
- Check out the version of your codebase you want to analyze. The directory
should be ready to build, with all dependencies already installed.
Running ``codeql database create``
----------------------------------
CodeQL databases are created by running the following command from the checkout root
of your project:
::
codeql database create <database> --language=<language-identifier>
You must specify:
- ``<database>``: a path to the new database to be created. This directory will
be created when you execute the command---you cannot specify an existing
directory.
- ``--language``: the identifier for the language to create a database for.
CodeQL supports creating databases for the following languages:
.. include:: ../../reusables/extractors.rst
Other options may be specified depending on the location of your source file and
the language you want to analyze:
- ``--source-root``: the root folder for the primary source files used in
database creation. By default, the command assumes that the current
directory is the source root---use this option to specify a different location.
- ``--command``: for compiled languages only, the build commands that invoke the
compiler. Do not specify ``--command`` options for Python and
JavaScript. Commands will be run from the current folder, or ``--source-root``
if specified. If you don't include a ``--command``, CodeQL will attempt to
detect the build system automatically, using a built-in autobuilder.
For full details of all the options you can use when creating databases,
see the `database create reference documentation <../codeql-cli-manual/database-create.html>`__.
Progress and results
--------------------
Errors are reported if there are any problems with the options you have
specified. For interpreted languages, the extraction progress is displayed in
the console---for each source file, it reports if extraction was successful or if
it failed. For compiled languages, the console will display the output of the
build system.
When the database is successfully created, you'll find a new directory at the
path specified in the command. This directory contains a number of
subdirectories, including the relational data (required for analysis) and a
source archive---a copy of the source files made at the time the database was
created---which is used for displaying analysis results.
Obtaining databases from LGTM.com
---------------------------------
`LGTM.com <https://lgtm.com>`__ analyzes thousands of open-source projects using
CodeQL. For each project on LGTM.com, you can download an archived CodeQL
database corresponding to the most recently analyzed revision of the code. These
databases can also be analyzed using the CodeQL CLI.
.. include:: ../../reusables/download-lgtm-database.rst
Before running an analysis, unzip the databases and try :doc:`upgrading <upgrading-codeql-databases>` the
unzipped databases to ensure they are compatible with your local copy of the
CodeQL queries and libraries.
.. pull-quote::
Note
.. include:: ../../reusables/index-files-note.rst
Creating databases for non-compiled languages
---------------------------------------------
The CodeQL CLI includes extractors to create databases for non-compiled
languages---specifically, JavaScript (and TypeScript) and Python. These
extractors are automatically invoked when you specify JavaScript or Python as
the ``--language`` option when executing ``database create``. When creating
databases for these languages you must ensure that all additional dependencies
are available.
.. pull-quote:: Important
When running ``database create`` for JavaScript, TypeScript, and Python, you must not
specify a ``--command`` option. If you do, you will override the normal
extractor invocation, which will create an empty database.
JavaScript and TypeScript
~~~~~~~~~~~~~~~~~~~~~~~~~
Creating databases for JavaScript requires no additional dependencies, but if
the project includes TypeScript files, you must install Node.js 6.x
or later. In the command line you can specify ``--language=javascript`` to
extract both JavaScript and TypeScript files::
codeql database create --language=javascript --source-root <folder-to-extract> <output-folder>/javascript-database
Here, we have specified a ``--source-root`` path, which is the location where
database creation is executed, but is not necessarily the checkout root of the
codebase.
Python
~~~~~~
When creating databases for Python you must ensure:
- You have the all of the required versions of Python installed.
- You have access to the `pip <https://pypi.org/project/pip/>`__
packaging management system and can install any
packages that the codebase depends on.
- You have installed the `virtualenv <https://pypi.org/project/virtualenv/>`__ pip module.
In the command line you must specify ``--language=python``. For example
::
codeql database create --language=python <output-folder>/python-database
executes the ``database create`` subcommand from the code's checkout root,
generating a new Python database at ``<output-folder>/python-database``.
Creating databases for compiled languages
-----------------------------------------
For compiled languages, CodeQL needs to invoke the required build system to
generate a database, therefore the build method must be available to the CLI.
Detecting the build system
~~~~~~~~~~~~~~~~~~~~~~~~~~
The CodeQL CLI includes autobuilders for C/C++, C#, Go, and Java code. CodeQL
autobuilders allow you to build projects for compiled languages without
specifying any build commands. When an autobuilder is invoked, CodeQL examines
the source for evidence of a build system and attempts to run the optimal set of
commands required to extract a database.
An autobuilder is invoked automatically when you execute ``codeql database
create`` for a compiled ``--language`` if don't include a
``--command`` option. For example, for a Java codebase, you would simply run::
codeql database create --language=java <output-folder>/java-database
If a codebase uses a standard build system, relying on an autobuilder is often
the simplest way to create a database. For sources that require non-standard
build steps, you may need to explicitly define each step in the command line.
.. pull-quote:: Creating databases for Go
For Go, you should always use the CodeQL autobuilder. Install the Go
toolchain (version 1.11 or later) and, if there are dependencies, the
appropriate dependency manager (such as `dep
<https://golang.github.io/dep/>`__ or `Glide <http://glide.sh/>`__).
Do not specify any build commands, as you will override the autobuilder
invocation, which will create an empty database.
Specifying build commands
~~~~~~~~~~~~~~~~~~~~~~~~~
The following examples are designed to give you an idea of some of the build
commands that you can specify for compiled languages.
.. pull-quote:: Important
The ``--command`` option accepts a single argument---if you need to
use more than one command, specify ``--command`` multiple times.
If you need to pass subcommands and options, the whole argument needs to be
quoted to be interpreted correctly.
- C/C++ project built using ``make``::
codeql database create cpp-database --language=cpp --command=make
- C# project built using ``dotnet build`` (.NET Core 3.0 or later)::
codeql database create csharp-database --language=csharp --command='dotnet build /t:rebuild'
On Linux and macOS (but not Windows), you need to disable shared compilation when building C# projects
with .NET Core 2 or earlier, so expand the command to::
codeql database create csharp-database --language=csharp --command='dotnet build /p:UseSharedCompilation=false /t:rebuild'
- Java project built using Gradle::
codeql database create java-database --language=java --command='gradle clean test'
- Java project built using Maven::
codeql database create java-database --language=java --command='mvn clean install'
- Java project built using Ant::
codeql database create java-database --language=java --command='ant -f build.xml'
- Project built using a custom build script::
codeql database create new-database --language=<language> --command='./scripts/build.sh'
This command runs a custom script that contains all of the commands required
to build the project.
Further reading
---------------
- ":ref:`Analyzing your projects in CodeQL for VS Code <analyzing-your-projects>`"

286
docs/codeql/codeql-cli/using-the-codeql-cli/creating-codeql-query-suites.rst Normal file
View File

@@ -0,0 +1,286 @@
.. _creating-codeql-query-suites:
Creating CodeQL query suites
============================
CodeQL query suites provide a way of selecting queries, based on their
filename, location on disk or in a QL pack, or metadata properties.
Create query suites for the queries that you want to frequently use in
your CodeQL analyses.
Query suites allow you to pass multiple queries to
CodeQL without having to specify the path to each query file individually.
Query suite definitions are stored in YAML files with the extension ``.qls``. A
suite definition is a sequence of instructions, where each instruction is a YAML
mapping with (usually) a single key. The instructions are executed in the order
they appear in the query suite definition. After all the instructions in the
suite definition have been executed, the result is a set of selected queries.
.. note::
Any custom queries that you want to add to a query suite must be in a :doc:`QL
pack <../codeql-cli-reference/about-ql-packs>` and contain the correct query metadata.
For more information, see
":doc:`Using custom queries with the CodeQL CLI <using-custom-queries-with-the-codeql-cli>`."
Locating queries to add to a query suite
----------------------------------------
When creating a query suite, you first need to specify the locations of the
queries that you want to select. You can define the location of one or more
queries using:
- A ``query`` instruction---tells CodeQL to look for one or more specified ``.ql``
files::
- query: <path-to-query>
The argument must be one or more file paths, relative to the QL pack containing
the suite definition.
- A ``queries`` instruction---tells CodeQL to recursively scan a directory
for ``.ql`` files::
- queries: <path-to-subdirectory>
The path of the directory must be relative to the root of the QL pack that
contains the suite definition file. To find the queries relative to a
different QL pack, add a ``from`` field::
- queries: <path-to-subdirectory>
from: <ql-pack-name>
- A ``qlpack`` instruction---tells CodeQL to look for queries in a named QL pack::
- qlpack: <qlpack-name>
.. note::
When pathnames appear in query suite definitions, they must always
be given with a forward slash, ``/``, as a directory separator.
This ensures that query suite definitions work on all operating systems.
You must add at least one ``query``, ``queries``, or ``qlpack`` instruction to
your suite definition, otherwise no queries will be selected. If the suite
contains no further instructions, all the queries found from the list of files,
in the given directory, or in the named QL pack are selected. If there are further
filtering instructions, only queries that match the constraints imposed by those
instructions will be selected.
Filtering the queries in a query suite
----------------------------------------
After you have defined the initial set of queries to add to your suite by
specifying ``query``, ``queries``, or ``qlpack`` instructions, you can add
``include`` and ``exclude`` instructions. These instructions define selection
criteria based on specific properties:
- When you execute an ``include`` instruction on a set of queries, any
queries that match your conditions are retained in the selection, and queries
that don't match are removed.
- When you execute an ``exclude`` instructions on a set of queries,
any queries that match your conditions are removed from the selection, and queries
that don't match are retained.
The order of your filter instructions is important. The first filter instruction
that appears after the locating instructions determines whether the queries are
included or excluded by default. If the first filter is an ``include``, the
initially located queries will only be part of the suite if they match an
explicit ``include`` filter. If the first filter is an ``exclude``, the initially
located queries are part of the suite unless they are explicitly excluded.
Subsequent instructions are executed in order and the instructions that appear
later in the file take precedence over the earlier instructions. So, ``include``
instructions can be overridden by a later ``exclude`` instructions that match
the same query. Similarly, ``exclude``\ s can be overridden by a later
``include``.
For both instructions, the argument is a constraint block---that is, a YAML map
representing the constraints. Each constraint is a map entry, where the key is
typically a query metadata property. The value can be:
- A single string.
- A ``/``\ -enclosed `regular expression <https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html>`__.
- A list containing strings, regular expressions, or both.
To match a constraint, a metadata value must match one of the strings or
regular expressions. When there is more than one metadata key, each key must be matched.
For more information about query metadata properties, see ":ref:`Metadata for CodeQL queries
<metadata-for-codeql-queries>`."
In addition to metadata tags, the keys in the constraint block can also be:
- ``query filename``---matches on the last path component of the query file name.
- ``query path``---matches on the path to the query file relative to its
enclosing QL pack.
- ``tags contain``---one of the given match strings must match
one of the space-separated components of the value of the ``@tags`` metadata property.
- ``tags contain all``---each of the given match strings must match one of the
components of the ``@tags`` metadata property.
Examples
~~~~~~~~
To define a suite that selects all queries with ``@kind problem``
and ``@precision high`` from the ``my-custom-queries`` directory, use::
- queries: my-custom-queries
- include:
kind: problem
precision: very-high
To create a suite that selects all queries with ``@kind problem`` from the
``my-custom-queries`` directory except those with ``@problem.severity
recommendation``, use::
- queries: my-custom-queries
- include:
kind: problem
- exclude:
problem.severity: recommendation
To create a suite that selects all queries with ``@tag security`` and
``@problem.severity high`` or ``very-high`` from the ``codeql-cpp`` QL pack,
use::
- qlpack: codeql-cpp
- include:
tags contain: security
problem.severity:
- high
- very-high
Reusing existing query suite definitions
-----------------------------------------
Existing query suite definitions can be reused by specifying:
- An ``import`` instruction---adds the queries selected by a
previously defined ``.qls`` file to the current suite::
- import: <path-to-query-suite>
The path to the imported suite must be relative to the QL pack containing the
current suite definition. If the imported query suite is in a different QL
pack you can use::
- import: <path-to-query-suite>
from: <ql-pack>
Queries added using an ``import`` instruction can be filtered using subsequent
``exclude`` instructions.
- An ``apply`` instruction---adds all of the instructions from a
previously defined ``.qls`` file to the current suite. The instructions in the
applied ``.qls`` file are executed as if they appear in place of ``apply``.
Any ``include`` and ``exclude`` instructions from the applied suite also act on
queries added by any earlier instructions::
- apply: <path-to-query-suite>
The ``apply`` instruction can also be used to apply a set of reusable
conditions, saved in a ``.yml`` file, to multiple query definitions. For more
information, see the `example <#example>`__ below.
- An ``eval`` instruction---performs the same function as an ``import``
instruction, but takes a full suite definition as the argument, rather than the
path to a ``.qls`` file on disk.
Example
~~~~~~~
To use the same conditions in multiple query suite definitions, create a
separate ``.yml`` file containing your instructions. For example, save the
following in a file called ``reusable-instructions.yml``::
- include:
kind:
- problem
- path-problem
tags contain: security
precision:
- high
- very-high
Add ``reusable-instructions.yml`` to the same QL pack as your current query
suite (for example, ``my-custom-queries``). Apply the reusable instructions
to the queries in your current suite using::
- qlpack: my-custom-queries
- apply: reusable-instructions.yml
To apply the same conditions to a different suite or directory within the same
QL pack, create a new definition and change (or replace) the ``qlpack``
instruction. For example::
- queries: queries/cpp/custom
- apply: reusable-instructions.yml
You can also create a suite definition using ``reusable-instructions.yml`` on
queries in a different QL pack. If the ``.qls`` file is in the same QL pack as
the queries, you can add a ``from`` field immediately after the ``apply``
instruction::
- qlpack: my-other-custom-queries
- apply: reusable-instructions.yml
from: <name-of-ql-pack>
Naming a query suite
--------------------
You can provide a name for your query suite by specifying a ``description``
instruction::
- description: <name-of-query-suite>
This value is displayed when you run `codeql resolve queries
<../codeql-cli-manual/resolve-queries.html>`__, if the suite is added to a "well-known"
directory. For more information, see "`Specifying well-known query suites
<#specifying-well-known-query-suites>`__."
Saving a query suite
--------------------
Save your query suite in a file with a ``.qls`` extension and add it to a QL
pack. For more information, see ":ref:`About QL packs <custom-ql-packs>`."
Specifying well-known query suites
----------------------------------
You can use QL packs to declare directories that contain "well-known" query
suites. You can use "well-known" query suites on the command line by referring
to their file name,
without providing their full path. This gives you a simple way of specifying a
set of queries, without needing to search inside QL packs and distributions.
To declare a directory that contains "well-known" query suites, add the directory
to the ``suites`` property in the ``qlpack.yml`` file at the root of your QL pack.
For more information, see "`About QL packs <../codeql-cli-reference/qlpack-overview.html#qlpack-yml-properties>`__."
Using query suites with CodeQL
------------------------------
You can specify query suites on the command line for any command that accepts
``.qls`` files. For example, you can compile the queries selected by a suite
definition using ``query compile``, or use the queries in an analysis using
``database analyze``. For more information about analyzing CodeQL databases, see
":doc:`Analyzing databases with the CodeQL CLI <analyzing-databases-with-the-codeql-cli>`."
Viewing the query suites used on LGTM.com
-----------------------------------------
The query suite definitions used to select queries to run on LGTM.com can be
found in the CodeQL repository. For example, to view the CodeQL queries for
JavaScript, visit
https://github.com/github/codeql/tree/main/javascript/ql/src/codeql-suites.
These suite definitions apply reusable filter patterns to the queries
located in the standard QL packs for each supported language. For more
information, see the `suite-helpers
<https://github.com/github/codeql/tree/main/misc/suite-helpers>`__ in the CodeQL
repository.
Further reading
---------------
- "`CodeQL queries
<writing-codeql-queries:codeql-queries>`"

235
docs/codeql/codeql-cli/using-the-codeql-cli/getting-started-with-the-codeql-cli.rst Normal file
View File

@@ -0,0 +1,235 @@
.. _getting-started-with-the-codeql-cli:
Getting started with the CodeQL CLI
===================================
To run CodeQL commands, you need to set up the CLI so that it can access
the tools, queries, and libraries required to create and analyze databases.
.. include:: ../../reusables/license-note.rst
.. _setting-up-cli:
Setting up the CodeQL CLI
-------------------------
The CodeQL CLI can be set up to support many different use cases and directory
structures. To get started quickly, we recommend adopting a relatively simple
setup, as outlined in the steps below.
If you use Linux, Windows, or macOS version 10.14 ("Mojave") or earlier, simply
follow the steps below. For macOS version 10.15 ("Catalina"), steps 1 and 4 are
slightly different---for further details, see the sections labeled **Information
for macOS "Catalina" users**.
1. Download the CodeQL CLI zip package
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The CodeQL CLI download package is a zip archive containing tools, scripts, and
various CodeQL-specific files. If you don't have an Enterprise license then, by
downloading this archive, you are agreeing to the `GitHub CodeQL Terms and
Conditions <https://securitylab.github.com/tools/codeql/license>`__.
.. pull-quote:: Important
There are several different versions of the CLI available to download, depending
on your use case:
- If you want to use the most up to date CodeQL tools and features, download the
version tagged ``latest``.
- If you want to create CodeQL databases to upload to LGTM Enterprise, download
the version that is compatible with the relevant LGTM Enterprise version
number. Compatibility information is included in the description for each
release on the `CodeQL CLI releases page
<https://github.com/github/codeql-cli-binaries/releases>`__ on GitHub. Using the
correct version of the CLI ensures that your CodeQL databases are
compatible with your version of LGTM Enterprise. For more information,
see `Preparing CodeQL databases to upload to LGTM
<https://help.semmle.com/lgtm-enterprise/admin/help/prepare-database-upload.html>`__
in the LGTM admin help.
If you use Linux, Windows, or macOS version 10.14 ("Mojave") or earlier, simply
`download the zip archive
<https://github.com/github/codeql-cli-binaries/releases>`__
for the version you require.
If you want the CLI for a specific platform, download the appropriate ``codeql-PLATFORM.zip`` file.
Alternatively, you can download ``codeql.zip``, which contains the CLI for all supported platforms.
.. container:: toggle
.. container:: name
**Information for macOS "Catalina" users**
.. pull-quote:: macOS "Catalina"
If you use macOS version 10.15 ("Catalina"), you need to ensure that your web
browser does not automatically extract zip files. If you use Safari,
complete the following steps before downloading the CodeQL CLI zip archive:
i. Open Safari.
ii. From the Safari menu, select **Preferences...**.
iii. Click the **General** Tab.
iv. Ensure the check-box labeled **Open "safe" files after downloading**.
is unchecked.
2. Create a new CodeQL directory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Create a new directory where you can place the CLI and any queries and libraries
you want to use. For example, ``$HOME/codeql-home``.
The CLI's built-in search operations automatically look in all of its sibling
directories for the files used in database creation and analysis. Keeping these
components in their own directory prevents the CLI searching unrelated sibling
directories while ensuring all files are available without specifying any
further options on the command line.
.. _local-copy-codeql-queries:
3. Obtain a local copy of the CodeQL queries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `CodeQL repository <https://github.com/github/codeql>`__ contains
the queries and libraries required for CodeQL analysis of C/C++, C#, Java,
JavaScript/TypeScript, and Python.
Clone a copy of this repository into ``codeql-home``.
By default, the root of the cloned repository will be called ``codeql``.
Rename this folder ``codeql-repo`` to avoid conflicting with the CodeQL
CLI that you will extract in step 4. If you use git on the command line, you can
clone and rename the repository in a single step by running
``git clone git@github.com:github/codeql.git codeql-repo`` in the ``codeql-home`` folder.
The CodeQL libraries and queries for Go analysis live in the `CodeQL for Go
repository <https://github.com/github/codeql-go/>`__. Clone a copy of this
repository into ``codeql-home``.
The cloned repositories should have a sibling relationship.
For example, if the root of the cloned CodeQL repository is
``$HOME/codeql-home/codeql-repo``, then the root of the cloned CodeQL for Go
repository should be ``$HOME/codeql-home/codeql-go``.
Within these repositories, the queries and libraries are organized into QL
packs. Along with the queries themselves, QL packs contain important metadata
that tells the CodeQL CLI how to process the query files. For more information,
see ":doc:`About QL packs <../codeql-cli-reference/about-ql-packs>`."
.. pull-quote:: Important
There are different versions of the CodeQL queries available for different
users. Check out the correct version for your use case:
- For the most up to date CodeQL queries, check out the ``main`` branch.
This branch represents the very latest version of CodeQL's analysis. Even
databases created using the most recent version of the CLI may have to be
upgraded before you can analyze them. For more information, see
":doc:`Upgrading CodeQL databases <upgrading-codeql-databases>`."
- For the queries used on `LGTM.com <https://lgtm.com>`__, check out the
``lgtm.com`` branch. You can run these queries on databases you've recently
downloaded from LGTM.com. Older databases may need to be upgraded before
you can analyze them. The queries on the ``lgtm.com`` branch are also more
likely to be compatible with the ``latest`` CLI, so you'll be less likely
to have to upgrade newly-created databases than if you use the ``main``
branch.
- For the queries used in a particular LGTM Enterprise release, check out the
branch tagged with the relevant release number. For example, the branch
tagged ``v1.23.0`` corresponds to LGTM Enterprise 1.23. You must use this
version if you want to upload data to LGTM Enterprise. For further
information, see `Preparing CodeQL databases to upload to LGTM
<https://help.semmle.com/lgtm-enterprise/admin/help/prepare-database-upload.html>`__
in the LGTM admin help.
4. Extract the zip archive
~~~~~~~~~~~~~~~~~~~~~~~~~~
For Linux, Windows, and macOS users (version 10.14 "Mojave", and earlier)
simply
extract the zip archive into the directory you created in step 2.
For example, if the path to your copy of the CodeQL repository is
``$HOME/codeql-home/codeql-repo``, then extract the CLI into
``$HOME/codeql-home/``.
.. container:: toggle
.. container:: name
**Information for macOS "Catalina" users**
.. pull-quote:: macOS "Catalina"
macOS "Catalina" users should run the following commands in the Terminal,
where ``${install_loc}`` is the path to the directory you created in step 2:
i. ``mv ~/Downloads/codeql*.zip ${install_loc}``
ii. ``cd ${install_loc}``
iii. ``xattr -c codeql*.zip``
iv. ``unzip codeql*.zip``
5. Launch ``codeql``
~~~~~~~~~~~~~~~~~~~~
Once extracted, you can run CodeQL processes by running the ``codeql``
executable in a couple of ways:
- By executing ``<extraction-root>/codeql/codeql``, where
``<extraction-root>`` is the folder where you extracted the CodeQL CLI
package.
- By adding ``<extraction-root>/codeql`` to your ``PATH``, so that you
can run the executable as just ``codeql``.
At this point, you can execute CodeQL commands. For a full list of the CodeQL
CLI commands, see the ":ref:`CodeQL CLI reference <codeql-cli-reference>`."
.. pull-quote:: Note
If you add ``codeql`` to your ``PATH``, it can be accessed by CodeQL
for Visual Studio Code to compile and run queries.
For more information about configuring VS Code to access the CodeQL CLI, see
":ref:`Setting up CodeQL in Visual Studio Code <setting-up-codeql-in-visual-studio-code>`."
6. Verify your CodeQL CLI setup
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
CodeQL CLI has subcommands you can execute to verify that you are correctly set
up to create and analyze databases:
- Run ``codeql resolve languages`` to show which languages are
available for database creation. This will list the languages supported by
default in your CodeQL CLI package.
- Run ``codeql resolve qlpacks`` to show which QL packs the CLI can find. This
will display the names of the QL packs included in the CodeQL repositories:
``codeql-cpp``, ``codeql-csharp``, ``codeql-go``,
``codeql-java``, ``codeql-javascript``, and ``codeql-python``. The CodeQL
repositories also contain 'upgrade' packs and 'legacy' packs. Upgrade packs
are used by the CLI when you want to upgrade a database so that it can be
analyzed with a newer version of the CodeQL toolchain than was used to create
it. Legacy packs ensure that custom queries and libraries created using older
products are compatible with your version of CodeQL.
.. _using-two-versions-of-the-codeql-cli:
Using two versions of the CodeQL CLI
------------------------------------
If you want to use the latest CodeQL features to execute queries or CodeQL tests,
but also want to prepare databases that are compatible with a specific version of
LGTM Enterprise, you may need to install two versions of the CLI. The
recommended directory setup depends on which versions you want to install:
- If both versions are 2.0.2 (or newer), you can unpack both CLI archives in the
same parent directory.
- If at least one of the versions is 2.0.1 (or older), the unpacked CLI archives cannot
be in the same parent directory, but they can share the same grandparent
directory. For example, if you unpack version 2.0.2 into
``$HOME/codeql-home/codeql-cli``, the older version should be
unpacked into ``$HOME/codeql-older-version/old-codeql-cli``. Here, the common
grandparent is the ``$HOME`` directory.

56
docs/codeql/codeql-cli/using-the-codeql-cli/index.rst Normal file
View File

@@ -0,0 +1,56 @@
.. _using-the-codeql-cli:
Using the CodeQL CLI
====================
.. include:: ../../reusables/codeql-cli-overview.rst
See the following links to learn how to get set up and run CodeQL commands:
- :doc:`About the CodeQL CLI <about-the-codeql-cli>`: Software
developers and security researchers can secure their code using the CodeQL CLI.
- :doc:`Getting started with the CodeQL CLI
<getting-started-with-the-codeql-cli>`: Set up the
CodeQL CLI so that you can run CodeQL processes from your command line.
- :doc:`Creating CodeQL databases
<creating-codeql-databases>`: Create relational
representations of source code that can be queried like any other database.
- :doc:`Analyzing CodeQL databases
<analyzing-databases-with-the-codeql-cli>`: Analyze your code using queries
written in a specially-designed, object-oriented query language.
- :doc:`Upgrading CodeQL databases
<upgrading-codeql-databases>`: Upgrade your databases so
that they can be analyzed using the most up to date CodeQL products.
- :doc:`Using custom queries with the CodeQL CLI
<using-custom-queries-with-the-codeql-cli>`: Use custom queries to extend your
analysis or highlight errors that are specific to a particular codebase.
- :doc:`Creating CodeQL query suites <creating-codeql-query-suites>`:
Define query suite definitions for groups of frequently used queries.
- :doc:`Testing custom queries <testing-custom-queries>`: Set up
regression testing of custom queries to ensure that they behave as expected in
your analysis.
- :doc:`Testing query help files <testing-query-help-files>`:
Test query help files by rendering them as markdown to ensure they are valid
before uploading them to the CodeQL repository or using them in code scanning.
.. toctree::
:titlesonly:
:hidden:
about-the-codeql-cli
getting-started-with-the-codeql-cli
creating-codeql-databases
analyzing-databases-with-the-codeql-cli
upgrading-codeql-databases
using-custom-queries-with-the-codeql-cli
creating-codeql-query-suites
testing-custom-queries
testing-query-help-files

282
docs/codeql/codeql-cli/using-the-codeql-cli/testing-custom-queries.rst Normal file
View File

@@ -0,0 +1,282 @@
.. _testing-custom-queries:
Testing custom queries
======================
CodeQL provides a simple test framework for automated regression testing
of queries. Test your queries to ensure that they behave as expected.
During a query test, CodeQL compares the results the user expects
the query to produce with those actually produced. If the expected and
actual results differ, the query test fails. To fix the test, you should iterate
on the query and the expected results until the actual results and the expected
results exactly match. This topic shows you how to create test files and execute
tests on them using the ``test run`` subcommand.
.. container:: toggle
.. container:: name
**Information for LGTM Enterprise 1.23 users**
CodeQL tests are a new feature in CodeQL CLI version 2.0.2.
If you are an LGTM Enterprise 1.23 user, you should still use CodeQL CLI
version 2.0.1 to prepare databases to upload to your instance of LGTM. You
can use version 2.0.2 (or newer) to test your custom queries, but databases
created with versions newer than 2.0.1 are not compatible with LGTM
Enterprise 1.23. For more information, see ":ref:`Getting started with the CodeQL CLI <using-two-versions-of-the-codeql-cli>`."
Setting up a test QL pack for custom queries
--------------------------------------------
All CodeQL tests must be stored in a special "test" QL pack.
That is, a directory for test files with a ``qlpack.yml``
file that defines:
.. code-block:: yaml
name: <name-of-test-pack>
version: 0.0.0
libraryPathDependencies: <codeql-libraries-and-queries-to-test>
extractor: <language-of-code-to-test>
The ``libraryPathDependencies`` value specifies the CodeQL queries to test.
The ``extractor`` defines which language the CLI will use
to create test databases from the code files stored in this QL pack.
For more information, see ":doc:`About QL packs <../codeql-cli-reference/about-ql-packs>`."
You may find it useful to look at the way query tests are organized in the
`CodeQL repository <https://github.com/github/codeql>`__.
Each language has a ``src`` directory, ``ql/<language>/ql/src``,
that contains libraries and queries for analyzing codebases.
Alongside the ``src`` directory,
there's a ``test`` directory with tests for these libraries and queries.
Each ``test`` directory is configured as a test QL pack with two subdirectories:
- ``query-tests`` a series of subdirectories with tests for queries stored in the ``src`` directory.
Each subdirectory contains test code and a QL reference file that specifies the query to test.
- ``library-tests`` a series of subdirectories with tests for QL library files.
Each subdirectory contains test code and queries that were written as unit tests for a library.
Setting up the test files for a query
-------------------------------------
For each query you want to test, you should create a sub-directory in the test QL pack.
Then add the following files to the subdirectory before you run the test command:
- A query reference file (``.qlref`` file) defining the location of the query to test.
The location is defined relative to the root of the QL pack that contains the
query. Usually, this is a QL pack specified by the
``libraryPathDependencies`` for the test pack.
For more information, see ":doc:`Query reference files <../codeql-cli-reference/query-reference-files>`."
You don't need to add a query reference file if the query you want to
test is stored in the test directory,
but it's generally good practice to store queries separately from tests.
The only exception is unit tests for QL libraries, which tend to be
stored in test packs, separate from queries that generate alerts or paths.
- The example code you want to run your query against. This
should consist of one or more files containing examples of the code the
query is designed to identify.
You can also define the results you expect to see when you run the query against
the example code, by creating a file with the extension ``.expected``.
Alternatively, you can leave the test command to create the ``.expected`` file
for you. (If you're using CodeQL CLI 2.0.2--2.0.6, you need to create an
``.expected`` file otherwise the command will fail to find your test query.
You can create an empty ``.expected`` file to workaround this limitation.)
For an example showing how to create and test a query, see the `example
<#example>`__ below.
.. pull-quote:: Important
Your ``.ql``, ``.qlref``, and ``.expected`` files must have consistent names.
If you want to directly specify the ``.ql`` file itself in the test command,
it must have the same base name as the corresponding ``.expected`` file. For
example, if the query is ``MyJavaQuery.ql``, the expected results file must
be ``MyJavaQuery.expected``.
If you want to specify a ``.qlref`` file in the command, it must have the same base
name as the corresponding ``.expected`` file, but the query itself
may have a different name.
The names of the example code files don't have to be consistent with the
other test files. All example code files found next to the ``.qlref`` (or ``.ql``)
file and in any subdirectories will be used to create a test database.
Therefore, for simplicity, we recommend you don't save test files in
directories that are ancestors of each other.
Running ``codeql test run``
---------------------------
CodeQL query tests are executed by running the following command::
codeql test run <test|dir>
The ``<test|dir>`` argument can be one or more of the following:
- Path to a ``.ql`` file.
- Path to a ``.qlref`` file that references a ``.ql`` file.
- Path to a directory that will be searched recursively for ``.ql`` and
``.qlref`` files.
You can also specify:
- .. include:: ../../reusables/threads-query-execution.rst
For full details of all the options you can use when testing queries,
see the `test run reference documentation <../codeql-cli-manual/test-run.html>`__.
Example
-------
The following example shows you how to set up a test for a query that searches
Java code for ``if`` statements that have empty ``then`` blocks. It includes
steps to add the custom query and corresponding test files to separate QL packs
outside your checkout of the CodeQL repository. This ensures when you update the
CodeQL libraries, or check out a different branch, you won't overwrite your
custom queries and tests.
Prepare a query and test files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
#. Develop the query. For example, the following simple query finds empty ``then``
blocks in Java code:
.. code-block:: ql
import java
from IfStmt ifstmt
where ifstmt.getThen() instanceof EmptyStmt
select ifstmt, "This if statement has an empty then."
#. Save the query to a file named ``EmptyThen.ql`` in a directory with your
other custom queries. For example,
``custom-queries/java/queries/EmptyThen.ql``.
#. If you haven't already added your custom queries to a QL pack,
create a QL pack now. For example, if your custom Java queries
are stored in ``custom-queries/java/queries``, add a ``qlpack.yml`` file with the
following contents to ``custom-queries/java/queries``:
.. code-block:: yaml
name: my-custom-queries
version: 0.0.0
libraryPathDependencies: codeql-java
For more information about QL packs, see ":doc:`About QL packs
<../codeql-cli-reference/about-ql-packs>`."
#. Create a QL pack for your Java tests by adding a ``qlpack.yml`` file
with the following contents to ``custom-queries/java/tests``,
updating ``libraryPathDependencies`` to match the name of your QL pack of custom queries:
.. include:: ../../reusables/test-qlpack.rst
#. Within the Java test pack, create a directory to contain the test files
associated with ``EmptyThen.ql``.
For example, ``custom-queries/java/tests/EmptyThen``.
#. In the new directory, create ``EmptyThen.qlref`` to define the location of ``EmptyThen.ql``.
The path to the query must be specified relative to the root of
the QL pack that contains the query. In this case, the query is in the
top level directory of the QL pack named ``my-custom-queries``,
which is declared as a dependency for ``my-query-tests``.
Therefore, ``EmptyThen.qlref`` should simply contain ``EmptyThen.ql``.
#. Create a code snippet to test. The following Java code contains an
empty ``if`` statement on the third line. Save it in
``custom-queries/java/tests/EmptyThen/Test.java``.
.. code-block:: java
class Test {
public void problem(String arg) {
if (arg.isEmpty())
;
{
System.out.println("Empty argument");
}
}
public void good(String arg) {
if (arg.isEmpty()) {
System.out.println("Empty argument");
}
}
}
Execute the test
^^^^^^^^^^^^^^^^
To execute the test, move into the ``custom-queries`` directory and run ``codeql
test run java/tests/EmptyThen``.
When the test runs it:
#. Finds one test in the ``EmptyThen`` directory.
#. Extracts a CodeQL database from the ``.java`` files stored in the ``EmptyThen`` directory.
#. Compiles the query referenced by the ``EmptyThen.qlref`` file.
If this step fails, it's because the CLI can't find your custom QL pack.
Re-run the command and specify the location of your custom QL pack, for example:
``codeql test run --search-path=java java/tests/EmptyThen``
For information about saving the search path as part of your configuration, see
":doc:`Specifying command options in a CodeQL configuration file <../codeql-cli-reference/specifying-command-options-in-a-codeql-configuration-file>`."
#. Executes the test by running the query and generating an ``EmptyThen.actual`` results file.
#. Checks for an ``EmptyThen.expected`` file to compare with the ``.actual`` results file.
#. Reports the results of the test --- in this case, a failure: ``0 tests passed; 1 tests failed:``.
The test failed because we haven't yet added a file with the expected results of the query.
View the query test output
^^^^^^^^^^^^^^^^^^^^^^^^^^
CodeQL generates the following files in the ``EmptyThen`` directory:
- ``EmptyThen.actual``, a file that contains the actual results generated by the
query.
- ``EmptyThen.testproj``, a test database that you can load into VS Code and use to debug failing tests.
When tests complete successfully, this database is deleted in a housekeeping step.
You can override this step by running ``test run`` with the ``--keep-databases`` option.
In this case, the failure was expected and is easy to fix.
If you open the ``EmptyThen.actual`` file, you can see the results of the test:
.. code-block:: none
| Test.java:3:5:3:22 | stmt | This if statement has an empty then. |
This file contains a table, with a column for the location of the result,
along with separate columns for each part of the ``select`` clause the query outputs.
Since the results are what we expected, we can update the file extension to define
this as the expected result for this test (``EmptyThen.expected``).
If you rerun the test now, the output will be similar but it will finish by reporting:
``All 1 tests passed.``.
If the results of the query change, for example, if you revise the ``select`` statement for the query,
the test will fail. For failed results, the CLI output includes a unified diff of the
``EmptyThen.expected`` and ``EmptyThen.actual`` files.
This information may be sufficient to debug trivial test failures.
For failures that are harder to debug, you can import ``EmptyThen.testproj``
into CodeQL for VS Code, execute ``EmptyThen.ql``, and view the results in the
``Test.java`` example code. For more information, see ":ref:`Analyzing your projects
<analyzing-your-projects>`" in the CodeQL for VS Code
help.
Further reading
---------------
- ":ref:`CodeQL queries
<codeql-queries>`"
- ":ref:`Testing CodeQL queries in Visual Studio Code <testing-codeql-queries-in-visual-studio-code>`"

81
docs/codeql/codeql-cli/using-the-codeql-cli/testing-query-help-files.rst Normal file
View File

@@ -0,0 +1,81 @@
.. _testing-query-help-files:
Testing query help files
========================
Test query help files by rendering them as markdown to ensure they are valid
before uploading them to the CodeQL repository or using them in code scanning.
Query help is documentation that accompanies a query to explain how the query works,
as well as providing information about the potential problem that the query identifies.
It is good practice to write query help for all new queries. For more information,
see `Contributing to CodeQL <https://github.com/github/codeql/blob/main/CONTRIBUTING.md>`__
in the CodeQL repository.
The CodeQL CLI includes a command to test query help and render the content as
markdown, so that you can easily preview the content in your IDE. Use the command to validate
query help files before uploading them to the CodeQL repository or sharing them with other users.
Prerequisites
-------------
- The query help (``.qhelp``) file must have an accompanying query (``.ql``) file with
an identical base name.
- The query help file should follow the standard structure and style for query help documentation.
For more information, see the `Query help style guide <https://github.com/github/codeql/blob/main/docs/query-help-style-guide.md>`__
in the CodeQL repository.
Running ``codeql generate query-help``
--------------------------------------
You can test query help files by running the following command::
codeql generate query-help <qhelp|query|dir|suite> --format=<format> [--output=<dir|file>]
where ``<qhelp|query|dir|suite>`` is one of:
- the path to a ``.qhelp`` file.
- the path to a ``.ql`` file.
- the path to a directory containing queries and query help files.
- the path to a query suite, or the name of a well-known query suite for a QL pack.
For more information, see "`Creating CodeQL query suites <creating-codeql-query-suites.html#specifying-well-known-query-suites>`__."
You must specify a ``--format`` option, which defines how the query help is rendered.
Currently, you must specify ``markdown`` to render the query help as markdown.
The ``--output`` option defines a file path where the rendered query help will be saved.
- For directories containing ``.qhelp`` files or a query suites
defining one or more ``.qhelp`` files, you must specify an ``--output`` directory.
Filenames within the output directory will be derived from the ``.qhelp`` file names.
- For single ``.qhelp`` or ``.ql`` files, you may specify an ``--output`` option.
If you don't specify an output path, the rendered query help is written to ``stdout``.
For full details of all the options you can use when testing query help files,
see the `generate query-help reference documentation
<codeql-cli-manual:generate-query-help>`__.
Results
-------
When you run the command, CodeQL attempts to render
each ``.qhelp`` file that has an accompanying ``.ql`` file. For single files, the rendered
content will be printed to ``stdout`` if you don't specify an ``--output`` option. For all other
use cases, the rendered content is saved to the specified output path.
By default, the CodeQL CLI will print a warning message if:
- Any of the query help is invalid, along with a description of the invalid query help elements
- Any ``.qhelp`` files specified in the command don't have the same base name
as an accompanying ``.ql`` file
- Any ``.ql`` files specified in the command don't have the same base name
as an accompanying ``.qhelp`` file
You can tell the CodeQL CLI how to handle these warnings by including a ``--warnings`` option in your command.
For more information, see the `generate query-help reference documentation <../codeql-cli-manual/generate-query-help.html#cmdoption-codeql-generate-query-help-warnings>`__.
Further reading
---------------
- ":ref:`Query help files <query-help-files>`"

54
docs/codeql/codeql-cli/using-the-codeql-cli/upgrading-codeql-databases.rst Normal file
View File

@@ -0,0 +1,54 @@
.. _upgrading-codeql-databases:
Upgrading CodeQL databases
==========================
As the CodeQL CLI tools and queries evolve, you may find that some of your
CodeQL databases become out of date. You must upgrade out-of-date databases
before you can analyze them.
Databases become out of date when:
- For databases created using the CodeQL CLI, the version of CLI tools used to
create them is older than your copy of the CodeQL queries.
- For databases downloaded from LGTM.com, the CodeQL tools used by LGTM.com to create
that revision of the code are older than your copy of the CodeQL queries.
The ``main`` branch of the CodeQL queries is updated more often than both the
CLI and LGTM.com, so databases are most likely to become out of date if you use
the queries on this branch. For more information about the different versions of
the CodeQL queries, see ":ref:`Getting started with the CodeQL CLI <local-copy-codeql-queries>`."
Out-of-date databases must be upgraded before they can be analyzed. This topic
shows you how to upgrade a CodeQL database using the ``database upgrade``
subcommand.
Prerequisites
-------------
Archived databases downloaded from LGTM.com must be unzipped before they are
upgraded.
Running ``codeql database upgrade``
-----------------------------------
CodeQL databases are upgraded by running the following command::
codeql database upgrade <database>
where ``<database>``, the path to the CodeQL database you
want to upgrade, must be specified.
For full details of all the options you can use when upgrading databases,
see the `database upgrade reference documentation <../codeql-cli-manual/database-upgrade.html>`.
Progress and results
--------------------
When you execute the ``database upgrade`` command, CodeQL identifies the version
of the :ref:`schema <codeql-database-schema>` associated with the database. From
there, it works out what (if anything) is required to make the database work
with your queries and libraries. It will rewrite the database, if necessary, or
make no changes if the database is already compatible (or if it finds no
information about how to perform an upgrade). Once a database has been upgraded
it cannot be downgraded for use with older versions of the CodeQL products.

77
docs/codeql/codeql-cli/using-the-codeql-cli/using-custom-queries-with-the-codeql-cli.rst Normal file
View File

@@ -0,0 +1,77 @@
.. _using-custom-queries-with-the-codeql-cli:
Using custom queries with the CodeQL CLI
=========================================
You can customize your CodeQL analyses by writing your own queries to highlight
specific vulnerabilities or errors.
This topic is specifically about writing
queries to use with the `database analyze <../codeql-cli-manual/database-analyze.html>`__
command to produce :ref:`interpreted results <interpret-query-results>`.
.. include:: ../../reusables/advanced-query-execution.rst
Writing a valid query
---------------------
Before running a custom analysis you need to write a valid query, and save it in
a file with a ``.ql`` extension. There is extensive documentation available to
help you write queries. For more information, see ":ref:`CodeQL queries
<codeql-queries>`."
.. _including-query-metadata:
Including query metadata
------------------------
Query metadata is included at the top of each query file. It provides users with information about
the query, and tells the CodeQL CLI how to process the query results.
When running queries with the ``database analyze`` command, you must include the
following two properties to ensure that the results are interpreted correctly:
- Query identifier (``@id``): a sequence of words composed of lowercase letters or
digits, delimited by ``/`` or ``-``, identifying and classifying the query.
- Query type (``@kind``): identifies the query is an alert (``@kind problem``)
or a path (``@kind path-problem``).
For more information about these metadata properties, see ":ref:`Metadata for CodeQL queries
<metadata-for-codeql-queries>`" and the `Query metadata style guide
<https://github.com/github/codeql/blob/main/docs/query-metadata-style-guide.md>`__.
.. pull-quote:: Note
Metadata requirements may differ if you want to use your query with other
applications. For more information, see ":ref:`Metadata for CodeQL queries
<metadata-for-codeql-queries>`
."
Creating a custom QL pack
-------------------------
When writing your own queries, you should save them in a custom QL pack
directory. QL packs provide a way of organizing
the files used in CodeQL analysis. This directory must contain a file
named ``qlpack.yml`` at the root. Your custom queries should be saved in the QL
pack root, or its subdirectories.
For each QL pack, the ``qlpack.yml`` file includes information that tells CodeQL
how to compile the queries, what 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 QL packs <custom-ql-packs>`."
Contributing to the CodeQL repository
-------------------------------------
If you would like to share your query with other CodeQL users, you can open a
pull request in the `CodeQL repository <https://github.com/github/codeql>`__. For
further information, see `Contributing to CodeQL
<https://github.com/github/codeql/blob/main/CONTRIBUTING.md>`__.
Further reading
---------------
- ":ref:`CodeQL queries
<codeql-queries>`"