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

reorg sphinx docs

Browse Source
This commit is contained in:
james
2020-11-10 14:56:01 +00:00
parent 7c3ea0e264
commit 896d46469b
217 changed files with 10808 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -0,0 +1,230 @@
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 <ql-language-reference: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: .

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

@@ -0,0 +1,72 @@
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 :doc:`codeql test run <../commands/test-run>`, :doc:`codeql database check <../commands/dataset-check>`, :doc:`codeql query format <../commands/query-format>`,and :doc:`codeql resolve extractor <../commands/resolve-extractor>`.
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 :doc:`codeql database create <../commands/database-create>` or :doc:`codeql database finalize <../commands/database-finalize>`.
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.

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

@@ -0,0 +1,36 @@
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:
CLI commands
------------
The following links provide detailed information about each CodeQL CLI command,
including its usage and options. For information about the terms used in these
pages, see the ":doc:`CodeQL glossary <codeql-overview:codeql-glossary>`."
.. include:: ../commands-toc.rst

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

@@ -0,0 +1,45 @@
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>`__.

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

@@ -0,0 +1,290 @@
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 :doc:`database analyze reference <../commands/database-analyze>`.
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 | – |
+------------------------+-----------------------------+-----------+

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

@@ -0,0 +1,70 @@
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>