You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
You can view, write, and edit all types of CodeQL packs in Visual Studio Code using the CodeQL extension.
11
11
12
-
TODO
12
+
TODO - EDIT THIS CONTENT!
13
+
14
+
About the CodeQL model editor
15
+
-----------------------------
16
+
17
+
The CodeQL model editor is a new feature in CodeQL for VS Code to support GitHub staff creating CodeQL models for libraries and frameworks written in Java and C#.
18
+
19
+
The editor takes a CodeQL database and runs some telemetry queries to identify uses of APIs that can be used to reason about the dataflow through the codebase. There are two modes of operation:
20
+
21
+
- Application mode: the editor identifies the external APIs used by the codebase. An external (or third party) API is any API that is not part of the CodeQL database you are analyzing. This mode is most useful for improving CodeQL results for the specific codebase.
22
+
- Framework mode: the editor identifies the publicly accessible APIs in the codebase. This mode is most useful for improving the CodeQL results for any codebases that use those APIs.
23
+
24
+
Setting up the CodeQL model editor
25
+
----------------------------------
26
+
27
+
To set up the CodeQL model editor, you need to be using CodeQL for VS Code 1.8.7 or later with the following settings:
28
+
29
+
.. code-block:: json
30
+
31
+
"codeQL.canary": true, CHECK THIS
32
+
"codeQL.model.editor": true,
33
+
34
+
Open the user settings editor (JSON) using the command palette (Ctrl/Cmd+Shift+P) and using the command “Preferences: Open User Settings (JSON)”, add these two settings to the file.
35
+
36
+
If you want to test the CodeQL model packs you generate in VS Code then this setting is also required:
37
+
``"codeQL.runningQueries.useExtensionPacks": true`` CHECK THIS
38
+
39
+
WHAT DOES ``"codeQL.model.llmGeneration": true,`` do?
40
+
41
+
Using the CodeQL model editor
42
+
-----------------------------
43
+
44
+
The easiest way to explain this is by using an example, so we'll run through an example. This is the same example as used in the demo.
45
+
46
+
#. Open your CodeQL workspace in VS Code, e.g., the vscode-codeql-starter workspace
47
+
#. Open the CodeQL extension and add the CodeQL database for dsp-testing/sql2o-example from GitHub
48
+
#. Use the command palette to run the “CodeQL: Open Model Editor (Beta)” command
49
+
#. The CodeQL model editor will open and run some telemetry queries to identify APIs in the code
50
+
#. When the queries are complete, the APIs that have been identified are shown in the editor:
51
+
- By default the editor runs in application mode, so displays the external APIs used by the codebase.
52
+
- If you switch to framework mode, the editor will display the publicly accessible APIs in the codebase.
53
+
#. You can now start modeling the external API calls manually by selecting a model type and entering the correct values in each field, as defined in the Java models-as-data documentation
54
+
#. You can generate the CodeQL automatically:
55
+
- If you are working in application mode click on “Model from source” and enter the name of the repo that contains the source code for the package you want to model. For example, in this case you can enter dsp-testing/sql2o-import to download the relevant CodeQL database and model any APIs from that repo
56
+
- If you are working in framework mode click on “Generate” to generate any models directly from the source code of the framework you are modeling.
57
+
#. Once any modeling is complete, click “Save” or “Save all”. You can now see that the calls are shown as supported. The generated models files are saved in your workspace at .github/codeql/extensions/<pack-name>, where the pack name is the same as the repo.
58
+
- If you are in application mode, the editor will create a separate model file for each package that you model.
59
+
- If you are in framework mode, the edit will generate a single model file for the entire framework.
60
+
#. If you have set up VS Code to use data extensions (using the “codeQL.runningQueries.useExtensionPacks” setting), then you can also run a query and see that the unsafe calls are now detected.
61
+
62
+
Known limitations
63
+
-----------------
64
+
65
+
Only Java is supported
66
+
It's not possible to place the extension pack in a different directory than the root of a workspace folder
Copy file name to clipboardExpand all lines: docs/codeql/codeql-for-visual-studio-code/working-with-codeql-packs-in-visual-studio-code.rst
+12-10Lines changed: 12 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,29 +17,29 @@ There are three types of CodeQL pack, each with a specific purpose.
17
17
18
18
- Query packs are designed to be run. When a query pack is published, the bundle includes all the transitive dependencies and pre-compiled representations of each query, in addition to the query sources. This ensures consistent and efficient execution of the queries in the pack.
19
19
- Library packs are designed to be used by query packs (or other library packs) and do not contain queries themselves. The libraries are not compiled separately.
20
-
- Model packs are used to model dependencies that are not supported by the standard CodeQL libraries. When you add a model pack to your analysis, all extensible queries also explore the sources and sinks of the dependencies defined in the pack.
20
+
- Model packs are used to model dependencies that are not supported by the standard CodeQL libraries. When you add a model pack to your analysis, all extensible queries also analyze the sources and sinks of the dependencies defined in the pack.
To install dependencies for a CodeQL pack in your Visual Studio Code workspace, run the **CodeQL: Install Pack Dependencies** command from the Command Palette and select the packs you want to install dependencies for.
25
25
26
26
You can write and run query packs that depend on the CodeQL standard libraries, without needing to check out the standard libraries in your workspace. Instead, you can install only the dependencies required by the query packs you want to use.
27
27
28
-
Working with CodeQL query packs in Visual Studio Code
One of the main benefits of working with a CodeQL query pack is that all dependecies are resolved, not just those defined within the query and standard libraries.
32
32
33
33
Creating and editing CodeQL query packs
34
-
---------------------------------------
34
+
'''''''''''''''''''''''''''''''''''''''
35
35
To create a new query pack, you will need to use the CodeQL CLI from a terminal, which you can do within Visual Studio Code or outside of it with the ``codeql pack init`` command. Once you create an empty pack, you can edit the ``qlpack.yml`` file or run the ``codeql pack add`` command to add dependencies or change the name or version. For detailed information, see "`Creating and working with CodeQL packs <https://docs.github.com/en/code-security/codeql-cli/using-the-codeql-cli/creating-and-working-with-codeql-packs>`__."
36
36
37
37
You can create or edit queries in a CodeQL pack in Visual Studio Code as you would with any CodeQL query, using the standard code editing features such as autocomplete suggestions to find elements to use from the pack's dependencies.
38
38
39
39
You can then use the CodeQL CLI to publish your pack to share with others. For detailed information, see "`Publishing and using CodeQL packs <https://docs.github.com/en/code-security/codeql-cli/using-the-codeql-cli/publishing-and-using-codeql-packs>`__."
40
40
41
-
Viewing CodeQL query packs and their dependencies in Visual Studio Code
To download a query pack that someone else has created, run the **CodeQL: Download Packs** command from the Command Palette.
44
44
You can download all the core query packs, or enter the full name of a specific pack to download. For example, to download the core queries for analyzing Java and Kotlin, enter ``codeql/java-queries``.
45
45
@@ -49,9 +49,11 @@ If you want to understand a query in a CodeQL pack better, you can open the quer
49
49
50
50
To view the full definition of an element of a query, you can right-click and choose **Go to Definition**. If the library pack is present within the same Visual Studio Code workspace, this will take you to the definition within the workspace. Otherwise it will take you to the definition within your package cache, the shared location where downloaded dependencies are stored, which is in your home directory by default.
51
51
52
-
Working with CodeQL model packs in Visual Studio Code
Copy file name to clipboardExpand all lines: docs/codeql/codeql-overview/codeql-glossary.rst
+13Lines changed: 13 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -34,6 +34,19 @@ A database (or CodeQL database) is a directory containing:
34
34
- log files generated during database creation, query
35
35
execution, and other operations.
36
36
37
+
.. _codeql-packs:
38
+
39
+
CodeQL packs
40
+
------------
41
+
42
+
CodeQL packs are used to create, share, depend on, and run CodeQL queries, libraries, and models. You can publish your own CodeQL packs and download packs created by others. CodeQL query packs may contain queries, library files, query suites, and metadata. CodeQL library packs include one or more CodeQL libraries. CodeQL model packs include one or more data extension files that extend the core libraries by modeling additional libraries and frameworks (dependencies of your code base).
43
+
44
+
.. _data-extensions::
45
+
46
+
Data extensions
47
+
---------------
48
+
When you want to model the sources and sinks of a custom dependency, you can create a CodeQL library (``.qll`` file) and write queries that use it, but it's usually much simpler to create a data extension file. If you model the sources and sinks in data extension, you can use this information to expand the standard queries to cover your custom dependencies. You don't need to write any new queries.
The CodeQL model editor and CodeQL model packs are currently in beta and subject to change. During the beta, model packs are supported only by Java/Kotlin analysis. To use this beta functionality, install the latest version of the CodeQL CLI bundle from: https://github.com/github/codeql-action/releases.
CodeQL model packs are currently in beta and subject to change. During the beta, model packs are supported only by Java/Kotlin analysis. To use this beta functionality, install the latest version of the CodeQL CLI bundle from: https://github.com/github/codeql-action/releases.
0 commit comments