Cloud Posture 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
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]" |
 |
TipUse 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 Cloud Posture
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 Cloud Posture
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 Cloud Posture
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
Procedure
- 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 OR or AND. 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.
What to do next
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)