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 that can be used in any combination except initially:
-
?— This wildcard indicates a single character. -
*— This wildcard indicates zero or more characters.
The * wildcard can also be used check for the existence of a field with any value, 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: *
Nested Field Syntax
Nested fields are lists of repeated records (like services).
You can require that two field-value pairs must be true of a single record within a nested field using parantheses. The field names in paranthesis do not need to repeat the portion of the path that represents the nested field.
For example, this search is looking for services that are reporting both software packages. The second software package must meet two criteria as well:
services: (software.product: "Windows server 2012 R2" and software: (product: IIS and version: 8.5))
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
Specify multiple criteria that a host must match in order to be considered a hit.
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.
services in parentheses ():
services:(port = 8880 and service_name = "HTTP")
.
OR
Provide multiple criteria that a host can match in order to be considered a hit.
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
Provide critera that a host must not match in order to be considered a hit.
Searching for
not services:(service_name: "HTTP" and port: 443)
would return hosts that do not have HTTP running on 443.
Searching for
services:(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: [2023-08-01 to `2023-08-28T18:12:50.000000001Z`]. One-sided limits can also be specified:
[2023-08-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 |
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 entire URI will escape all of the asterisks within:
services.software.uniform_resource_identifier: `cpe:2.3:a:cloudflare:load_balancing:*:*:*:*:*:*:*:*`
.