You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
66
68
67
-
Configuring settings for testing queries
68
-
-----------------------------------------
69
+
Configuring settings for variant analysis
70
+
------------------------------------------
71
+
72
+
You can define or edit lists of GitHub repositories for variant analysis, and change to a different controller repository using the **Variant analysis** settings.
73
+
74
+
For information on the purpose and requirements for a controller repository, see ":ref:`About the controller repository <controller-repository>`."
75
+
TODO
76
+
The items shown in the Variant Analysis Repositories panel can also be managed by editing a file in your VS Code workspace called databases.json. This file contains a JSON representation of all the items displayed in the panel. To open your databases.json file in an editor window, click the { } icon in the top right of the variant analysis repositories panel. You can then see a structured representation of the repos, orgs and lists in your panel. For example:
77
+
78
+
{
79
+
"version": 1,
80
+
"databases": {
81
+
"variantAnalysis": {
82
+
"repositoryLists": [
83
+
{
84
+
"name": "My favourite JavaScript repos",
85
+
"repositories": [
86
+
"facebook/react",
87
+
"babel/babel",
88
+
"angular/angular"
89
+
]
90
+
}
91
+
],
92
+
"owners": [
93
+
"microsoft"
94
+
],
95
+
"repositories": [
96
+
"apache/hadoop"
97
+
]
98
+
}
99
+
},
100
+
"selected": {
101
+
"kind": "variantAnalysisSystemDefinedList",
102
+
"listName": "top_10"
103
+
}
104
+
}
105
+
106
+
You can change the items shown in the panel or add new items by directly editing this file.
107
+
108
+
Configuring settings for testing queries locally
109
+
------------------------------------------------
69
110
70
111
To increase the number of threads used for testing queries, you can update the **Running Tests > Number Of Threads** setting.
Copy file name to clipboardExpand all lines: docs/codeql/codeql-for-visual-studio-code/exploring-data-flow-with-path-queries.rst
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,7 +3,7 @@
3
3
.. _exploring-data-flow-with-path-queries:
4
4
5
5
Exploring data flow with path queries
6
-
=================================================
6
+
=====================================
7
7
8
8
You can run CodeQL queries in VS Code to help you track the flow of data through a program, highlighting areas that are potential security vulnerabilities.
@@ -10,24 +10,137 @@ Running CodeQL queries at scale with multi-repository variant analysis
10
10
About multi-repository variant analysis
11
11
---------------------------------------
12
12
13
-
Explain what MVRA is, when it's useful, and basic billing (uses actions minutes for private repos).
13
+
When you write a query to find variants of a security vulnerability and finish testing it locally, the next step is to run it on a large group of repositories. Multi-repository variant analysis (variant analysis) makes it easy run a query on up to 1000 repositories without leaving Visual Studio Code.
14
+
15
+
The core functionality of the CodeQL extension helps you write queries and run them locally against a CodeQL database. In contrast, variant analysis allows you to send your CodeQL query to GitHub.com to be tested against a list of repositories.
14
16
15
17
.. _controller-repository:
16
18
17
19
About the controller repository
18
20
-------------------------------
19
-
Explain what a controller repository is, how to choose a good repository, can a team use a single repository, and any other questions that came up during the private beta test. Note that if you want to run MRVA on private repositories, you need to use a private controller repository to enable analysis.
20
-
21
-
Getting started with variant analysis
22
-
-------------------------------------
23
-
Explain how to set it up for the first time.
24
-
Explain how to run variant analysis.
25
-
Explain how the results view works.
26
-
27
-
Configuring variant analysis
28
-
----------------------------
29
-
Explain how to create your own list of repositories.
30
-
Explain how to change your controller repository.
21
+
22
+
When you run variant analysis, the analysis is run entirely using dynamic workflows for GitHub Actions. You don't need to create any workflows, but you must specify which GitHub repository the CodeQL extension should use as the "controller repository."
23
+
24
+
Functions of the controller repository
25
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
26
+
27
+
- **Workflow management:** the workflow runs that are triggered when you run variant analysis are shown on the **Actions** tab for the repository in much the same as other workflow runs.
28
+
- **Billing:** when you analyze private repositories, the actions minutes used by CodeQL analysis are billed to the owner of the controller repository.
29
+
30
+
Requirements of the controller repository
31
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
32
+
33
+
- The repository must have at least one commit.
34
+
- The ``GITHUB_TOKEN`` must have "Read and write permissions" when running workflows in this repository. For more information, see "`Managing GitHub Actions settings for a repository <https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#setting-the-permissions-of-the-github_token-for-your-repository>`__."
35
+
- The repository visibility must be "public" if you plan to analyze public repositories. The variant analysis will be free.
36
+
- The repository visibility must be "private" or "internal" if you need to analyze private and internal repositories. 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 "`About billing for GitHub Actions <https://docs.github.com/en/billing/managing-billing-for-github-actions/about-billing-for-github-actions>`__."
37
+
38
+
TODO: Check on "internal" repositories.
39
+
40
+
.. pull-quote::
41
+
42
+
Note
43
+
44
+
You can update your settings to use a different controller repository when you want to run variant analysis on a different group of repositories. For example, if you have finished testing the query on open source code and now want to test it on your private code. However, you must wait until any previous analysis is complete before you change the controller repository.
45
+
46
+
TODO: check that the guess in the note above is accurate.
47
+
48
+
Setting up variant analysis
49
+
---------------------------
50
+
51
+
You can configure the CodeQL extension to run variant analysis by defining a controller repository.
:alt:Screenshot of the CodeQL extension in Visual Studio Code. The "Variant Analysis Repositories" section is expanded and the "Set up controller repository" button is highlighted with a dark orange outline.
56
+
57
+
#. In Visual Studio Code, click **QL** in the left sidebar to display the CodeQL extension.
58
+
59
+
#. Expand **Variant Analysis Repositories** and click **Set up controller repository** to display a field for the controller repository.
60
+
61
+
#. Type the owner and name of the repository on GitHub.com that you want to use as your controller repository and press the **Enter** key.
62
+
63
+
#. If you are prompted to authenticate with GitHub, follow the instructions and sign into your pesonal or organization account. When you have finished following the process, a prompt from GitHub Authentication may ask for permission to open a URI in Visual Studio Code, click **Open**.
64
+
65
+
The name of the controller repository is saved in your settings for the CodeQL extension. For information on how to edit the controller repository, see ":ref:`Customizing settings <customizing-settings>`."
66
+
67
+
Running a query at scale using variant analysis
68
+
-----------------------------------------------
69
+
70
+
#. Expand the **Variant Analysis Repositories** section, to show the default lists of the top 10, top 100, and top 1000 public repositories on GitHub.com. These are ranked by considering various metrics such as number of stars, number of watchers, number of forks etc.
71
+
72
+
#. Select the **Top 10 repositories** to test your query against.
73
+
74
+
#. Open the query you want to run, right-click in the query file, and select **CodeQL: Run Variant Analysis** to start variant analysis.
75
+
76
+
The CodeQL extension builds a CodeQL pack with your library and any library dependencies. The CodeQL pack and your selected repository list are posted to an API endpoint on GitHub.com which triggers a GitHub Actions dynamic workflow in your controller repository. The workflow spins up multiple parallel jobs to execute the CodeQL query against the repositories in the list, optimizing query execution. As each workflow run finishes, the results are processed and displayed in a variant analysis results view in Visual Studio Code.
77
+
78
+
.. pull-quote::
79
+
80
+
Note
81
+
82
+
If you need to cancel the variant analysis run for any reason, click **Stop query** in the Variant Analysis Results view.
83
+
84
+
Exploring your results
85
+
----------------------
86
+
87
+
When you run variant analysis, as soon as a workflow to run your analysis on GitHub is running, a Variant Analysis Results view opens to display the results as soon as they are ready. You can use this view to monitor progress, see any errors, and access the workflow logs in your controller repository.
:alt:Screenshot of the "Variant Analysis Results" view showing a partially complete run. Analysis of ``angular/angular`` is still running but all other results are displayed. ``facebook/create-react-app`` has three results for this query.
91
+
92
+
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.
93
+
94
+
For each repository, you can see:
95
+
96
+
- Number of results found by the query
97
+
- Visibility of the repository
98
+
- Whether analysis is still running (black, moving circle) or finished (green checkmark)
99
+
- Number of stars the repository has on GitHub
100
+
- How long ago the CodeQL database that was analyzed was created
:alt:Screenshot of an example result in the "Variant Analysis Results" view. The result has blue links to the source files in GitHub so you can go straight to the repository to fix the problem. There is also a "Show paths" link because this is a data flow query.
106
+
107
+
#. Click the repository name to show a summary of each result.
108
+
109
+
#. Explore the information available for each result using links to the source files in GitHub.com and, for data flow queries, the **Show paths** link. For more information, see "ref:`Exploring data flow with path queries <exploring-data-flow-with-path-queries>`."
110
+
111
+
Exporting your results
112
+
----------------------
113
+
114
+
#. Optionally, click **Export results** to export the results to a gist on GitHub.com or to a markdown file
115
+
116
+
117
+
Creating your own lists of repositories
118
+
---------------------------------------
119
+
120
+
The Variant analysis repositories panel is used to select and manage the repos queried during variant analysis. We provide predefined lists of the most important repositories per language (Top 10, Top 100, or Top 1000) but you can also add your own lists, single repos, or GitHub organizations to the panel. To add new items, use the buttons located on the top right of the panel.
121
+
122
+
Note: When you run variant analysis against a list of repositories, the query will only be executed against the repos that currently have a CodeQL database available to download. We store CodeQL databases for thousands of public repositories, including all repos that run code scanning. So the best way to make a repository available for variant analysis is to enable code scanning with CodeQL.
123
+
Adding a single GitHub repository or organization for variant analysis
124
+
Click the + icon.
125
+
From the drop down menu, choose to either add a GitHub repository or a GitHub organisation/owner.
126
+
Specify either the org/repo or org identifier in the text box.
127
+
Adding a new list of repositories for variant analysis
128
+
Click the +📁 icon.
129
+
Specify a name for your list in the drop down text box and hit enter.
130
+
Add repos to the list by first clicking on the name of the new list in the panel. Then click + and specify the org/repo identifier for each repo you want to add.
131
+
132
+
#. Optionally, click **Copy repository list** to add a list of the repositories that have results for your query to the clipboard as JSON. For example:
Copy file name to clipboardExpand all lines: docs/codeql/codeql-for-visual-studio-code/troubleshooting-variant-analysis.rst
+40-2Lines changed: 40 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,9 +7,47 @@ Troubleshooting variant analysis
7
7
8
8
.. include:: ../reusables/beta-note-mrva.rst
9
9
10
-
This article explains how to debug problems with variant analysis. That is, analysis where the
11
-
CodeQL databases are on GitHub.com and not locally on your machine.
10
+
This article explains how to debug problems with variant analysis. That is, analysis run using GitHub Actions
11
+
and not locally on your machine.
12
12
For information on troubleshooting local analysis, see
13
13
":ref:`Troubleshooting CodeQL for Visual Studio Code <troubleshooting-codeql-for-visual-studio-code>`."
14
14
15
+
When you run variant analysis, there are two key places where errors and warnings are displayed:
16
+
17
+
#. **Visual Studio Code errors** - any problems with creating a CodeQL pack and sending the analysis to GitHub.com are reported as Visual Studio Code errors in the bottom right corner of the application. The problem information is also available in the **Problems** view.
18
+
#. **Variant Analysis Results** - any problems with the variant analysis run are reported in this view.
19
+
20
+
Variant analysis warning: Problem with controller repository
:alt:Screenshot of the "Variant Analysis Results" view showing a warning banner with the text "warning: Problem with controller repository" and "Publicly visible controller repository can't be used to analyze private repositories. 1 private repository was not analyzed." The "Show logs" button is highlighted with a dark orange outline.
28
+
29
+
In this example, the user ran variant analysis on a custom list of two repositories. One of the repositories was a private repository and could not be analyzed because they had a public controller repository. Only the public repository was analyzed. To analyze both repositories, they need to edit their settings and update the controller repository to a private repository. For information on how to edit the controller repository, see ":ref:`Customizing settings <customizing-settings>`."
30
+
31
+
CodeQL extension error: Bundling pack failed
32
+
--------------------------------------------
33
+
34
+
If the CodeQL extension fails to create the CodeQL pack, you will see an error message in the bottom right corner of Visual Studio Code. For example:
:alt:Screenshot of a Visual Studio Code error shown in the bottom right corner of the application. The error message "Bundling pack failed" is visible. The "Show log" button is highlighted with a dark orange outline.
39
+
40
+
TODO: Ask James to check this is a reasonable example, or to create a better screenshot for this example.
41
+
42
+
The most likely cause of this type of error is that your current workspace does not contain the CodeQL workspace.
43
+
44
+
You can update your environment to fix this problem as follows.
45
+
46
+
#. Change the root of your workspace for Visual Studio Code to be the same as your CodeQL workspace.
47
+
48
+
TODO: Ask for more information about this step above.
49
+
50
+
#. Add an extra folder in your workspace (**File > Add Folder to Workspace**) for the suite-helpers: ``codeql/misc/suite-helpers``.
51
+
52
+
#. Using the terminal in Visual Studio Code, use the CodeQL CLI to download the ``codeql/suite-helpers`` pack: ``codeql pack download codeql/suite-helpers``.
0 commit comments