Relative Time in CenQL
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" |
Updated about 2 months ago