Censys Query Language

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

There are two primary ways to search across host, web property, and certificate data: full-text queries and field-value queries. You can also use the Query Assistant in the Platform web UI to generate valid CenQL queries using natural language input.

📘

Note

You can directly look up a host or certificate by entering its IP address or SHA-256 hash, respectively, in the Platform search bar.

Full-text queries

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.

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

Field-value queries

CenQL queries can target field-value pairs, like host.location.city="Ann Arbor". 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.

• 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:

field=~`^Hello\s\w{5}$`

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 for hosts and web properties in the Censys Platform.

• If you run the query web.endpoints.http.body: "click save", the 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 web.endpoints.http.body: "access=denied, the query undergoes the same tokenization process, converting access=denied into access denied and will match on that phrase. When the Platform checks a document, it verifies that the query's tokens appear in the correct order.

Tokenization and certificate data

Tokenization via the : operator works differently for certificate data in the Platform.

All *.common_name and cert.names fields utilize a subdomain analyzer. This method would extract the tokens abcdefg-1234567.example.domain.com,example.domain.com, and domain.com from cert.parsed.subject.common_name: "abcdefg-1234567.example.domain.com".

The only way to search for matches based on a component of a string that would be tokenized when using : is to use regex. For example, you could run:

cert.parsed.subject.common_name=~`^abcdefg-1234567`

This would return any certificates with common names that begin with abcdefg-1234567.

Aliased fields

Some fields are grouped into aliases to make it easier to search across multiple fields at once. Aliases can be used in the Platform web UI or API.

The table below lists aliases and their fields.

Alias nuances

Aliases cannot be used in queries that target nested fields. For example, host.services: (protocol: SSH and product: "OpenSSH") is invalid.

Only fields that your account has access to are included in an alias search. If you search across the product alias on a Censys Free account, then *.components fields will not be included.

You cannot create a report broken down by an alias.

twist function

Use the twist function to find field values that are similar to a specified value. This is similar to the functionality provided by dnstwist, but has a more limited scope. When targeting domains, the twist function in CenQL will run fewer permutations than dnstwist does.

Additionally, the function is less successful at finding related values to domains that are limited to two or three characters (for example, ab.com or abc.com).

The twist function is available to all users.

You can build queries that incorporate the twist function using the following structure:

twist([fieldname], `[value]`)

You can use the twist function to find typosquatted domains or domains attempting to impersonate a valid domain by omitting known domains from your query. For example, the following query will find web properties that use names similar to censys.io but will omit results that include censys.io.

twist(web.hostname, `censys.io`) and not web.hostname:`censys.io`

You can use a query similar to the one provided above in a collection to find existing and new suspicious domains.

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.

Quick search across CIDR blocks

To quickly search for a CIDR block in the Platform web UI, you can input a range of IPs in CIDR notation in the search bar without specifying a field to target.

To combine a CIDR block search with other fields, use host.ip and the format host.ip: "cidrblock".

Field types

When you target certain data fields with CenQL queries, they must include valid values for that field type. The following table provides examples of data field types and values in the Censys datasets.