diff --git a/assets/images/help/security/codeql-for-vs-code-access-logs.png b/assets/images/help/security/codeql-for-vs-code-access-logs.png new file mode 100644 index 000000000000..fa5aa273f7b5 Binary files /dev/null and b/assets/images/help/security/codeql-for-vs-code-access-logs.png differ diff --git a/assets/images/help/security/codeql-for-vs-code-add-list.png b/assets/images/help/security/codeql-for-vs-code-add-list.png new file mode 100644 index 000000000000..61a3a7edd644 Binary files /dev/null and b/assets/images/help/security/codeql-for-vs-code-add-list.png differ diff --git a/assets/images/help/security/codeql-for-vs-code-controller-repository.png b/assets/images/help/security/codeql-for-vs-code-controller-repository.png new file mode 100644 index 000000000000..76d5b3c25098 Binary files /dev/null and b/assets/images/help/security/codeql-for-vs-code-controller-repository.png differ diff --git a/assets/images/help/security/codeql-for-vs-code-extension-settings.png b/assets/images/help/security/codeql-for-vs-code-extension-settings.png new file mode 100644 index 000000000000..66220359b885 Binary files /dev/null and b/assets/images/help/security/codeql-for-vs-code-extension-settings.png differ diff --git a/assets/images/help/security/codeql-for-vs-code-extensions-view.png b/assets/images/help/security/codeql-for-vs-code-extensions-view.png new file mode 100644 index 000000000000..c107435cf238 Binary files /dev/null and b/assets/images/help/security/codeql-for-vs-code-extensions-view.png differ diff --git a/assets/images/help/security/codeql-for-vs-code-model-application-mode-expanded.png b/assets/images/help/security/codeql-for-vs-code-model-application-mode-expanded.png new file mode 100644 index 000000000000..9ef33780bc70 Binary files /dev/null and b/assets/images/help/security/codeql-for-vs-code-model-application-mode-expanded.png differ diff --git a/assets/images/help/security/codeql-for-vs-code-model-application-mode.png b/assets/images/help/security/codeql-for-vs-code-model-application-mode.png new file mode 100644 index 000000000000..7150d0c2ec74 Binary files /dev/null and b/assets/images/help/security/codeql-for-vs-code-model-application-mode.png differ diff --git a/assets/images/help/security/codeql-for-vs-code-model-dependency-mode-expanded.png b/assets/images/help/security/codeql-for-vs-code-model-dependency-mode-expanded.png new file mode 100644 index 000000000000..917973ca134e Binary files /dev/null and b/assets/images/help/security/codeql-for-vs-code-model-dependency-mode-expanded.png differ diff --git a/assets/images/help/security/codeql-for-vs-code-model-dependency-mode-plus.png b/assets/images/help/security/codeql-for-vs-code-model-dependency-mode-plus.png new file mode 100644 index 000000000000..f5ca02c963b1 Binary files /dev/null and b/assets/images/help/security/codeql-for-vs-code-model-dependency-mode-plus.png differ diff --git a/assets/images/help/security/codeql-for-vs-code-model-dependency-mode.png b/assets/images/help/security/codeql-for-vs-code-model-dependency-mode.png new file mode 100644 index 000000000000..22e586d10f39 Binary files /dev/null and b/assets/images/help/security/codeql-for-vs-code-model-dependency-mode.png differ diff --git a/assets/images/help/security/codeql-for-vs-code-run-all-tests.png b/assets/images/help/security/codeql-for-vs-code-run-all-tests.png new file mode 100644 index 000000000000..7e2b100ea7c2 Binary files /dev/null and b/assets/images/help/security/codeql-for-vs-code-run-all-tests.png differ diff --git a/assets/images/help/security/codeql-for-vs-code-running-a-query.png b/assets/images/help/security/codeql-for-vs-code-running-a-query.png new file mode 100644 index 000000000000..06e7ff34eee9 Binary files /dev/null and b/assets/images/help/security/codeql-for-vs-code-running-a-query.png differ diff --git a/assets/images/help/security/codeql-for-vs-code-test-output.png b/assets/images/help/security/codeql-for-vs-code-test-output.png new file mode 100644 index 000000000000..8f43cca44f9a Binary files /dev/null and b/assets/images/help/security/codeql-for-vs-code-test-output.png differ diff --git a/assets/images/help/security/codeql-for-vs-code-variant-analysis-repo-lists.png b/assets/images/help/security/codeql-for-vs-code-variant-analysis-repo-lists.png new file mode 100644 index 000000000000..9cf729f0c91e Binary files /dev/null and b/assets/images/help/security/codeql-for-vs-code-variant-analysis-repo-lists.png differ diff --git a/assets/images/help/security/codeql-for-vs-code-variant-analysis-result.png b/assets/images/help/security/codeql-for-vs-code-variant-analysis-result.png new file mode 100644 index 000000000000..00564a03e97d Binary files /dev/null and b/assets/images/help/security/codeql-for-vs-code-variant-analysis-result.png differ diff --git a/assets/images/help/security/codeql-for-vs-code-variant-analysis-results-view.png b/assets/images/help/security/codeql-for-vs-code-variant-analysis-results-view.png new file mode 100644 index 000000000000..ad5a96db7da6 Binary files /dev/null and b/assets/images/help/security/codeql-for-vs-code-variant-analysis-results-view.png differ diff --git a/content/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup.md b/content/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup.md index 00b0f4b3d73d..4e698bbb1dd0 100644 --- a/content/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup.md +++ b/content/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup.md @@ -86,7 +86,7 @@ If you use frameworks and libraries that are not recognized by the standard libr For default setup, you need to define the models of your additional dependencies in {% data variables.product.prodname_codeql %} model packs. You can extend coverage in default setup with {% data variables.product.prodname_codeql %} model packs for individual repositories, or at scale for all repositories in an organization. -For more information about {% data variables.product.prodname_codeql %} model packs and writing your own, see [Using the {% data variables.product.prodname_codeql %} model editor](https://codeql.github.com/docs/codeql-for-visual-studio-code/using-the-codeql-model-editor) in the {% data variables.product.prodname_codeql %} documentation. +For more information about {% data variables.product.prodname_codeql %} model packs and writing your own, see "[AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/using-the-codeql-model-editor)." ### Extending coverage for a repository diff --git a/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/about-the-codeql-cli.md b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/about-the-codeql-cli.md index 77de26330e4d..d4b474b69217 100644 --- a/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/about-the-codeql-cli.md +++ b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/about-the-codeql-cli.md @@ -109,23 +109,4 @@ codeql github upload-results \ --sarif=python-results.sarif ``` -## About the {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_codeql %} license - -**License notice:** If you don’t have a {% data variables.product.prodname_enterprise %} license then, by installing this product, you are agreeing to the [{% data variables.product.prodname_dotcom %} {% data variables.product.prodname_codeql %} Terms and Conditions](https://securitylab.github.com/tools/codeql/license). - -{% data variables.product.prodname_dotcom %} {% data variables.product.prodname_codeql %} is licensed on a per-user basis. Under the license restrictions, you can use {% data variables.product.prodname_codeql %} to perform the following tasks: - -- To perform academic research. -- To demonstrate the software. -- To test {% data variables.product.prodname_codeql %} queries that are released under an OSI-approved License to confirm that new versions of those queries continue to find the right vulnerabilities. - -Where "OSI-approved License" means an Open Source Initiative (OSI)-approved open source software license. - -If you are working with an Open Source Codebase (that is, a codebase that is released under an OSI-approved License) you can also use {% data variables.product.prodname_codeql %} for the following tasks: - -- To perform analysis of the Open Source Codebase. -- If the Open Source Codebase is hosted and maintained on {% data variables.product.prodname_dotcom_the_website %}, to generate {% data variables.product.prodname_codeql %} databases for or during automated analysis, continuous integration, or continuous delivery. - -{% data variables.product.prodname_codeql %} can’t be used for automated analysis, continuous integration or continuous delivery, whether as part of normal software engineering processes or otherwise, except in the express cases set forth herein unless you have a license for {% data variables.product.prodname_GH_advanced_security %}. - -{% data reusables.advanced-security.ghas-trial %} +{% data reusables.code-scanning.codeql-license %} diff --git a/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli.md b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli.md index 86753cde91e3..93271c2f1e44 100644 --- a/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli.md +++ b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli.md @@ -68,7 +68,7 @@ For Linux, Windows, and macOS users (version 10.14 "Mojave", and earlier) simply {% note %} **Note:** If you add `codeql` to your `PATH`, it can be accessed by {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} to compile and run queries. - For more information about configuring {% data variables.product.prodname_vscode_shortname %} to access the {% data variables.product.prodname_codeql_cli %}, see "[Setting up {% data variables.product.prodname_codeql %} in {% data variables.product.prodname_vscode %}](https://codeql.github.com/docs/codeql-for-visual-studio-code/setting-up-codeql-in-visual-studio-code/#setting-up-codeql-in-visual-studio-code)." + For more information about configuring {% data variables.product.prodname_vscode_shortname %} to access the {% data variables.product.prodname_codeql_cli %}, see "[AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/configuring-access-to-the-codeql-cli)." {% endnote %} diff --git a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/advanced-setup-of-the-codeql-cli.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/advanced-setup-of-the-codeql-cli.md index 850d78eda7d6..ccd5d0f7f59b 100644 --- a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/advanced-setup-of-the-codeql-cli.md +++ b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/advanced-setup-of-the-codeql-cli.md @@ -107,7 +107,7 @@ If you want to use the latest {% data variables.product.prodname_codeql %} featu {% data variables.product.prodname_dotcom %} stores {% data variables.product.prodname_codeql %} databases for over 200,000 repositories on {% data variables.product.prodname_dotcom_the_website %}, which you can download using the REST API. The list of repositories is constantly growing and evolving to make sure that it includes the most interesting codebases for security research. -You can also analyze databases from {% data variables.product.prodname_dotcom_the_website %} using the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode_shortname %} extension. For more information, see "[Analyzing your projects](https://codeql.github.com/docs/codeql-for-visual-studio-code/analyzing-your-projects)." +You can also analyze databases from {% data variables.product.prodname_dotcom_the_website %} using the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode_shortname %} extension. For more information, see "[AUTOTITLE](/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries)." You can check if a repository has any {% data variables.product.prodname_codeql %} databases available for download using the `/repos///code-scanning/codeql/databases` endpoint. For example, to check for {% data variables.product.prodname_codeql %} databases using the [{% data variables.product.prodname_cli %}](https://cli.github.com/manual/gh_api) you would run: diff --git a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs.md index 3542e560f001..4eafb990aa49 100644 --- a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs.md +++ b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs.md @@ -78,7 +78,7 @@ The `codeql pack init` command creates the directory structure and configuration {% data reusables.code-scanning.beta-model-packs %} -Model packs can be used to expand {% data variables.product.prodname_code_scanning %} analysis to recognize libraries and frameworks that are not supported by default. Model packs use data extensions, which are implemented as YAML and describe how to add data for new dependencies. When a model pack is specified, the data extensions in that pack will be added to the {% data variables.product.prodname_code_scanning %} analysis automatically. For more information about {% data variables.product.prodname_codeql %} model packs and data extensions, see [Using the {% data variables.product.prodname_codeql %} model editor](https://codeql.github.com/docs/codeql-for-visual-studio-code/using-the-codeql-model-editor) in the {% data variables.product.prodname_codeql %} documentation. +Model packs can be used to expand {% data variables.product.prodname_code_scanning %} analysis to recognize libraries and frameworks that are not supported by default. Model packs use data extensions, which are implemented as YAML and describe how to add data for new dependencies. When a model pack is specified, the data extensions in that pack will be added to the {% data variables.product.prodname_code_scanning %} analysis automatically. For more information about {% data variables.product.prodname_codeql %} model packs and data extensions, see "[AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/using-the-codeql-model-editor)." A model pack is a {% data variables.product.prodname_codeql %} pack with the following characteristics in the `qlpack.yml` file: diff --git a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries.md index 1b366ab9dc75..e0140e81f661 100644 --- a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries.md +++ b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries.md @@ -227,9 +227,9 @@ This information may be sufficient to debug trivial test failures. For failures that are harder to debug, you can import `EmptyThen.testproj` into {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode_shortname %}, execute `EmptyThen.ql`, and view the results in the -`Test.java` example code. For more information, see "[Analyzing your projects](https://codeql.github.com/docs/codeql-for-visual-studio-code/analyzing-your-projects/#analyzing-your-projects)" in the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode_shortname %} help. +`Test.java` example code. For more information, see "[AUTOTITLE](/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/managing-codeql-databases#choosing-a-database-to-analyze)." ## Further reading - "[{% data variables.product.prodname_codeql %} queries](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries)" -- "[Testing {% data variables.product.prodname_codeql %} queries in {% data variables.product.prodname_vscode %}](https://codeql.github.com/docs/codeql-for-visual-studio-code/testing-codeql-queries-in-visual-studio-code/#testing-codeql-queries-in-visual-studio-code)." +- "[AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/testing-codeql-queries-in-vs-code)." diff --git a/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/about-codeql-for-vs-code.md b/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/about-codeql-for-vs-code.md new file mode 100644 index 000000000000..a4d539c8cd49 --- /dev/null +++ b/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/about-codeql-for-vs-code.md @@ -0,0 +1,57 @@ +--- +title: About CodeQL for VS Code +shortTitle: About the extension +versions: + fpt: '*' + ghec: '*' + ghes: '*' +topics: + - Advanced Security + - Code scanning + - CodeQL +type: reference +intro: 'You can write, run, and test {% data variables.product.prodname_codeql %} queries inside {% data variables.product.prodname_vscode %} with the {% data variables.product.prodname_codeql %} extension.' +--- + +## About {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} + +You can run {% data variables.product.prodname_codeql %} queries on databases generated from source code, in order to find errors and security vulnerabilities in a codebase. For more information about {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %}, see "[AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql)." + +With the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension, you can: + +- Write custom {% data variables.product.prodname_codeql %} queries and supporting libraries. +- Directly view and use the {% data variables.product.prodname_codeql %} security queries from the large, open-source [`github/codeql`](https://github.com/github/codeql) repository. +- Run queries over one or more {% data variables.product.prodname_codeql %} databases. +- Track the flow of data through a program, highlighting areas that are potential security vulnerabilities. +- View, create, and edit all types of {% data variables.product.prodname_codeql %} packs of queries or libraries that you can use or publish to share with others. +- Run unit tests for {% data variables.product.prodname_codeql %} queries. +- Use a dedicated editor for viewing, creating, and editing {% data variables.product.prodname_codeql %} model packs, which are used to extend standard {% data variables.product.prodname_codeql %} analysis. + +The {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension also adds a {% data variables.product.prodname_codeql %} sidebar view to {% data variables.product.prodname_vscode_shortname %}. This contains a list of local {% data variables.product.prodname_codeql %} databases, an overview of the queries that you have run in the current session, and a variant analysis view for large-scale analysis. + +### IntelliSense + +The extension provides standard IntelliSense features for query files (extension `.ql`) and library files (extension `.qll`) that you open in the {% data variables.product.prodname_vscode_shortname %} editor. These include: + +- Syntax highlighting +- Right-click options (such as **Go To Definition**) +- Autocomplete suggestions +- Hover information + +For more information about Intellisense in {% data variables.product.prodname_vscode_shortname %}, see [IntelliSense](https://code.visualstudio.com/docs/editor/intellisense) in the {% data variables.product.prodname_vscode %} documentation. + +You can also use the {% data variables.product.prodname_vscode_shortname %} **Format Document** command to format your code according to the [{% data variables.product.prodname_codeql %} style guide](https://github.com/github/codeql/blob/main/docs/ql-style-guide.md). + +### The {% data variables.product.prodname_vscode_command_palette_shortname %} + +You can run commands for the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension from the {% data variables.product.prodname_vscode_command_palette_shortname %}. For more information about the {% data variables.product.prodname_vscode_command_palette_shortname %}, see "[User Interface](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette)" in the {% data variables.product.prodname_vscode_shortname %} documentation. + +## Data and telemetry + +If you specifically opt in to permit {% data variables.product.prodname_dotcom %} to do so, {% data variables.product.prodname_dotcom %} will collect usage data and metrics for the purposes of helping the core developers to improve the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension. For more information, see "[AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/telemetry-in-codeql-for-visual-studio-code)." + +{% data reusables.code-scanning.codeql-license %} + +## Next steps + +To learn about how to install the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension, see "[AUTOTITLE](/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/installing-codeql-for-vs-code)." diff --git a/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries.md b/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries.md new file mode 100644 index 000000000000..959e373f9337 --- /dev/null +++ b/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries.md @@ -0,0 +1,40 @@ +--- +title: Exploring data flow with path queries +shortTitle: Explore data flow +versions: + fpt: '*' + ghec: '*' + ghes: '*' +topics: + - Advanced Security + - Code scanning + - CodeQL +type: reference +intro: 'You can run {% data variables.product.prodname_codeql %} queries in {% data variables.product.prodname_vscode %} to help you track the flow of data through a program, highlighting areas that are potential security vulnerabilities.' +--- + +## About path queries + +A path query is a {% data variables.product.prodname_codeql %} query with the property `@kind path-problem`. You can find a number of these in the standard {% data variables.product.prodname_codeql %} libraries. + +You can run the standard {% data variables.product.prodname_codeql %} path queries to identify security vulnerabilities and manually look through the results. For more information about how {% data variables.product.prodname_codeql %} tracks data flow, see "[About data flow analysis](https://codeql.github.com/docs/writing-codeql-queries/about-data-flow-analysis/)" in the {% data variables.product.prodname_codeql %} documentation. + +Once you're familiar with data flow analysis and existing queries, you can write your own path queries in {% data variables.product.prodname_codeql %}. For more information, see "[Next steps](#next-steps)." + +## Running path queries in {% data variables.product.prodname_vscode_shortname %} locally + +1. Open a path query in {% data variables.product.prodname_vscode_shortname %}. +1. Right-click in the window with the query open, and select **{% data variables.product.prodname_codeql %}: Run Query on Selected Database**. Alternatively, you can also run this from the {% data variables.product.prodname_vscode_command_palette_shortname %}. +1. Once the query has finished running, you can see the results in the "Results" view (under `alerts` in the dropdown menu). Each query result describes the flow of information between a source and a sink. +1. Expand the result to see the individual steps that the data follows. +1. Click each step to jump to it in the source code and investigate the problem further. + +## Next steps + +{% ifversion codeql-vs-code-mrva %} + +When you are ready to run a path query at scale, you can use the "Variant Analysis Repositories" view to run the query against up to 1,000 repositories on {% data variables.product.prodname_dotcom_the_website %}. For more information, see "[AUTOTITLE](/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries-at-scale-with-multi-repository-variant-analysis)." + +{% endif %} + +For information about how to use the correct format and metadata for your own path queries, see "[Creating path queries](https://codeql.github.com/docs/writing-codeql-queries/creating-path-queries/#creating-path-queries)" in the {% data variables.product.prodname_codeql %} documentation. The {% data variables.product.prodname_codeql %} documentation also contains detailed information about how to define new sources and sinks, as well as templates and examples of how to extend the standard {% data variables.product.prodname_codeql %} libraries to suit your analysis. diff --git a/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/index.md b/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/index.md new file mode 100644 index 000000000000..a4bdba31db28 --- /dev/null +++ b/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/index.md @@ -0,0 +1,22 @@ +--- +title: Getting started with the {% data variables.product.prodname_codeql %} for Visual Studio Code extension +shortTitle: Getting started +intro: 'The {% data variables.product.prodname_codeql %} extension for {% data variables.product.prodname_vscode %} makes it easy to run a query to find problems in codebases.' +product: '{% data reusables.gated-features.codeql %}' +versions: + fpt: '*' + ghes: '*' + ghec: '*' +topics: + - Advanced Security + - Code scanning + - CodeQL +children: + - /about-codeql-for-vs-code + - /installing-codeql-for-vs-code + - /managing-codeql-databases + - /running-codeql-queries + - /exploring-data-flow-with-path-queries + - /running-codeql-queries-at-scale-with-multi-repository-variant-analysis +--- + diff --git a/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/installing-codeql-for-vs-code.md b/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/installing-codeql-for-vs-code.md new file mode 100644 index 000000000000..60d2d2476625 --- /dev/null +++ b/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/installing-codeql-for-vs-code.md @@ -0,0 +1,69 @@ +--- +title: Installing CodeQL for Visual Studio Code +shortTitle: Extension installation +versions: + fpt: '*' + ghec: '*' + ghes: '*' +topics: + - Advanced Security + - Code scanning + - CodeQL +type: reference +intro: 'To get started with {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %}, you need to install and set up the extension.' +allowTitleToDifferFromFilename: true +--- + +## Prerequisites + +The {% data variables.product.prodname_codeql %} extension requires a minimum of {% data variables.product.prodname_vscode %} 1.82.0. Older versions are not supported. + +## Installing the extension + +You can install the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension using one of several different methods: + +- Using the {% data variables.product.prodname_vscode %} Marketplace in a browser. + +- Searching in the "Extensions" view in {% data variables.product.prodname_vscode %}. + +- Using a VSIX file. + +### Using the {% data variables.product.prodname_vscode %} Marketplace + +1. In your browser, go to the ["{% data variables.product.prodname_codeql %}" page](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-codeql) in the {% data variables.product.prodname_vscode %} Marketplace. + +1. Click **Install**, then follow the on-screen prompts. + +### Searching in the "Extensions" view + +1. In {% data variables.product.prodname_vscode_shortname %}, open the "Extensions" view. + +1. Search for "{% data variables.product.prodname_codeql %}", then click **Install**. + +### Using the {% data variables.product.prodname_codeql %} VSIX file + +1. Download the [{% data variables.product.prodname_codeql %} VSIX file](https://github.com/github/vscode-codeql/releases) from the `github/vscode-codeql` repository on {% data variables.product.prodname_dotcom %}. + +1. In {% data variables.product.prodname_vscode_shortname %}, open the "Extensions" view. + +1. At the top right of the sidebar, click the ellipsis then click **Install from VSIX...**. + +1. Select the {% data variables.product.prodname_codeql %} VSIX file downloaded in step 1. + +1. Follow the on-screen prompts to complete the installation. + +## Next steps + +To learn how to work with {% data variables.product.prodname_codeql %} databases in the extension, see "[AUTOTITLE](/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/managing-codeql-databases)." + +If you have already found, downloaded, or created a {% data variables.product.prodname_codeql %} database, you can learn how to use the extension to run queries on {% data variables.product.prodname_codeql %} databases and view the results. For more information, see "[AUTOTITLE](/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries)." + +{% ifversion codeql-model-packs %} + +To learn how to model additional dependencies of a codebase and improve your {% data variables.product.prodname_code_scanning %} results, see "[AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/using-the-codeql-model-editor)." + +{% endif %} + +To learn how to configure access to a different version of the {% data variables.product.prodname_codeql_cli %} than the one installed with the extension, see "[AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/configuring-access-to-the-codeql-cli)." + +To learn how to set up a {% data variables.product.prodname_codeql %} workspace, see "[AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/setting-up-a-codeql-workspace)." diff --git a/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/managing-codeql-databases.md b/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/managing-codeql-databases.md new file mode 100644 index 000000000000..381b4e40afd8 --- /dev/null +++ b/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/managing-codeql-databases.md @@ -0,0 +1,48 @@ +--- +title: Managing CodeQL databases +shortTitle: Manage CodeQL databases +versions: + fpt: '*' + ghec: '*' + ghes: '*' +topics: + - Advanced Security + - Code scanning + - CodeQL +type: reference +intro: 'You can work with {% data variables.product.prodname_codeql %} databases using the extension.' +--- + +## About {% data variables.product.prodname_codeql %} databases + +To analyze a project, you need to select a {% data variables.product.prodname_codeql %} database for that project. You can select a database locally (from a ZIP archive or an unarchived folder), from a public URL, or from a project's URL on {% data variables.product.prodname_dotcom_the_website %}. To read about how to create a database with the {% data variables.product.prodname_codeql_cli %}, see "[AUTOTITLE](/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-databases)." + +### Downloading a database from {% data variables.product.prodname_dotcom %} + +{% data variables.product.prodname_dotcom %} stores {% data variables.product.prodname_codeql %} databases for over 200,000 repositories on {% data variables.product.prodname_dotcom_the_website %}. + +You can check if a repository has any {% data variables.product.prodname_codeql %} databases available for download, and if so download it, using the REST API. For more information, see "[List {% data variables.product.prodname_codeql %} databases for a repository](/rest/code-scanning/code-scanning#list-codeql-databases-for-a-repository)" and "[Get a {% data variables.product.prodname_codeql %} database for a repository](/rest/code-scanning/code-scanning#get-a-codeql-database-for-a-repository)" in the {% data variables.product.prodname_dotcom %} REST API documentation. + +## Choosing a database to analyze + +1. Hover over the title bar of the "Databases" view and choose the appropriate icon to select your database. You can select a local database (from a ZIP archive or an unarchived folder), from a public URL, or from a project's URL on {% data variables.product.prodname_dotcom_the_website %}. + +1. Once you've chosen a database, it will be displayed in the "Databases" view. To see the menu options for interacting with a database, right-click an entry in the list. You can select multiple databases at once. + +{% note %} + +**Note:** You can also analyze test databases. Test databases (folders with a `.testproj` extension) are generated when you run regression tests on custom queries using the {% data variables.product.prodname_codeql_cli %}. If a query fails a regression test, you may want to import the test database into {% data variables.product.prodname_vscode %} to debug the failure. For more information about running query tests, see "[AUTOTITLE](/code-security/codeql-cli/using-the-codeql-cli/testing-custom-queries)." + +{% endnote %} + +## Filtering databases and queries by language + +Optionally, to see databases containing a specific language and queries written for that language, you can apply a language filter using the language selector. + +1. To see available language filters, in the sidebar, open the "Language" view. + +1. Hover over the language filter you would like to apply, then click **Select**. + +## Next steps + +To learn how to use the extension to analyze your projects by running queries on {% data variables.product.prodname_codeql %} databases, see "[AUTOTITLE](/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries)." diff --git a/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries-at-scale-with-multi-repository-variant-analysis.md b/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries-at-scale-with-multi-repository-variant-analysis.md new file mode 100644 index 000000000000..17ee54a3020a --- /dev/null +++ b/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries-at-scale-with-multi-repository-variant-analysis.md @@ -0,0 +1,177 @@ +--- +title: Running CodeQL queries at scale with multi-repository variant analysis +shortTitle: Queries at scale +versions: + feature: codeql-vs-code-mrva +topics: + - Advanced Security + - Code scanning + - CodeQL +type: reference +intro: 'You can run {% data variables.product.prodname_codeql %} queries on a large number of repositories on {% data variables.product.prodname_dotcom_the_website %} from {% data variables.product.prodname_vscode %}.' +--- + +{% data reusables.code-scanning.mrva-beta %} + +## About running {% data variables.product.prodname_codeql %} queries at scale with multi-repository variant analysis + +With multi-repository variant analysis (MRVA), you can run {% data variables.product.prodname_codeql %} queries on a list of up to 1,000 repositories on {% data variables.product.prodname_dotcom_the_website %} from {% data variables.product.prodname_vscode %}. + +When you run MRVA against a list of repositories, your query is run against each repository that has a {% data variables.product.prodname_codeql %} database available to analyze. {% data variables.product.company_short %} creates and stores the latest {% data variables.product.prodname_codeql %} database for the default branch of thousands of public repositories, including every repository that runs {% data variables.product.prodname_code_scanning %} using {% data variables.product.prodname_codeql %}. + +You need to enable {% data variables.product.prodname_code_scanning %} using {% data variables.product.prodname_codeql %} on {% data variables.product.prodname_dotcom_the_website %}, using either default setup or advanced setup, before adding your repository to a list for analysis. For information about enabling {% data variables.product.prodname_code_scanning %} using {% data variables.product.prodname_codeql %}, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning-for-a-repository#configuring-code-scanning-automatically)." + +### How MRVA runs queries against {% data variables.product.prodname_codeql %} databases on {% data variables.product.prodname_dotcom_the_website %} + +When you run MRVA, the analysis is run entirely using {% data variables.product.prodname_actions %}. You don't need to create any workflows, but you must specify which {% data variables.product.prodname_dotcom %} repository the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension should use as a controller repository. As the analysis of each repository completes, the results are sent to {% data variables.product.prodname_vscode_shortname %} for you to view. + +The {% data variables.product.prodname_codeql %} extension builds a {% data variables.product.prodname_codeql %} pack with your library and any library dependencies. The {% data variables.product.prodname_codeql %} pack and your selected repository list are posted to an API endpoint on {% data variables.product.prodname_dotcom_the_website %}, which triggers a {% data variables.product.prodname_actions %} dynamic workflow in your controller repository. The workflow spins up multiple parallel jobs to execute the {% data variables.product.prodname_codeql %} query against the repositories in the list, optimizing query execution. As each repository is analyzed, the results are processed and displayed in {% data variables.product.prodname_vscode_shortname %}. + +### Prerequisites + +- You must define a controller repository before you can run your first multi-repository variant analysis. + +- Controller repositories can be empty, but they must have at least one commit. + +- The controller repository visibility can be "public" if you plan to analyze public repositories. The variant analysis will be free. + +- The controller repository visibility must be "private" if you need to analyze any private or internal repositories. {% ifversion fpt or ghec %} Any actions minutes used by variant analysis, above the free limit, will be charged to the repository owner. For more information about free minutes and billing, see "[AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions)."{% endif %} + +## Setting up a controller repository for MRVA + +1. In the "Variant Analysis Repositories" view, click **Set up controller repository** to display a field for the controller repository. + + ![Screenshot of the "Variant Analysis Repositories" view. The button to "Set up controller repository" is highlighted in dark orange.](/assets/images/help/security/codeql-for-vs-code-controller-repository.png) + +1. Type the owner and name of the repository on {% data variables.product.prodname_dotcom_the_website %} that you want to use as your controller repository and press the **Enter** key. + +1. If you are prompted to authenticate with {% data variables.product.company_short %}, follow the instructions and sign in to your personal or organization account. When you have finished, a prompt from {% data variables.product.company_short %} Authentication may ask for permission to open in {% data variables.product.prodname_vscode %}, click **Open**. + +The name of the controller repository is saved in your settings for the {% data variables.product.prodname_codeql %} extension. For information on how to edit the controller repository, see "[AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings)." + +## Running a query at scale using MRVA + +1. By default, the "Variant Analysis Repositories" view shows the default lists of the Top 10, Top 100, and Top 1000 public repositories on {% data variables.product.prodname_dotcom_the_website %} for the language that you are analyzing. + +1. Optionally, you can add a new repository, organization, or list. For more information, see "[Creating custom lists of repositories](#creating-a-custom-list-of-repositories). + +1. Select which {% data variables.product.company_short %} repository or repositories you want to run your query against. + + ![Screenshot of the "Variant Analysis Repositories" view. The "octo-org/octo-repo" row is highlighted blue and its "Select" button outlined in orange.](/assets/images/help/security/codeql-for-vs-code-variant-analysis-repo-lists.png) + +1. Open the query you want to run, right-click in the query file, and select **{% data variables.product.prodname_codeql %}: Run Variant Analysis** to start variant analysis. + +{% note %} + +**Note:** To a cancel a variant analysis run, click **Stop query** in the "Variant Analysis Results" view. + +{% endnote %} + +### Errors and warnings + +When you run MRVA, there are two key places where errors and warnings are displayed: + +- {% data variables.product.prodname_vscode %} errors: any problems with creating a {% data variables.product.prodname_codeql %} pack and sending the analysis to {% data variables.product.prodname_dotcom_the_website %} are reported as {% data variables.product.prodname_vscode %} errors in the bottom right corner of the application. Information is also available in the "Problems" view. + +- "Variant Analysis Results": any problems with the variant analysis run are reported in this view. + +## Exploring your results + +As soon as a workflow to run your variant analysis on {% data variables.product.company_short %} is running, a "Variant Analysis Results" view opens to display the results as they are ready. You can use this view to monitor progress, see any errors, and access the workflow logs in your controller repository. + +![Screenshot of "Variant Analysis Results" showing a run for "FileAccessToHttp.ql". Blue circles show the number of results found or "-" still running.](/assets/images/help/security/codeql-for-vs-code-variant-analysis-results-view.png) + +When your variant analysis run is scheduled, the "Results" view automatically opens. Initially, the view shows a list of every repository that was scheduled for analysis. As each repository is analyzed, the view is updated to show a summary of the number of results. To view the detailed results for a repository (including results paths), click the repository name. + +For each repository, you can see: + +- Number of results found by the query + +- Visibility of the repository + +- Whether analysis is still running or has finished + +- Number of stars the repository has on {% data variables.product.company_short %} + +### Seeing the results for a repository + +1. Click the repository name to show a summary of each result. + +1. Explore the information available for each result using links to the source files on {% data variables.product.prodname_dotcom_the_website %}. For data flow queries, there'll be an additional "Show paths" link. + + ![Screenshot of the "Variant Analysis Results" view, with blue links to GitHub source files. There is a "Show paths" link, highlighted in dark orange.](/assets/images/help/security/codeql-for-vs-code-variant-analysis-result.png) + +### Exporting your results + +You can export your results for further analysis or to discuss them with collaborators. In the "Results" view, click **Export results** to export the results to a secret gist on {% data variables.product.prodname_dotcom_the_website %} or to a Markdown file in your workspace. + +## Selecting a single {% data variables.product.company_short %} repository or organization for analysis + +1. In the "Variant Analysis Repositories" view, click **+** to add a new database. + +1. From the dropdown menu, select **From a {% data variables.product.company_short %} repository** or **All repositories of {% data variables.product.company_short %} org or owner**. + +1. Type the identifier of the repository or organization that you want to use into the field. + +## Creating a custom list of repositories + +{% note %} + +**Note:** {% data variables.product.prodname_codeql %} analysis always requires a {% data variables.product.prodname_codeql %} database to run queries against. When you run variant analysis against a list of repositories, your query will only be executed against the repositories that currently have a {% data variables.product.prodname_codeql %} database available to download. The best way to make a repository available for variant analysis is to enable {% data variables.product.prodname_code_scanning %} with {% data variables.product.prodname_codeql %}. For information about enabling {% data variables.product.prodname_code_scanning %} using {% data variables.product.prodname_codeql %}, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning-for-a-repository#configuring-code-scanning-automatically)." + +{% endnote %} + +1. In the "Variant Analysis Repositories" view, click the "Add list" icon. + + ![Screenshot of the "Variant Analysis Results" view. The "add-list" icon is highlighted in dark orange.](/assets/images/help/security/codeql-for-vs-code-add-list.png) + +1. Type a name for the new list and press **Enter**. + +1. Select your list in the view, then click **+** to add a repository to your list. + +### Managing your custom lists of repositories + +You can manage and edit your custom lists by right-clicking on either the list name, or a repository name within the list, and selecting an option from the context menu. + +The custom lists are stored in your workspace in a `databases.json` file. If you want to edit this file directly in {% data variables.product.prodname_vscode %}, you can open it by clicking **{ }** in the view header. + +For example, if you want to continue analyzing a set of repositories that had results for your query, click **Copy repository list** in the "Variant Analysis Results" view to add a list of only the repositories that have results to the clipboard as JSON. + +In the following example snippet, `my-organization/my-repository` had results for a query: + +```json +{ + "name": "new-repo-list", + "repositories": [ + "my-organization/my-repository" + ] +} +``` + +You can then insert the `new-repo-list` of repositories into `databases.json`for easy access in the "Variant Analysis Repositories" view. + +### Using {% data variables.product.company_short %} code search to add repositories to a custom list + +{% note %} + +**Note:** This feature uses the legacy code search via the {% data variables.product.company_short %} code search API. For more information on the syntax to use, see "[AUTOTITLE](/search-github/searching-on-github/searching-code)." + +{% endnote %} + +You can use code search directly in the {% data variables.product.prodname_codeql %} extension to add a subset of repositories from {% data variables.product.prodname_dotcom_the_website %} to a custom list. + +For example, to add all repositories in the `rails` organization on {% data variables.product.company_short %}, search `org:rails`. + +You can add a maximum of 1,000 repositories to a custom list per search. + +1. In the "Variant Analysis Repositories" view, choose the list that you want to add repositories to. You can create a new list or choose an existing list that already contains repositories. + +1. Right-click on the list you have chosen and then click **Add repositories with {% data variables.product.prodname_dotcom%} code search**. + +1. In the pop-up that appears at the top of the application, under the search bar, select a language for your search from the choices in the dropdown. + +1. In the search bar, type the search query that you want to use and press **Enter**. + +You can view the progress of your search in the bottom right corner of the application in a box with the text `Searching for repositories...`. If you click **Cancel**, no repositories will be added to your list. Once complete, you will see the resulting repositories appear in the dropdown under your custom list in the Variant Analysis Repositories view. + +Some of the resulting repositories will not have {% data variables.product.prodname_codeql %} databases and some may not allow access by the {% data variables.product.prodname_codeql %} extension for {% data variables.product.prodname_vscode %}. When you run an analysis on the list, the "Variant Analysis Results" view will show you which repositories were analyzed, which denied access, and which had no {% data variables.product.prodname_codeql %} database. diff --git a/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries.md b/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries.md new file mode 100644 index 000000000000..7ebdc44fa293 --- /dev/null +++ b/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries.md @@ -0,0 +1,162 @@ +--- +title: Running CodeQL queries +shortTitle: Run CodeQL queries +versions: + fpt: '*' + ghec: '*' + ghes: '*' +topics: + - Advanced Security + - Code scanning + - CodeQL +type: reference +intro: 'You can run queries on {% data variables.product.prodname_codeql %} databases and view the results in {% data variables.product.prodname_vscode %}.' +allowTitleToDifferFromFilename: true +--- + +## About running {% data variables.product.prodname_codeql %} queries + +The [`github/codeql`](https://github.com/github/codeql) repository contains a large number of example queries. You can access any existing queries in your workspace through the "Queries" view. + +### Prerequisites + +To analyze a codebase, you run queries against a {% data variables.product.prodname_codeql %} database extracted from the code, so you'll need to select a database to work with in the extension. You can select a database locally (from a ZIP archive or an unarchived folder), from a public URL, or from a project's URL on {% data variables.product.prodname_dotcom_the_website %}. For more information, see "[AUTOTITLE](/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/managing-codeql-databases)." + +## Running a single query + +1. In the sidebar, open the "Queries" view. + +1. To run a query against the selected database, hover over the desired query, then click the **Run local query** icon. + + ![Screenshot of the "Queries" view, with the "Run local query" button outlined in dark orange.](/assets/images/help/security/codeql-for-vs-code-running-a-query.png) + +The {% data variables.product.prodname_codeql %} extension runs the query on the current database and reports progress in the bottom-right corner of the application. When the results are ready, they're displayed in the {% data variables.product.prodname_codeql %} "Query Results" view. + +If there are any problems running a query, a notification is displayed in the bottom right corner of the application. In addition to the error message, the notification includes details of how to fix the problem. + +## Running all queries in a directory + +You can run every query in a directory. + +1. In the sidebar, open the "Queries" view. + +1. Hover over the desired directory of queries, then click the **Run local queries** icon. + +## Running a selection of queries + +You can run multiple queries with a single command. + +1. Go to the File Explorer. + +1. Select multiple files or folders that contain queries. + +1. Right-click and select **{% data variables.product.prodname_codeql %}: Run Queries in Selected Files**. + +## Running a query without any setup + +When working on a new query, you can open a "Quick Query" tab to easily execute your code and view the results, without having to save a `.ql` file in your workspace. Select **{% data variables.product.prodname_codeql %}: Quick Query** from the {% data variables.product.prodname_vscode_command_palette_shortname %}, then to run the query use **{% data variables.product.prodname_codeql %}: Run Query on Selected Database**. + +You can see all quick queries that you've run in the current session in the "Query History" view. Click an entry to see the exact text of the quick query that produced the results. For more information, see "[Viewing your query history](#viewing-your-query-history)." + +Once you're happy with your quick query, you should save it in a {% data variables.product.prodname_codeql %} pack so you can access it later. For more information, see "[AUTOTITLE](/code-security/codeql-cli/codeql-cli-reference/about-codeql-packs)." + +## Running a specific part of a query or library + +This can be helpful if you're debugging a query or library and you want to locate the part that is wrong. + +Instead of using **{% data variables.product.prodname_codeql %}: Run Query on Selected Database** to run the whole query (the [select clause](https://codeql.github.com/docs/ql-language-reference/queries/#select-clauses) and any [query predicates](https://codeql.github.com/docs/ql-language-reference/queries/#query-predicates)), you can use **{% data variables.product.prodname_codeql %}: Quick Evaluation** to run a specific part of a `.ql` or `.qll` file. + +**{% data variables.product.prodname_codeql %}: Quick Evaluation** evaluates a code snippet that you have selected, instead of the whole query, and displays results of that selection in the "Results" view. + +Possible targets for quick evaluation include: + +- Selecting the name of a {% data variables.product.prodname_codeql %} entity (such as a [class](https://codeql.github.com/docs/ql-language-reference/types/#classes) or [predicate](https://codeql.github.com/docs/ql-language-reference/predicates/#predicates)) to evaluate that entity. + +- Selecting a [formula](https://codeql.github.com/docs/ql-language-reference/formulas/#formulas) or [expression](https://codeql.github.com/docs/ql-language-reference/expressions/#expressions) with free variables to evaluate that formula or expression. + +For example, in the following snippet, you could select the predicate name `foo` or the formula `s = "bar"` for quick evaluation: + +```bash +predicate foo(string s) { s = "bar" } +``` + +## Running a query on multiple databases + +This can be helpful if you want to test your query on multiple codebases, or find a vulnerability in multiple projects. + +1. Open a query (`.ql`) file. + +1. Right-click and select **{% data variables.product.prodname_codeql %}: Run Query on Multiple Databases**. + +1. From the dropdown menu, select the databases that you want to run the query on. + +## Viewing your query history + +To see the queries that you have run in the current session, open the "Query History" view. + +The "Query History" view contains information including the date and time when the query was run, the name of the query, the database on which it was run, and how long it took to run the query: + +- To customize the information that is displayed, right-click an entry and select **Rename**. + +- Optionally, filter the view by language using the language selector. For more information, see "[Filtering databases and queries by language](#filtering-databases-and-queries-by-language)." + +- Click an entry to display the corresponding results, and double-click to display the query itself in the editor (or right-click and select **View Query**). + +- To display the exact text that produced the results for a particular entry, right-click it and select **View Query Text**. This can differ from **View Query**, as the query file may have been modified since you last ran it. + +- To remove queries from the view, select all the queries you want to remove, then right-click and select **Delete**. + +## Understanding your query results + +1. Click a query in the "Query History" view to display its results in the "Results" view. + + {% note %} + + **Note:** Depending on the query, you can also choose different views such as CSV, [AUTOTITLE](/code-security/codeql-cli/codeql-cli-reference/sarif-output), or [DIL format](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#dil). For example, to view the DIL format, right-click a result and select **View DIL**. The available output views are determined by the format and the metadata of the query. For more information, see "[{% data variables.product.prodname_codeql %} queries](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries)." + + {% endnote %} + +1. Use the dropdown menu in the "Results" view to choose which results to display, and in what form to display them, such as a formatted alert message or a table of raw results. + +1. To sort the results by the entries in a particular column, click the column header. + +If a result links to a source code element, you can click it to display it in the source. + +To use standard code navigation features in the source code, you can right-click an element and use the commands **Go to Definition** or **Go to References**. This runs a {% data variables.product.prodname_codeql %} query over the active file, which may take a few seconds. This query needs to run once for every file, so any additional references from the same file will be fast. + +{% note %} + +**Note:** If you're using an older database, code navigation commands such as **Go to Definition** and **Go to References** may not work. +To use code navigation, try unzipping the database and running `codeql database cleanup ` on the unzipped database using the {% data variables.product.prodname_codeql_cli %}. Then, re-add the database to {% data variables.product.prodname_vscode %}. For more information, see "[AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/database-cleanup)." + +{% endnote %} + +### Comparing query results + +When you're writing or debugging a query, it's useful to see how your changes affect the results. You can compare two sets of results to see exactly what has changed. To compare results, the two queries must be run on the same database. + +1. Right-click a query in the "Query History" view and select **Compare Results**. + +1. A Quick Pick menu shows all valid queries to compare with. Select a query. + +1. The "Compare" view shows the differences in the results of the two queries. + +## Troubleshooting + +To see the logs from running a particular query, right-click the query in the "Query History" view and select **Show Query Log**. If the log file is too large for the extension to open in {% data variables.product.prodname_vscode_shortname %}, the file will be displayed in your file explorer so you can open it with an external program. + +For details about compiling and running queries, as well as information about database upgrades, check the {% data variables.product.prodname_codeql %} Query Server log. For more information, see "[AUTOTITLE](/code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/accessing-logs)." + +By default, the extension deletes logs after each workspace session. To override this behavior, you can specify a custom directory for query server logs. For more information, see "[AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings)." + +You can use the **{% data variables.product.prodname_codeql %}: Restart Query Server** command to restart the query server. This restarts the server without affecting your {% data variables.product.prodname_codeql %} session history. You are most likely to need to restart the query server if you make external changes to files that the extension is using. For example, regenerating a {% data variables.product.prodname_codeql %} database that’s open in {% data variables.product.prodname_vscode_shortname %}. In addition to problems in the log, you might also see: errors in code highlighting, incorrect results totals, or duplicate notifications that a query is running. + +## Next steps + +You can optionally use the extension to create your own custom queries. For more information, see "[AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/creating-a-custom-query)." + +{% ifversion codeql-vs-code-mrva %} + +For information on running analysis at scale across many {% data variables.product.prodname_codeql %} databases, see "[AUTOTITLE](/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries-at-scale-with-multi-repository-variant-analysis)." + +{% endif %} diff --git a/content/code-security/codeql-for-vs-code/index.md b/content/code-security/codeql-for-vs-code/index.md new file mode 100644 index 000000000000..ec0ad647cea8 --- /dev/null +++ b/content/code-security/codeql-for-vs-code/index.md @@ -0,0 +1,19 @@ +--- +title: Use CodeQL inside Visual Studio Code +shortTitle: CodeQL for VS Code +allowTitleToDifferFromFilename: true +intro: 'Use the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension to write, run, and test {% data variables.product.prodname_codeql %} queries inside {% data variables.product.prodname_vscode %}.' +product: '{% data reusables.gated-features.codeql %}' +versions: + fpt: '*' + ghes: '*' + ghec: '*' +topics: + - Advanced Security + - Code scanning + - CodeQL +children: + - /getting-started-with-codeql-for-vs-code + - /using-the-advanced-functionality-of-the-codeql-for-vs-code-extension + - /troubleshooting-codeql-for-vs-code +--- diff --git a/content/code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/accessing-logs.md b/content/code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/accessing-logs.md new file mode 100644 index 000000000000..f2470ab87fe0 --- /dev/null +++ b/content/code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/accessing-logs.md @@ -0,0 +1,44 @@ +--- +title: 'Accessing logs' +shortTitle: 'Access logs' +versions: + fpt: '*' + ghec: '*' + ghes: '*' +topics: + - Advanced Security + - Code scanning + - CodeQL +type: reference +intro: 'If you need to troubleshoot problems with {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %}, there are several logs you can access.' +allowTitleToDifferFromFilename: true +--- + +## About logs + +Progress and error messages are displayed as notifications in the bottom right corner of the {% data variables.product.prodname_vscode %} workspace. These link to more detailed logs and error messages in the "Output" window. + +You can access the following logs: + +- {% data variables.product.prodname_codeql %} Extension + +- {% data variables.product.prodname_codeql %} Language Server + +- {% data variables.product.prodname_codeql %} Query Server + +- {% data variables.product.prodname_codeql %} Tests + +{% note %} + +**Note:** The {% data variables.product.prodname_codeql %} Language Server log contains more advanced debug logs for {% data variables.product.prodname_codeql %} language maintainers. You should only need these to provide details in a bug report. + +{% endnote %} + +## Accessing logs + +1. In {% data variables.product.prodname_vscode %}, open the "Output" window. + +1. Use the dropdown to select the log view you need. For example, "{% data variables.product.prodname_codeql %} Extension Log". + + ![Screenshot of the "Output" window in VS Code (as highlighted in dark orange). The dropdown is also highlighted, with "CodeQL Extension Log" selected.](/assets/images/help/security/codeql-for-vs-code-access-logs.png) + \ No newline at end of file diff --git a/content/code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/index.md b/content/code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/index.md new file mode 100644 index 000000000000..9dad800dd10d --- /dev/null +++ b/content/code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/index.md @@ -0,0 +1,16 @@ +--- +title: Troubleshooting CodeQL for VS Code +intro: 'Learn how to resolve problems with the {% data variables.product.prodname_codeql %} extension for {% data variables.product.prodname_vscode %}.' +product: '{% data reusables.gated-features.codeql %}' +versions: + fpt: '*' + ghec: '*' + ghes: '*' +topics: + - Advanced Security + - Code scanning + - CodeQL +children: + - /accessing-logs + - /warning-problem-with-controller-repository +--- diff --git a/content/code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/warning-problem-with-controller-repository.md b/content/code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/warning-problem-with-controller-repository.md new file mode 100644 index 000000000000..09b46352d29a --- /dev/null +++ b/content/code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/warning-problem-with-controller-repository.md @@ -0,0 +1,30 @@ +--- +title: 'Problem with controller repository' +versions: + feature: codeql-vs-code-mrva +topics: + - Advanced Security + - Code scanning + - CodeQL +type: reference +intro: 'If you see this warning, update your controller repository to a private repository.' +allowTitleToDifferFromFilename: true +--- + +{% data reusables.code-scanning.mrva-beta %} + +## About this warning + +```text +Publicly visible controller repository can't be used to analyze private repositories. NUMBER private repositories were not analyzed. +``` + +If you run variant analysis on a custom list of repositories, you may receive this warning as a banner in {% data variables.product.prodname_vscode %}, where NUMBER is the number of private repositories that have not been analyzed. + +## Confirming the cause of the problem + +When you run variant analysis, you'll see any errors and warnings displayed in the "Variant Analysis Results" view. + +## Fixing the problem + +To analyze private repositories, you should edit your settings to update your controller repository to a private repository. For information on how to edit the controller repository, see "[AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings#configuring-settings-for-variant-analysis)." diff --git a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/configuring-access-to-the-codeql-cli.md b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/configuring-access-to-the-codeql-cli.md new file mode 100644 index 000000000000..0fbebfe63be3 --- /dev/null +++ b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/configuring-access-to-the-codeql-cli.md @@ -0,0 +1,37 @@ +--- +title: Configuring access to the CodeQL CLI +shortTitle: CodeQL CLI access +versions: + fpt: '*' + ghec: '*' + ghes: '*' +topics: + - Advanced Security + - Code scanning + - CodeQL +type: reference +intro: 'The {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension uses the {% data variables.product.prodname_codeql_cli %} to compile and run queries.' +allowTitleToDifferFromFilename: true +--- + +## Configuring access to the {% data variables.product.prodname_codeql_cli %} + +If you already have the {% data variables.product.prodname_codeql_cli %} installed and added to your `PATH`, the extension will use that version. This might be the case if you create your own {% data variables.product.prodname_codeql %} databases instead of downloading them from {% data variables.product.prodname_dotcom_the_website %}. For more information, see "[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis)." + +Otherwise, the extension automatically manages access to the executable of the {% data variables.product.prodname_codeql_cli %} for you. This ensures that the {% data variables.product.prodname_codeql_cli %} is compatible with the {% data variables.product.prodname_codeql %} extension. You can also check for updates with the **{% data variables.product.prodname_codeql %}: Check for CLI Updates** command from the {% data variables.product.prodname_vscode_command_palette_shortname %}. + +{% note %} + +**Notes:** + +- The extension-managed {% data variables.product.prodname_codeql_cli %} is not accessible from the terminal. If you intend to use the CLI outside of the extension (for example to create databases), we recommend that you install your own copy of the {% data variables.product.prodname_codeql_cli %}." + +- To override the default behavior and use a specific version of the {% data variables.product.prodname_codeql_cli %}, you can specify the {% data variables.product.prodname_codeql_cli %} **Executable Path** in the extension settings. For more information, see "[AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings)." + +{% endnote %} + +## Troubleshooting + +If you have any difficulty setting up access to the {% data variables.product.prodname_codeql_cli %}, check the {% data variables.product.prodname_codeql %} Extension log for error messages or to see the location of the {% data variables.product.prodname_codeql_cli %} being used. For more information, see "[AUTOTITLE](/code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/accessing-logs)." In particular, in the Extension log you can see the location of the {% data variables.product.prodname_codeql_cli %} that is being used. This is useful if you want to see whether this is an extension-managed CLI or an external one. + +If you use the extension-managed {% data variables.product.prodname_codeql_cli %}, the extension checks for updates automatically (or with the **{% data variables.product.prodname_codeql %}: Check for CLI Updates** command) and prompts you to accept the updated version. If you use an external CLI, you need to update it manually (when updates are necessary). diff --git a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/creating-a-custom-query.md b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/creating-a-custom-query.md new file mode 100644 index 000000000000..d059999bcaff --- /dev/null +++ b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/creating-a-custom-query.md @@ -0,0 +1,45 @@ +--- +title: Creating a custom query +shortTitle: Custom query creation +versions: + fpt: '*' + ghec: '*' + ghes: '*' +topics: + - Advanced Security + - Code scanning + - CodeQL +type: reference +intro: 'You can work from a template to write your own code to create a custom query to analyze a specific language.' +--- + +## About custom queries + +{% note %} + +**Note:** Creating a custom query is optional, and the [`github/codeql`](https://github.com/github/codeql) repository contains a large number of example queries you can use instead. + +{% endnote %} + +You create a new query file from a template for a given language, which imports the standard libraries for analyzing that language. For more information, see "[About {% data variables.product.prodname_codeql %} queries](https://codeql.github.com/docs/writing-codeql-queries/about-codeql-queries/)" in the {% data variables.product.prodname_codeql %} documentation. + +## Creating a custom query + +1. In the extension sidebar, open the "Queries" view, then click the **Create query** icon. + +1. In the {% data variables.product.prodname_vscode_command_palette_shortname %}, select the target language for your query. If you've chosen not to create your custom query in an existing directory, selecting a language will autogenerate a directory labeled `codeql-custom-queries-LANGUAGE`, where `LANGUAGE` is the name of the selected language. A query template labeled `example.ql` will then be added to the existing or autogenerated directory. + +1. In the template, write your custom query, then save the file. Once your query is finished, you can run it from the "Queries" view. + +## Further reading + +You can read about how to create queries for supported languages in the {% data variables.product.prodname_codeql %} documentation: + +- [{% data variables.product.prodname_codeql %} for C and C++](https://codeql.github.com/docs/codeql-language-guides/codeql-for-cpp/) +- [{% data variables.product.prodname_codeql %} for C#](https://codeql.github.com/docs/codeql-language-guides/codeql-for-csharp/) +- [{% data variables.product.prodname_codeql %} for Go](https://codeql.github.com/docs/codeql-language-guides/codeql-for-go/) +- [{% data variables.product.prodname_codeql %} for Java and Kotlin](https://codeql.github.com/docs/codeql-language-guides/codeql-for-java/) +- [{% data variables.product.prodname_codeql %} for JavaScript and TypeScript](https://codeql.github.com/docs/codeql-language-guides/codeql-for-javascript/) +- [{% data variables.product.prodname_codeql %} for Python](https://codeql.github.com/docs/codeql-language-guides/codeql-for-python/) +- [{% data variables.product.prodname_codeql %} for Ruby](https://codeql.github.com/docs/codeql-language-guides/codeql-for-ruby/) +- [{% data variables.product.prodname_codeql %} for Swift](https://codeql.github.com/docs/codeql-language-guides/codeql-for-swift/) diff --git a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings.md b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings.md new file mode 100644 index 000000000000..d695596b2746 --- /dev/null +++ b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings.md @@ -0,0 +1,134 @@ +--- +title: Customizing settings +shortTitle: Customize settings +versions: + fpt: '*' + ghec: '*' + ghes: '*' +topics: + - Advanced Security + - Code scanning + - CodeQL +type: reference +intro: 'You can edit the settings for the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension to suit your needs.' +--- + +## About settings in the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension + +You can change numerous settings for the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension, including: + +- Which version of the {% data variables.product.prodname_codeql_cli %} the extension uses. +- How the extension displays previous queries. +- How the extension runs queries. + +## Editing settings + +1. Open the "Extensions" view and right-click **{% data variables.product.prodname_codeql %}**, then click **Extension Settings**. + + ![Screenshot of the "Extensions" view, with the right-click menu displayed and "Extension Settings" outlined in dark orange.](/assets/images/help/security/codeql-for-vs-code-extensions-view.png) + +1. In the Settings window, edit settings as desired. The new settings are saved automatically. + + ![Screenshot of the CodeQL for VS Code Extension Settings window displayed inside VS Code.](/assets/images/help/security/codeql-for-vs-code-extension-settings.png) + +{% note %} + +**Note:** Alternatively, you can edit the settings in JSON format by opening the {% data variables.product.prodname_vscode_command_palette_shortname %} and selecting **Preferences: Open User Settings (JSON)**. + +{% endnote %} + +### Choosing a version of the {% data variables.product.prodname_codeql_cli %} + +To override the default behavior and use a specific version of the {% data variables.product.prodname_codeql_cli %}, you can specify the {% data variables.product.prodname_codeql_cli %} "Executable Path" in the extension settings, and point it to your existing copy of the {% data variables.product.prodname_codeql_cli %}. That is, the file named `codeql` (Linux and macOS), or `codeql.exe` (Windows). For more information about the default behavior, see "[AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/configuring-access-to-the-codeql-cli)." + +### Changing the labels of query history items + +The query history "Format" setting controls how the extension lists queries in the query history. By default, each item has a label with the following format: + +```bash +QUERY-NAME on DATABASE-NAME - QUERY-STATUS NUMBER-OF-RESULTS [QUERY-RUNTIME] +``` + +To override the default label, you can specify a different format for the query history items. + +### Changing the retention period for query history items + +By default, items in the "Query History" view are retained for 30 days. You can set a different time to live (TTL) by changing the "Query History: Ttl" setting. To retain items indefinitely, set the value to 0. + +### Configuring settings for running queries locally + +There are a number of settings under "Running Queries". For example, if your queries run too slowly and time out frequently, you may want to increase the memory by changing the "Running Queries: Memory" setting. + +If you want to examine query performance, enable the "Running Queries: Debug" setting to include timing and tuple counts. This will then be shown in the logs in the {% data variables.product.prodname_codeql %} "Query Server" tab of the "Output" view. The tuple count is useful because it indicates the size of the [predicates](https://codeql.github.com/docs/ql-language-reference/predicates/#predicates) computed by the query. + +To save query server logs in a custom location, edit the "Running Queries: Custom Log Directory" setting. If you use a custom log directory, the extension saves the logs permanently, instead of deleting them automatically after each workspace session. This is useful if you want to investigate these logs to improve the performance of your queries. + +### Configuring settings for variant analysis + +{% ifversion codeql-vs-code-mrva %} + +There are a number of settings under "Variant Analysis" that you can use to define or edit lists of {% data variables.product.company_short %} repositories for variant analysis, and change to a different controller repository. For information on the purpose and requirements for a controller repository, see "[AUTOTITLE](/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries-at-scale-with-multi-repository-variant-analysis)." + +{% endif %} + +You can also edit the items shown in the "Variant Analysis Repositories" view by editing a file in your {% data variables.product.prodname_vscode %} workspace called `databases.json`. This file contains a JSON representation of all the items displayed in the view. To open your `databases.json` file in an editor window, click the **{ }** icon in the top right of the "Variant Analysis Repositories" view. You can then see a structured representation of the repositories, organizations and lists in your view. For example: + +```json +{ + "version": 1, + "databases": { + "variantAnalysis": { + "repositoryLists": [ + { + "name": "My favorite JavaScript repos", + "repositories": [ + "facebook/react", + "babel/babel", + "angular/angular" + ] + } + ], + "owners": [ + "microsoft" + ], + "repositories": [ + "apache/hadoop" + ] + } + }, + "selected": { + "kind": "variantAnalysisSystemDefinedList", + "listName": "top_10" + } +} +``` + +You can change the items shown in the view or add new items by directly editing this file. + +### Configuring settings for adding databases + +To automatically add database source folders to your workspace, you can enable the "Adding Databases: Add Database Source to Workspace" setting. + +This setting is disabled by default. You may want to enable the setting if you regularly browse the source code of databases (for example, to view the abstract syntax tree of the code). For more information, see "[AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/exploring-the-structure-of-your-source-code)." + +{% note %} + +If you are in a single-folder workspace, adding database source folders will cause the workspace to reload as a multi-root workspace. This may cause query history and database lists to reset. + +Before enabling this setting, we recommend that you save your workspace as a multi-root workspace. For more information, see [Multi-root Workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces) in the {% data variables.product.prodname_vscode %} documentation. + +{% endnote %} + +### Configuring settings for testing queries locally + +To increase the number of threads used for testing queries, you can update the "Running Tests: Number Of Threads" setting. + +To pass additional arguments to the {% data variables.product.prodname_codeql_cli %} when running tests, you can update the "Running Tests: Additional Test Arguments" setting. For more information about the available arguments, see "[AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/test-run/)." + +### Configuring settings for telemetry and data collection + +You can configure whether the {% data variables.product.prodname_codeql %} extension collects telemetry data. This is disabled by default. For more information, see "[AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/telemetry-in-codeql-for-visual-studio-code)." + +## Further reading + +- [User and Workspace Settings](https://code.visualstudio.com/docs/getstarted/settings) in the {% data variables.product.prodname_vscode %} documentation diff --git a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/exploring-the-structure-of-your-source-code.md b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/exploring-the-structure-of-your-source-code.md new file mode 100644 index 000000000000..19abb418e38d --- /dev/null +++ b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/exploring-the-structure-of-your-source-code.md @@ -0,0 +1,38 @@ +--- +title: Exploring the structure of your source code +shortTitle: Explore code structure +versions: + fpt: '*' + ghec: '*' + ghes: '*' +topics: + - Advanced Security + - Code scanning + - CodeQL +type: reference +intro: 'You can use the AST viewer to display the abstract syntax tree of a {% data variables.product.prodname_codeql %} database.' +--- + +## About the abstract syntax tree + +The abstract syntax tree (AST) of a program represents the program's syntactic structure. Nodes on the AST represent elements such as statements and expressions. A {% data variables.product.prodname_codeql %} database encodes these program elements and the relationships between them through a database schema. For more information about database schemas, see [{% data variables.product.prodname_codeql %} glossary](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#ql-database-schema) in the {% data variables.product.prodname_codeql %} documentation. + +{% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} contains an AST viewer. The viewer consists of a graph visualization view that lets you explore the AST of a file in a {% data variables.product.prodname_codeql %} database. This helps you see which {% data variables.product.prodname_codeql %} classes correspond to which parts of your source files. + +## Viewing the abstract syntax tree of a source file + +{% note %} + +**Note:** If you don't have an appropriate query (usually `printAST.ql`) in your workspace, the **{% data variables.product.prodname_codeql %}: View AST** command in the following steps won't work. To fix this, you can update your copy of the [`github/codeql`](https://github.com/github/codeql) repository from the `main` branch. If you do this, query caches may be discarded, so your next query runs may be slower. + +{% endnote %} + +1. Open the "Databases" view in the extension, and right-click the database that you want to explore. Click **Add Database Source to Workspace**. + +1. Navigate to a {% data variables.product.prodname_codeql %} database's source file in the File Explorer. + +1. Run **{% data variables.product.prodname_codeql %}: View AST** from the {% data variables.product.prodname_vscode_command_palette_shortname %}. This runs a {% data variables.product.prodname_codeql %} query (usually called `printAST.ql`) over the active file, which may take a few seconds. Once the query is complete, the AST viewer will display the structure of the source file. + +1. To see the nested structure of the source file, click the arrows and expand the nodes. + +You can click a node in the AST viewer to jump to it in the source code. Conversely, if you click a section of the source code, the AST viewer displays the corresponding node. diff --git a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/index.md b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/index.md new file mode 100644 index 000000000000..746c0ec033fc --- /dev/null +++ b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/index.md @@ -0,0 +1,24 @@ +--- +title: Using the advanced functionality of the {% data variables.product.prodname_codeql %} for VS Code extension +shortTitle: Advanced functionality +intro: 'The {% data variables.product.prodname_codeql %} extension for {% data variables.product.prodname_vscode %} adds rich language support for {% data variables.product.prodname_codeql %} and supports writing queries to find problems in codebases.' +product: '{% data reusables.gated-features.codeql %}' +versions: + fpt: '*' + ghes: '*' + ghec: '*' +topics: + - Advanced Security + - Code scanning + - CodeQL +children: + - /using-the-codeql-model-editor + - /creating-a-custom-query + - /managing-codeql-packs + - /exploring-the-structure-of-your-source-code + - /testing-codeql-queries-in-vs-code + - /customizing-settings + - /setting-up-a-codeql-workspace + - /configuring-access-to-the-codeql-cli + - /telemetry-in-codeql-for-visual-studio-code +--- diff --git a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/managing-codeql-packs.md b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/managing-codeql-packs.md new file mode 100644 index 000000000000..1e793a39b0af --- /dev/null +++ b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/managing-codeql-packs.md @@ -0,0 +1,67 @@ +--- +title: Managing CodeQL query packs and library packs +shortTitle: Manage CodeQL packs +versions: + fpt: '*' + ghec: '*' + ghes: '*' +topics: + - Advanced Security + - Code scanning + - CodeQL +type: reference +intro: 'You can view, write, and edit {% data variables.product.prodname_codeql %} query and library packs in {% data variables.product.prodname_vscode %} using the {% data variables.product.prodname_codeql %} extension.' +allowTitleToDifferFromFilename: true +--- + +{% data reusables.codeql-cli.beta-note-package-management %} + +## Benefits of using the {% data variables.product.prodname_codeql %} extension for {% data variables.product.prodname_vscode %} to work with packs + +With the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension, you can: + +- Write {% data variables.product.prodname_codeql %} query packs without needing to check out the standard libraries in your workspace. + +- Install dependencies for {% data variables.product.prodname_codeql %} query packs inside your {% data variables.product.prodname_vscode_shortname %} workspace. + +- Download {% data variables.product.prodname_codeql %} query packs. + +- View a {% data variables.product.prodname_codeql %} query pack and all of its dependencies. + +For more information about creating and editing {% data variables.product.prodname_codeql %} query and library packs, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs)." + +## Installing dependencies for {% data variables.product.prodname_codeql %} query packs + +1. In {% data variables.product.prodname_vscode_shortname %}, open the {% data variables.product.prodname_vscode_command_palette_shortname %} and run **{% data variables.product.prodname_codeql %}: Install Pack Dependencies**. + +1. Select the packs that you want to install dependencies for. + +## Downloading {% data variables.product.prodname_codeql %} query packs + +1. In {% data variables.product.prodname_vscode_shortname %}, open the {% data variables.product.prodname_vscode_command_palette_shortname %} and run **{% data variables.product.prodname_codeql %}: Download Packs**. + +1. You can download all the core query packs, or enter the full name of a specific pack to download. You can download query packs created by other users. + +## Viewing a {% data variables.product.prodname_codeql %} query pack and its dependencies + +1. In {% data variables.product.prodname_vscode_shortname %}, open the `qlpack.yml` file in the root of any {% data variables.product.prodname_codeql %} pack directory. + +1. In the `dependencies` section of the `qlpack.yml` file, you'll see what libraries the pack depends on. + +1. Optionally, you can use {% data variables.product.prodname_vscode_shortname %}'s Intellisense features. For example, if you hover over an element from a library depended on by the pack, {% data variables.product.prodname_vscode %} will resolve it so you can see documentation about the element. + +1. To view the full definition of an element of a query, you can right-click and select **Go to Definition**. + + - If the library pack is present within the same {% data variables.product.prodname_vscode %} workspace, this will take you to the definition within the workspace. + + - Otherwise, you will see the definition stored in your package cache, where downloaded dependencies are saved. The package cache is a shared location that is stored in your home directory by default. + +{% ifversion codeql-model-packs %} + +## Working with {% data variables.product.prodname_codeql %} model packs + +{% data reusables.code-scanning.beta-model-packs %} + +{% data variables.product.prodname_codeql %} model packs can be used to expand {% data variables.product.prodname_code_scanning %} analysis to include dependencies that are not supported by default. The {% data variables.product.prodname_codeql %} extension for {% data variables.product.prodname_vscode %} includes a dedicated editor for creating and editing model packs. For information on using the model editor, see "[AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/using-the-codeql-model-editor)." + +{% endif %} diff --git a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/setting-up-a-codeql-workspace.md b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/setting-up-a-codeql-workspace.md new file mode 100644 index 000000000000..e637f7aab9c4 --- /dev/null +++ b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/setting-up-a-codeql-workspace.md @@ -0,0 +1,65 @@ +--- +title: Setting up a CodeQL workspace +shortTitle: CodeQL workspace setup +versions: + fpt: '*' + ghec: '*' + ghes: '*' +topics: + - Advanced Security + - Code scanning + - CodeQL +type: reference +intro: 'When you''re working with {% data variables.product.prodname_codeql %}, you need access to the standard libraries and queries.' +allowTitleToDifferFromFilename: true +--- + +## Setting up a {% data variables.product.prodname_codeql %} workspace + +There are several different ways to give the extension access to the standard libraries and queries from the [`github/codeql`](https://github.com/github/codeql) repository: + +- Use the {% data variables.product.prodname_codeql %} starter workspace, which contains a series of directories named in the format `codeql-custom-queries-LANGUAGE`. These are ready for you to start developing your own custom queries for each language, using the standard libraries. There are also some example queries to get you started. This is the recommended method. + +- Update an existing workspace for {% data variables.product.prodname_codeql %}. This is recommended for advanced users. + +- {% data variables.product.prodname_codeql_cli %} users can open the directory containing their extracted {% data variables.product.prodname_codeql_cli %} archive. + +### Option 1: Using the starter workspace (recommended) + +{% note %} + +**Note:** The {% data variables.product.prodname_codeql %} repository is included as a submodule in the starter workspace. You should use `git submodule update --remote` regularly to keep the submodules up to date, and ensure that they remain compatible with newer versions of the {% data variables.product.prodname_vscode_shortname %} extension and the {% data variables.product.prodname_codeql_cli %}. + +{% endnote %} + +1. Clone the [vscode-codeql-starter repository](https://github.com/github/vscode-codeql-starter/) to your computer. Make sure you include the submodules, either by using `git clone --recursive`, or by using `git submodule update --init --remote` after cloning. + +1. In {% data variables.product.prodname_vscode_shortname %}, click **File** then **Open Workspace from File...** to open the `vscode-codeql-starter.code-workspace` file from your checkout of the workspace repository. + +### Option 2: Updating an existing workspace for {% data variables.product.prodname_codeql %} (advanced) + +1. In {% data variables.product.prodname_vscode_shortname %}, select **File** then **Add Folder to Workspace...**, and find your local checkout of the [{% data variables.product.prodname_codeql %} repository](https://github.com/github/codeql). + +1. Create one new directory per target language to hold custom queries and libraries, using either the **New Folder** or **Add Folder to Workspace...** options. + +1. Create a `qlpack.yml` file in each target language directory (the `main` branch of `github/codeql` already has these files). This tells the {% data variables.product.prodname_codeql_cli %} the target language for that directory and what its dependencies are. {% data variables.product.prodname_codeql %} will look for the dependencies in all the open workspace directories, or on the user's search path. + + For example, to make a custom {% data variables.product.prodname_codeql %} directory called `my-custom-cpp-pack` depend on the {% data variables.product.prodname_codeql %} standard library for C++, create a `qlpack.yml` file with the following contents: + + ```yaml + name: my-custom-cpp-pack + version: 0.0.0 + libraryPathDependencies: codeql/cpp-all + ``` + + For more information about why you need to add a `qlpack.yml` file, see "[AUTOTITLE](/code-security/codeql-cli/codeql-cli-reference/about-codeql-packs)." + +### Option 3: Open the directory containing the extracted {% data variables.product.prodname_codeql_cli %} archive + +{% note %} + +**Note:** For this option, you need to set up the {% data variables.product.prodname_codeql_cli %}. For more information, see "[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli)." + +{% endnote %} + +In {% data variables.product.prodname_vscode_shortname %}, open the directory where you extracted the {% data variables.product.prodname_codeql_cli %} .zip archive to create a {% data variables.product.prodname_codeql %} directory (for example `codeql-home`). diff --git a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/telemetry-in-codeql-for-visual-studio-code.md b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/telemetry-in-codeql-for-visual-studio-code.md new file mode 100644 index 000000000000..44def2fcd569 --- /dev/null +++ b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/telemetry-in-codeql-for-visual-studio-code.md @@ -0,0 +1,80 @@ +--- +title: Telemetry in CodeQL for Visual Studio Code +shortTitle: Telemetry +versions: + fpt: '*' + ghec: '*' + ghes: '*' +topics: + - Advanced Security + - Code scanning + - CodeQL +type: reference +allowTitleToDifferFromFilename: true +intro: 'If you specifically opt in to permit {% data variables.product.company_short %} to do so, {% data variables.product.company_short %} will collect usage data and metrics for the purposes of helping the core developers to improve the {% data variables.product.prodname_codeql %} extension for {% data variables.product.prodname_vscode_shortname %}.' +--- + +This data will not be shared with any parties outside of {% data variables.product.company_short %}. IP addresses and installation IDs will be retained for a maximum of 30 days. Anonymous data will be retained for a maximum of 180 days. + +{% note %} + +**Note:** Telemetry collection is disabled by default in {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %}. When telemetry collection is disabled, no data will be sent to {% data variables.product.company_short %} servers. + +{% endnote %} + +## Why we collect data + +{% data variables.product.company_short %} collects aggregated, anonymous usage data and metrics to help us improve {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode_shortname %}. IP addresses and installation IDs are collected only to ensure that anonymous data is not duplicated during aggregation. + +## What data is collected + +If you opt in, {% data variables.product.company_short %} collects the following information related to the usage of the extension. The data collected are: + +- The identifiers of any {% data variables.product.prodname_codeql %}-related {% data variables.product.prodname_vscode_shortname %} commands that are run. For each command, these are: the timestamp, time taken, and whether or not the command completed successfully. + +- Interactions with UI elements, including buttons, links, and other inputs. Intereacts that are not recorded are: link targets, text inputs, mouse movement, and mouse hovering. + +- Occurrence of exceptions and errors. All sensitive information such as file paths and non-static exception message content are removed before uploading. + +- The {% data variables.product.prodname_vscode_shortname %} extension version. + +- Randomly generated GUID that uniquely identifies a {% data variables.product.prodname_codeql %} extension installation. This is discarded before aggregation. + +- IP address of the client sending the telemetry data. This is discarded before aggregation. + +- Whether any {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode_shortname %} extension settings are configured. For more information about customizing settings, see "[AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings)." + +## How long data is retained + +IP addresses and GUIDs will be retained for a maximum of 30 days. Anonymous, aggregated data that includes command identifiers, run times, and timestamps will be retained for a maximum of 180 days. + +## Access to the data + +IP addresses and GUIDs will only be available to the core developers of {% data variables.product.prodname_codeql %}. Aggregated data will be available to {% data variables.product.company_short %} employees. + +## What data is not collected + +We only collect the minimal amount of data we need to answer the questions about how our users are experiencing this product. To that end, we do not collect the following information: + +- {% data variables.product.company_short %} user ID + +- {% data variables.product.prodname_codeql %} database names or contents + +- Contents of {% data variables.product.prodname_codeql %} queries + +- File system paths + +- User-input text + +- Mouse interactions, such as movement or hovers + +## Disabling telemetry reporting + +You can disable telemetry collection by setting `codeQL.telemetry.enableTelemetry` to `false` in your settings. For more information, see "[AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings)." + +Additionally, telemetry collection will be disabled if the global `telemetry.telemetryLevel` setting is set to `off`. For more information about global telemetry collection, see [Visual Studio Code FAQ](https://code.visualstudio.com/docs/supporting/faq#_how-to-disable-telemetry-reporting) in the {% data variables.product.prodname_vscode %} documentation. + +## Further reading + +- "[AUTOTITLE](/free-pro-team@latest/site-policy/privacy-policies/github-general-privacy-statement)" +- "[AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-terms-of-service)" diff --git a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/testing-codeql-queries-in-vs-code.md b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/testing-codeql-queries-in-vs-code.md new file mode 100644 index 000000000000..3c2f9a3e2f5f --- /dev/null +++ b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/testing-codeql-queries-in-vs-code.md @@ -0,0 +1,57 @@ +--- +title: Testing CodeQL queries in Visual Studio Code +shortTitle: Test CodeQL queries +versions: + fpt: '*' + ghec: '*' + ghes: '*' +topics: + - Advanced Security + - Code scanning + - CodeQL +type: reference +intro: 'You can run unit tests for {% data variables.product.prodname_codeql %} queries using the {% data variables.product.prodname_vscode %} extension.' +allowTitleToDifferFromFilename: true +--- + +## About testing queries in {% data variables.product.prodname_vscode_shortname %} + +To ensure that your {% data variables.product.prodname_codeql %} queries produce the expected results, you can run tests that compare the expected query results with the actual results. + +The {% data variables.product.prodname_codeql %} extension automatically registers itself with the "Testing" view. This view displays all tests found in your current workspace and provides a UI for exploring and running tests in your workspace. + +For more information about creating {% data variables.product.prodname_codeql %} tests, see "[AUTOTITLE](/code-security/codeql-cli/using-the-codeql-cli/testing-custom-queries)". + +To see more detailed output from running unit tests, open the {% data variables.product.prodname_codeql %} Tests log. For information, see "[AUTOTITLE](/code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/accessing-logs)." + +## Testing the results of your queries + +1. In {% data variables.product.prodname_vscode %}, open the "Testing" view in the sidebar. + +1. To run a specific test, hover over the file or folder name and click the play button. To run all tests in your workspace, click the play button at the top of the view. If a test takes too long to run, you can click the stop button at the top of the view to cancel the test. + + ![Screenshot of the "Testing" view, with the "Run Test" button (to run all tests) outlined in dark orange.](/assets/images/help/security/codeql-for-vs-code-run-all-tests.png) + +1. The icons show whether a test passed or failed. If it failed, click the test in the "Test Results" to display the differences between the expected output and the actual output. + + ![Screenshot of the "Test Results" view displaying the differences between the expected output and actual output for a test.](/assets/images/help/security/codeql-for-vs-code-test-output.png) + +1. Compare the results. If you want to update the test with the actual output, right-click the test in the "Testing" view and click **Accept Test Output**. + +## Monitoring the performance of your queries + +Query performance is important when you want to run a query on large databases, or as part of your continuous integration system. + +If you want to examine query performance, enable the "Running Queries: Debug" setting to include timing and tuple counts. This will then be shown in the logs in the {% data variables.product.prodname_codeql %} "Query Server" tab of the "Output" view. The tuple count is useful because it indicates the size of the [predicates](https://codeql.github.com/docs/ql-language-reference/predicates/#predicates) computed by the query. For more information about changing settings, see "[AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings#configuring-settings-for-running-queries-locally)." + +When a query is evaluated, the query server caches the predicates that it calculates. So when you want to compare the performance of two evaluations, you should run **{% data variables.product.prodname_codeql %}: Clear Cache** to clear the query server's cache before each run. This ensures that you're comparing equivalent data. + +For more information about monitoring the performance of your {% data variables.product.prodname_codeql %} queries, see "[Troubleshooting query performance](https://codeql.github.com/docs/writing-codeql-queries/troubleshooting-query-performance/#troubleshooting-query-performance)" and "[Evaluation of QL programs](https://codeql.github.com/docs/ql-language-reference/evaluation-of-ql-programs/#evaluation-of-ql-programs)" in the {% data variables.product.prodname_codeql %} documentation. + +{% ifversion codeql-vs-code-mrva %} + +## Next steps + +When you are sure that your query finds the results you want to identify, you can use variant analysis to run it at scale. For information on running analysis at scale across many {% data variables.product.prodname_codeql %}databases, see "[AUTOTITLE](/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries-at-scale-with-multi-repository-variant-analysis)." + +{% endif %} diff --git a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/using-the-codeql-model-editor.md b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/using-the-codeql-model-editor.md new file mode 100644 index 000000000000..c82ef67ae5fa --- /dev/null +++ b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/using-the-codeql-model-editor.md @@ -0,0 +1,162 @@ +--- +title: Using the CodeQL model editor +shortTitle: CodeQL model editor +versions: + feature: 'codeql-model-packs' +topics: + - Advanced Security + - Code scanning + - CodeQL +type: reference +intro: 'You can view, write, and edit {% data variables.product.prodname_codeql %} model packs in {% data variables.product.prodname_vscode %}.' +--- + +{% data reusables.code-scanning.beta-model-packs %} + +## About the {% data variables.product.prodname_codeql %} model editor + +With {% data variables.product.prodname_codeql %} model packs, you can expand your {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} analysis to recognize custom libraries and frameworks used by your codebase that are not supported by default. With the {% data variables.product.prodname_codeql %} model editor, you can create your own model packs. The 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. + +For more information about customizing {% data variables.product.prodname_code_scanning %} analysis with model packs, including downloading others' packs to run in your own analysis, see "[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#using-model-packs-to-analyze-calls-to-custom-dependencies)." + +When you open the model editor, it analyzes the currently selected {% data variables.product.prodname_codeql %} database and identifies where the application uses external APIs and all public methods. An external (or third-party) API is any API that is not part of the {% data variables.product.prodname_codeql %} database you have selected. + +The model editor has two different modes: + +- _Application mode_ (default view): The editor lists each external framework used by the selected {% data variables.product.prodname_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 {% data variables.product.prodname_codeql %} results for a specific codebase. + +- _Dependency mode_: The editor identifies all of the publicly accessible APIs in the selected {% data variables.product.prodname_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 {% data variables.product.prodname_codeql %} analysis for all codebases that use the dependency. + +## Displaying the {% data variables.product.prodname_codeql %} model editor + +{% note %} + +**Note:** To use this beta functionality, install the latest version of the {% data variables.product.prodname_codeql %} extension for {% data variables.product.prodname_vscode %}. + +{% endnote %} + +1. Open your {% data variables.product.prodname_codeql %} workspace in {% data variables.product.prodname_vscode_shortname %}. For example, the [`vscode-codeql-starter` workspace](https://github.com/github/vscode-codeql-starter). If you are using the starter workspace, update the `ql` submodule from `main` to ensure that you have the queries used to gather data for the model editor. + +1. In {% data variables.product.prodname_vscode %}, click **QL** in the left sidebar to display the {% data variables.product.prodname_codeql %} extension. + +1. In the "Databases" view, select the {% data variables.product.prodname_codeql %} database that you want to model from. + +1. In the {% data variables.product.prodname_codeql %} "Method Modeling" view, click **Start modeling** to display the model editor. Alternatively, use the {% data variables.product.prodname_vscode_command_palette_shortname %} to run the **{% data variables.product.prodname_codeql %}: Open Model Editor (Beta)** command. + +1. The {% data variables.product.prodname_codeql %} model editor runs a series of telemetry queries to identify APIs in the code, and the editor is displayed in a new tab. + +1. When the telemetry queries are complete, the APIs that have been identified are shown in the editor. + +{% tip %} + +**Tip:** You can move the {% data variables.product.prodname_codeql %} "Method Modeling" view from the primary sidebar to the secondary sidebar, if you want more space while you are modeling calls or methods. If you close the view, you can reopen it from the "View" menu in {% data variables.product.prodname_vscode_shortname %} and clicking **Open View...**. + +{% endtip %} + +## Modeling the calls your codebase makes to external APIs + +You typically use this approach when you are looking at a specific codebase where you want to improve the precision of {% data variables.product.prodname_codeql %} results. This is useful when the codebase uses frameworks or libraries that are not supported by {% data variables.product.prodname_codeql %}, and if the source code of the framework or library is not included in the analysis. + +This section uses an open source Java project called "sofa-jraft" as an example. The experience of modeling calls to external APIs written in other compiled languages is similar. + +1. In {% data variables.product.prodname_vscode %}, select the {% data variables.product.prodname_codeql %} database that you want to improve {% data variables.product.prodname_codeql %} coverage for. + +1. Display the {% data variables.product.prodname_codeql %} model editor. By default the editor runs in application mode, so the list of external APIs used by the selected codebase is shown. + + ![Screenshot of the "Application mode" view of the CodeQL model pack editor in Visual Studio Code showing two of the external Java frameworks used by the "sofa-jraft" codebase.](/assets/images/help/security/codeql-for-vs-code-model-application-mode.png) + +1. Click to expand an external API and view the list of calls from the codebase to the external dependency. + + ![Screenshot of the "Application mode" view of the CodeQL model pack editor in Visual Studio Code showing the calls to the "rocksdbjni" framework ready for modeling. The "View" option for the first call is highlighted with a dark orange outline.](/assets/images/help/security/codeql-for-vs-code-model-application-mode-expanded.png) + +1. Click **View** associated with an API call or method to show where it is used in your codebase. + +1. The file containing the first call from your codebase to the API is opened, and a {% data variables.product.prodname_codeql %} "Methods Usage" view is displayed in {% data variables.product.prodname_vscode_shortname %} (where the "Problems" and "Terminal" views are usually displayed). The {% data variables.product.prodname_codeql %} "Methods Usage" view lists of all the calls from your code to the API, grouped by method. You can click through each use to decide how to model your use of the method. + +1. When you have determined how to model your use of the method, you can select a different model type. Click the dropdown under "Model Type" in the {% data variables.product.prodname_codeql %} "Method Modeling" view of the {% data variables.product.prodname_codeql %} extension. This change is automatically reflected in the main model editor. + +1. The remaining fields in that row are updated with the options available for the chosen model type: + + - "Source": choose the "Output" element to model. + - "Sink": choose the "Input" element to model. + - "Flow summary": choose the "Input" and "Output" elements to model. + +1. Define the "Kind" of dataflow for the model. + +1. When you have finished modeling, display the main model editor and click **Save all** or **Save** (shown at the bottom-right of each expanded list of methods). The percentage of methods modeled in the editor is updated. + +The models are stored in your workspace at `.github/codeql/extensions/CODEQL-MODEl-PACK`, where `CODEQL-MODEL-PACK` is the name of the {% data variables.product.prodname_codeql %} database that you selected. That is, the name of the repository, hyphen, the language analyzed by {% data variables.product.prodname_codeql %}. For more information, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#creating-a-codeql-model-pack)." + +The models are stored in a series of YAML data extension files, one for each external API. For example: + +```yaml +.github/codeql/extensions/sofa-jraft-java # the model pack directory + models + jmh-core.model.yml # models calls to jmh-core@1.20 + rocksdbjni.model.yml # models calls to rocksdbjni@7.7.3 +``` + +## 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 {% data variables.product.prodname_codeql %} model pack to the {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_container_registry %} for your whole organization to use. + +This section uses an open source Java project called "sofa-jraft" as an example. The experience of modeling calls to external APIs written in other compiled languages is similar. + +1. Select the {% data variables.product.prodname_codeql %} database that you want to model. + +1. Display the {% data variables.product.prodname_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. + + ![Screenshot of the "Dependency mode" view of the CodeQL model pack editor in Visual Studio Code showing three of the packages published by the "sofa-jraft" codebase.](/assets/images/help/security/codeql-for-vs-code-model-dependency-mode.png) + +1. Click to expand a package and view the list of available methods. + +1. Click **View** associated with a method to show its definition. + + ![Screenshot of the "Dependency mode" view of the CodeQL model pack editor in Visual Studio Code showing one model for the "com.alipay.sofa.jraft.option.BallotBoxOptions.getClosureQueue()" method. The "+" button is outlined in dark orange. Click this button to create a second model for the method.](/assets/images/help/security/codeql-for-vs-code-model-dependency-mode-expanded.png) + +1. When you have determined how to model the method, define the "Model type". + +1. The remaining fields in that row are updated with the options available for the chosen model type: + + - "Source": choose the "Output" element to model. + - "Sink": choose the "Input" element to model. + - "Flow summary": choose the "Input" and "Output" elements to model. + +1. Define the "Kind" of dataflow for the model. + +1. 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-PACK` is the name of the {% data variables.product.prodname_codeql %} database that you selected. That is, the name of the repository, hyphen, the language analyzed by {% data variables.product.prodname_codeql %}. For more information, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#creating-a-codeql-model-pack)." + +The models are stored in a series of YAML data extension files, one for each public method. For example: + +```yaml +.github/codeql/extensions/sofa-jraft-java # the model pack directory + models + com.alipay.sofa.jraft.option.model.yml # models public methods in package + com.alipay.sofa.jraft.rhea.options.model.yml +``` + +The editor will create a separate model file for each package that you model. + +## Modeling methods with multiple potential flows + +Some methods support more than one data flow. It is important to model all the data flows for a method, otherwise you cannot detect all the potential problems associated with using the method. First you model one data flow for the method, and then use the **+** button in the method row to specify a second data flow model. + +![Screenshot of the "Dependency mode" view of the CodeQL model pack editor in Visual Studio Code showing the public methods available in the "com.alipay.soft.jraft.option" package ready for modeling. The "View" option for the first method is highlighted with a dark orange outline.](/assets/images/help/security/codeql-for-vs-code-model-dependency-mode-plus.png) + +## Testing {% data variables.product.prodname_codeql %} model packs in {% data variables.product.prodname_vscode_shortname %} + +You can test any {% data variables.product.prodname_codeql %} model packs you create in {% data variables.product.prodname_vscode_shortname %} with the "Running Queries: Use Extension Packs" setting. For more information, see "[AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings)." This method works for both databases and for variant analysis repositories. + +- To run queries on a {% data variables.product.prodname_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.useExtensionPacks": "all",` + +- To run queries on a {% data variables.product.prodname_codeql %} database without using model packs, update your `settings.json` file with: `"codeQL.runningQueries.useExtensionPacks": "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 in results, you may need to introduce a known bug to verify that the model behaves as expected. + +## Further reading + +- [AUTOTITLE](/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) + +- [AUTOTITLE](/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) diff --git a/content/code-security/index.md b/content/code-security/index.md index 5ae6ce3e592e..ac17c53b697c 100644 --- a/content/code-security/index.md +++ b/content/code-security/index.md @@ -49,6 +49,7 @@ children: - /secret-scanning - /code-scanning - /codeql-cli + - /codeql-for-vs-code - /security-advisories - /supply-chain-security - /dependabot diff --git a/data/features/codeql-vs-code-mrva.yml b/data/features/codeql-vs-code-mrva.yml new file mode 100644 index 000000000000..7c186212b3c8 --- /dev/null +++ b/data/features/codeql-vs-code-mrva.yml @@ -0,0 +1,5 @@ +# Reference: #12703. +# Migration of CodeQL for VS Code documentation +versions: + fpt: '*' + ghec: '*' diff --git a/data/reusables/code-scanning/beta-model-packs.md b/data/reusables/code-scanning/beta-model-packs.md index 4e675ea80ca8..75bbb6556160 100644 --- a/data/reusables/code-scanning/beta-model-packs.md +++ b/data/reusables/code-scanning/beta-model-packs.md @@ -2,7 +2,7 @@ {% note %} -**Note:** Model packs are currently in beta and subject to change. During the beta, model packs are supported only by {% data variables.code-scanning.codeql_model_packs_support %} analysis. +**Note:** {% data variables.product.prodname_codeql %} model packs and the {% data variables.product.prodname_codeql %} model editor are currently in beta and subject to change. During the beta, model packs are supported only by {% data variables.code-scanning.codeql_model_packs_support %} analysis. {% endnote %} diff --git a/data/reusables/code-scanning/codeql-license.md b/data/reusables/code-scanning/codeql-license.md new file mode 100644 index 000000000000..ada9c39bdbe7 --- /dev/null +++ b/data/reusables/code-scanning/codeql-license.md @@ -0,0 +1,20 @@ +## About the {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_codeql %} license + +**License notice:** If you don’t have a {% data variables.product.prodname_enterprise %} license then, by installing this product, you are agreeing to the [{% data variables.product.prodname_dotcom %} {% data variables.product.prodname_codeql %} Terms and Conditions](https://securitylab.github.com/tools/codeql/license). + +{% data variables.product.prodname_dotcom %} {% data variables.product.prodname_codeql %} is licensed on a per-user basis. Under the license restrictions, you can use {% data variables.product.prodname_codeql %} to perform the following tasks: + +- To perform academic research. +- To demonstrate the software. +- To test {% data variables.product.prodname_codeql %} queries that are released under an OSI-approved License to confirm that new versions of those queries continue to find the right vulnerabilities. + +Where "OSI-approved License" means an Open Source Initiative (OSI)-approved open source software license. + +If you are working with an Open Source Codebase (that is, a codebase that is released under an OSI-approved License) you can also use {% data variables.product.prodname_codeql %} for the following tasks: + +- To perform analysis of the Open Source Codebase. +- If the Open Source Codebase is hosted and maintained on {% data variables.product.prodname_dotcom_the_website %}, to generate {% data variables.product.prodname_codeql %} databases for or during automated analysis, continuous integration, or continuous delivery. + +{% data variables.product.prodname_codeql %} can’t be used for automated analysis, continuous integration or continuous delivery, whether as part of normal software engineering processes or otherwise, except in the express cases set forth herein unless you have a license for {% data variables.product.prodname_GH_advanced_security %}. + +{% data reusables.advanced-security.ghas-trial %} diff --git a/data/reusables/code-scanning/mrva-beta.md b/data/reusables/code-scanning/mrva-beta.md new file mode 100644 index 000000000000..ac6b75997a46 --- /dev/null +++ b/data/reusables/code-scanning/mrva-beta.md @@ -0,0 +1,9 @@ +{% ifversion codeql-vs-code-mrva %} + +{% note %} + +**Note:** Multi-repository variant analysis is currently available as a beta release and is subject to change. To use this feature, you must upgrade {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} to a minimum of version 1.8.0. + +{% endnote %} + +{% endif %}