Censys Search Language

Use the Censys Search Language (CSL) in both Legacy Search and Attack Surface Management (ASM). While both products use CSL, the the available fields in each differ.

• In Legacy Search, you use CSL to search across the map of the entire Internet when targeting host records or billions of certificate records when targeting certificates.
• In ASM, you use CSL to search across web assets that been attributed to your organization via Censys' exhaustive attribution process.
  • Asset record data fields in ASM are prepended by the type of asset they have been identified on. For example, host.dns.names is present on host assets and web_entity.port is present on web entity assets.

Queries written in the Censys Search Language provide criteria that a record must meet to be returned as a hit.

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

Field-value pairs

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 (=).

📘

Note

You can see all of the data fields available in the Legacy Search datasets on the data definitions page in the web app.

Legacy Search examples

ASM examples

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.

Legacy 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.

ASM example

Boolean logic

Censys allows the binary operators or, and, 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.

Legacy Search examples

ASM examples

AND

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

Legacy Search example

📘

Note

Unless specified, search criteria apply to a host or certificate as a whole. This query returns hosts with any service on port 443 and HTTP on any port.

ASM example

📘

Note:

The query returns hosts with any service on port 443 and HTTP on any port. To apply the search criteria to single service, see the Nested Searches syntax section below.

NOT

Use not to exclude hosts with certain characteristics.

Legacy Search example

ASM examples

Nested fields

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.

Examples of nested fields include:

Legacy 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.

ASM examples

Time ranges and values

Use relative time variables to reference relevant time frames in your queries.

Legacy Search examples

Censys ASM examples

Ranges

Ranges allow you to define a spectrum within which a value may fall for the host to be considered a hit. This is useful for numerical values such as dates, version numbers, and IP addresses.

Legacy Search examples

ASM examples

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.

Legacy Search example

ASM example

Escape sequences and reserved characters

Escape sequences

The following sequences are interpreted as Unicode escape sequences. Use them to search for special characters in commonly used places, 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.

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 backticks.

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

Use backticks around the entire URI to escape all the asterisks within.

Legacy Search example

ASM example