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

Merge pull request #7056 from jf205/sarif-query-help

Browse Source 
Add new option to database analyze tutorial
This commit is contained in:
James Fletcher
2021-11-09 10:19:29 +00:00
committed by GitHub
parent 954fd8d6f7 96ff2f5125
commit 1bacce487e
4 changed files with 41 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -63,6 +63,11 @@ 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,
see ":ref:`Including query help for custom CodeQL queries in SARIF files <including-query-help-for-custom-codeql-queries-in-sarif-files>`."
- .. include:: ../reusables/threads-query-execution.rst
@@ -201,6 +206,29 @@ 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
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``.
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``
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>`"
and ":doc:`Testing query help files <testing-query-help-files>`."
Results
-------

4
docs/codeql/codeql-cli/testing-query-help-files.rst
View File

@@ -15,6 +15,10 @@ 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.
From CodeQL CLI 2.7.1 onwards, you can also include the markdown-rendered query help in SARIF files
generated during CodeQL analyses so that the query help can be displayed in the code scanning UI.
For more information, see
":ref:`Analyzing databases with the CodeQL CLI <including-query-help-for-custom-codeql-queries-in-sarif-files>`."
Prerequisites
-------------