Add first draft of CodeQL model editor

Author: felicitymay

docs/codeql/codeql-for-visual-studio-code/setting-up-codeql-in-visual-studio-code.rst

@@ -74,6 +74,8 @@ To use the starter workspace:
 
 #. In VS Code, use the **File** > **Open Workspace** option to open the ``vscode-codeql-starter.code-workspace`` file from your checkout of the workspace repository.
 
+Remember to update the ``ql`` submodule in the starter workspace periodically to ensure that it remains compatible with newer versions of the VS Code extension and the CodeQL CLI.
+
 .. _existing-workspace:
 
 Updating an existing workspace for CodeQL

docs/codeql/codeql-for-visual-studio-code/using-the-codeql-model-editor.rst

@@ -7,64 +7,113 @@ Using the CodeQL model editor
 
 .. include:: ../reusables/beta-note-model-pack-editor-vsc.rst
 
-You can view, write, and edit all types of CodeQL packs in Visual Studio Code using the CodeQL extension. 
+You can view, write, and edit all types of CodeQL packs in Visual Studio Code using the CodeQL extension. The model editor is designed to help you model external dependencies of your codebase that are not supported by the standard CodeQL Libraries.
 
-TODO - EDIT THIS CONTENT!
+About the CodeQL model editor
+-----------------------------
 
-Explain how to find the data extension files that you've created and test them. Also how to save to the right location in a GitHub repository for default and advanced setup to use.
+The CodeQL model editor guides you through modeling the calls to external dependencies in your application or fully modeling all the public entry and exit points in an external dependency
 
-Copy file into GitHub folder
+When you open the model editor, it analyzes the currently selected CodeQL database and identifies where the application uses external APIs. An external (or third party) API is any API that is not part of the CodeQL database you have selected.
 
-For testing:     "codeQL.runningQueries.useModelPacks": true, - does it work for MRVA
+The model editor has two different modes:
 
-About the CodeQL model editor
------------------------------
+- Application mode (default view): The editor lists each the external framework used by the seelcted CodeQL database. When you expand a framework, a list of all calls to and from the external API is shown with the options available to model dataflow through each call. This mode is most useful for improving the CodeQL results for the specific codebase.
 
-The CodeQL model editor guides you through the process of creating CodeQL models for libraries and frameworks that you rely on that are not supported by the standard CodeQL Libraries.
+- Dependency mode: The editor identifies the all publicly accessible APIs in the selected CodeQL database. This view guides you through modeling each public API that the codebase makes available. When you have finished modeling the entire API, you can save the model and use it to improve the CodeQL analysis for all codebases that use the dependency.
 
-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:
+Displaying the CodeQL model editor
+----------------------------------
 
-- 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.
-- 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.
+#. Open your CodeQL workspace in VS Code, for example, the vscode-codeql-starter workspace.
+   If you haven't updated the `ql` submodule for a while, update it from `main` to ensure that you have the queries used to gather data for the model editor.
+#. Open the CodeQL extension and select the CodeQL database that you want to model from the Databases section of the left side pane.
+#. Use the command palette to run the “CodeQL: Open Model Editor (Beta)” command.
+#. The CodeQL model editor will open in a new tab and run a series of telemetry queries to identify APIs in the code.
+#. When the queries are complete, the APIs that have been identified are shown in the editor.
 
-Using the CodeQL model editor
------------------------------
+Modeling the calls to external APIs from your codebase
+------------------------------------------------------
 
-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.
+You typically use this method when you are looking at a specific codebase where you want to improve the precision of CodeQL results. This is usually when the codebase uses frameworks or libraries that are not supported by CodeQL and they also are not used by other teams in your organization. 
 
-#. Open your CodeQL workspace in VS Code, e.g., the vscode-codeql-starter workspace 
-#. Open the CodeQL extension and add the CodeQL database for dsp-testing/sql2o-example from GitHub
-#. Use the command palette to run the “CodeQL: Open Model Editor (Beta)” command
-#. The CodeQL model editor will open and run some telemetry queries to identify APIs in the code
-#. When the queries are complete, the APIs that have been identified are shown in the editor:
-   - By default the editor runs in application mode, so displays the external APIs used by the codebase. 
-   - If you switch to framework mode, the editor will display the publicly accessible APIs in the codebase.
+#. Select the CodeQL database that you want to improve CodeQL coverage for.
+#. Display the CodeQL model editor, by default the editor runs in application mode, so displays the list of external APIs used by the selected codebase.
+   INSERT SCREENSHOT?
 
-#. 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
-#. You can generate the CodeQL automatically:
-   - 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
-   - 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.
+#. Click to expand an external API and view the list of calls from the codebase to the external dependency.
+#. Click **View** associated with an API call or method to show where it is used in your codebase.
+#. When you have determined how to model the call or method, define the **Model type**.
+#. The remaining fields are updated with available options:
+   - **Source**: choose the **Output** element to model.
+   - **Sink**: choose the **Input** element to model.
+   - **Flow summary**: choose the **Input** and **Output** elements to model.
 
-#. 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.
-   - If you are in application mode, the editor will create a separate model file for each package that you model.
-   - If you are in framework mode, the edit will generate a single model file for the entire framework.
+#. Define the **Kind** of data flow for the model.
+#. When you have finished modeling, click **Save all** or  **Save** (shown at the bottom right of each expanded list of calls). The percentage of calls modeled in the editor is updated.
 
