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-text queries and field queries.

Full-text search

A full-text search searches across the entire record for a value, such as “example.com.” It matches any record that contains the search term in any field.

📘

Note

Full-text queries only target the cert.names, cert.parsed.issuer_dn, and cert.parsed.subject_dn fields for certificate records.

Field-value pairs

CenQL queries can target field-value pairs, like host.location.city="Ann Arbor".

• Field queries target a specific field on a record and can specify the comparison behavior. The syntax for targeting a field-value pair is <field name> <operator> <value>.
• The table below outlines the field-value pair operators that are supported.

Field-value pairs and full-text searches can be combined with logical operators like and, or, and not. You can use comparison operators to target ranges of values.

Field-value pair operators

The following operators are supported for field queries:

Tokenization

The : operator in CenQL uses tokenization to split text into searchable "chunks." Instead of scanning the entire data field as one large block of text, the Platform breaks it into smaller tokens.

Tokenization examples

The two examples below describe how tokenization works in the Censys Platform.

• If you query web.endpoints.http.body: "click save", our Platform locates all services running HTTP and scans the body. It tokenizes "click" and "save" separately and ensures that they are in close proximity to each other in the body. Optimized tokenization allows Censys to handle large amounts of data, including HTML bodies, titles, and metadata, without slowing down performance.
• Similarly, when a user searches for access=denied, the query undergoes the same tokenization process, converting access=denied into access denied. When the Platform checks the document, it verifies whether the query's tokens appear in the correct order. Since the document contains access denied (even though it was originally written as access+denied), the search still matches.

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 in the table 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.

not

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

Parentheses and brackets

Use parentheses to include multiple field value pairs or nested fields in a single search query. Brackets can be used to target specific values.

Ranges

Ranges for values like numbers and dates can be defined using the comparison operators >, <, >=, and <=. Integer and date values must be wrapped in quotes or backticks.

You can also use relative time variables with comparison operators.

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.

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.

Unicode escape sequences

The following sequences will be interpreted as unicode escape sequences to allow users to search for these special characters where they are commonly found, such as service banners and HTTP bodies.

Regular expression (regex)

CenQL supports using regular expression (regex) in advanced queries. Documentation for using regex in CenQL is available here.

Supported values

CenQL supports the following value types: