Use Relative Time in Queries

This guide explains how to use relative time in your Censys Query Language (CenQL) queries in the Censys Platform.

Changes from Censys Search Language in Legacy Search

Searching across time ranges in CenQL differs from the approach used in Censys Search Language (CSL), the domain-specific language for Legacy Search. The primary differences are as follows:

CenQL uses the comparison operators <, >, <=, and >= for defining ranges. The target time range must be wrapped in quotation marks.

For more information about CenQL operators, see Censys Query Language.

In CenQL, as in CSL, you can use the now value to indicate the approximate time at the moment of your search.

The table below provides an example of a CSL query that uses relative time and its equivalent syntax in CenQL.

Query description	CSL syntax	CenQL syntax
Certificates that were added in the past hour	`added\_at: \[now-1h TO \*]`	`cert.added\_at > "now-1h"`

Simple relative time example queries

Use relative time variables to reference relevant time frames in your queries. The following table contains some example CenQL queries that highlight how to target different timeframes and variables.

Description and timeframe	CenQL query
Hosts with certificates that were added to Censys within the last 24 hours	`host.services.cert.added\_at > "now-24h"`
Hosts with certificates that were added to Censys within the last 4 days	'host.services.cert.added_at > "now-4d"'
Hosts with certificates that were added to Censys within the last week	host.services.cert.added_at > "now-1w"
Hosts with certificates that were added to Censys within the last month (note that month is denoted by a capital M)	host.services.cert.added_at > "now-1M"
Hosts with certificates that were added to Censys within the last year	host.services.cert.added_at > "now-1y"
Certificates that were revoked in the past 8 hours	cert.revocation.crl.revocation_time > "now-8h"
Websites that presenting certificates that were revoked in the past year	web.cert.revocation.crl.revocation_time > "now-1y"
Hosts with services that were last scanned in the past hour	host.services.scan_time > "now-1h"

Searching forward in time

Not all fields support searching in the future. However, some fields, like host.services.software.life_cycle.end_of_life_date or cert.parsed.validity_period.not_after, can have valid dates that are in the future.

Here are some example queries you can run to search the future:

Description and timeframe	CenQL query
Hosts running software that is either already end-of-life or will be end-of-life in the next 6 months	host.services.software.life_cycle.end_of_life_date < "now+6M"
Certificates that are expiring in the next 8 hours	cert.parsed.validity_period.not_after > "now" and cert.parsed.validity_period.not_after < "now+8h"

Complex relative time queries

You can use rounding and multiple comparison operators to be very specific about what dates you want to target. Using \[time variable] rounds to the nearest day, minute, hour, month, etc. The following table contains some complex query examples.

Description and timeframe	CenQL query
Hosts with certificates that were added to Censys today	host.services.cert.added_at > "now/d" and host.services.cert.added_at< "now+1d/d"
Hosts with certificates that were added to Censys yesterday	host.services.cert.added_at > "now-1d/d" and host.services.cert.added_at < "now/d"
Hosts with certificates that were added to Censys either yesterday or today	host.services.cert.added_at> "now-1d/d"
Hosts with certificates that were added to Censys within the last calendar week	host.services.cert.added_at > "now/w" and host.services.cert.added_at < "now+1w/w"
Hosts with certificates that were added to Censys within the last calendar month	host.services.cert.added_at > "now/m" and host.services.cert.added_at < "now+1m/m"
Hosts with certificates that were added to Censys within the last calendar year	host.services.cert.added_at > "now/y" and host.services.cert.added_at < "now+1y/y"