Step 4 - Understanding the query, binding objects

[github-learning-lab]

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

[github-learning-lab]

⌨️ 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>).

1. Edit the file calls-to-dollar-arg.ql and start by copying your previous query.
2. Use the auto-completion feature to find the class that represents simple expressions, and declare a variable (eg. dollarArg) that belongs to this class.
3. Use auto-completion again on your dollarCall variable of type CallExpr to guess the predicate that gets the argument at a 0-based index. Start typing get and browse the predicates, and their contextual documentation.
4. Combine this with your logic from the previous step with an and in the where clause.
5. Once you're happy with the results, submit your solution.

[github-learning-lab]

Congratulations, looks like the query you introduced in 70dc0d8 finds the correct results!

Take a look at the instructions for the next step to continue.