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

This topic describes how to use filter queries to control the results of Semmle analysis.

Overview

You can use filter queries to limit the data returned by a query (or query category) during the analysis of your code. Standard filter queries are provided with the Semmle Core installation. You can also write your own filter queries using QL and save them as .ql files, in the same way as other query files (for more information see Learning QL and Query file requirements). When you add filter queries to the appropriate query suite file, only results that pass the filter will be reported. 

Limiting a single query

You can limit the results returned by a single query by editing:

  • Query file–use QL to define additional constraints to limit the results that are returned, this limits the results returned by the query for all analyses.
  • Query suite file–update the query row to include a filter query, this limits the results returned by the query for all analyses that use this query suite.

You can find the standard filters in the language subdirectories of the queries directory of your Semmle Core distribution. Custom filters can be developed in an IDE with a QL plugin or extension installed. For information on installing a QL plugin or extension, see QL plugins and extensions. For more information about developing filter queries in your IDE, see Writing a filter query and Running a filter query.

To limit a single query, you can add a filter query in a query suite file using the following format:

+ [<path>/<filter-query>] <path>/<query>: /<category>

where <path>/<filter-query> defines the name and location of the filter query, <path>/<query> defines the name and location of the query that you want to apply the filter to. Optionally, you can assign the filtered results to a specified <category>.

Example

A custom query, custom-query.ql, is referenced in a query suite by specifying its path. Optionally, the query is assigned a category to link it to similar queries. In the example below, custom-query.ql is assigned to  Correctness/Custom :

+ ${semmle_home}/custom/language/correctness/custom-query.ql: /Correctness/Custom

When you add a filter, custom-filter.ql, to limit the results generated by custom-query.ql, the row where the query is referenced is updated to:

+ [${semmle_home}/custom/language/filters/custom-filter.ql] ${semmle_home}/custom/language/correctness/custom-query.ql: /Correctness/Custom

When you now analyze a snapshot using a query suite that includes the updated definition of the custom-rule.ql query, all new results generated for this query are filtered using the custom-filter.ql. This means that, of the results generated by the custom-rule.ql, only those that pass through the custom-filter.ql are output into the results file.

Limiting a category

You also can limit the results returned by all queries that contribute to a particular category by adding a new row to a query suite file using the following format:

> [<path>/<filter-query>] /<category>

where <path>/<filter-query> defines the name and location of the filter query and <category> defines the category that you want to apply the filter to.

Example

To filter all results shown in the standard Correctness category and sub-categories using a custom filter, correctness-filter.ql, you would add the following row to the required query suite file:

> [${semmle_home}/custom/language/filters/correctness-filter.ql] /Correctness

When you carry out an analysis using a query suite that includes the new filter, all results generated by queries assigned to the Correctness category are filtered using the custom-filter.ql. This means that, of the results generated by the queries in the Correctness category, only the results that are passed by the filter will be output into the results file.

Limiting all results

You can also apply filters to restrict the results generated by all queries referenced in a query suite, if necessary. For example, if a project includes sections of automatically generated code in the source files, you may wish to exclude the results generated during the analysis of these sections. Filter queries that identify and exclude parts of your code that appear to be automatically generated code for different languages are included with the Semmle Core installation. To exclude the results from automatically generated code you need to add one of the following queries to your query suite:

For C and C++ projects
> [${odasa_queries}/semmlecode-cpp-queries/filters/Autogenerated.ql] /
For C# and Python projects
> [${odasa_queries}/semmlecode-<language>-queries/filters/NotGenerated.ql] /
For Java projects
> [${odasa_queries}/semmlecode-queries/filters/NotGenerated.ql] /

For JavaScript, two standard filter queries are available for excluding results in minified or other generated code, and in framework libraries:

For JavaScript projects
> [${odasa_queries}/semmlecode-javascript-queries/filters/FilterGenerated.ql] /
> [${odasa_queries}/semmlecode-javascript-queries/filters/FilterFrameworks.ql] /

When you use analyzeSnapshot with a query suite that includes the new filter, all queries are filtered to exclude results from automatically generated code.