Step 4 - Understanding the query, binding objects
github-learning-lab opened this issue · 2 comments
Step 4: Anatomy of a query
Now let's analyze what you have written. A CodeQL query has the following basic structure:
import /* ... path to some CodeQL libraries ... */
from /* ... variable declarations ... */
where /* ... logical formulas that say something about the variables ... */
select /* ... expressions to output ... */
The from
/where
/select
part is the query clause: it describes what we are trying to find in the source code.
Let's look closer at the query we wrote in the previous step.
Show the query
import javascript
from CallExpr dollarCall
where dollarCall.getCalleeName() = "$"
select dollarCall
Imports
At the top of the query is import javascript
. This is an import statement . It brings into scope the standard CodeQL library that models JavaScript/TypeScript code, allowing us to use its features in our query. We'll use this library in every query, and in later steps we'll also use some more specialized libraries.
Classes
In the from
section, there is a declaration CallExpr dollarCall
. Here we declare a variable named dollarCall
which has the type CallExpr
. CallExpr
is a class declared in the standard library (you can jump to the definition using F12
). A class represents a collection of values, in this case the collection of all function calls.
Predicates
Now look at the expression dollarCall.getCalleeName()
in the where
section. Here we call the predicate getCalleeName
on the variable dollarCall
of type CallExpr
. Predicates are the building blocks of a query: they express logical properties that we want to hold. Some predicates return results (like getCalleeName
) , and some predicates do not (they just assert that a property must be true).
So far your query finds all functions with the name $
. It does this by asserting that the result of dollarCall.getCalleeName()
is equal to the string "$"
. But what we want actually is to find the first argument of each of these calls.
One way to do this is to declare two variables: one to represent function calls, and one to represent call arguments. Then you will have to create a relationship between these variables in the where
section, so that they are restricted to the first arguments of calls to functions named $
.
⌨️ Activity: Find the 1st argument to all calls to $
We want to identify the expression that is used as the first argument for each call, such as in $(<first-argument>)
.
- Edit the file
calls-to-dollar-arg.ql
and start by copying your previous query. - Use the auto-completion feature to find the class that represents simple expressions, and declare a variable (eg.
dollarArg
) that belongs to this class. - Use auto-completion again on your
dollarCall
variable of typeCallExpr
to guess the predicate that gets the argument at a 0-based index. Start typingget
and browse the predicates, and their contextual documentation. - Combine this with your logic from the previous step with an
and
in thewhere
clause. - Once you're happy with the results, submit your solution.
Congratulations, looks like the query you introduced in d9e70fd finds the correct results!
Take a look at the instructions for the next step to continue.