Open menu

CQL Filter Method

Conformity Query Language is a free text syntax that provides advanced features for filtering checks, allowing complex queries more powerful than what can be done with Simple Filters.

CQL allows you to search by field/value pairs. The syntax allows you to specify the relationship and order in which the criteria are considered using logical operators, parentheses, and quotation marks.

Contents

Logical operators

Wildcards

Regular expressions

Fields list

Using CQL to filter your checks

Query examples

Logical operators

The base syntax for a field/value search criteria is [field]:[value], where the colon character (:) specifies that the given field must be equal to the specified value in order for a check to be returned in the search results.

Logical operators allow you to specify more than one criteria and to indicate the relationship between them. CQL will support the following explicit logical operators:

Operator name Operator Description Example
EQUALS : Matches if the right side equals the left side, i.e. field equals value service : EC2
NOT EQUALS :- Matches if the right side does not equal the left side, i.e. field does not equal value service :- IAM
AND AND Matches if the check contains both criteria status : SUCCESS AND riskLevel : HIGH
OR OR Matches if the check contains either criteria compliance : MAS OR compliance : HITRUST
Parentheses () Parentheses are used to denote modifications to normal order of operations (precedence rules). In an expression like (compliance : MAS OR compliance : HITRUST) AND status: SUCCESS, the part of the expression within the parentheses is evaluated first, and then the result is used in the rest of the expression. (compliance : MAS OR compliance : HITRUST) AND status : SUCCESS
Quotation marks " Used to enclose strings when they contain special characters and/or spaces. message : "Continuous Backups are not enabled for [ddb-users-dev]"

Important:

  • Use parentheses liberally to clearly group terms in the search query.
  • When strings contain characters other than letters and numbers and spaces and are not to be interpreted as regex they should be enclosed in ". This is the case for example, for free text fields like “resource” and “message”.
  • When using regular expressions, reserved characters . . ? + * { } [ ] ( ) " \ must be escaped with a \
  • Unlike the other fields which search for an exact match, ‘message’ and ‘ruleTitle’ fields use a full-text search, where the search returns all relevant results rather than just exact matches. If you search for Quick fox jumps, you probably want the document that contains A quick brown fox jumps over the lazy dog, and you might also want documents that contain related words like fast fox or foxes leap.

Resource Wildcards

The resource field supports wildcard searches. This syntax supports two operators:

  • ?, which matches any single character
  • _*, which can match zero or more characters, including an empty one
    _Example:
    • Find all resources starting with “sg-” and ending with any number of characters:
      resource : sg-*
    • Find all resources starting with “sg-” and ending with any one character + the letter “s”
      resource : sg-?s

Be mindful that wildcard queries can use an enormous amount of memory and perform very badly — just think how many terms need to be queried to match the query string a* b* c*

Resource regular expressions

The resource field supports regular expression patterns. They can be embedded in the query string by wrapping them in forward-slashes ("/"):

resource : /arn:aws:iam::[0-9]{12}:policy\/.*Part1/

The supported regular expression syntax is explained in Filters and Search.

Fields list

Field Name Data type Description Example
ruleTitle string Will match if the title of the rule contains relevant results matching the value. Please refer to the full-text search explanation above. ruleTitle : "Unrestricted SSH Access"
ruleId string Will match if the rule id is an exact match. Select from the autocomplete dropdown. ruleId : EC2-081 OR ruleId : EC2-088
message string Will match if the message contains relevant results matching the value. Please refer to the full-text search explanation above. message : "access keys"
resource string
regex
Will match if the resource id matches the value. Can also match by wildcard or regex, see above description. resource : "aws-glue-an-data"

resource : /arn:aws:iam::[0-9]{12}:policy\/.*Part1/

resource : "aws-*-an-??-data"
newerThanDays number olderThanDays’ and ‘newerThanDays’ range refers to days to go back from today. It converts the number of days entered to the date when the check was created and assigned a status, or where the status changed from “Success” to “Failure” or from “Failure” to “Success”. You can use this filter by entering values for the number of days you wish to view before ‘olderThanDays’ and after ‘newerThanDays’. You must pass at least 2 days up to 1 day to see any checks for a specific time duration. To display checks from a particular day up to today, pass the number of days in ‘newerThanDays’ and don’t set ‘olderThanDays’. newerThanDays : 20
olderThanDays number To display all checks for up to a particular day, pass a number of days to go back from today in ‘olderThanDays’ and don’t set ‘newerThanDays’. olderThanDays : 20
filterTag string Will match if the assigned metadata tags to your resources have at least one tag with this value as the key or value of the tag. To match both key and value, specify them in key::value pairs filterTag : "env::dev"

filterTag : "env"

filterTag : "dev"
service string Will match if the provider service is an exact match. For more information about services, please refer to Conformity Services Endpoint. service : IAM
category string Will match if the category is an exact match. Possible values are: security or cost-optimisation or operational-excellence or reliability or performance-efficiency category : security
region string Will match if the region is an exact match. For more information about regions, please refer to Conformity Region Endpoint. region : eu-west-2
riskLevel string Will match if the risk level is an exact match. Possible values are:
LOW or MEDIUM or HIGH or VERY_HIGH or EXTREME
riskLevel : HIGH
resourceType string Will match if the resource type is an exact match. For more information about services, please refer to Conformity ResourceTypes Endpoint. resourceType : ec2-securitygroup OR resourceType : ec2-instance
provider string Will match if the cloud provider is an exact match. provider : aws
compliance string Will match if the compliance standard is an exact match. For more information about compliance standards, please refer to our API documentation on field ‘compliances’. compliance : AWAF
status string Will match if the status of the check is an exact match. Possible values are SUCCESS or FAILURE status : SUCCESS
suppressed string Whether or not include all suppressed checks. The default value is true for “v1” and omitted for “v2”.Possible values are true or false suppressed : true

Using CQL to filter your checks

  1. Click on Browse all checks and select the CQL filter method.
  2. Start typing to select a field to search. Select the equal : or not equal :- operator and select a value from the list of available values.
  3. You can stop here or continue adding conditions with OR or AND. Use parentheses to ensure the precedence of conditions.
  4. If your field doesn’t have a dropdown, enter a search text enclosed by “” and click on the Apply filter button once you are done.

Query examples

  • service : EC2 OR category : security OR riskLevel : HIGH OR status : SUCCESS
  • service : EC2 AND category :- security
  • (service : ELB OR category : security) AND riskLevel :- MEDIUM
  • service : EC2 AND ( category : security OR riskLevel : HIGH) AND status : SUCCESS
  • ((service : ELB OR service : CloudFront) AND status : FAILURE) OR (message : SSL OR ruleTitle : SSL)
  • (service : VPC AND status : FAILURE) OR region : ca-central-1
  • service : EC2 AND (( category : security OR riskLevel : HIGH) OR status :- SUCCESS)