Full Text Searches

When no field is specified, Censys attempts a full-text search over all fields.

For example, searching for Dell will return hosts whose location.city is "Dell Rapids" in addition to hosts whose services.software.vendor is "Dell." If you're interested in Dell-manufactured devices, you'd want to specify fields where that information is stored.

Specifying Fields and Values

Effective searches will specify the field where an attribute is stored. For this, you'll need to know the fields in the dataset you're searching.

See a full list of fields and their value types under the Data Definitions tab or choose to view Raw Data on a details page, such as the table view of the host for Google Public DNS.

A typical search provides at least one field—which reflects the nesting of the JSON schema using dot notation (e.g., services.http.response.headers.server.headers)—and a value. If the value type is text, a fuzzy match would be returned as a result; if the value type is keyword, only an exact match would be returned.

For example, you can search for all hosts with an HTTP service returning an HTTP status code by specifying the field and value: services.http.response.status_code: 500 .

Wildcards

By default, Censys searches for complete values. For example, the search Del will not return records that contain the word Dell. Wildcards can used to expand a search to include partial matches in the results.

There are two wildcards:

  • ? — This wildcard indicates a single character.
  • * — This wildcard indicates zero or more characters.
Combining wildcards can be extremely useful as well.

The query below leverages knowledge of the CPE software format and searches for services running Microsoft IIS webservers with a major version <10 (because the ? represent only a single character) and a minor version identified (because of the presence of the period). The * wildcard accounts for the rest of the CPE format: services.software.uniform_resource_identifier: cpe:2.3:a:microsoft:iis:?.*

The other use of the * wildcard is to check for the existence of a field, which is helpful for hosts whose services are unknown. For example, this query will return hosts with at least one service that has completed a TLS handshake with Censys: services.tls: *

Networks, Protocols, and Ports

Search for blocks of IP addresses using CIDR notation (e.g., ip: 23.20.0.0/14) or by providing a range: ip: [23.20.0.0 to 23.20.5.34]. Search for hosts running a particular protocol by searching the service name field: services.service_name: S7 . Search for hosts with specific ports by searching the port field: services.port: 3389

Combining Search Criteria with Boolean Logic

Combine multiple search criteria using AND, OR, NOT, and parentheses. Booleans are case insensitive.

By default, criteria combined by boolean expressions are evaluated against a host as a whole.

AND

Searching for services.port: 8880 and services.service_name: HTTP will return hosts that have port 8880 open (with ANY service running on it) and a HTTP service running on ANY port.

To search for HTTP services running on port 8880, use the same_service() function: same_service(services.port: 8880 and services.service_name: HTTP) .

OR

Searching for services.port: 21 or services.service_name: FTP will return any hosts that have either port 21 open (with ANY service running on it) and an FTP service running on ANY port.

NOT

Searching for not same_service(service_name: HTTP and port: 443) would return hosts that do not have HTTP running on 443.

Searching for same_service(service_name: "HTTP" and not port:443) would return any host that has an HTTP service that is not running on port 443. This could include hosts that have HTTP on 443, as long as there is one other HTTP service on a different port number.

Ranges

Search for ranges of numbers using [ and ] for inclusive ranges and { and } for exclusive ranges. For example, services.http.response.status_code: [500 to 503] . Dates should be formatted using the following syntax: [2012-01-01 to 2012-12-31]. One-sided limits can also be specified: [2012-01-01 to *]. The to operator is case insensitive.

Regular Expressions

Regexes are restricted to paid customers. The full regex syntax is available here.

Note Censys regex searches are case-insensitive except when the exact match operator = is used.

For example, services.software.vendor:/De[l]+/ will return results where the word is either capitalized or lowercase, while services.software.vendor=/De[l]+/ will only return results for the capitalized word.

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.

Escape Sequence Character Represented
\a Alert
\b Backspace
\e Escape character
\f Formfeed / Page break
\n Newline
\r Carriage return
\t Horizontal tab
\v Vertical tab
For example, services.banner="Hello\nWorld" will interpret the \n as a newline instead of as an escaped n.

Reserved Characters

The following characters will be interpreted as control characters unless they are escaped (i.e., preceded) with a backslash or encapsulated in a string that is surrounded by back ticks.

= > < ) } ] " * ? : \ /

For example, asterisks are common in CPE software identifiers, and escaping each asterisk is tedious, so backticks around the URI will escape all of the asterisks within: (services.software.uniform_resource_identifier: `cpe:2.3:a:cloudflare:cloudflare_load_balancer:*:*:*:*:*:*:*:*`).