hohn/codeql
1
0
Fork 0
mirror of https://github.com/github/codeql.git synced 2026-01-28 05:42:58 +01:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Update analyzing databases docs

Browse Source 
Add more information about running packs. Include the `--download` flag.
This commit is contained in:
Andrew Eisenberg
2022-01-17 10:20:58 -08:00
parent 7fcf567eda
commit 0cd6556964
1 changed files with 31 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -26,6 +26,7 @@ Running ``codeql database analyze``
When you run ``database analyze``, it:
#. Optionally downloads any referenced CodeQL packages that are not available locally.
#. 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.
@@ -50,10 +51,13 @@ You must specify:
You can also specify:
- ``<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. If omitted, the default query suite for the language
- ``...<query-specifications>``: a list of queries to run over your database. This
is a list of arguments. Where each argument can be:
- a path to a query file
- a path to a directory containing query files
- a path to a query suite file
- the name of a CodeQL query pack
If omitted, the default query suite for the language
of the database being analyzed will be usedFor more information, see the
:ref:`examples <database-analyze-examples>` below.
@@ -63,11 +67,14 @@ You can also specify:
language to the GitHub code scanning API. For more information about this use case,
see `Configuring CodeQL CLI in your CI system <https://docs.github.com/en/code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system>`__ in the GitHub documentation.
- ``--sarif-add-query-help``: (supported in version 2.7.1 onwards) adds any custom query help written
in markdown to SARIF files (v2.1.0 or later) generated by the analysis. Query help stored in ``.qhelp`` files must be
converted to ``.md`` before running the analysis. For further information,
- ``--sarif-add-query-help``: (supported in version 2.7.1 onwards) adds any custom query help written
in markdown to SARIF files (v2.1.0 or later) generated by the analysis. Query help stored in ``.qhelp`` files must be
converted to ``.md`` before running the analysis. For further information,
see ":ref:`Including query help for custom CodeQL queries in SARIF files <including-query-help-for-custom-codeql-queries-in-sarif-files>`."
- ``--download``: a boolean flag that will allow the CLI to download any referenced CodeQL packages that are not available locally.
If this flag is missing and a referenced CodeQL package is not available locally, the command will fail.
- .. include:: ../reusables/threads-query-execution.rst
@@ -119,17 +126,16 @@ Running a CodeQL pack
.. include:: ../reusables/beta-note-package-management.rst
To run an existing CodeQL query pack from the GitHub Container registry, you need to download it first::
To run an existing CodeQL query pack from the GitHub Container registry, you can specify one or more
pack names and use the ``--download`` flag::
codeql pack download microsoft/coding-standards@1.0.0
codeql database analyze --download <database> microsoft/coding-standards@1.0.0 github/secutiry-queries --format=sarifv2.1.0 --output=query-results.sarif
Afterwards, you can run the pack on a specific database::
codeql database analyze <database> microsoft/coding-standards@1.0.0 <scope>/<other-pack> --format=sarifv2.1.0 --output=query-results.sarif
The ``analyze`` command above runs the default suite from ``microsoft/coding-standards v1.0.0`` and the latest version of ``scope/other-pack`` on the specified database.
The ``analyze`` command above runs the default suite from ``microsoft/coding-standards v1.0.0`` and the latest version of ``github/secutiry-queries`` on the specified database.
For further information about default suites, see ":ref:`Publishing and using CodeQL packs <publishing-and-using-codeql-packs>`".
For more information about CodeQL packs, see :doc:`About CodeQL Packs <about-codeql-packs>`.
Running query suites
~~~~~~~~~~~~~~~~~~~~
@@ -176,7 +182,7 @@ Integrating a CodeQL pack into a code scanning workflow in GitHub
.. include:: ../reusables/beta-note-package-management.rst
You can use CodeQL query packs in your Code Scanning setup. This allows you to select query packs published by various sources and use them to analyze your code.
You can use CodeQL query packs in your Code Scanning setup. This allows you to select query packs published by various sources and use them to analyze your code.
For more information, see "`Using CodeQL query packs in the CodeQL action <https://docs.github.com/en/code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-codeql-query-packs/>`_" or "`Downloading and using CodeQL query packs in your CI system <https://docs.github.com/en/code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system#downloading-and-using-codeql-query-packs>`_."
@@ -206,28 +212,28 @@ A SARIF results file is generated. Specifying ``--format=sarif-latest`` ensures
that the results are formatted according to the most recent SARIF specification
supported by CodeQL.
.. _including-query-help-for-custom-codeql-queries-in-sarif-files:
.. _including-query-help-for-custom-codeql-queries-in-sarif-files:
Including query help for custom CodeQL queries in SARIF files
Including query help for custom CodeQL queries in SARIF files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you use the CodeQL CLI to to run code scanning analyses on third party CI/CD systems,
you can include the query help for your custom queries in SARIF files generated during an analysis.
After uploading the SARIF file to GitHub, the query help is shown in the code scanning UI for any
alerts generated by the custom queries.
After uploading the SARIF file to GitHub, the query help is shown in the code scanning UI for any
alerts generated by the custom queries.
From CodeQL CLI 2.7.1 onwards, you can include markdown-rendered query help in SARIF files
From CodeQL CLI 2.7.1 onwards, you can include markdown-rendered query help in SARIF files
by providing the ``--sarif-add-query-help`` option when running
``codeql database analyze``.
``codeql database analyze``.
For more information, see `Configuring CodeQL CLI in your CI system <https://docs.github.com/en/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system#analyzing-a-codeql-database>`__
in the GitHub documentation.
You can write query help for custom queries directly in a markdown file and save it alongside the
corresponding query. Alternatively, for consistency with the standard CodeQL queries,
you can write query help in the ``.qhelp`` format. Query help written in ``.qhelp``
corresponding query. Alternatively, for consistency with the standard CodeQL queries,
you can write query help in the ``.qhelp`` format. Query help written in ``.qhelp``
files can't be included in SARIF files, and they can't be processed by code
scanning so must be converted to markdown before running
the analysis. For more information, see ":ref:`Query help files <query-help-files>`"
scanning so must be converted to markdown before running
the analysis. For more information, see ":ref:`Query help files <query-help-files>`"
and ":doc:`Testing query help files <testing-query-help-files>`."
Results