Censys Search Language

The Censys Search Language is what you use to find hosts that are of interest to you. Queries written in the Censys Search Language provide a list of criteria that a host must have have in order to be returned as a hit.

This guide will introduce query writing with examples that you can follow to see in the Search product.

Search Basics: Construct a Query

Full Text Searches

A query that doesn’t specify a field will launch a search across all text-based fields for the word or phrase submitted.

Query for Hosts with any field that contains the term “hello”:

hello

You can search for a multiple-word phrase by surrounding it in double quotes.

Query for Hosts with any field that contains the term “Hello World”:

 "Hello World"

These searches are not case sensitive. You will see results with any capitalization of the letters in your search term.

Querying With Field, Value Pairs

Search structured fields for a value that can be stored there. Fields reflect the nested structure of the host schema using dot notation to separate keys.

Find all devices that have an HTTP Server header with the word "Apache" in it:

services.http.response.headers.server: Apache

Important! The search above does not limit hits to only the exact word specified. So a host with “Apache Server” in the server header would also be returned as a result.

If you want to search for an exact match, use the equals operator (=).

Find all devices whose HTTP Sever header contains exactly the word "Apache":

services.http.response.headers.server=Apache

Wildcard Searches

You can use the asterisk symbol (*) to substitute zero or more unknown characters. Use the question mark (?) to substitute for exactly one unknown character. These wildcard symbols are helpful for finding records where you know some part of a value, but not how it will end.

For example, the search above returns hosts with the Server header “Apache” and “Apache Server”, but does not return hosts with “Apache/2.4.38” in the server header since it matches on whitespace-delimited words.

Search for server header values that start with Apache using the wildcard:

services.http.response.headers.server: Apache*

Warning! Censys does not support leading wildcard searches (e.g., “*Apache”) because we’re unable to use any indices to complete this search.

However, since leading wildcards are very desirable for fields containing DNS-style domain names (e.g., the name on a certificate), the search “censys.io” will include results for all subdomains of censys.io by default. To restrict those searches to exactly the name provided, use the equals operator (=).

Boolean Logic

Censys allows the binary operators and, or, and not, as well as parentheses to combine search criteria.

OR

Use or to provide multiple options that a host could match in order to be considered a hit.

Return all hosts located either in the United States or Canada:

location.country: Canada or location.country: “United States”

You can also use a set to shorten what would otherwise be a long or statement.

Return all hosts whose country is among this set of countries in the Americas:

location.country: {Canada, Chile, Honduras, Mexico, “United States”, Uruguay}

AND

Use and to make a search more specific by providing multiple criteria that must match in order for a host to be considered a hit.

Return hosts with port 443 open (with any service running) and an HTTP service running on any port:

services.port: 443 and services.service_name: HTTP

Important! Search criteria applies to a host as a whole, unless specified otherwise. The query above returns hosts with any service on port 443 and HTTP on any port.

Searching in the Same Service

Use the same_service() operator to apply multiple search criteria to a single service.

Return hosts that are running an HTTP service on port 8888:

same_service(services.port: 8888 and services.service_name: HTTP)

NOT

Use not to exclude hosts with certain characteristics.

Find hosts running SSH on a non-standard port (i.e., neither 22 nor 2222):

same_service(services.service_name: SSH and not service.port: {22, 2222})

Ranges

Ranges allow you to specify a spectrum that a value may fall into in order for the host to be considered a hit. This is useful for numerical values such as dates, version numbers, and even IP addresses.

Search for hosts whose rDNS name was resolved by Censys within a (recent) date range, not including the first value given:

dns.reverse_dns.resolved_at: {2021-11-22 to 2021-11-23]

Search for online IPs in a non-standard IP range, including the first and last values given:

ip: [216.189.94.1 to 216.189.94.32]

Censys also supports CIDR notation of IP ranges, which shows a IPv4 or IPv6 address with a slash followed by a decimal to indicate how many bits (from left to right) are fixed and do not change.

Search for online hosts whose IPv4 address fall between 8.8.0.0 and 8.8.255.255:

ip: 8.8.0.0/16

Quotes

Double Quotes (")

Double quotes are for searching for a phrase instead of a single word. You must wrap whitespace-separated words in double quotes when searching in order for the phrase to be evaluated as a whole. Searches that specify a phrase for a field value are invalid without the double quotes.

Search for hosts with an HTML title 

services.http.response.html_title: "your dashboard"

Backticks (`)

Backticks are used to escape all reserved characters occurring therein. For example, CPE-formatted software strings use many reserved characters. Instead of escaping each one, wrap the whole string in backticks.

Search for hosts running Microsoft IIS version 10.0:

services.software.uniform_resource_identifier: `cpe:2.3:a:microsoft:iis:10.0:*:*:*:*:*:*:*`