Note: This documentation is for the legacy command-line tool odasa.
The final version was released in May 2020. Support for this tool expires in May 2021.

For documentation on the new generation CodeQL CLI, see CodeQL CLI .
In particular, you may find the Notes for legacy QL CLI users useful in planning your migration.

Skip to end of metadata
Go to start of metadata

On this page:

Related topics:

HIDDEN

Overview

Sometimes you may see alerts that you don't agree with or that you feel are not useful to you. You may also want to ignore an alert if you would rather not spend a long time re-writing your code for little potential benefit. In cases like these, you can disable individual alerts by adding 'suppression comments' to selected lines of your source code. 

Suppression comments

An alert suppression is an inline comment which is made up of:

  • A suppression annotation, which is not case sensitive: lgtm or LGTM. For Java, you can also use @SuppressionWarnings annotations.
  • An optional query identifier, [query id].

You can find the query identifier next to the @id property in the metadata at the top of most query files. If you don't specify a query identifier, then all alerts generated by the code on the commented line are suppressed. Adding an identifier allows you to selectively suppress alerts for a specific query. For further information on query identifiers, see Query metadata.

Suppression comments

The syntax of suppression comments is language-dependent:

  • "// lgtm..." for C/C++, C#, Go, Java, and JavaScript
  • "# lgtm..." for Python

Additionally, for Python the #noqa comment without any trailing text is also interpreted as a suppression comment. It has the same effect as #lgtm.

Whitespace is allowed both before and after the the word lgtm and the [ and ] symbols.

Adding suppression comments

For C/C++. C#, Go, Java, JavaScript, and Python, suppression comments apply to the entire line on which they appear. If an alert spans multiple lines of code, you need to insert the suppression comment on the first line. If an alert spans across multiple lines of code, you need to insert the suppression comment above the first line.

If you would like to suppress alerts for more than one query on the same line of code, you should include lgtm annotations for each query on that line. For example:

  • "// lgtm[query1-id] lgtm[query2-id]" for C/C++, C#, Go, Java, and JavaScript
  • "# lgtm[query1-id] lgtm[query2-id]" for Python

Using @SuppressWarnings annotations in Java

For code written in Java, you can also suppress alerts flagged using Java built-in @SuppressWarnings annotations. For these annotations, you must specify the query-id for the alert that you want to suppress:

  • @SuppressWarnings("lgtm[query1-id]","lgtm[query2-id]")

You typically add the annotation to a code element, and it'll suppress all alerts for the query within that element, not just on the line the annotation was added.

Example

The code snippet below - without the suppression comment - is taken from the standard Python library and uses multiple inheritance to define a class:

class ForkingTCPServer(ForkingMixIn, TCPServer): pass # lgtm[py/conflicting-attributes]

In general, multiple inheritance should be used with care. The main issue is when both base classes define the same method, and one is unintentionally overridden. The 'conflicting attributes in base classes' query flags this type of override. If the override is deliberate, as it is in the example, you can add a suppression comment to suppress the alert. Its query identifier is py/conflicting-attributes.

Excluding commented alerts from your analysis

If you perform analysis using LGTM, the suppression comments are automatically recognized. However, if you use alert suppression alongside a QL command line tool, such as analyzeSnapshot, you must add the AlertSuppression.ql query to your query suite file (or list of queries) so that the tool can identify the suppression comments. For example, the alert suppression query can be directly referenced in a query suite for analysis of Python code as follows: 

# Alert suppression directly referenced in query suite
+ semmlecode-python-queries/analysis/AlertSuppression.ql

Alternatively, if you are using analyzeSnapshot and you haven't specified a --suite flag, you can add the alert suppression query to your list of queries using the --queries flag. For further information see analyzeSnapshot.

When you implement alert suppression, your analysis won't generate alerts for the lines of code where you have added suppression comments. You may wish to take further action, depending on your reason for using alert suppression.

What should I do if an alert is a false positive?

If you believe that a particular alert generated by a standard query is a false positive that should not have been reported, consider raising an issue in the query repository. In the case of custom queries which are problematic, please report issues to the relevant author or distributor. For more information about the query language used to write queries, see Learning QL.