Translate Queries for Certs 2.0
Censys Certs 2.0 better represents the data of certificate records, and doesn’t include redundant pre-certificates, but how do you update your old queries?
Browse these "before and after" examples that showcase differences between legacy Certs and Certs 2.0. Observe the differences in data fields, query syntax, and results and then apply the changes to your favorite queries!
Pre-Certificates
Excluding pre-certificates from searches in order to remove redundant hits is no longer necessary. The only time a record of pre-certificate is included in the Censys index is when its final certificate has not been added.
Search Product |
Search Query |
No. of Results |
1.0 |
|
|
2.0 |
|
The only records representing pre-certs in the new data set do not have a corresponding final certificate.
The difference in counts below can be attributed to
Name Searches
Common Name (CN) is deprecated from the X.509 standard in favor of Subject Alternative Names (SAN), which are type-specific; however, since change is slow, issued certificates may be using both or one or the other fields.
For ease of use, Censys collects and store all of the names within the certificate in a single field.
For technical accuracy, this field has been removed from the parsed section of the certificate record and moved to the root level in a field called names.
Search Product |
Search Query |
No. of Results |
1.0 |
|
|
2.0 |
|
Search for Expired Certificates
These queries return certificates that are expired.
Search Product |
Search Query |
No. of Results |
1.0 |
|
|
2.0 |
|
Labels are replacing tags with categorization and other information attached by Censys for fast searching and filtering.
Also, unlike tags, labels related to validation are always accurate as of the validated_at timestamp on the certificate record.
Search for Certificates Submitted to a Certain CT Log
These queries return certificates submitted to a particular Certificate Transparency Log since a certain time.
Search Product |
Search Query |
No. of Results |
1.0 |
|
|
2.0 |
|
The number of Certificate Transparency logs has grown, and so the new schema no longer contains the names of CT logs in its schema. Instead, the new schema leverages nesting to allow queries that can specify criteria for a single object within an array of them.
Since certificates can be submitted to more than one log, there may be more than one object in the entries array.
Search for Services With an Exact Attribute
These queries return certificates containing exactly the name censys.io (where only subdomains would not qualify as a match).
Search Product |
Search Query |
No. of Results |
1.0 |
|
|
2.0 |
|
In Certs 1.0, exact matches could be sought in fields that had an accompanying field that ended in .raw, but not every field in the schema had an equivalent .raw.
In Certs 2.0, searching for an exact match for a phrase is as simple as using the exact match operator (=).
Search for Certificates With Some Matching Attributes
These queries return certificates with either of the two names below in any of their name fields.
Search Product |
Search Query |
No. of Results |
1.0 |
|
|
2.0 |
|
Notice in the 2.0 query: There’s no OR.
Search 2.0 accepts boolean operators like or, but it also has a set operator {}, which more succinctly denotes what could otherwise be a long (but perfectly valid) or statement.
Search for Certificates That Do Not Have An Attribute
These queries return certificates that contain a certain name, but have not been submitted to a CT log.
Search Product |
Search Query |
No. of Results |
1.0 |
|
|
2.0 |
|
Most of the hits in the Certs 1.0 results are incorrect because the old pipeline did not update tags when new metadata, such as CT information, was discovered.
More Information
The new Data Definitions tab contains every field in the new schema.
Comments
0 comments
Please sign in to leave a comment.