Topics on this page
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
Using CQL to filter your checks
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]" |
- 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
- Find all resources starting with “sg-” and ending with any number of characters:
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
- Click on Browse all checks and select the CQL filter method.
- 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. - You can stop here or continue adding conditions with
ORorAND. Use parentheses to ensure the precedence of conditions. - 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 : SUCCESSservice : EC2 AND category :- security(service : ELB OR category : security) AND riskLevel :- MEDIUMservice : 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-1service : EC2 AND (( category : security OR riskLevel : HIGH) OR status :- SUCCESS)