MQL Built-in Functions Reference

Built-in functions are the core language features that let you filter, transform, and make assertions across collections of data. They are the difference between just retrieving raw data and turning that data into meaningful answers.

Think of built-ins as the verbs of MQL:

• .where() narrows down what you're looking at.
• .map() transforms the results.
• .all(), .any(), .none(), .one() let you assert truth over collections.
• .length, and .containsOnly help you structure and compare results.

Overview

Array Functions

Map Functions

String Functions

Number Functions

Time Functions

IP / Network Functions

Array Functions

array.all

Assert that all elements in an array satisfy the condition. Empty arrays return true.

Ensure all EC2 instances do not have a public IP address:

aws.ec2.instances.all( publicIp == empty )

Example output:

aws.ec2.instances.all( publicIp == empty )
[failed] [].all()
  actual:   [
    0: aws.ec2.instance region="us-east-1" state="running" instanceType="t2.large" instanceId="i-0684b0bfd64641234" architecture="x86_64" platformDetails="Linux/UNIX" {
      publicIp: "54.144.152.249"
    }
  ]

array.any

Assert that at least one element in an array satisfies the condition. Empty arrays return false.

Check if at least one SSH service is running:

services.any(name == "sshd" && running == true)

Example output:

services.any(name == "sshd" && running == true)
[ok] value: true

array.contains

Check if an array contains a specific value or if any element matches a predicate. Returns true if found.

Check if any package is named openssl:

packages.map(name).contains("openssl")

Example output:

packages.map(name).contains("openssl")
[failed] [].contains()
  expected: > 0
  actual:   0

array.containsAll

Check that an array contains all specified values. Returns true only if all are present.

Ensure both root and ec2-user exist:

users.map(name).containsAll(["root","ec2-user"])

Example output:

users.map(name).containsAll(["root","ec2-user"])
[failed] [].containsAll()
  expected: == []
  actual:   [
    0: "ec2-user"
  ]

array.containsNone

Check that an array contains none of the specified values. Returns true if no matches are found.

Ensure no insecure packages are installed:

packages.map(name).containsNone(["telnet","rsh"])

Example output:

packages.map(name).containsNone(["telnet","rsh"])
[failed] [].containsNone()
  expected: == []
  actual:   [
    0: "telnet"
  ]

array.containsOnly

Check that all elements in an array are from an allowlist. Returns true if no other values appear.

Ensure only root and shadow groups own /etc/gshadow:

["/etc/gshadow"].where(file(_).exists) {
  file(_) {
    group.name.lines.containsOnly(["root","shadow"])
  }
}

Example output:

["/etc/gshadow"].where(file(_).exists) {
} } group.name.lines.containsOnly(["root","shadow"])
where: [
  0: {
    file: {
      [].containsOnly(): true
    }
  }
]

array.duplicates

Return duplicate values from an array.

Find duplicate package names:

packages.map(name).duplicates

array.first

Return the first element of an array.

Get the first package installed on the system:

packages.map(name).first

array.flat

Flatten nested arrays into a single array.

Flatten a deeply nested array:

[[[1,2,3]]].flat

array.in

Check if a string is in an array

Is the string 'term' in the array ['a','b','c']

> 'term'.in(['a','b','c'])
false

Is the string 'term' in the array ['term']:

> 'term'.in(['term'])
true

array.join

Join all values in an array into a single string

Join the values ["a", "b", "c"] into "abc"

["a", "b", "c"].join
"abc"

array.last

Return the last element of an array.

Get the last installed package:

packages.map(name).last

array.length

Return the number of elements in an array.

Count the number of installed packages:

packages.length

array.map

Transform each element of an array. Returns a new array with the transformed values.

List all package names:

packages.map(name)

array.none

Assert that no elements in an array satisfy the condition.

Ensure no X11-related packages are installed:

packages.none(name == /^x(org|server|11)/i)

array.notIn

Check if a string is not in an array

Is the string 'term' not in the array ['a','b','c']

> 'term'.notIn(['a','b','c'])
true

Is the string 'term' not in the array ['term']:

> 'term'.notIn(['term'])
false

array.one

Assert that exactly one element in an array satisfies the condition.

Ensure exactly one default route exists:

routes.one(destination == "0.0.0.0/0")

array.reverse

Reverse the order of elements in an array.

Reverse the order of values in an array

> [1, 2, 3].reverse
[3, 2, 1]

Reverse the order of period separated values using split, reverse, and join

> "123.456.789.10".split(".").reverse.join(".")
"10.789.456.123"

array.sample

Return a random sample of elements from an array.

Return one random package:

packages.sample(5)

Example output:

packages.sample(5)
packages.sample: [
  0: package id = macos://Notes/4.12.7/arm64
  1: package id = macos://Calculator/11.0/arm64
  2: package id = macos://UAD Updater/11.7.0/arm64
  3: package id = macos://MakePDF/10.1/arm64
  4: package id = macos://AirDrop/15.5/arm64
]

array.unique

Return only unique elements from an array.

List unique package names:

packages.map(name).unique

array.where

Filter an array by a boolean condition. Returns a new array of elements that satisfy the predicate.

List all packages that start with "openssl":

packages.where(name == /^openssl/)

Map Functions

map.all

Assert that all entries in the map satisfy a condition. Empty maps return true.

All net.* kernel parameters are non-zero:

kernel.parameters.where(key == /^net\./).all(value != 0)

map.any

Assert that at least one entry in the map satisfies a condition. Empty maps return false.

Any kernel parameter is named kernel.kptr_restrict:

kernel.parameters.any(key == "kernel.kptr_restrict")

map.contains

Check whether any entry in the map satisfies a condition. Returns true if at least one match is found.

At least one kernel parameter vm.swappiness is set to 60 or less:

