Semmle 1.19
Skip to end of metadata
Go to start of metadata

This topic describes how to analyze a snapshot database of your code using the QL command-line tools.

Overview

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.

Prerequisites

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 odyssey project and runs all queries in the JavaScript code review suite. In this case, the results of the queries are all stored in a results.csv file in the current directory.

odasa analyzeSnapshot --project projects\odyssey --latest --output-file results.csv --suite queries\suites\javascript\code-review

If you are using the --queries flag to specify one or more queries, then the command may have the following structure:

odasa analyzeSnapshot --project projects\odyssey --latest --output-file results.csv --queries queries\semmlecode-javascript-queries\query1.ql queries\semmlecode-javascript-queries\query2.ql

Be aware that queries specified using the --queries flag or referenced in a query suite must have @id and @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: csv, sarifv1 and 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:

ColumnDescriptionExample
Name Name of the query that identified the alertInefficient regular expression
Description Description of the queryA regular expression that requires exponential time to match certain inputs can be a performance bottleneck, and may be vulnerable to denial-of-service attacks.
Severity Severity of the query

error

Message Alert messageThis part of the regular expression may cause exponential backtracking on strings containing many repetitions of '\\\\'.
Path Path of the file containing the alert./vendor/codemirror/markdown.js
Start line Line of the file where the code that triggered the alert begins617
Start columnColumn of the start line that marks the start of the alert code.32
End lineLine of the file where the code that triggered the alert ends617
End columnWhere 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, @id or @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 @id or @kind requirement, 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.

What next?

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.

Suppressing alerts

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.