mirror of
https://github.com/github/codeql.git
synced 2026-04-28 02:05:14 +02:00
Add article on running queries
This commit is contained in:
Felicity Chapman
@@ -5,17 +5,16 @@
|
||||
CodeQL tools
|
||||
============
|
||||
|
||||
GitHub provides the CodeQL command-line interface and CodeQL for Visual Studio
|
||||
Code for performing CodeQL analysis on open source codebases.
|
||||
GitHub provides the CodeQL command-line interface and CodeQL for Visual Studio Code for performing CodeQL analysis on open source codebases. For information on the use cases for each tool, see ":ref:`Running CodeQL queries <running-codeql-queries>`."
|
||||
|
||||
CodeQL command-line interface
|
||||
-----------------------------
|
||||
|
||||
The CodeQL command-line interface (CLI) is primarily used to create databases for
|
||||
security research. You can also query CodeQL databases directly from the command line
|
||||
The CodeQL command-line interface (CLI) is primarily used to create databases for
|
||||
security research. You can also query CodeQL databases directly from the command line
|
||||
or using the Visual Studio Code extension.
|
||||
The CodeQL CLI can be downloaded from `GitHub releases <https://github.com/github/codeql-cli-binaries/releases>`__.
|
||||
For more information, see "`CodeQL CLI <https://docs.github.com/en/code-security/codeql-cli>`__" and the `CLI changelog <https://github.com/github/codeql-cli-binaries/blob/main/CHANGELOG.md>`__.
|
||||
The CodeQL CLI can be downloaded from "`GitHub releases <https://github.com/github/codeql-cli-binaries/releases>`__."
|
||||
For more information, see "`CodeQL CLI <https://docs.github.com/en/code-security/codeql-cli>`__" and the ":ref:`Change log <codeql-changes>`."
|
||||
|
||||
CodeQL packs
|
||||
-----------------------------
|
||||
@@ -38,15 +37,15 @@ maintained by GitHub are:
|
||||
- ``codeql/python-all`` (`changelog <https://github.com/github/codeql/tree/codeql-cli/latest/python/ql/lib/CHANGELOG.md>`__, `source <https://github.com/github/codeql/tree/codeql-cli/latest/python/ql/lib>`__)
|
||||
- ``codeql/ruby-queries`` (`changelog <https://github.com/github/codeql/tree/codeql-cli/latest/ruby/ql/src/CHANGELOG.md>`__, `source <https://github.com/github/codeql/tree/codeql-cli/latest/ruby/ql/src>`__)
|
||||
- ``codeql/ruby-all`` (`changelog <https://github.com/github/codeql/tree/codeql-cli/latest/ruby/ql/lib/CHANGELOG.md>`__, `source <https://github.com/github/codeql/tree/codeql-cli/latest/ruby/ql/lib>`__)
|
||||
- ``codeql/swift-queries`` (`changelog <https://github.com/github/codeql/tree/codeql-cli/latest/swift/ql/src/CHANGELOG.md>`__, `source <https://github.com/github/codeql/tree/codeql-cli/latest/swift/ql/src>`__)
|
||||
- ``codeql/swift-all`` (`changelog <https://github.com/github/codeql/tree/codeql-cli/latest/swift/ql/lib/CHANGELOG.md>`__, `source <https://github.com/github/codeql/tree/codeql-cli/latest/swift/ql/lib>`__)
|
||||
|
||||
For more information, see "`About CodeQL packs <https://docs.github.com/en/code-security/codeql-cli/codeql-cli-reference/about-codeql-packs>`__."
|
||||
|
||||
CodeQL bundle
|
||||
-----------------------------
|
||||
|
||||
The CodeQL bundle consists of the CodeQL CLI together with the standard CodeQL query and library packs
|
||||
maintained by GitHub. The bundle can be downloaded from `GitHub releases <https://github.com/github/codeql-action/releases>`__.
|
||||
Use this when running `code scanning with CodeQL <https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql>`__ on GitHub Actions or in another CI system.
|
||||
The CodeQL bundle consists of the CodeQL CLI together with the standard CodeQL query and library packs maintained by GitHub. The bundle is used by the CodeQL action in GitHub to generate code scanning results. If you use an external CI system, you can download the bundle from `GitHub releases <https://github.com/github/codeql-action/releases>`__, generate code scanning results, and upload them to GitHub.
|
||||
|
||||
CodeQL for Visual Studio Code
|
||||
-----------------------------
|
||||
@@ -54,4 +53,4 @@ CodeQL for Visual Studio Code
|
||||
You can analyze CodeQL databases in Visual Studio Code using the CodeQL
|
||||
extension, which provides an enhanced environment for writing and running custom
|
||||
queries and viewing the results. For more information, see "`CodeQL
|
||||
for Visual Studio Code <https://docs.github.com/en/code-security/codeql-for-vs-code/>`__."
|
||||
for Visual Studio Code <https://docs.github.com/en/code-security/codeql-for-vs-code/>`__."
|
||||
|
||||
@@ -9,8 +9,11 @@ Get to know more about queries and learn some key query-writing skills by solvin
|
||||
|
||||
- :ref:`QL tutorials <ql-tutorials>`: Solve puzzles to learn the basics of QL before you analyze code with CodeQL. The tutorials teach you how to write queries and introduce you to key logic concepts along the way.
|
||||
|
||||
- :ref:`Running CodeQL queries <running-codeql-queries>`: Guide to running queries as you try out the tutorials and start to develop your own queries.
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
codeql-queries
|
||||
ql-tutorials
|
||||
running-codeql-queries
|
||||
|
||||
@@ -0,0 +1,34 @@
|
||||
:tocdepth: 1
|
||||
|
||||
.. _running-codeql-queries:
|
||||
|
||||
Running CodeQL queries
|
||||
======================
|
||||
|
||||
There are several options available for running one or more CodeQL queries on a codebase. The best option depends on what your aims are.
|
||||
|
||||
Work through a CodeQL tutorial
|
||||
------------------------------
|
||||
|
||||
If you're working through a CodeQL tutorial, the CodeQL extension for Visual Studio Code makes it easy to run the queries in the tutorial. Unless you want to run the query on a specific code base, it's easiest to run queries on one of the many CodeQL databases that are available on GitHub. To get started, see "`Installing CodeQL for Visual Studio Code <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/installing-codeql-for-vs-code>`__".
|
||||
|
||||
Develop a new CodeQL query
|
||||
--------------------------
|
||||
|
||||
If you're developing a new query, the CodeQL extension for Visual Studio Code makes it easy to run a query and compare the results with previous runs as you refine the query. The extension also provides autocomplete suggestions, syntax highlighting, and other features that make it easier to write and debug queries. To get started, see "`Installing CodeQL for Visual Studio Code <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/installing-codeql-for-vs-code>`__".
|
||||
|
||||
When you're ready to test the query on a wide range of codebases, you can choose from the pre-defined sets of CodeQL databases or define a custom group of codebases to run the query against. For more information, see "`Running CodeQL queries at scale with multi-repository variant analysis <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries-at-scale-with-multi-repository-variant-analysis>`__".
|
||||
|
||||
Run your query against a specific codebase
|
||||
-------------------------------------------
|
||||
|
||||
If the codebase that you want to run your query against doesn't have a CodeQL database, you can create one using the CodeQL CLI. For more information, see "`Setting up the CodeQL CLI <https://docs.github.com/en/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli>`__" and "`Preparing your code for CodeQL analysis <https://docs.github.com/en/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis>`__".
|
||||
|
||||
Once you have created a CodeQL database, you can make the database available to the CodeQL extension in Visual Studio Code, or run the query using the CodeQL CLI. For more information, see "`Analyzing your code with CodeQL queries <https://docs.github.com/en/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries>`__".
|
||||
|
||||
Run the standard CodeQL queries
|
||||
-------------------------------
|
||||
|
||||
The easiest way to run the standard CodeQL queries on a repository hosted on the GitHub platform is to enable code scanning with CodeQL (this requires GitHub Actions to be enabled). When you enable default setup, you can choose from a default set of security queries or an extended set of security queries. Any results are shown as code scanning alerts on the **Security** tab of the repository. For more information, see "`Configuring default setup for code scanning <https://docs.github.com/en/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning>`__".
|
||||
|
||||
If you want to run the standard CodeQL queries on a repository that is not hosted on the GitHub platform, or where GitHub Actions are disabled, you can use the CodeQL CLI. For more information, see "`About the CodeQL CLI <https://docs.github.com/en/code-security/codeql-cli/getting-started-with-the-codeql-cli/about-the-codeql-cli>`__".
|
||||
Reference in New Issue
Block a user