Suppressing results when running with the CodeQL CLI

[NateD-MSFT]

Hi there,

I'm a dev over in the Windows group at Microsoft. We've been building up a repo of CodeQL queries related to or useful for driver development (https://github.com/microsoft/Windows-Driver-Developer-Supplemental-Tools) and have been evangelizing the tool to partners.

One aspect we've been running into issues with is that, as is the case with any static analysis tool, CodeQL has queries that may provide useful results but may also cause false positives. With our other tools, it's possible for driver developers to use pragmas or comments to suppress specific warnings in their code when they know it's a false positive.

I've done some research, but to the best of my knowledge there is no such mechanism available for CodeQL at the CLI level. Is this correct? If so, I'd love to know the general thoughts on suppression going forward and if there is any plan to add this feature at the CLI/code level. (I understand LGTM previously had suppression comments that worked for LGTM, but LGTM is going away - and regardless, these comments wouldn't help devs running the CLI.)

[aibaars]

Hi @NateD-MSFT , the CodeQL CLI does support suppression annotations. It works by running a query with @kind alert-suppression as part of the analysis. These queries looks for suppression annotation and return the code-ranges that are affected by such an annotation. When these alert-suppression queries are run together with a suite of alert queries then CodeQL CLI will mark any alerts that are affect by a suppression annotation with a suppressions.kind: ["InSource"] marker in the SARIF output.

Here is an example of an alert suppression query:

codeql/go/ql/src/AlertSuppression.ql

Line 4 in e566357

* @kind alert-suppression

.

[aibaars]

Alert suppressions are defined by special QL queries with @kind alert-suppression . You can define a custom alert-suppression query that finds the annotations you need.

[NateD-MSFT]

Okay - is there documentation on this style of query? From what I can tell, the existing queries select, for example, "lgtm[cpp/windows/drivers/queries/extended-deprecated-apis]" as part of the result they return, which suggests to me that CodeQL internally takes that text and strips it to get the ID "cpp/windows/drivers/queries/extended-deprecated-apis" and matches that to suppress any violations with that query ID.

For our purposes, we would like to have, for example, a query where the ID in the CodeQL query might be "cpp/windows/drivers/queries/extended-deprecated-apis" but we could still suppress it with existing VS-style suppressions, which would use a numerical ID (1234) instead of the new CodeQL text ID.

[aibaars]

I don't think there is any documentation for that type of query. The query needs to have @kind alert-suppression and a select with 4 columns:

1. the annotation itself , type Location or any element with a getLocation/hasLocation predicate.
2. the text of the annotation, type string
3. a suppression "instruction" of the form lgtm or lgtm[queryID], type string
4. the target area (or target AST element) affected by the suppression, type Location or any element with a getLocation/hasLocation predicate.

[NateD-MSFT]

Thanks for the additional detail! I think with this we should be able to construct a suppression query that can take the old format and convert it into a CodeQL-suppression-readable format.

An additional question for you: do you know if this mechanism and syntax are expected to be supported for the foreseeable future, or are there plans in the pipeline to change or deprecate any part of this?

I really appreciate your help in all this.

[aibaars]

You're welcome. There are no plans to change or remove this mechanism for now. However, I can't make any promises.