Guides
Start typing to search…

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.

CenQL Syntax

Primary search methods

There are two primary ways to search for hosts, web properties, and certificates:

  • Full document query: Searching 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: Searching 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.

📘

You can't perform full text search on certificates in the Censys Platform.

Field Query Operators

The following operators are supported for field queries:

Operator

Description

Example query

Hit

Miss

:

Matches if the field contains the value.

For string fields, this performs a case-insensitive substring match.

field: "hello"

Hello World

Hi World

=

Matches if the field is exactly equal to the value.

For string fields, this performs a case-sensitive exact match.

field= "hello"

hello

anything else

=, ~

Matches if the field’s value matches against the given regex.

Regex matches against the entire field, there is an implicit leading ^ and trailing $.

Note that in CenQL, special characters must be double-escaped with two backslashes. For example, \w+ and \.

field=~ "Hello.*"

Hello World

World Hello

<, >, <=, >=

Matches by comparing the field’s value to the specified value.

Range operators work for string, numbers, dates, and ip addresses.

field > 10

20

9

:*

Matches if the field contains any non-zero value

field: *

hello

""

: (<expression>)

See examples of relative time queries using CenQL operators here.

📘

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

Supported values

CenQL supports the following value types:

Type

Description

Examples

Number

A floating point number

0\ 100 1.1234

Boolean

True or False

True False

IP Address

IPv4 and IPv6 values

1.1.1.1\ ff06::c3

CIDR

A range of IP addresses

192.0.2.0/24\ 2001:db8::/32

String

Quoted strings may contain white-space, keywords, escapes, and certain special characters.

Quoted strings may use single ' or double " quotes. A string that is quoted in backticks ` do not need to escape any character except a backtick.

Unquoted strings are limited to those that match the regex [a-zA-Z][a-zA-Z0-9._-]*

"hello world"\
"hello "world"" 'hello "world"' hello hello.world hello-world hello_world hello " ' world hello \ world

Full text search

CenQL's advanced queries require that keywords are unquoted and multi-word values are quoted.

CenQL performs case-insensitive substring matching with the colon operator.

Examples:

my.field: foo\
my.field: "foo bar faz"

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.

Query targetCenQL Query
Hosts with a specific service on a specific porthost.services: (port = "22" and protocol = "SSH")
Hosts with a specific software version installedhost.services.software: (product = "httpd" and version = "2.4.62")
Hosts with a specific HTTP headerhost.services.endpoints.http.headers: (key = "Server" and value.headers = "nginx")
Hosts running a specific software with a specific HTML titlehost.services: (software.product = "nginx" and endpoints.http.html_title = "Welcome to nginx!")

Updated 4 days ago