Nullcon Berlin - CodeQL Workshop Setup Instructions

Update: The workshop presentation slides are now ready for download: nullcon-23-codeql-workshop.pdf

---

Please follow these instructions to the end (including the Select CodeQL Database and Test your installation sections) before the workshop starts.

You can choose between two options to run the workshop exercises:

• Option A: GitHub Codespace (Using a Browser or VS Code - CodeQL is run remotely on a Linux based GitHub Codespace in the cloud)
• Option B: Local installation (Using VS Code - CodeQL is run locally on your machine)

Option A: GitHub Codespace

Use a remote GitHub Codespace to work on the workshop exercises.

Prerequisites

• Stable internet connection throughout the workshop.
• GitHub account (sign up for free)
• Browser or Visual Studio Code (VS Code) with the GitHub Codespaces extension installed on your local machine.

Note: The first 120h hours per core of Codespace usage are free per month, we use a codespace with 4 cores for this workshop since 4 cores is the current maximum for free accounts. (If you have a Pro account, we recommend switching to an 8-core machine.)

Step-by-Step

1. Login to your GitHub account
2. Go to the repo https://github.com/p-/nullcon-berlin-2023-workshop / (short link: https://gh.io/nc-2023-ws)
3. Click on Code -> Codespaces
4. Click on the plus sign (+) to create a new codespace.

=> VS Code will start in your browser and a remote Codespace will be built (this may take some time). If you are asked to open the workspace vscode-codeql-starter.code-workspace click on "Open Workspace".

5. Continue with Selecting a CodeQL Database
6. Then Test your installation

Use existing Codespace

If you've already prepared a Codespace this workshop you can simply start it by going to the codespace repo and clicking on "Code -> Codespaces" and then click on the randomly generated name of this codespace (this will be faster than creating a new one):

Option B: Local installation

Use a local CodeQL installation to work on the workshop exercises.

Prerequisites

• Requires downloading up to 2 GB of data in total.
• Visual Studio Code (VS Code) and git installed on your local machine.

Step-by-Step

1. Install VS Code extension for CodeQL
2. In the terminal, in a directory specified by you: $ git clone https://github.com/p-/nullcon-berlin-2023-workshop.git
3. $ cd nullcon-berlin-2023-workshop
4. $ git submodule init
5. $ git submodule update --recursive
6. In VS Code: File -> Open Workspace from File... vscode-codeql-starter.code-workspace

=> VS Code will start and the CodeQL CLI (binaries) will be installed. (approx. 500 MB of additional data need to be downloaded))

7. Continue with Selecting a CodeQL Database
8. Then Test your installation

Troubleshooting the local installation

In case you see errors such as:

• Failed to run query: Could not resolve library path for [..]
• Could not resolve module [..]
• Could not resolve type [..]

=> It is very likely that you missed cloning the git submodules (namely the ql repo). To fix this follow the Step-by-Step instructions starting with step 3.

Select CodeQL Database

1. Make sure you have the workspace vscode-codeql-starter.code-workspace open in VS Code.
2. Go To the CodeQL View
3. Click on "Choose Database from Archive" and select the vulnerable-jxpath-project-codeql-db-with-cache.zip file in the root of the repository.

Now you can test your installation:

Test your installation

Prerequisites

Make sure that the previously chosen CodeQL database is selected in the CodeQL view. (Click on "Select" if it's not)

=> When the database is selected it should look like this (note the checkmark):

Step-by-Step

1. In VS Code: go to the workspace folder: codeql-custom-queries-java
2. Create a new file test.ql
3. add the following content: select "Hello World!"
4. Save file and right click in file on "CodeQL: Run Query on Selected Database"

=> The output should look like this: