1. Censys
  2. Censys Internet Intelligence Platform
  3. How to Use the Internet Intelligence Platform

Other Articles In This Section

In this article

Censys Query Language in the Internet Intelligence Platform

Use CenQL to write queries and search your data in the Censys Internet Intelligence Platform (IIP).

A complete list of data fields available for host, web property, and certificate records in IIP is available in the in-app data definitions.

To learn about searching data in Search 2.0, please see Writing Queries in Censys Search Language.

CenQL syntax

Primary search methods

There are two primary ways to search for hosts, web properties, and certificates:

  • Full document query: Searching across the entire record for a value, like "example.com". 
    • A full-document query matches any document that contains the search term in any field. 
  • Field query: Searching on a specific field, like host.location.city="Ann Arbor".

    • Field queries target a specific field on the document and can specify the comparison behavior. The format of a field query is <field name> <operator> <value>.
    • The Field query operators table below outlines the various operators that are supported.

Both field queries and full-document queries can be combined with logical operators like and, or, and not.

Field query operators

The following operators are supported for field queries:

Operator Description Example query Hit Miss
:

Matches if the field contains the value.

For string fields, this performs a case-insensitive substring match.

 field: "hello" Hello World Hi World
=

Matches if the field is exactly equal to the value.

For string fields, this performs a case-sensitive exact match.

 field= "hello" hello anything else
=~

Matches if the field’s value matches against the given regex.

Regex matches against the entire field, there is an implicit leading ^ and trailing $.

Note that in CenQL, special characters must be double-escaped with two backslashes. For example, \\w+ and \\.

 field=~ "Hello.*" Hello World World Hello
>, <, >=, <=

Matches by comparing the field’s value to the specified value.

Range operators work for string, numbers, dates, and ip addresses.

 field > 10 20 9
:* Matches if the field contains any non-zero value field: * hello ""
: (<expression>) Matches if <expression> returns true for a single nested value in the field. host.services:(port: 80 and protocol: HTTP) [{port: 80, protocol: "HTTP"}] [{port: 443, protocol: "HTTP"}]

See examples of relative time queries using CenQL operators here.

Note that CenQL uses standard comparison operators (>, <, >=, <=), which differs from Censys Search Language used in Search 2.0 ([x TO y]).

Supported values

CenQL supports the following value types:

Type Description Examples
Number A floating point number
  • 0
  • 100
  • 1.1234
Boolean True or false
  • true
  • false
IP Address IPv4 and IPv6 values
  • 1.1.1.1
  • ff06::c3
CIDR A range of IP addresses
  • 192.0.2.0/24
  • 2001:db8::/32
String

Quoted strings may contain white-space, keywords, escapes, and certain special characters.

Quoted strings may use single ' or double " quotes. String that are quoted in backticks ` do not need to escape any character except a backtick.

Unquoted strings are limited to those that match the regex [a-zA-Z][a-zA-Z0-9\.\_\-]*
  • "hello world"
  • "hello \"world\""
  • 'hello "world"'
  • hello
  • hello.world
  • hello-world
  • hello_world
  • `hello " ' world`
  • `hello \ world`

Full text search

CenQL's advanced queries require that keywords are unquoted and multi-word values are quoted.

CenQL will perform case-insensitive substring matching with the colon operator.

Examples:

  • my.field: foo

  • my.field: "foo bar faz"

Nested fields

Use nested fields to apply multiple search criteria to a single object within a list of like objects, instead of to the entity as a whole. This accomplishes the same function as using same_service in Search 2.0.

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.

Some examples of nested fields in CenQL queries are provided below.

Query target CenQL query
Hosts with a specific service on a specific port host.services: (port = "22" and protocol = "SSH")
Hosts with a specific software version installed

host.services.software: (product = "httpd" and version = "2.4.62")
Hosts with a specific HTTP header

host.services.endpoints.http.headers: (key = "Server" and value.headers = "nginx")
Hosts running a specific software with a specific HTML title

host.services: (software.product = "nginx" and endpoints.http.html_title = "Welcome to nginx!")

Related articles