Writing Queries in Censys Search Language
Overview
You can use the Censys Search Language in both Censys Search and Censys Attack Surface Management (ASM) to write queries and search your hosts, certificates, and assets. While the search language is the same across both platforms, the available fields differ.
- Search host and certificate records in Censys Search
- Search assets in Censys ASM
Queries written in the Censys Search Language provide criteria that a record must meet to be returned as a hit.
Using AI to produce query syntax
Censys offers a Beta feature that leverages the natural-language processing of ChatGPT to produce valid query syntax in the Censys Search Language. Note that this is only available for creating queries to use in Censys Search; it is not available for Censys ASM queries. Check it out here: CensysGPT Beta.
Full text searches
You can search for a word or phrase. When you do not specify a field, the search is conducted across all text-based fields. The search terms are not case sensitive.
Examples
- Query for hosts with any field that contains the term “hello”:
hello
- Query for multi-word phrase "hello world":
"hello world"
Field, Value Searches
Search structured fields for a value stored there. Fields reflect the nested structure of the host schema using dot notation to separate keys. To search for an exact match, use the equals sign (=
).
Censys ASM examples
- Find all assets that have an HTTP Server header with the word "Apache" in it
host.services.http.response.headers.value: Apache or web_entity.instances.http.response.headers.value: Apache
- Find all assets whose HTTP Server header contains exactly the word "Apache"
host.services.http.response.headers.value=Apache or web_entity.instances.http.response.headers.value=Apache
Wildcard Searches
Wildcard symbols are helpful for finding records where you know some part of a value, but not all.
- Use the asterisk symbol (
*
) to substitute zero or more unknown characters. - Use the question mark (
?
) to substitute for exactly 1 unknown character.
Censys Search example
For example, a query that specifies a value of "email" does not return records where the value is “e-mail,” because it matches on tokenized words.
-
Search for variations of email using the
*
wildcard:services.http.response.headers: (key: server and value: e*mail)
Censys ASM example
- Search for server header values that start with hero using the wildcard:
host.services: (http.response.headers.key: server and http.response.headers.value.headers: hero*) or web_entity.instances: (http.response.headers.key: server and http.response.headers.value.headers: hero*)
Boolean logic searches
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 record can match to be considered a hit.
Censys Search examples
You can also use a set to shorten what can 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}
Censys ASM examples
- Return all hosts located either in the United States or Canada:
location.country: Canada or location.country: “United States”
-
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 for a host to be considered a hit.
Censys Search example
NOT
Use not
to exclude hosts with certain characteristics.
Censys Search example
Censys ASM examples
- Find hosts running SSH on a non-standard port (for example, neither 22 nor 2222):
host.services: (service_name: SSH and not port: {22, 2222})
- Find any web entities with an instance using an HTTP protocol other than 1.1:
web_entity.instances.http.response.protocol: * and not web_entity.instances.http.response.protocol: "http/1.1"
Nested Searches
Use nested query syntax to apply multiple search criteria to a single object within a list of like objects, instead of to the entity as a whole.
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.
Nested searches in Censys Search
Commonly used fields
Hosts:
-
services
-
services.software
-
services.http.response.headers
Certificates:
-
ct.entries
Censys Search examples
The services
record on a host can contain any number of services. If you want certain criteria to all be true of a single service on a host, nest field/value pairs inside parentheses following the services
field name.
-
- Return hosts with an HTTP service returning a specific Etag header value:
services.http.response.headers: (key: `Etag` and value.headers: `"6001043d.16d"`)
Time related searches
Relative time
Use relative time variables to reference relevant time frames in your queries.
Time | Command |
Today | [now/d TO now] |
Within the last 4 hours | [now-4h TO now] |
Within the last week | [now-1w TO now] |
Within the last month | [now-1M TO now] |
Within the last year | [now-1y TO now] |
Within the next 12 hours | [now TO now+12h] |
Within the next 24 hours | [now TO now+1d] |
Within the next week | [now TO now+1w] |
Within the next month | [now TO now+1M] |
Censys Search examples
- Search for hosts Updated in the Past Hour:
last_updated_at: [now-1h TO *]
- Search for CVEs with a KEV added in the Past 6 Months:
cves.kev.date_added: [now-6M TO *]
- Search for certificates that were Revoked in the past 8 hours:
revocation.crl.revocation_time: [now-8h TO *]
Censys ASM examples
- Search for a domain that is expiring tomorrow:
Domain.expiration_date: [* TO now+1d]
- Search for a risk discovered in the past 3 days:
Risks.discovered_at: [now-3d TO *]
- Search for assets discovered today:
association_date: [now/d TO *]
Ranges
Ranges allow you to define a spectrum that a value may fall into for the host to be considered a hit. This is useful for numerical values such as dates, version numbers, and IP addresses.
Censys Search examples
Time range
IP range
Censys also supports CIDR notation of IP ranges:
-
Search for online hosts whose IPv4 address fall between 35.180.0.0 and 35.180.255.255
ip: 35.180.0.0/16
Censys ASM examples
Time range
- Search for certificates whose expiration date is within a (recently passed) date range, not including the first value given:
certificate.parsed.validity_period.not_after: {2022-08-01 to 2022-08-23]
IP range
- Search for hosts in a non-standard IP range, including the first and last values given:
host.ip: [216.189.94.1 to 216.189.94.32]
- Search for hosts in use within a network assigned to your organization (use the Seed page to look up these CIDRs):
host.ip: 8.8.0.0/16
Double Quotes (")
Double quotes search for a phrase instead of a single word. You must wrap whitespace-separated words in double quotes when searching for the phrase to be evaluated as a whole. Searches that specify a phrase for a field value are invalid without the double quotes.
Censys Search example
Censys ASM example
- Search for hosts with an HTML title:
host.services.http.response.html_title: "your dashboard"
Escape Sequences and Reserved Characters
Escape Sequences
The following sequences are interpreted as unicode escape sequences. Use them to search for these special characters where they are commonly found, such as service banners and HTTP bodies.
For example, services.banner:"Hello\nWorld"
interprets the \n
as a newline instead of as an escaped n
.
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 |
Reserved Characters
The following characters are interpreted as control characters unless they are escaped (preceded) with a backslash or encapsulated in a string that is surrounded by back ticks.
= > < ) } ] " * ? : \ /
Use backticks around the entire URI to escape all the asterisks within.
Censys Search example
- Search for hosts running Microsoft IIS version 10.0:
services.software.uniform_resource_identifier: `cpe:2.3:a:cloudflare:load_balancing:*:*:*:*:*:*:*:*`
Censys ASM example
- Search for hosts running Microsoft IIS version 10.0:
host.services.software.uniform_resource_identifier: `cpe:2.3:a:cloudflare:load_balancing:*:*:*:*:*:*:*:*`
Comments
0 comments
Article is closed for comments.