Censys Query Language

Use Censys Query Language (CenQL) to write queries and search your data in the Censys Platform.

A complete list of data fields available for host, web property, and certificate records in the Platform is available in the in-app data definitions.

There are two primary ways to search for hosts, web properties, and certificates: full-document queries and field queries.

Full-document query

Searches across the entire record for a value, like “example.com”.  A full-document query matches any document that contains the search term in any field. 

Field query

Field queries searches on a specific field, like host.location.city="Ann Arbor".

• Field queries target a specific field on the document and can specify the comparison behavior. The format of a field query looks like <field name> <operator> <value>.
• The field query operators table below outlines the various operators that are supported.

Both field queries and full-document queries can be combined with logical operators like and, or, and not.

Field query operators

The following operators are supported for field queries:

To view examples of relative time queries using CenQL operators, see Relative Time.

📘

Note

CenQL uses standard comparison operators ( >, <, >=, <=) to replace ([x TO y]) that was used by the Censys Search Language in Legacy Search.

Boolean operators and parentheses

You can combine and modify search criteria using and, or, not, and parentheses. Boolean operators are case insensitive.

and

Use and to specify multiple criteria that an entire record must match in order to be considered a hit. The query host.services.port=8880 and host.services.protocol=HTTP will return hosts that have port 8880 open (with any service running on it) and an HTTP service running on any port.

Note that the query syntax provided above does not require that returned matches are on the same service, just that a host has both of the queried field values present anywhere on the record. The query syntax above could return host records that use port 8880 and are not HTTP. To require that multiple search criteria are present in a single nested object, you need to use nested fields.

or

The or operator can be used to provide multiple criteria that a record can match in order to be considered a hit.

The query host.services.port=21 or host.services.protocol=FTP returns any hosts that have either port 21 open (with any service running on it) or an FTP service running on any port.

not

The not operator is used to provide criteria that a host must not match in order to be considered a hit.

The query not host.location.country="United States" returns all host records not located in the United States.

Parentheses

Use parentheses to include multiple field value pairs or nested fields in a single search query.

The query not (host.location.country="United States" or host.location.country="India") returns all host records not located in the United States or India. Another version of this query is not (host.location.country: {"United States", "India"}), which uses {} brackets to target a range of values in the host.location.country field.

A complex example using parentheses and boolean operators is host.services.port: 80 and host.services.port: 443 and not host.services:(not port:{80, 443}). This query will only return hosts with services on both port 80 and 443.

Supported values

CenQL supports the following value types:

Nested fields

Use nested fields to apply multiple search criteria to a single object within a list of like objects instead of to the entity as a whole. This accomplishes the same function as using same_service in Legacy Search.

To apply all of the search criteria to a single object within an array, use parentheses to group those nested fields after the colon separating the nested field name.

Some examples of nested fields in CenQL queries are provided below.