Query Language

The query language used by the rule service is a LISP style language: (<operator> <args>...).

Operators

The following are the operators

Operator	Syntax	Description
eq	(eq left right)	Equality comparison
contains	(contains needle haystack)	Text contains search (case-insensitive)
matches	(matches pattern target)	Regex pattern matching
any	(any needle expr)	Value search in JSON objects
and	(and expr1 expr2 ...)	Logical AND
or	(or expr1 expr2 ...)	Logical OR
not	(not expr)	Logical NOT

Equality (eq)

Compares two values for exact equality.

(eq $.name "s3-encryption")
(eq $.type "security")
(eq $.version "1.0.0")
(eq $.annotations.stable true)

Contains (contains)

Searches for text within a field (case-insensitive).

(contains "aws" $.name)
(contains "s3" $.resource)
(contains "prod" $.metadata.environment)

Matches (matches)

Uses regex patterns for matching.

(matches /aws_.*/i $.resource)
(matches /^s3-.*/ $.name)
(matches /prod|staging/ $.environment)

Regex Flags:

• i - Case insensitive

• g - Global match

• m - Multiline

Any (any)

Searches for a specific value within JSON data structures.

(any "prod" $.metadata)
(any "CIS" $.classification)
(any "encryption" $.body.config)
(any "enabled" $.annotations)

AND (and)

All conditions must be true.

(and (eq $.type "security") (contains "aws" $.resource))
(and
  (eq $.iacLanguage "terraform")
  (any "prod" $.metadata)
  (not (contains "deprecated" $.name))
)

OR (or)

At least one condition must be true.

(or (contains "aws" $.resource) (contains "azure" $.resource))
(or (eq $.name "rule1") (eq $.name "rule2") (eq $.name "rule3"))

NOT (not)

Negates a condition.

(not (contains "test" $.name))
(not (any "deprecated" $.metadata))
(not (eq $.environment "dev"))

Fields

Each object has fields that can be referenced.

Field	Description	Example
finding.name	Rule name	(eq finding.name "s3-encryption")
finding.shortName	Rule short name	(contains "s3" finding.shortName)
finding.type	Rule type	(eq finding.type "security")
finding.version	Rule version	(eq finding.version "1.0.0")
finding.iacLanguage	IaC language	(eq finding.iacLanguage "terraform")
finding.metadata	Rule metadata	(any "prod" finding.metadata)
finding.body	Rule body content	(contains "aws_s3_bucket" finding.body)
finding.annotations	Rule annotations	(eq finding.annotations.stable true)
finding.classification	Rule classifications	(any "CIS" finding.classification)
channel.name	Channel name	(eq channel.name "security-channel")
channel.query	Channel query	(contains "security" channel.query)
channel.filters	Channel filters	(contains "prod" channel.filters)
channel.accountId	Channel account ID	(eq channel.accountId "account-123")
classification.name	Classification name	(eq classification.name "CIS")
classification.parent	Parent classification	(eq classification.parent "Security")
classification.shortName	Classification short name	(contains "CIS" classification.shortName)
classification.description	Classification description	(contains "security" classification.description)
classification.annotations	Classification annotations	(eq classification.annotations.stable true)

Note: There is also a $ object which represents "this" and changes behavior based on what is being returned. If executed against rules then it is a finding, if executed against channels it is a channel, and if executed against classifications then it is a classification.

Data Types

Type	Syntax	Example
String	"text"	"aws_s3_bucket"
Number	123 or -42.5	1 or 1000.0
Boolean	true or false	true
Null	null	null
Regex	/pattern/flags	/aws_.*/i

String Escaping

• Use \" for quotes: "He said \"Hello\""

• Use \\ for backslashes: "path\\to\\file"

Regex Escaping

• Use \/ for forward slashes: /path\/to\/file/

• Use \\ for backslashes: /path\\to\\file/

Common Patterns

Find Rules by Resource Type

(contains "aws_s3_bucket" $.resource)
(matches /aws_.*_bucket/i $.resource)

Exclude Test/Deprecated Rules

(not (any "test" $.metadata))
(not (contains "deprecated" $.name))
(not (any "deprecated" $.metadata))

Note: The positive can also be used in a filter.

Complex Filtering

(and
  (eq finding.type "security")
  (not (any "deprecated" finding.metadata.annotations))
  (any "prod" finding.metadata)
  (contains "aws" finding.metadata.annotations["resource"])
)

Troubleshooting

Common Issues

1. Query Syntax Errors

   • Ensure all parentheses are balanced

   • Use proper string escaping

   • Check operator argument counts

2. Field Not Found

   • Unknown fields default to $.body search

   • Use dot notation for nested fields

   • Check field names in the reference table

3. Regex Issues

   • Use proper escaping for special characters

   • Add flags like i for case-insensitive matching

   • Test regex patterns separately

4. any() Function Issues

   • Error: any() requires exactly 2 args

   • Solution: Use (any needle field) for single values, or use OR for multiple values

   // ❌ WRONG: Too many arguments
   (any "s3" "ec2" "rds" $.services)  // Error: requires 2 args
   
   // ✅ CORRECT: Single value search
   (any "prod" $.metadata)
   
   // ✅ CORRECT: Multiple values using OR
   (or (any "prod" $.metadata) (any "staging" $.metadata))

   • Memory Errors: Complex JSON searches can cause out-of-memory

   • Solution: Break complex queries into smaller parts or use alternatives like contains

5. Performance Considerations

   • Use specific field references when possible

   • Avoid overly complex nested queries

   • Consider using contains over any for simple text searches

   • Be cautious with any on very large JSON structures

Debugging Tips

1. Start Simple: Begin with basic queries and add complexity gradually

2. Test Components: Test individual parts of complex queries

3. Use Examples: Reference the examples in this guide

4. Check Syntax: Ensure proper S-Expression syntax