Full Text Searches
When no field is specified, Censys attempts a full-text search over all fields.
For example, searching for
apple
will return certificates whose parsed.names
section contains the word as well as certificates that were issued by Apple Inc. If you're interested in Apple-issued certificates, you'd want to specify the field (parsed.issuer.organization
) 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 all fields and their value types under the Data Definitions tab or, on a certificate record details page, choose a Raw Data view, such as the table view of the certificate for this Apple Root CA.
A typical search provides at least one field—which reflects the nesting of the JSON schema using dot notation (e.g., parsed.subject_key_info.fingerprint_sha256
)—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 find all certificates with a certain parent certificate using this field-value search:
parent_spki_fingerprint_sha256: 390bc358202771a65e7be7a87924d7f2a079de04feb5ffd4163fae4fbf9b11e9
.
Since this field's value type is a keyword, only an exact match will be returned. In other words, you can't search fingerprint
fields with a partial fingerprint (without using a wildcard).
Wildcards
By default, Censys searches for complete values. For example, the search for the word
app
will not return certificates records that contain the word apple
.
Wildcards can be used to expand a search to include partial matches in the results.
There are two wildcards:
-
?
— This wildcard indicates a single character. -
*
— This wildcard indicates zero or more characters.
The query below leverages wildcards to search for certificates issued to organizations that use a domain with the word "security:"
parsed.subject_dn: *@*security.*
The other use of the *
wildcard is to check for the existence of a field, which is helpful for certificates whose characteristics are unknown.
For example, this query will return certificates that contain an email address within the subject:
parsed.subject.email_address: *
Combining Search Criteria with Boolean Logic
Combine multiple search criteria using and
,
or
, not
, and parentheses. Booleans are case insensitive.
AND
Specify multiple criteria that must be true in order for a certificate to be considered a match.
Example:parsed.issuer_dn: * and parsed.subject_dn: * and parsed.validity_period.length_seconds=8639913600
will return any certificates with a value for both the Subject DN, and a validity length of 99999 days.
OR
Provide multiple options that a certificate could match in order to be considered a hit.
Example:
parsed.issuer.common_name: "Let's Encrypt" or parsed.issuer.common_name: "Apple, Inc."
will return any certs that are issued by either Let's Encrypt or Apple.
You can also use the set operator to shorten repetitive or statements by putting desired values in curly brackets:
parsed.issuer.common_name: {"Let's Encrypt", "Apple, Inc."}
NOT
Exclude certificates with certain characteristics.
Searching for
not labels=ct
returns certificates that were not sent to a Certificate Transparency log.
Ranges
Search for numerical values within a range using [
and ]
for inclusive ranges and {
and }
for exclusive
ranges.
Dates should be formatted according to RFC 3339 with the full range of specificity supported: [2023-01-01
to 2023-2-28:18:12.50.000000001Z]
. One-sided limits can also be specified:
[2023 to *]
. The to operator is case insensitive.
Nested Field Syntax
Nested fields are lists of repeated records. 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.
Example:
ct.entries: (key: `cloudflare_nimbus_2023` and value.added_to_ct_at: [2022-11-24 to 2022-12-31])
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.
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,
names: `*.censys.io`
returns certificates whose names section contains a name with the actual asterisk (*
) present.