You can set up this workspace in Visual Studio Code to get started with adaptive threat modeling.
Note: Adaptive threat modeling is in beta and subject to change. It is currently only available for JavaScript and TypeScript code.
-
Adaptive threat modeling requires a machine with a CPU with AVX (Advanced Vector Extensions). If you are not sure whether your CPU has AVX, check this list.
-
If you are running Windows, you may need to install the Microsoft Visual C++ 2019 Redistributable.
- Go to the Visual Studio downloads.
- From the "All Downloads" section, select Other Tools and Frameworks.
- Select your CPU architecture (
x64,ARM64, orx86), then press Download. - Launch the installer and follow the steps as prompted.
We found that this was not necessary for Windows 10 Pro during internal testing, however we have not tested other versions of Windows.
-
Install Visual Studio Code (VS Code).
-
Install the CodeQL extension for Visual Studio Code. Make sure that you have at least version 1.0.5 installed.
-
Install the adaptive threat modeling beta CodeQL CLI.
- Download the
codeql-all.zipfile that you have been provided with. The link to download this file is included in the "Getting started" document pinned to the #codeql-atm-beta channel on the GitHub Security Lab Slack instance. - If you use macOS Catalina, run
xattr -c codeql-all.zipbefore extracting the zip file. For more information on installing on macOS Catalina, see "Getting started with the CodeQL CLI." - Create a new directory named
codeql-cli-atm-homewhere you can place the adaptive threat modeling beta CodeQL CLI. For example,$HOME/codeql-cli-atm-home - Extract
codeql-all.zipinto thecodeql-cli-atm-homesubdirectory you just created.
- Download the
-
Check that the
codeql-cli-atm-homedirectory has the following structure:codeql-cli-atm-home └── codeql ├── LICENSE.md ├── Open-Source-Notices ├── codeql ├── codeql.cmd ├── codeql.exe ├── cpp ├── csharp ├── go ├── java ├── javascript ├── legacy-upgrades ├── lib-extra ├── ml-models ├── python └── tools -
Set the CodeQL CLI path setting in VS Code to the following path using the Settings Editor:
- For Windows, use
path/to/codeql-cli-atm-home/codeql/codeql.exe - For other operating systems, use
path/to/codeql-cli-atm-home/codeql/codeql
- For Windows, use
-
Clone this repository to your computer and check out the
experimental/atmbranch. You can do this from a terminal by runninggit clone --branch experimental/atm https://github.com/github/vscode-codeql-starter.git. -
Download the submodules by running
git submodule update --init --remotefrom a terminal with a current working directory of the cloned repository. -
In VS Code, click File > Open Workspace. Select the file
vscode-codeql-starter.code-workspacein your checkout of this repository. -
You will see several folders open in the left sidebar:
- The
qlfolder contains the open source CodeQL standard library for JavaScript. It tracks theexperimental/atmbranch of the CodeQL repository. This folder contains the boosted query for NoSQL injection, which is located atql/javascript/ql/src/experimental/adaptivethreatmodeling/NosqlInjectionATM.ql. You can also run the standard queries from here, and browse the libraries. - The
codeql-custom-queries-javascriptfolder is ready for you to start developing your own custom queries for JavaScript, while using the standard libraries. There is an example query,example.ql, to get you started.
- The
-
Open the boosted NoSQL injection query
N 799F osqlInjectionATM.qlin VS Code. This is located atql/javascript/ql/src/experimental/adaptivethreatmodeling/NosqlInjectionATM.ql. -
Select a database to run the query against using CodeQL for VS Code. An example database that demonstrates some of the potential vulnerabilities ATM can identify is provided in "Creating a boosted security query." For more information, see "Choosing a database" in the CodeQL for VS Code help.
-
Run the boosted query using CodeQL for VS Code. For more information, see "Running a query" in the CodeQL for VS Code help.
-
Each result of the boosted query is scored, with higher scores more likely to be true positive results.
-
Sort the results of the boosted query such that the results with the highest scores appear first by pressing the "Message" table header until a downwards arrow appears like so:
For information about writing new boosted queries, see the following:
From time to time, we may release updates to the adaptive threat modeling libraries and queries.
To keep these up to date, run git submodule update --remote regularly.
We want to help you get the most from ATM, and also hear your feedback. For more information, see "Support and feedback."
This project welcomes contributions. For more information, see CONTRIBUTING.md.
This project is licensed under the MIT License.
The CodeQL extension for Visual Studio Code is licensed under the MIT License. The version of CodeQL used by the CodeQL extension is subject to the GitHub CodeQL Terms & Conditions.