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, contact Semmle for further information.
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.
Viewing results from the analysis
You can generate results in three different file formats for code review:
sarifv2. For an overview of the difference between the two sarif file formats, see Schema changes between SARIF v1 and v2 from OASIS TC Static Analysis Results Interchange Format (SARIF). The results files 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.
Acting on the results
If you are using the analysis as part of your code assessment procedure, then there are a number of possible approaches that can be used to help interpret the results and act on the alerts. For further information, see using Semmle's analysis for automatic assessment.
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.