-#. 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.
+The models are stored in your workspace at ``.github/codeql/extensions/<codeql-model-pack>``, where ``<codeql-model-packe>`` is the name of the CodeQL database that you selected. That is, the name of the repository, hyphen, the language analyzed by CodeQL.
+
+The models are stored in a series of YAML data extension files, one for each external API. For example:
+
+- ``.github/codeql/extensions/sofa-jraft-java`` - model pack
+    - ``models``
+        - ``jmh-core.model.yml`` - model of calls to the ``[email protected]`` dependency.
+        - ``rocksdbjni.model.yml`` - model of calls to the ``[email protected]`` dependency.
+
+Modeling the public API of a codebase
+-------------------------------------
+
+You typically use this method when you want to model a framework or library that your organization uses in more than one codebase. Once you have finished creating and testing the model, you can publish the CodeQL model pack for your whole organization to use.
 
-Known limitations
------------------
+#. Select the CodeQL database that you want to model.
+#. Display the CodeQL model editor, by default the editor runs in application mode. Click **Model as dependency** to display dependency mode. The screen changes to show the public API of the framework or library.
+   INSERT SCREENSHOT?
 
-Only Java is supported
-It's not possible to place the extension pack in a different directory than the root of a workspace folder
+#. Click to expand a public method and view the list of available methods.
+#. Click **View** associated with a method to show its definition.
+#. When you have determined how to model the method, define the **Model type**.
+#. The remaining fields are updated with available options:
+   - **Source**: choose the **Output** element to model.
+   - **Sink**: choose the **Input** element to model.
+   - **Flow summary**: choose the **Input** and **Output** elements to model.
 
-How to use data extensions in CodeQL for VS Code
-When a query is run in CodeQL for VS Code, by default, the IDE will load data extensions for the given pack and its transitive dependencies as defined in the How to use Data Extensions in the CodeQL CLI section.
+#. Define the **Kind** of data flow for the model.
+#. When you have finished modeling, click **Save all** or  **Save** (shown at the bottom right of each expanded list of calls). The percentage of calls modeled in the editor is updated.
+
+The models are stored in your workspace at ``.github/codeql/extensions/<codeql-model-pack>``, where ``<codeql-model-packe>`` is the name of the CodeQL database that you selected. That is, the name of the repository, hyphen, the language analyzed by CodeQL.
+
+The models are stored in a series of YAML data extension files, one for each public method. For example:
+
+- ``.github/codeql/extensions/sofa-jraft-java`` - model pack
+    - ``models``
+        - ``com.alipay.sofa.jraft.option.model.yml`` - model of public methods in this Java package.
+        - ``com.alipay.sofa.jraft.rhea.options.model.yml`` - model of public methods in this Java package.
+
+The editor will create a separate model file for each package that you model.
+
+Testing CodeQL model packs
+--------------------------
+
+You can test any CodeQL model packs you create in VS Code by toggling the "use model packs" setting on and off. This method works for both databases and for variant analysis repositories.
+
+- To run queries on a CodeQL database with any model packs that are stored within the ``.github/codeql/extensions`` directory of the workspace, update your ``settings.json`` file with: ``"codeQL.runningQueries.useModelPacks": all,``.
+- To run queries on a CodeQL database without using model packs, update your ``settings.json`` file with: ``"codeQL.runningQueries.useModelPacks": none,``.
+
+If your model is working well, you should see a difference in the results of the two different runs. If you don't see any differences results, you may want to introduce a known bug to verify that the model behaves as expected.
+
+#. 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.
 
-To include extension packs in a VS Code workspace, there is a new setting called codeQL.runningQueries.useExtensionPacks. By default, this value is "none", which means that extension packs are not loaded for query evaluations. The other option is "all", which means that before running a query, the IDE will locate all extension packs in the workspace and load them during evaluation.
+Using CodeQL model packs with code scanning
+-------------------------------------------
 
-In the future, we may define other options to selectively load a subset of extension packs.
+There are two methods for using CodeQL model packs with code scanning:
 
-To use this option, simply set codeQL.runningQueries.useExtensionPacks to "all" and run queries as before. This option applies both to locally run queries and to variant analysis queries run remotely.
+#. Copy the model pack directory into the ``.github/codeql/extensions`` directory of the repository. It will automatically be used by all future code scanning analysis for the repository (default setup or advanced setup).
+#. Publish the model pack to the GitHub Container Registry as a CodeQL model pack. This can be downloaded and used by advanced setup for code scanning or by the CodeQL CLI running in an external CI system.
 
-For more information on the engineering and product decisions around extension packs in the VS Code extension, see Customization support in the CodeQL VS Code extension.
+For more information, see the following articles on the GitHub Docs site:
 
+- Default setup of code scanning: `Extending CodeQL coverage with CodeQL model packs in default setup <https://docs.github.com/en/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup#extending-codeql-coverage-with-codeql-model-packs-in-default-setup>`__
+- Advanced setup of code scanning: `Extending CodeQL coverage with CodeQL model packs <https://docs.github.com//en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#extending-codeql-coverage-with-codeql-model-packs>`__
+- CodeQL CLI setup in external CI system: `Using model packs to analyze calls to custom dependencies <https://docs.github.com/en/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system#using-model-packs-to-analyze-calls-to-custom-dependencies>`__