Relative Time in CenQL
This guide explains how to use relative time in your Censys Query Language (CenQL) queries in the Censys Platform. Reference the CenQL documentation on ranges for information about how to use ranges in general.
In CenQL queries, time ranges or values must be wrapped in quotation marks or backticks.
Relative time queries can be used in collections. For example, they can be used to find certificates that are expiring within a specific timeframe.
Units of time in CenQL
You can use the characters indicated in the table below to input units of time in CenQL queries.
You can prepend these characters with numerical values. For example, you can input 2M to indicate two months.
| Unit of time | Character |
|---|---|
| Minute | m |
| Month | M |
| Hour | h |
| Day | d |
| Week | w |
| Year | y |
Simple relative time example queries
Use relative time variables to reference relevant time frames in your queries. Use - with relative time variables to search for time values in the past. 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" |
Search 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. Use + with relative time variables to search for time values 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" |
| Certificates that contain a specific name in the subject common name that are expiring within the next month | cert.parsed.subject.common_name: "example.com" and cert.parsed.validity_period.not_after >= "now" and cert.parsed.validity_period.not_after < "now+1M" |
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, and so on. 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" |
Changes from Censys Search Language
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.
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. Use the Query Converter in the Platform web UI to convert your relative time CSL queries to CenQL syntax.
| Query description | CSL syntax | CenQL syntax |
|---|---|---|
| Certificates that were added in the past hour | added_at: [now-1h TO *] | cert.added_at > "now-1h" |
Updated 19 days ago