This topic describes how to analyze a snapshot database of your code using the QL command-line tools.
You can analyze your source code using the
analyzeSnapshot tool from the command line. This command runs a list of queries or queries referenced in a query suite file on a snapshot database of your code. The results can be output to various different file formats that can be readily used to highlight alerts on your code, used in manual code review, or integrated into an automated assessment process, if permitted by your license. If you are using a license that restricts integration and you want to discuss upgrading, contact GitHub Sales and Account Management team.
You need a snapshot database of your code. You may be able to download one from a store in your organization, otherwise you will have to generate one. For further information about generating a snapshot using the QL command-line tools, see generating a snapshot of your code.
Carrying out analysis from the command line
To analyze your source code, you can run a set of queries using the
analyzeSnapshot tool. When running this command, you define the snapshot that you wish to analyze and the queries to run in your analysis using the appropriate flags. There are flags to specify either the most recent or oldest snapshot or the snapshot of a specific code revision. The tool will also accept either a list of one or more queries or a query suite file, which directly references multiple queries. The following example selects the latest snapshot of the
results.csv file in the current directory.
If you are using the
--queries flag to specify one or more queries, then the command may have the following structure:
Be aware that queries specified using the
--queries flag or referenced in a query suite must have
@kind properties defined in their metadata in order to be used with
analyzeSnapshot. If you specify a query that doesn't have these properties an error is reported. You need to update the query metadata and rerun the command. For further information, see analyzeSnapshot.
If the version of the QL command-line tools you are using for an analysis is newer than the one you used to generate the snapshot, you may find that the snapshot is incompatible with the tools. You can upgrade a snapshot to match the latest version of the tools using the upgrade command.
Viewing results from the analysis
You can generate analysis results in a number of different file formats, including CSV, and several different versions of SARIF. For further information on the versions of SARIF supported by the QL command-line tools, see SARIF results file.
Analysis results generated using the command-line tools contain the following information for each alert:
|Name||Name of the query that identified the alert|
|Description||Description of the query|
|Severity||Severity of the query|
|Path||Path of the file containing the alert.|
|Start line||Line of the file where the code that triggered the alert begins|
|Start column||Column of the start line that marks the start of the alert code.||32|
|End line||Line of the file where the code that triggered the alert ends|
|End column||Where available, the column of the end line that marks the end of the alert code. Otherwise the end line is repeated.||617|
These results files can be integrated into your own code-review or debugging infrastructure. For example, the SARIF file output can be used to highlight alerts in the correct location in your source code using the appropriate IDE SARIF viewer plugin.
The metadata defined in each query file provides detailed information about the queries that you have used in your analysis. This information may be useful for the visualization of your results, and can be stored in a file of its own. For further information about extracting query metadata, see Extracting query metadata.
Alternative tools to run queries in the command line
You can run single queries in the command line using the
runQuery command. This is an advanced tool that differs from
analyzeSnapshot in several aspects. First,
@kind properties are not enforced, which means that the command will accept any query. As such this is a particularly useful tool for testing new queries before they are prepared for use in a full analysis or added to a query suite file. Secondly, because there is no
runQuery only outputs raw results, which cannot be used to highlight alerts on your source code. For further information see running a query from the command line.
Extending your analysis
You can extend the analysis of a particular project by adding custom queries. Custom queries can be used to highlight requirements or calculate metrics that are specific to a company or project. For further information, see Preparing custom queries.
You may see alerts that you don't agree with or would prefer to ignore rather than substantially change your code. You can selectively suppress certain alerts when this is the case. For further information, see suppressing alerts.