Basic query for Go code¶

Learn to write and run a simple CodeQL query using Visual Studio Code with the CodeQL extension.

For information about installing the CodeQL extension for Visual Studio code, see “Setting up CodeQL in Visual Studio Code.”

About the query¶

The query we’re going to run searches the code for methods defined on value types that modify their receiver by writing a field:

func (s MyStruct) valueMethod() { s.f = 1 } // method on value

This is problematic because the receiver argument is passed by value, not by reference. Consequently, valueMethod is called with a copy of the receiver object, so any changes it makes to the receiver will be invisible to the caller. To prevent this, the method should be defined on a pointer instead:

func (s *MyStruct) pointerMethod() { s.f = 1 } // method on pointer

For further information on using methods on values or pointers in Go, see the Go FAQ.

Finding a CodeQL database to experiment with¶

Before you start writing queries for Go code, you need a CodeQL database to run them against. The simplest way to do this is to download a database for a repository that uses Go directly from GitHub.com.

In Visual Studio Code, click the QL icon in the left sidebar to display the CodeQL extension.
Click From GitHub or the GitHub logo at the top of the CodeQL extension to open an entry field.
Copy the URL for the repository into the field and press the keyboard Enter key. For example, https://github.com/go-gorm/gorm.
Optionally, if the repository has more than one CodeQL database available, select go to download the database created from the Go code.

Information about the download progress for the database is shown in the bottom right corner of Visual Studio Code. When the download is complete, the database is shown with a check mark in the Databases section of the CodeQL extension (see screenshot below).

Running a quick query¶

The CodeQL extension for Visual Studio Code adds several CodeQL: commands to the command palette including Quick Query, which you can use to run a query without any set up.

From the command palette in Visual Studio Code, select CodeQL: Quick Query.
After a moment, a new tab quick-query.ql is opened, ready for you to write a query for your currently selected CodeQL database (here a go database). If you are prompted to reload your workspace as a multi-folder workspace to allow Quick queries, accept or create a new workspace using the starter workflow.

In the quick query tab, delete select "" and paste the following query beneath the import statement import go.

from Method m, Variable recv, Write w, Field f
where
  recv = m.getReceiver() and
  w.writesField(recv.getARead(), f, _) and
  not recv.getType() instanceof PointerType
select w, "This update to " + f + " has no effect, because " + recv + " is not a pointer."

Save the query in its default location (a temporary “Quick Queries” directory under the workspace for GitHub.vscode-codeql/quick-queries).
Right-click in the query tab and select CodeQL: Run Query on Selected Database. (Alternatively, run the command from the Command Palette.)

The query will take a few moments to return results. When the query completes, the results are displayed in a CodeQL Query Results view, next to the main editor view.

The query results are listed in two columns, corresponding to the expressions in the select clause of the query. The first column corresponds to w, which is the location in the source code where the receiver recv is modified. The second column is the alert message.

../../_images/basic-go-query-results-1.png

If any matching code is found, click a link in the w column to open the file and highlight the matching location.

../../_images/basic-go-query-results-2.png

Note

If you want to move your experimental query somewhere more permanent, you need to move the whole Quick Queries directory. The directory is a CodeQL pack with a qlpack.yml file that defines the content as queries for Go CodeQL databases. For more information about CodeQL packs, see “Working with CodeQL packs in Visual Studio Code.”

About the query structure¶

After the initial import statement, this simple query comprises three parts that serve similar purposes to the FROM, WHERE, and SELECT parts of an SQL query.

Query part	Purpose	Details
`import go`	Imports the standard CodeQL libraries for Go.	Every query begins with one or more `import` statements.
`from Method m, Variable recv, Write w, Field f`	Defines the variables for the query. Declarations are of the form: `<type> <variable name>`	We declare: `m` as a variable for all methods a `recv` variable, which is the receiver of `m` `w` as the location in the code where the receiver is modified `f` as the field that is written when `m` is called
`where recv = m.getReceiver() and w.writesField(recv.getARead(), f, _) and not recv.getType() instanceof PointerType`	Defines a condition on the variables.	`recv = m.getReceiver()` states that `recv` must be the receiver variable of `m`. `w.writesField(recv.getARead(), f, _)` states that `w` must be a location in the code where field `f` of `recv` is modified. We use a ‘don’t-care’ expression `_` for the value that is written to `f`—the actual value doesn’t matter in this query. `not recv.getType() instanceof PointerType` states that `m` is not a pointer method.
`select w, "This update to " + f + " has no effect, because " + recv + " is not a pointer."`	Defines what to report for each match. `select` statements for queries that are used to find instances of poor coding practice are always in the form: `select <program element>, "<alert message>"`	Reports `w` with a message that explains the potential problem.

Extend the query¶

Query writing is an inherently iterative process. You write a simple query and then, when you run it, you discover examples that you had not previously considered, or opportunities for improvement.

Remove false positive results¶

Among the results generated by the first iteration of this query, you can find cases where a value method is called but the receiver variable is returned. In such cases, the change to the receiver is not invisible to the caller, so a pointer method is not required. These are false positive results and you can improve the query by adding an extra condition to remove them.

To exclude these values:

Extend the where clause to include the following extra condition:

not exists(ReturnStmt ret | ret.getExpr() = recv.getARead().asExpr())

The where clause is now:

where e.isPure() and
  recv = m.getReceiver() and
  w.writesField(recv.getARead(), f, _) and
  not recv.getType() instanceof PointerType and
  not exists(ReturnStmt ret | ret.getExpr() = recv.getARead().asExpr())

Re-run the query.

There are now fewer results because value methods that return their receiver variable are no longer reported.