Skip to content

Commit 0675ba0

Browse files
authored
Merge pull request #17361 from github/12707-felicity-docs-landing
Update the Docs landing page for the CodeQL docs site
2 parents 9a62561 + 40fdd00 commit 0675ba0

File tree

10 files changed

+198
-142
lines changed

10 files changed

+198
-142
lines changed

docs/codeql/_templates/layout.html

Lines changed: 15 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{#
22
Override alabaster/layout.html template to customize the template
33
used to generate the CodeQL documentation.
4-
4+
55
The classes used in this template are provided by the GitHub Primer https://primer.style/css/.
66
The CSS for the primer can be found at https://unpkg.com/@primer/css/dist/primer.css
77

@@ -59,37 +59,34 @@
5959
CodeQL resources
6060
<div class="dropdown-caret"></div>
6161
</summary>
62-
6362
<ul class="dropdown-menu dropdown-menu-se dropdown-menu-dark">
64-
<li><a class="dropdown-item" href="https://codeql.github.com/docs/codeql-overview">CodeQL overview</a></li>
65-
<li class="dropdown-divider" role="separator"></li>
66-
<div class="dropdown-header">
67-
CodeQL tools
68-
</div>
69-
<li><a class="dropdown-item" href="https://codeql.github.com/docs/codeql-for-visual-studio-code">CodeQL for VS Code</a>
70-
<li><a class="dropdown-item" href="https://codeql.github.com/docs/codeql-cli">CodeQL CLI</a>
71-
</li>
63+
<li><a class="dropdown-item" href="codeql-overview">CodeQL overview</a></li>
7264
<li class="dropdown-divider" role="separator"></li>
7365
<div class="dropdown-header">
7466
CodeQL guides
7567
</div>
76-
<li><a class="dropdown-item" href="https://codeql.github.com/docs/writing-codeql-queries">Writing CodeQL queries</a></li>
77-
<li><a class="dropdown-item" href="https://codeql.github.com/docs/codeql-language-guides">CodeQL language guides</a>
68+
<li><a class="dropdown-item" href="writing-codeql-queries">Writing CodeQL queries</a></li>
69+
<li><a class="dropdown-item" href="codeql-language-guides">CodeQL language guides</a>
7870
<li class="dropdown-divider" role="separator"></li>
7971
<div class="dropdown-header">
8072
Reference docs
8173
</div>
82-
<li><a class="dropdown-item" href="https://codeql.github.com/docs/ql-language-reference/">QL language
74+
<li><a class="dropdown-item" href="ql-language-reference/">QL language
8375
reference</a>
84-
<li><a class="dropdown-item" href="https://codeql.github.com/codeql-standard-libraries">CodeQL
76+
<li><a class="dropdown-item" href="../codeql-standard-libraries">CodeQL
8577
standard-libraries</a>
86-
<li><a class="dropdown-item" href="https://codeql.github.com/codeql-query-help">CodeQL
78+
<li><a class="dropdown-item" href="../codeql-query-help">CodeQL
8779
query help</a>
8880
<li class="dropdown-divider" role="separator"></li>
8981
<div class="dropdown-header">
9082
Source files
9183
</div>
9284
<li><a class="dropdown-item" href="https://github.com/github/codeql">CodeQL repository</a>
85+
<li class="dropdown-divider" role="separator"></li>
86+
<div class="dropdown-header">
87+
Academic
88+
</div>
89+
<li><a class="dropdown-item" href="../publications">QL publications</a>
9390
</ul>
9491
</details>
9592

@@ -165,12 +162,12 @@
165162
</li>
166163
</ul>
167164
<ul class="list-style-none d-flex text-gray">
168-
<li class="mr-3">&copy;
165+
<li class="mr-3">&copy;
169166
<script type="text/javascript">document.write(new Date().getFullYear());</script> GitHub, Inc.</li>
170167
<li class="mr-3"><a
171-
href="https://docs.github.com/github/site-policy/github-terms-of-service"
168+
href="https://docs.github.com/site-policy/github-terms/github-terms-of-service"
172169
class="link-gray">Terms </a></li>
173-
<li><a href="https://docs.github.com/github/site-policy/github-privacy-statement"
170+
<li><a href="https://docs.github.com/site-policy/privacy-policies/github-privacy-statement"
174171
class="link-gray">Privacy </a></li>
175172
</ul>
176173
</div>

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,10 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat
2828

2929
- :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++.
3030

31+
- `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.
32+
33+
- `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).
34+
3135
- :doc:`Functions in C and C++ <functions-in-cpp>`: You can use CodeQL to explore functions in C and C++ code.
3236

3337
- :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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,9 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat
1717

1818
- :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.
1919

20+
- `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.
21+
2022
- :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.
2123

22-
- :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.
24+
- :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.
2325
To track the flow of untrusted data through a library, you can create a model of the library.

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,9 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat
2828

2929
- :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.
3030

31-
- :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.
31+
- :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.
32+
33+
- `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.
3234

