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

Overview

To simplify the management of your queries for analysis of multiple projects, it is often useful to group them together into query suites. When you modify or update an individual query file, all query suites in which the changed file is referenced will also be updated. 

Prerequisites

All queries to be added to your query suite file must have a header section that defines the name, description, and type of query. For use in analysis, this query metadata must include @id and @kind properties. For more information, see Query file requirements. Custom queries should be saved in a directory outside the Semmle Core distribution directory and compiled using the prepareQueries command. For more information, see Preparing custom queries.

Adding queries to a query suite

You can add one or more queries to a query suite file in two ways:

  • By directly referencing individual queries.
  • By using the @import directive to reference another query suite, for instance a set of default queries.

Referencing individual queries

The file path for each query must be defined relative to one of the predefined Semmle variables, relative to the location of the main Semmle Core queries directory (${odasa_queries}), or as an absolute path. Each query is specified on a separate line using the following format:

+ <path>/<query>: /<category>/<sub-cateogry>
  @<optional query directive>

where:

  • + indicates that the query should be enabled.
  • <path> is the file path of the query, as defined above.
  • <query> is the query to run.
  • <category>/<sub-category> is the query category, for example Correctness/Logic errors. These categories are used to group queries thematically for advanced analysis. For further information, see Filtering data.
  • @<optional query directive> is an optional directive used to alter the behavior of the preceding query. For further information, see Query directives.

Using the @import directive

You can also use the @import directive to reference one or more existing query suites. When you use @import, all of the individual queries referenced in the imported files are added to the new query suite. The file path for the query suite you are importing must be defined relative to one of the predefined variables, relative to the location of the query suite it is being imported into, or as an absolute path. For example:

  • The language-specific query suites, used to group standard queries thematically for a particular language, are located in the ${odasa_queries}/suites/<language> directory. 
  • ${odasa_queries}/customer/default contains query suites that assemble default sets of queries for each language by referencing the query suites in ${odasa_queries}/suites/<language>
  • You can store custom queries in a chosen location and provide an appropriate file path in your query suite file to include them in your analysis.

The following example is taken from a query suite for analyzing Java projects. Each @import directive imports a separate suite file.

# Import the standard rules for analyzing Java projects
@import ${odasa_queries}/customer/default/java
# Import the default security queries
@import ${odasa_queries}/suites/security/java/default
# Import custom queries
@import ${semmle_home}/custom-queries/query-suite

Example

If you wish to group a number of queries for analysis of multiple Java projects then your query suite may look like this:

Configuration file using query suites
# Import the default query suites for Java analysis
@import ${odasa_queries}/customer/default/java

# Add one or more standard queries
+ semmlecode-queries/Likely Bugs/Comparison/BitwiseSignCheck.ql: /Correctness/Arithmetic
+ semmlecode-queries/Likely Bugs/Comparison/NoComparisonOnFloats.ql: /Correctness/Arithmetic
+ semmlecode-queries/Likely Bugs/Arithmetic/CondExprTypes.ql: /Correctness/Arithmetic
+ semmlecode-queries/Likely Bugs/Arithmetic/OctalLiteral.ql: /Correctness/Arithmetic
 
# Add two extra custom queries
+ ${semmle_home}/custom-queries/java/CustomQuery1.ql: /Advisory/Declarations
+ ${semmle_home}/custom-queries/java/CustomQuery2.ql: /Correctness/Exceptions

In this example, the @import ${odasa_queries}/customer/default/java statement imports the default Semmle Core Java query suite. The four standard queries are referenced by their relative path, and the custom queries are stored in the location defined by environment variable SEMMLE_HOME

Disabling queries

You may find that some queries referenced in a query suite are not relevant to a particular project. When this is the case, you can disable these queries using the following format:

- /<category>/<sub-category>/<query>

where:

  • - indicates that the query should be disabled.
  • /<category>/<sub-category> is the dashboard category that the query results have been assigned to.
  • <query> is the query to disable.

You can also disable an entire category or sub-category of queries by using the syntax: - /<category>/<sub-category>. This will disable all queries that you have referenced in the query suite that match <category>/<sub-category>, whether they have been individually referenced or imported from another query suite file using @import.

Extracting query metadata

The metadata defined in a query file provides detailed information about the query which may be useful to store in a results file of its own. You can extract the metadata associated with the queries referenced in a query suite using the exportQueryMetadata command. This command takes a query suite, or one or more query files, and outputs the metadata into a SARIF v2 results file. For example, to extract the metadata defined in the queries referenced in a custom query suite, you would run the following command:

odasa exportQueryMetadata --suite ${semmle_home}/custom-queries/query-suite --output custom-suite-metadata.sarif 

where  ${semmle_home}/custom-queries/query-suite is the path of your custom query suite and custom-suite-metadata.sarif is the SARIF v2 file to store the metadata in. See exportQueryMetadata for more information about the command and Query file requirements for more information about query file metadata.

What next?

After defining a query suite you can generate query results using the command line tools.