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:
Operator | Description | Example query | Hit | Miss |
---|---|---|---|---|
| Matches if the field contains the value. For string fields, this performs a case-insensitive substring match. |
|
|
|
| Matches if the field is exactly equal to the value. For string fields, this performs a case-sensitive exact match. |
|
| anything else |
| Matches if the field’s value matches against the given regex. Regex matches against any part of the field that matches the regex input. You may include your own ^ and $ characters at the beginning and end of a regex, respectively, but using ^ or $ elsewhere will cause the query to fail. Note that in CenQL, special characters must be double-escaped with two backslashes. For example, \w+ and \. |
|
|
|
| Matches by comparing the field’s value to the specified value. Range operators work for string, numbers, dates, and ip addresses. |
|
|
|
| Matches if the field contains any non-zero value |
|
| "" |
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
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
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
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:
Type | Description | Examples |
---|---|---|
Number | A floating point number |
|
Boolean | True or False |
|
IP Address | IPv4 and IPv6 values |
|
CIDR | A range of IP addresses. CIDR notation must be wrapped in quotation marks or backticks. |
|
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 |
|
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 target | CenQL query |
---|---|
Hosts with a specific service on a specific port | host.services: (port = "22" and protocol = "SSH") |
Hosts with a specific software version installed | host.services.software: (product = "httpd" and version = "2.4.62") |
Hosts with a specific HTTP header | host.services.endpoints.http.headers: (key = "Server" and value.headers = "nginx") |
Hosts running a specific software with a specific HTML title | host.services: (software.product = "nginx" and endpoints.http.html_title = "Welcome to nginx!") |
Updated about 14 hours ago