3335
- :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.
3436

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat
2525

2626
- :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.
2727

28+
- `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.
29+
2830
- :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.
2931

3032
- :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

Lines changed: 35 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,33 @@
22

33
.. _about-codeql:
44

5+
.. meta::
6+
:description: Introduction to CodeQL, a language and toolchain for code analysis.
7+
:keywords: CodeQL, code analysis, CodeQL analysis, security vulnerabilities, variant analysis, resources, tutorials, interactive training, GitHub Security Lab, security researchers, CodeQL databases
8+
59
About CodeQL
610
============
711

8-
CodeQL is the analysis engine used by developers to automate security checks, and by
9-
security researchers to perform variant analysis.
12+
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.
13+
14+
Resources for learning CodeQL
15+
-----------------------------
16+
17+
- **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.
18+
19+
- :doc:`CodeQL queries <../writing-codeql-queries/codeql-queries>`: A general, language-neutral overview of the key components of a query.
20+
21+
- :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.
22+
23+
- :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.
1024

11-
In CodeQL, code is treated like data. Security vulnerabilities, bugs,
12-
and other errors are modeled as queries that can be executed against databases
13-
extracted from code. You can run the standard CodeQL queries, written by GitHub
14-
researchers and community contributors, or write your own to use in custom
15-
analyses. Queries that find potential bugs highlight the result directly in the
16-
source file.
25+
- **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.
26+
27+
- `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.
28+
29+
- `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.
30+
31+
- `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.
1732

1833
About variant analysis
1934
----------------------
@@ -30,6 +45,8 @@ queries. Then, develop or iterate over the query to automatically find logical
3045
variants of the same bug that could be missed using traditional manual
3146
techniques.
3247

48+
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.
49+
3350
CodeQL analysis
3451
---------------
3552

@@ -39,11 +56,13 @@ CodeQL analysis consists of three steps:
3956
#. Running CodeQL queries against the database
4057
#. Interpreting the query results
4158

59+
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.
60+
4261
Database creation
4362
~~~~~~~~~~~~~~~~~
4463

4564
To create a database, CodeQL first extracts a single relational representation
46-
of each source file in the codebase.
65+
of each source file in the codebase.
4766

4867
For compiled languages, extraction works by monitoring the normal build process.
4968
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
5271
binding and type information.
5372

5473
For interpreted languages, the extractor runs directly on the source code,
55-
resolving dependencies to give an accurate representation of the codebase.
74+
resolving dependencies to give an accurate representation of the codebase.
5675

5776
There is one :ref:`extractor <extractor>` for each language supported by CodeQL
5877
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
7291
query language called QL. You can run the queries checked out from the CodeQL
7392
repo (or custom queries that you've written yourself) using the `CodeQL
7493
for VS Code extension <https://docs.github.com/en/code-security/codeql-for-vs-code/>`__ or the `CodeQL CLI
75-
<https://docs.github.com/en/code-security/codeql-cli>`__. For more information about queries, see ":ref:`About CodeQL queries <about-codeql-queries>`."
94+
<https://docs.github.com/en/code-security/codeql-cli>`__. For more information about queries, see ":ref:`About CodeQL queries <about-codeql-queries>`."
7695

7796
.. _interpret-query-results:
7897

@@ -95,7 +114,7 @@ code.
95114
Following interpretation, results are output for code review and triaging. In
96115
CodeQL for Visual Studio Code, interpreted query results are automatically
97116
displayed in the source code. Results generated by the CodeQL CLI can be output
98-
into a number of different formats for use with different tools.
117+
into a number of different formats for use with different tools.
99118

100119

101120
About CodeQL databases
@@ -104,7 +123,7 @@ About CodeQL databases
104123
CodeQL databases contain queryable data extracted from a codebase, for a single
105124
language at a particular point in time. The database contains a full,
106125
hierarchical representation of the code, including a representation of the
107-
abstract syntax tree, the data flow graph, and the control flow graph.
126+
abstract syntax tree, the data flow graph, and the control flow graph.
108127

109128
Each language has its own unique database schema that defines the relations used
110129
to create a database. The schema provides an interface between the initial
@@ -114,13 +133,13 @@ every language construct.
114133

115134
For each language, the CodeQL libraries define classes to provide a layer of
116135
abstraction over the database tables. This provides an object-oriented view of
117-
the data which makes it easier to write queries.
136+
the data which makes it easier to write queries.
118137

119138
For example, in a CodeQL database for a Java program, two key tables are:
120139

121140
- The ``expressions`` table containing a row for every single expression in the
122-
source code that was analyzed during the build process.
123-
- The ``statements`` table containing a row for every single statement in the
141+
source code that was analyzed during the build process.
142+
- The ``statements`` table containing a row for every single statement in the
124143
source code that was analyzed during the build process.
125144

126145
The CodeQL library defines classes to provide a layer of abstraction over each

0 commit comments

Comments
 (0)