Merge pull request #17383 from github/10819-felicity-discovery

Update "About CodeQL" to cover the information needs of security researchers better

docs/codeql/codeql-language-guides/codeql-for-cpp.rst

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

docs/codeql/codeql-language-guides/codeql-for-go.rst

@@ -17,6 +17,8 @@ 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.

docs/codeql/codeql-language-guides/codeql-for-java.rst

@@ -30,6 +30,8 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat
 
 -  :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.
 
 -  :doc:`Overflow-prone comparisons in Java and Kotlin <overflow-prone-comparisons-in-java>`: You can use CodeQL to check for comparisons in Java/Kotlin code where one side of the comparison is prone to overflow.

docs/codeql/codeql-language-guides/codeql-for-javascript.rst

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

docs/codeql/codeql-overview/about-codeql.rst

@@ -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,6 +56,8 @@ 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
 ~~~~~~~~~~~~~~~~~
 

docs/codeql/writing-codeql-queries/running-codeql-queries.rst

@@ -2,6 +2,10 @@
 
 .. _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
 ======================