hohn/codeql
1
0
Fork 0
mirror of https://github.com/github/codeql.git synced 2026-04-25 08:45:14 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #17361 from github/12707-felicity-docs-landing

Browse Source 
Update the Docs landing page for the CodeQL docs site
This commit is contained in:
Felicity Chapman
2024-09-17 11:40:53 +01:00
committed by GitHub
parent 9a62561336 40fdd00e16
commit 0675ba0fa4
10 changed files with 198 additions and 142 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
docs/codeql/_templates/layout.html
View File

@@ -1,7 +1,7 @@
{#
Override alabaster/layout.html template to customize the template
used to generate the CodeQL documentation.
The classes used in this template are provided by the GitHub Primer https://primer.style/css/.
The CSS for the primer can be found at https://unpkg.com/@primer/css/dist/primer.css
@@ -59,37 +59,34 @@
CodeQL resources
<div class="dropdown-caret"></div>
</summary>
<ul class="dropdown-menu dropdown-menu-se dropdown-menu-dark">
<li><a class="dropdown-item" href="https://codeql.github.com/docs/codeql-overview">CodeQL overview</a></li>
<li class="dropdown-divider" role="separator"></li>
<div class="dropdown-header">
CodeQL tools
</div>
<li><a class="dropdown-item" href="https://codeql.github.com/docs/codeql-for-visual-studio-code">CodeQL for VS Code</a>
<li><a class="dropdown-item" href="https://codeql.github.com/docs/codeql-cli">CodeQL CLI</a>
</li>
<li><a class="dropdown-item" href="codeql-overview">CodeQL overview</a></li>
<li class="dropdown-divider" role="separator"></li>
<div class="dropdown-header">
CodeQL guides
</div>
<li><a class="dropdown-item" href="https://codeql.github.com/docs/writing-codeql-queries">Writing CodeQL queries</a></li>
<li><a class="dropdown-item" href="https://codeql.github.com/docs/codeql-language-guides">CodeQL language guides</a>
<li><a class="dropdown-item" href="writing-codeql-queries">Writing CodeQL queries</a></li>
<li><a class="dropdown-item" href="codeql-language-guides">CodeQL language guides</a>
<li class="dropdown-divider" role="separator"></li>
<div class="dropdown-header">
Reference docs
</div>
<li><a class="dropdown-item" href="https://codeql.github.com/docs/ql-language-reference/">QL language
<li><a class="dropdown-item" href="ql-language-reference/">QL language
reference</a>
<li><a class="dropdown-item" href="https://codeql.github.com/codeql-standard-libraries">CodeQL
<li><a class="dropdown-item" href="../codeql-standard-libraries">CodeQL
standard-libraries</a>
<li><a class="dropdown-item" href="https://codeql.github.com/codeql-query-help">CodeQL
<li><a class="dropdown-item" href="../codeql-query-help">CodeQL
query help</a>
<li class="dropdown-divider" role="separator"></li>
<div class="dropdown-header">
Source files
</div>
<li><a class="dropdown-item" href="https://github.com/github/codeql">CodeQL repository</a>
<li class="dropdown-divider" role="separator"></li>
<div class="dropdown-header">
Academic
</div>
<li><a class="dropdown-item" href="../publications">QL publications</a>
</ul>
</details>
@@ -165,12 +162,12 @@
</li>
</ul>
<ul class="list-style-none d-flex text-gray">
<li class="mr-3">&copy;
<li class="mr-3">&copy;
<script type="text/javascript">document.write(new Date().getFullYear());</script> GitHub, Inc.</li>
<li class="mr-3"><a
href="https://docs.github.com/github/site-policy/github-terms-of-service"
href="https://docs.github.com/site-policy/github-terms/github-terms-of-service"
class="link-gray">Terms </a></li>
<li><a href="https://docs.github.com/github/site-policy/github-privacy-statement"
<li><a href="https://docs.github.com/site-policy/privacy-policies/github-privacy-statement"
class="link-gray">Privacy </a></li>
</ul>
</div>

4
docs/codeql/codeql-language-guides/codeql-for-cpp.rst
View File

@@ -28,6 +28,10 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat
- :doc:`CodeQL library for C and C++ <codeql-library-for-cpp>`: When analyzing C or C++ code, you can use the large collection of classes in the CodeQL library for C and C++.
- `CodeQL CTF: U-Boot Challenge <https://securitylab.github.com/ctf/uboot/>`__: Follow the steps that members of GitHub Security Lab went through to find 13 CWE vulnerabilities in U-Boot.
- `CodeQL CTF: SEGV Hunt <https://securitylab.github.com/ctf/segv/>`__: Follow the steps that members of GitHub Security Lab went through to find unsafe uses of ``alloca`` in the GNU C Library (glibc).
- :doc:`Functions in C and C++ <functions-in-cpp>`: You can use CodeQL to explore functions in C and C++ code.
- :doc:`Expressions, types, and statements in C and C++ <expressions-types-and-statements-in-cpp>`: You can use CodeQL to explore expressions, types, and statements in C and C++ code to find, for example, incorrect assignments.

4
docs/codeql/codeql-language-guides/codeql-for-go.rst
View File

@@ -17,7 +17,9 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat
- :doc:`CodeQL library for Go <codeql-library-for-go>`: When you're analyzing a Go program, you can make use of the large collection of classes in the CodeQL library for Go.
- `CodeQL CTF: Go and don't return <https://securitylab.github.com/ctf/go-and-dont-return/>`__: Follow the steps that members of GitHub Security Lab went through to find a high severity vulnerability in MinIO, an Amazon S3-compatible object store.
- :doc:`Abstract syntax tree classes for working with Go programs <abstract-syntax-tree-classes-for-working-with-go-programs>`: CodeQL has a large selection of classes for representing the abstract syntax tree of Go programs.
- :doc:`Modeling data flow in Go libraries <modeling-data-flow-in-go-libraries>`: When analyzing a Go program, CodeQL does not examine the source code for external packages.
- :doc:`Modeling data flow in Go libraries <modeling-data-flow-in-go-libraries>`: When analyzing a Go program, CodeQL does not examine the source code for external packages.
To track the flow of untrusted data through a library, you can create a model of the library.

4
docs/codeql/codeql-language-guides/codeql-for-java.rst
View File

@@ -28,7 +28,9 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat
- :doc:`CodeQL library for Java and Kotlin <codeql-library-for-java>`: When analyzing Java/Kotlin code, you can use the large collection of classes in the CodeQL library for Java/Kotlin.
- :doc:`Analyzing data flow in Java and Kotlin <analyzing-data-flow-in-java>`: You can use CodeQL to track the flow of data through a Java/Kotlin program to its use.
- :doc:`Analyzing data flow in Java and Kotlin <analyzing-data-flow-in-java>`: You can use CodeQL to track the flow of data through a Java/Kotlin program to its use.
- `CodeQL CTF: CodeQL and Chill <https://securitylab.github.com/ctf/codeql-and-chill/>`__: Follow the steps that members of GitHub Security Lab went through to track the flow of tainted data from user-controlled bean properties to custom error messages, and identify the known injection vulnerabilities.
- :doc:`Java and Kotlin types <types-in-java>`: You can use CodeQL to find out information about data types used in Java/Kotlin code. This allows you to write queries to identify specific type-related issues.

2
docs/codeql/codeql-language-guides/codeql-for-javascript.rst
View File

@@ -25,6 +25,8 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat
- :doc:`CodeQL library for TypeScript <codeql-library-for-typescript>`: When you're analyzing a TypeScript program, you can make use of the large collection of classes in the CodeQL library for TypeScript.
- `CodeQL CTF: XSS-unsafe jQuery plugins <https://securitylab.github.com/ctf/jquery/>`__: Follow the steps that members of GitHub Security Lab went through to find cross-site scripting vulnerabilities in Bootstrap's jQuery plugins.
- :doc:`Analyzing data flow in JavaScript and TypeScript <analyzing-data-flow-in-javascript-and-typescript>`: This topic describes how data flow analysis is implemented in the CodeQL libraries for JavaScript/TypeScript and includes examples to help you write your own data flow queries.
- :doc:`Using flow labels for precise data flow analysis <using-flow-labels-for-precise-data-flow-analysis>`: You can associate flow labels with each value tracked by the flow analysis to determine whether the flow contains potential vulnerabilities.

51
docs/codeql/codeql-overview/about-codeql.rst
View File

@@ -2,18 +2,33 @@
.. _about-codeql:
.. meta::
:description: Introduction to CodeQL, a language and toolchain for code analysis.
:keywords: CodeQL, code analysis, CodeQL analysis, security vulnerabilities, variant analysis, resources, tutorials, interactive training, GitHub Security Lab, security researchers, CodeQL databases
About CodeQL
============
CodeQL is the analysis engine used by developers to automate security checks, and by
security researchers to perform variant analysis.
CodeQL is a language and toolchain for code analysis. It is designed to allow security researchers to scale their knowledge of a single vulnerability to identify variants of that vulnerability across a wide range of codebases. It is also designed to allow developers to automate security checks and integrate them into their development workflows.
In CodeQL, code is treated like data. Security vulnerabilities, bugs,
and other errors are modeled as queries that can be executed against databases
extracted from code. You can run the standard CodeQL queries, written by GitHub
researchers and community contributors, or write your own to use in custom
analyses. Queries that find potential bugs highlight the result directly in the
source file.
Resources for learning CodeQL
-----------------------------
- **CodeQL docs site:** contains information on the CodeQL language and libraries, with tutorials and guides to help you learn how to write your own queries.
- :doc:`CodeQL queries <../writing-codeql-queries/codeql-queries>`: A general, language-neutral overview of the key components of a query.
- :doc:`QL tutorials <../writing-codeql-queries/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.
- :doc:`CodeQL language guides <../codeql-language-guides/index>`: Guides to the CodeQL libraries for each language, including the classes and predicates that are available for use in queries, with worked examples.
- **GitHub Security Lab:** is GitHub's own security research team. They've created a range of resources to help you learn how to use CodeQL to find security vulnerabilities in real-world codebases.
- `Secure code game <https://github.com/skills/secure-code-game>`__: A series of interactive sessions that guide you from finding insecure code patterns manually, through to using CodeQL to find insecure code patterns automatically.
- `Security Lab CTF <https://securitylab.github.com/ctf/>`__: A series of Capture the Flag (CTF) challenges that are designed to help you learn how to use CodeQL to find security vulnerabilities in real-world codebases.
- `Security Lab blog <https://github.blog/tag/github-security-lab/>`__: A series of blog posts that describe how CodeQL is used by security researchers to find security vulnerabilities in real-world codebases.
About variant analysis
----------------------
@@ -30,6 +45,8 @@ queries. Then, develop or iterate over the query to automatically find logical
variants of the same bug that could be missed using traditional manual
techniques.
When you have a query that finds variants of a vulnerability, you can use multi-repository variant analysis to run that query across a large number of codebases, and identify all of the places where that vulnerability exists. 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>`__ in the GitHub docs.
CodeQL analysis
---------------
@@ -39,11 +56,13 @@ CodeQL analysis consists of three steps:
#. Running CodeQL queries against the database
#. Interpreting the query results
For information on the CodeQL toolchain and on running CodeQL to analyze a codebase, see the `CodeQL CLI <https://docs.github.com/en/code-security/codeql-cli>`__, `CodeQL for Visual Studio Code <https://docs.github.com/en/code-security/codeql-for-vs-code>`__, and `About code scanning with CodeQL <https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql>`__ in the GitHub docs.
Database creation
~~~~~~~~~~~~~~~~~
To create a database, CodeQL first extracts a single relational representation
of each source file in the codebase.
of each source file in the codebase.
For compiled languages, extraction works by monitoring the normal build process.
Each time a compiler is invoked to process a source file, a copy of that file is
@@ -52,7 +71,7 @@ syntactic data about the abstract syntax tree and semantic data about name
binding and type information.
For interpreted languages, the extractor runs directly on the source code,
resolving dependencies to give an accurate representation of the codebase.
resolving dependencies to give an accurate representation of the codebase.
There is one :ref:`extractor <extractor>` for each language supported by CodeQL
to ensure that the extraction process is as accurate as possible. For
@@ -72,7 +91,7 @@ against it. CodeQL queries are written in a specially-designed object-oriented
query language called QL. You can run the queries checked out from the CodeQL
repo (or custom queries that you've written yourself) using the `CodeQL
for VS Code extension <https://docs.github.com/en/code-security/codeql-for-vs-code/>`__ or the `CodeQL CLI
<https://docs.github.com/en/code-security/codeql-cli>`__. For more information about queries, see ":ref:`About CodeQL queries <about-codeql-queries>`."
<https://docs.github.com/en/code-security/codeql-cli>`__. For more information about queries, see ":ref:`About CodeQL queries <about-codeql-queries>`."
.. _interpret-query-results:
@@ -95,7 +114,7 @@ code.
Following interpretation, results are output for code review and triaging. In
CodeQL for Visual Studio Code, interpreted query results are automatically
displayed in the source code. Results generated by the CodeQL CLI can be output
into a number of different formats for use with different tools.
into a number of different formats for use with different tools.
About CodeQL databases
@@ -104,7 +123,7 @@ About CodeQL databases
CodeQL databases contain queryable data extracted from a codebase, for a single
language at a particular point in time. The database contains a full,
hierarchical representation of the code, including a representation of the
abstract syntax tree, the data flow graph, and the control flow graph.
abstract syntax tree, the data flow graph, and the control flow graph.
Each language has its own unique database schema that defines the relations used
to create a database. The schema provides an interface between the initial
@@ -114,13 +133,13 @@ every language construct.
For each language, the CodeQL libraries define classes to provide a layer of
abstraction over the database tables. This provides an object-oriented view of
the data which makes it easier to write queries.
the data which makes it easier to write queries.
For example, in a CodeQL database for a Java program, two key tables are:
- The ``expressions`` table containing a row for every single expression in the
source code that was analyzed during the build process.
- The ``statements`` table containing a row for every single statement in the
source code that was analyzed during the build process.
- The ``statements`` table containing a row for every single statement in the
source code that was analyzed during the build process.
The CodeQL library defines classes to provide a layer of abstraction over each

19
docs/codeql/codeql-overview/codeql-tools.rst
View File

@@ -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/>`__."

182
docs/codeql/index.html
View File

@@ -35,13 +35,6 @@
<ul class="dropdown-menu dropdown-menu-se dropdown-menu-dark">
<li><a class="dropdown-item" href="codeql-overview">CodeQL overview</a></li>
<li class="dropdown-divider" role="separator"></li>
<div class="dropdown-header">
CodeQL tools
</div>
<li><a class="dropdown-item" href="codeql-for-visual-studio-code">CodeQL for VS Code</a>
<li><a class="dropdown-item" href="https://docs.github.com/en/code-security/codeql-cli/getting-started-with-the-codeql-cli/about-the-codeql-cli">CodeQL CLI</a>
</li>
<li class="dropdown-divider" role="separator"></li>
<div class="dropdown-header">
CodeQL guides
</div>
@@ -62,6 +55,11 @@
Source files
</div>
<li><a class="dropdown-item" href="https://github.com/github/codeql">CodeQL repository</a>
<li class="dropdown-divider" role="separator"></li>
<div class="dropdown-header">
Academic
</div>
<li><a class="dropdown-item" href="../publications">QL publications</a>
</ul>
</details>
</div>
@@ -70,32 +68,30 @@
<div class="blankslate">
<img src="https://ghicons.github.com/assets/images/blue/svg/Code%20QL.svg" class="mb-3" />
<h1>CodeQL documentation</h1>
<p class="f2">Discover vulnerabilities across a codebase with CodeQL, our industry-leading semantic code
analysis
engine. CodeQL lets you query code as though it were data. Write a query to find all variants of a
<p class="f2">CodeQL enables you to query code as though it were data. Write a query to find all variants of a
vulnerability, eradicating it forever. Then share your query to help others do the same.</p>
</div>
<div class="d-flex flex-column flex-md-row flex-justify-center">
<div class="Box col-lg-5 col-sm-12 border-0">
<div class="Box-header border-0 bg-white">
<h3 class="Box-title text-mono f3 text-center">
BACKGROUND INFORMATION
</h3>
<h2 class="Box-title text-mono f2 text-center">
CODEQL RELEASE INFORMATION
</h2>
</div>
<div class="Box-body border-bottom-0">
<div class="Subhead border-0">
<a href="codeql-overview/about-codeql">
<div class="Subhead-heading f4 text-center">About CodeQL</div>
</a>
<div class="Subhead-description">Learn more about how CodeQL works...</div>
</div>
<div class="Subhead border-0">
<a href="codeql-overview/supported-languages-and-frameworks/">
<div class="Subhead-heading f4 text-center">Supported languages and frameworks</div>
</a>
<div class="Subhead-description">View the languages, libraries, and frameworks supported in the
latest version of CodeQL...</div>
latest release of CodeQL...</div>
</div>
<div class="Subhead border-0">
<a href="codeql-overview/about-codeql">
<div class="Subhead-heading f4 text-center">Change logs</div>
</a>
<div class="Subhead-description">Read about the improvements to the queries, libraries, and tooling in each release...</div>
</div>
<div class="Subhead border-0">
<a href="codeql-overview/system-requirements/">
@@ -105,90 +101,83 @@
latest version of CodeQL...</div>
</div>
<div class="Subhead border-0">
<a href="../publications">
<div class="Subhead-heading f4 text-center">Academic publications</div>
<a href="codeql-overview/supported-languages-and-frameworks/">
<div class="Subhead-heading f4 text-center">CodeQL cverage of CWEs</div>
</a>
<div class="Subhead-description">Read academic articles published by the team behind CodeQL...
</div>
<div class="Subhead-description">Detailed information on the coverage of Common Weakness Enumerations (CWEs) in the latest release...</div>
</div>
</div>
</div>
<div class="Box col-lg-5 col-sm-12 border-0">
<div class="Box-header border-0 bg-white">
<h3 class="Box-title text-mono f3 text-center">
CODEQL TOOLS
</h3>
<h2 class="Box-title text-mono f2 text-center">
LEARN TO WRITE CODEQL
</h2>
</div>
<div class="Box-body border-bottom-0">
<div class="Subhead border-0">
<a href="https://docs.github.com/en/code-security/codeql-cli/getting-started-with-the-codeql-cli/about-the-codeql-cli">
<div class="Subhead-heading f4 text-center">CodeQL CLI</div>
</a>
<div class="Subhead-description border-bottom-0">The CodeQL command-line interface (CLI) is used
to create
databases for security research....</div>
</div>
<div class="Subhead border-0">
<a href="codeql-for-visual-studio-code">
<div class="Subhead-heading f4 text-center">CodeQL for Visual Studio Code</div>
</a>
<div class="Subhead-description">CodeQL for Visual Studio Code adds rich language
support for CodeQL...</div>
</div>
<div class="Subhead border-0">
<a
href="https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning">
<div class="Subhead-heading f4 text-center">Code scanning with CodeQL</div>
</a>
<div class="Subhead-description">Use code scanning with CodeQL to analyze the code in a GitHub
repository to find
security
vulnerabilities...</div>
</div>
<div class="Subhead border-0">
<a href="codeql-overview/about-codeql">
<div class="Subhead-heading f4 text-center">About CodeQL</div>
</a>
<div class="Subhead-description">Learn what CodeQL is and how it works...</div>
</div>
<div class="Subhead border-0">
<a href="writing-codeql-queries">
<div class="Subhead-heading f4 text-center">Writing CodeQL queries</div>
</a>
<div class="Subhead-description">Get to know more about queries and learn some key
query-writing skills by solving puzzles...</div>
</div>
<div class="Subhead border-0">
<a href="codeql-language-guides">
<div class="Subhead-heading f4 text-center">CodeQL language guides</div>
</a>
<div class="Subhead-description">Experiment and learn how to write effective and efficient
queries for CodeQL databases generated from the languages supported in CodeQL
analysis...</div>
</div>
<div class="Subhead border-0">
<a href="writing-codeql-queries/running-codeql-queries">
<div class="Subhead-heading f4 text-center">Running CodeQL queries</div>
</a>
<div class="Subhead-description">Learn about the options available for running CodeQL queries on one or multiple codebases...</div>
</div>
</div>
</div>
</div>
<div class="d-flex flex-column flex-md-row flex-justify-center">
<div class="Box col-lg-5 col-sm-12 border-0">
<div class="Box-header border-0 bg-white">
<h3 class="Box-title text-mono f3 text-center">
CODEQL GUIDES
</h3>
<h2 class="Box-title text-mono f2 text-center">
CODEQL RESOURCES
</h2>
</div>
<div class="Box-body border-bottom-0">
<div class="Subhead border-0">
<a href="writing-codeql-queries">
<div class="Subhead-heading f4 text-center">Writing CodeQL queries</div>
</a>
<div class="Subhead-description">Get to know more about queries and learn some key
query-writing skills by solving puzzles.....</div>
</div>
<div class="Subhead border-0">
<a href="codeql-language-guides">
<div class="Subhead-heading f4 text-center">CodeQL language guides</div>
</a>
<div class="Subhead-description">Experiment and learn how to write effective and efficient
queries for CodeQL databases generated from the languages supported in CodeQL
analysis...</div>
<div class="Subhead border-0">
<a href="https://github.com/github/codeql-cli-binaries/releases">
<div class="Subhead-heading f4 text-center">CodeQL CLI releases</div>
</a>
<div class="Subhead-description">Download the latest version of the CodeQL CLI...</div>
</div>
<div class="Subhead border-0">
<a href="https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-codeql">
<div class="Subhead-heading f4 text-center">CodeQL extension for Visual Studio Code</div>
</a>
<div class="Subhead-description">Download the extension from the Visual Studio Code Marketplace...</div>
</div>
<div class="Subhead border-0">
<a href="https://github.com/github/codeql">
<div class="Subhead-heading f4 text-center">CodeQL repository</div>
</a>
<div class="Subhead-description">Contribute to the source code of the libraries and queries for CodeQL...
</div>
</div>
</div>
<div class="Box col-lg-5 col-sm-12 border-0">
<div class="Box-header border-0 bg-white">
<h3 class="Box-title text-mono f3 text-center">
<h2 class="Box-title text-mono f2 text-center">
CODEQL REFERENCE DOCS
</h3>
</h2>
</div>
<div class="Box-body border-bottom-0">
<div class="Subhead border-0">
@@ -213,10 +202,8 @@
<div class="Subhead-description">View the query help for the queries included in the code
scanning query suites...</div>
</div>
</div>
</div>
</div>
</article>
<div class="footer mt-6 bg-gray-light border-y border-gray-dark no-print">
@@ -234,7 +221,7 @@
</a>
</div>
<div class="col-6 col-sm-3 col-lg-2 mb-6 mb-md-2 pr-3 pr-lg-0 pl-lg-4">
<h4 class="mb-3 text-mono text-gray-light text-normal">Product</h4>
<h3 class="mb-3 text-mono text-gray-light text-normal">Product</h3>
<ul class="list-style-none text-gray f5">
<li class="lh-condensed mb-3"><a href="https://github.com/features"
data-ga-click="Footer, go to features, text:features" class="link-gray">Features</a>
@@ -242,6 +229,9 @@
<li class="lh-condensed mb-3"><a href="https://github.com/security"
data-ga-click="Footer, go to security, text:security" class="link-gray">Security</a>
</li>
<li class="lh-condensed mb-3"><a href="https://github.com/features/copilot"
data-ga-click="Footer, go to copilot, text:copilot"
class="link-gray">Copilot</a></li>
<li class="lh-condensed mb-3"><a href="https://github.com/enterprise"
data-ga-click="Footer, go to enterprise, text:enterprise"
class="link-gray">Enterprise</a></li>
@@ -256,16 +246,16 @@
</ul>
</div>
<div class="col-6 col-sm-3 col-lg-2 mb-6 mb-md-2 pr-3 pr-md-0 pl-md-4">
<h4 class="mb-3 text-mono text-gray-light text-normal">Platform</h4>
<h3 class="mb-3 text-mono text-gray-light text-normal">Platform</h3>
<ul class="list-style-none f5">
<li class="lh-condensed mb-3"><a href="https://developer.github.com/"
<li class="lh-condensed mb-3"><a href="https://docs.github.com/get-started/exploring-integrations/about-building-integrations"
data-ga-click="Footer, go to api, text:api" class="link-gray">Developer API</a></li>
<li class="lh-condensed mb-3"><a href="http://partner.github.com/"
data-ga-click="Footer, go to partner, text:partner" class="link-gray">Partners</a></li>
<li class="lh-condensed mb-3"><a href="https://atom.io"
data-ga-click="Footer, go to atom, text:atom" class="link-gray">Atom</a></li>
<li class="lh-condensed mb-3"><a href="http://electron.atom.io/"
data-ga-click="Footer, go to electron, text:electron" class="link-gray">Electron</a>
<li class="lh-condensed mb-3"><a href="https://github.com/edu"
data-ga-click="Footer, go to education, text:education" class="link-gray">Education</a></li>
<li class="lh-condensed mb-3"><a href="https://cli.github.com/"
data-ga-click="Footer, go to cli, text:cli" class="link-gray">GitHub CLI</a>
</li>
<li class="lh-condensed mb-3"><a href="https://desktop.github.com/"
data-ga-click="Footer, go to desktop, text:desktop" class="link-gray">GitHub Desktop</a>
@@ -273,9 +263,9 @@
</ul>
</div>
<div class="col-6 col-sm-3 col-lg-2 mb-6 mb-md-2 pr-3 pr-md-0 pl-md-4">
<h4 class="mb-3 text-mono text-gray-light text-normal">Support</h4>
<h3 class="mb-3 text-mono text-gray-light text-normal">Support</h3>
<ul class="list-style-none f5">
<li class="lh-condensed mb-3"><a href="/" class="link-gray">Help</a></li>
<li class="lh-condensed mb-3"><a href="https://docs.github.com" class="link-gray">GitHub Docs</a></li>
<li class="lh-condensed mb-3"><a href="https://github.community" class="link-gray">Community
Forum</a></li>
<li class="lh-condensed mb-3"><a href="https://services.github.com/"
@@ -287,12 +277,12 @@
</ul>
</div>
<div class="col-6 col-sm-3 col-lg-2 mb-6 mb-md-2 pr-3 pr-md-0 pl-md-4">
<h4 class="mb-3 text-mono text-gray-light text-normal">Company</h4>
<h3 class="mb-3 text-mono text-gray-light text-normal">Company</h3>
<ul class="list-style-none f5">
<li class="lh-condensed mb-3"><a href="https://github.com/about" class="link-gray">About</a>
</li>
<li class="lh-condensed mb-3"><a href="https://github.blog/" class="link-gray">Blog</a></li>
<li class="lh-condensed mb-3"><a href="https://github.com/about/careers"
<li class="lh-condensed mb-3"><a href="https://github.careers/"
class="link-gray">Careers</a></li>
<li class="lh-condensed mb-3"><a href="https://github.com/about/press"
class="link-gray">Press</a></li>
@@ -359,9 +349,9 @@
<li class="mr-3">&copy;
<script type="text/javascript">document.write(new Date().getFullYear());</script> GitHub, Inc.</li>
<li class="mr-3"><a
href="https://docs.github.com/github/site-policy/github-terms-of-service"
href="https://docs.github.com/site-policy/github-terms/github-terms-of-service"
class="link-gray">Terms </a></li>
<li><a href="https://docs.github.com/github/site-policy/github-privacy-statement"
<li><a href="https://docs.github.com/site-policy/privacy-policies/github-privacy-statement"
class="link-gray">Privacy </a></li>
</ul>
</div>

3
docs/codeql/writing-codeql-queries/index.rst
View File

@@ -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

38
docs/codeql/writing-codeql-queries/running-codeql-queries.rst Normal file
View File

@@ -0,0 +1,38 @@
:tocdepth: 1
.. _running-codeql-queries:
.. meta::
:description: Overview of how to run CodeQL queries locally, in GitHub, or in your CI system.
:keywords: CodeQL, code analysis, CodeQL analysis, code scanning, GitHub code scanning, writing a new query, testing a new query, code scanning alerts
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 allows you 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 allows you 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 where GitHub Actions are disabled, you can use the CodeQL CLI in your existing CI system. For more information, see "`Using code scanning with your existing CI system <https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system>`__".