1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
# CodeQL & Chromium
This directory contains:
* scripts used for indexing CodeQL databases, and
* sample queries designed to catch potential bugs in Chrome.
## Getting Started
This guide covers how to run CodeQL queries in both **VSCode** and at the
**command line**.
We strongly recommend using VSCode unless you have a specific need to use the
command line. The CodeQL extension for VSCode features a lot of really nice
autocomplete/fast-debug features for writing CodeQL queries that will generally
make you much more productive.
We try to keep this guide up-to-date but if you run into any issues, check the
official CodeQL documentation
([VSCode](https://codeql.github.com/docs/codeql-for-visual-studio-code/),
[CLI](https://docs.github.com/en/code-security/codeql-cli/getting-started-with-the-codeql-cli)),
if that still doesn't help or you suspect it's an issue specific to the database
build itself, feel free to contact codeql-discuss@chromium.org.
## VSCode Instructions
1. Download a database.
You can download recent databases at the
[chrome-codeql-databases GCS bucket](https://commondatastorage.googleapis.com/chrome-codeql-databases/).
(There are a LOT of databases there. We'll prune them in the future, but
for now you probably want to just filter by a date prefix, e.g.
`codeql-$YEAR-$MONTH-$DAY`. Within the folder for a particular date, you may
see more than one database. The database for Chrome always begins with
`chrome`. You may download other databases if you like! They represent
other `gn` targets that are used within Chrome and may be of interest to
security researchers.)
2. Install the VSCode CodeQL Extension
Open the Extensions view in VSCode (ctrl+shift+X or cmd+shift+X). Search
for "CodeQL" and install the official CodeQL extension.
You should see a "QL" icon pop up at the bottom of the Activity Bar on the
left-hand side of the screen once it's installed.
3. Install CodeQL Runtimes.
Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P).
Type CodeQL: Download Packs and press Enter. Select "Download all core
query packs."
Restart VSCode.
4. Load your query files.
Otherwise, you probably want to start with the query files in the Chromium
source tree.
In the File Explorer view, go to
`File > Open Folder > $YOUR_CHROME_CHECKOUT/src/tools/codeql`.
This will cause the queries to appear in the File Explorer view, AS WELL as
in the CodeQL view (accessed by tapping the "QL" icon in the Activity Bar).
5. Load the CodeQL database.
In the CodeQL view, next to "Databases", click "Choose Database From
Archive", then choose the `zip` file for the database you downloaded.
(This import step took ~4-5 minutes on a 128-core 512GB RAM machine; and ~10
minutes on a 6-core 16GB RAM laptop.)
6. Install pack dependencies.
Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P).
Type "Install Pack Dependencies".
Type (or select) "chrome-ql-queries".
7. (Optional) Load source code.
In the CodeQL view, right-click your database and click "Add Database Source
to Workspace" to make the source code for the database appear in VSCode's
File Explorer. This is optional but can be useful for exploring files after
the completion of a query.
8. Run a query.
To run one of the preexisting queries, while in the CodeQL view, right-click
your chosen query ("Queries" should be listed right under "Databases") and
choose "Run against local database."
However, the preexisting queries are unlikely to return anything, since
hopefully Chromium has already run and fixed any issues ourselves, so you
may want to try writing a new query.
To write a new query from scratch: go to the File Explorer view, add a new
file with the extension `.ql` to the `codel/queries` folder, and write your
query
there.
Here's a "Hello world!" style query you can try that will return methods
from Mojo interface implementations in Chrome.
```
import cpp
import lib.Ipc
from MojoInterfaceImpl impl
select impl, impl.getAMethod()
```
This query took ~5 minutes to run on a 128-core 512GB RAM machine. In
general, the more complicated a query is, the more time it will take; in
particular,
[global data flow](https://codeql.github.com/docs/writing-codeql-queries/about-data-flow-analysis/)
(often required for e.g. taint tracking) will take much longer.
## Command-Line Interface Instructions
1. Install the CodeQL CLI.
You'll want to install the most recent release from
[here](https://github.com/github/codeql-action/releases).
2. Download and unzip the database.
This is identical to step 1 in the VSCode Instructions, but you will
additionally unzip the database after you download it.
3. Start writing queries.
It's "choose your own adventure" from here (you might find the
[official CodeQL C++ docs useful](https://codeql.github.com/docs/codeql-language-guides/basic-query-for-cpp-code/)),
but, if you'd like a "hello world" example to play with:
Make a directory for your queries.
Inside that new directory, make a qlpack.yml file.
```
name: my-custom-cpp-pack
version: 0.0.0
dependencies: codeql/cpp-all
```
Then create a `myquery.ql` file inside that same directory:
```
import cpp
import lib.Ipc
from MojoInterfaceImpl impl
select impl, impl.getAMethod()
```
Finally:
`codeql query run -d $PATH_TO_DATABASE -o output.bqrs myquery.ql`
## Known Issues
**"There was no upgrade path to the target dbscheme"**
This suggests there's a version mismatch between the CodeQL CLI used to create
the database, the version of the QL libraries used by the query, and the version
of the CodeQL CLI used by VSCode.
Check [this issue](https://github.com/github/codeql/issues/12331) for how to
check the version of each of those things. I was able to resolve one instance
of this issue by upgrading my local CLI tools version to match that used to
build the Chromium database.
**CodeQL: View AST "Can't infer database from the provided source"**
The AST viewer seems to be broken at the moment. There's no workaround for this
right now.
## Automation
The file targets_to_index.py in this directory determines which targets should
be indexed into CodeQL databases in automation.
To add a target, append it to the list of `full_targets` in that file.
The file queries_to_run.json in this directory determines which CodeQL queries
should be run against which CodeQL databases in automation.
To add a query, add the query's filename to the list corresponding to the
database you would like to run that query against.
## Other Resources
* [CodeQL for C and C++](https://codeql.github.com/docs/codeql-language-guides/codeql-for-cpp/)
|