kernel.parameters.contains(key == "vm.swappiness" && value <= 60)

map.keys

Return the keys of a map as an array.

List kernel parameter names:

kernel.parameters.keys

map.length

Return the number of entries in a map.

Count the number of installed packages:

packages.length

map.none

Assert that no entries in the map satisfy a condition.

No kernel parameter named net.ipv4.ip_forward is set to 1:

kernel.parameters.where(key == "net.ipv4.ip_forward").none(value == 1)

map.one

Assert that exactly one entry in the map satisfies a condition.

Exactly one label sets the environment to prod:

asset.labels.one(key == "env" && value == "prod")

map.sample

Return a random sample of entries from a map. When a number is provided, returns that many entries.

Return a single random kernel parameter:

kernel.parameters.sample

map.values

Return the values of a map as an array.

List kernel parameter values:

kernel.parameters.values

map.where

Filter map entries by a boolean condition. Returns a new map with only the matching key/value pairs.

Kernel parameters with names starting with net.:

kernel.parameters.where(key == /^net\./)

String Functions

string.camelcase

Convert a string to camelCase.

Convert a phrase to camelCase:

"hello world".camelcase

string.contains

Check if a string contains a substring or matches a regex. Returns true if found.

Check if /etc/passwd content contains root:

file("/etc/passwd").content.contains("root")

string.downcase

Convert a string to lowercase.

Convert a username to lowercase:

"ROOT".downcase

string.find

Find all regex matches in a string. Returns an array of matches.

Find all numeric substrings:

"error codes: 123 456 789".find(/[0-9]+/)

string.in

Check if the string is contained in a list. Returns true if found.

Check if prod is in the list of environments:

"prod".in(["dev","test","prod"])

string.inrange

Check if the string (when interpreted as a number) falls within a range. Returns true if within bounds.

Check if "42" is between 10 and 100:

"42".inRange(10, 100)

string.length

Return the number of characters in a string.

Count the characters in a package name:

"openssl".length

string.lines

Split a string into an array of lines.

Split /etc/passwd into lines:

file("/etc/passwd").content.lines

string.notin

Check if the string is not contained in a list. Returns true if not found.

Check if qa is not in the list of environments:

"qa".notIn(["dev","test","prod"])

string.split

Split a string by a delimiter. Returns an array.

Split a comma-separated string:

"dev,test,prod".split(",")

string.trim

Trim whitespace (or optionally specified characters) from the beginning and end of a string.

Trim spaces from a string:

"  hello  ".trim

string.upcase

Convert a string to uppercase.

Convert a username to uppercase:

"root".upcase

Number Functions

number.inrange

Check if a number falls within a specified inclusive range. Returns true if within bounds.

Check if a number is between 10 and 100:

42.inRange(10, 100)

Time Functions

time.days

Return the days component of a time or duration.

Get the days value of the current time:

now.days

Extract days from a parsed duration:

parse.duration("2d3h").days

time.hours

Return the hours component of a time or duration.

Get the hours value of the current time:

now.hours

Extract hours from a parsed duration:

parse.duration("1h30m15s").hours

time.inrange

Check whether a time falls between two other times (inclusive).

Check if the current time is in a maintenance window:

now.inRange(
  parse.date("2006-01-02 15:04", "2025-05-01 00:00"),
  parse.date("2006-01-02 15:04", "2025-05-01 06:00")
)

Check if a certificate expiry date is within the next 30 days:

cert.notAfter.inRange(now, now + parse.duration("720h"))

time.minutes

Return the minutes component of a time or duration.

Get the minutes value of the current time:

now.minutes

Extract minutes from a parsed duration:

parse.duration("1h30m15s").minutes

time.seconds

Return the seconds component of a time or duration.

Get the seconds value of the current time:

now.seconds

time.unix

Convert a time into Unix epoch seconds.

Get the current Unix epoch:

now.unix

Convert a parsed date into Unix epoch:

parse.date("2006-01-02", "2025-01-01").unix

IP / Network Functions

ip.address

Return the network address of a CIDR.

Get the network address from a CIDR:

ip("192.168.1.10/24").address

IPv6 example:

ip("2001:db8:abcd:1::123/64").address

ip.cidr

Return the CIDR block as a string.

CIDR for an IPv4 address with mask:

ip("10.0.5.7/16").cidr

CIDR for an IPv6 network:

ip("2001:db8::1/48").cidr

ip.inrange

Check whether an IP (or network) is within another network (inclusive). Returns true if contained.

IPv4 address in a CIDR:

ip("10.0.5.7/32").inRange("10.0.0.0/16")

IPv6 address in a CIDR:

ip("2001:db8::123/128").inRange("2001:db8::/48")

ip.isunspecified

Return true if the IP is unspecified (0.0.0.0 for IPv4 or :: for IPv6).

Unspecified IPv4:

ip("0.0.0.0/0").isUnspecified

Unspecified IPv6:

ip("::/0").isUnspecified

ip.prefix

Return the network prefix (network portion) of the IP.

IPv4 example:

ip("192.168.0.1").prefix

Another IPv4 example:

ip("10.0.5.123").prefix

ip.prefixlength

Return the prefix length of a CIDR.

Prefix length for IPv4:

ip("192.168.1.10/24").prefixLength

Prefix length for IPv6:

ip("2001:db8::1/56").prefixLength

ip.subnet

Return the subnet derived from the CIDR.

IPv4 example (to be confirmed):

ip("192.168.0.1/24").subnet

IPv6 example:

ip("2001:db8::123/64").subnet

ip.suffix

Return the host suffix (host bits) of the IP within its network.

IPv4 example:

ip("192.168.0.1").suffix

ip.version

Return the IP version (4 or 6).

IPv4 example:

ip("192.168.1.10/24").version