Asset Inventory Search Language
The Censys Search Language is what you use to find assets that are of interest to you. Queries written in the Censys Search Language provide a list of criteria that an asset 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 ASM 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 assets 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 assets 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 stored there. Fields reflect the nested structure of the asset schema using dot notation to separate keys.
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
|
Important
|
The search above does not limit hits to only the exact word specified. So an asset with “Apache Server” or "Apache-Serve" 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 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
Advanced Searching Techniques
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.
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*)
Because of the wildcard, this search could return Server headers with a variety of values, such as "heroku-router".
|
Warning
|
Censys does not support leading wildcard searches (e.g., *Hero) because we’re unable to use any indices to complete this search.
|
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
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:
host.location.country: Canada or host.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:
host.location.country: {Canada, Chile, Honduras, Mexico, “United States”, Uruguay}
AND
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 there) and an HTTP service (running on any port):
host.services.port: 443 and host.services.service_name: HTTP
|
Important
|
The query above returns hosts with any service on port 443 and HTTP on any port. To apply the search criteria to single service, see the Nested syntax section. |
NOT
Exclude hosts with certain characteristics using not.
Find hosts running SSH on a non-standard port (i.e., neither 22 nor 2222):
host.services:(service_name: SSH and not port: {22, 2222})
|
Warning
|
Using the NOT operator naïvely can lead to unexpected results. |
For example, the search below:
not web_entity.instances.http.response.protocol: "http/1.1"
seems like it would return any web entities with an instance reporting an HTTP protocol other than 1.1. In actuality, this query will also return any web entity or asset of any type that does not have an HTTP protocol field.
So the query necessary to return (only) web entities with an instance using an HTTP protocol other than 1.1 must specify that a value does indeed exist for that field, followed by the excluding value:
web_entity.instances.http.response.protocol: * and not web_entity.instances.http.response.protocol: "http/1.1"
Nested Queries
Nested fields are an array of objects, like host.services or web_entity.instances.
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.
Find hosts that are running a plain HTTP service on port 443:
host.services: (port: 443 and extended_service_name: HTTP)
Find web entities that have at least one instance with both the word "username" and "password" in the body.
web_entity.instances: (http.response.body: "username" and http.response.body: "password")
Ranges
Ranges allow you to specify a spectrum that a value may fall into in order for the asset to be considered a hit. This is useful for numerical values such as dates, version numbers, and even IP addresses.
Search for certificates whose expiration date was 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]
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]
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 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
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:
host.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:
host.services.software.uniform_resource_identifier: `cpe:2.3:a:microsoft:iis:10.0:*:*:*:*:*:*:*`
Comments
0 comments
Please sign in to leave a comment.