1. Censys
  2. Censys Search
  3. Censys Search Integrations

Other Articles In This Section

In this article

Censys Search Python Library

Censys offers a Python library to call the Censys Search API directly from code to access up-to-the-nanosecond data for hosts, virtual hosts, and X.509 certificates.

Every Search API endpoint is supported by the Python library. This article shows you how to use the library to interact with 3 popular endpoints:

  1. search: Allows searches through Censys hosts and certificates using the same query syntax as the web app.

  2. view: Returns structured data about a host, virtual host, or certificate, given the resource’s ID.

  3. names: Returns the names of hosts.

Getting Set Up

To install the library with PyPi, type the following command in your terminal:

pip install censys

To configure your credentials, which are available on the Account page, type the following command in your terminal:

censys config

Paste in the values for your API ID and Secret.

Examples

These examples are written in Python. They do not work in your terminal.

Search Hosts

The example below searches for hosts running an HTTP service on any port.

from censys.search import CensysHosts

h = CensysHosts()

# Single page of search results
query = h.search("service.service_name: HTTP", per_page=5)
print(query())

# Multiple pages of search results
# You can optionally pass in a number of results to be returned
# each page and the number of pages you want returned.
for page in h.search("service.service_name: HTTP", per_page=5, pages=2):
    print(page)

# You can also get all pages of results by using -1 for pages
for page in h.search("service.service_name: HTTP", pages=-1):
    print(page)

# View each result returned
# For `hosts` this looks like a mapping of IPs to view results
query = h.search("service.service_name: HTTP", per_page=5, pages=2)
print(query.view_all())

View

The example below requests the Censys view of a single host (Google Public DNS) on March 1, 2021.

from censys.search import CensysHosts

h = CensysHosts()

# Fetch a specific host and its services
host = h.view("8.8.8.8")
print(host)

# Please note that historical API access is required to use the at_time option.
host = h.view("8.8.8.8", at_time="2021-03-01T17:49:05Z")
print(host)

# You can also pass in a date or datetime object.
from datetime import date
host = h.view("8.8.8.8", at_time=date(2021, 3, 1))
print(host)

List Host Names

Retrieve all of the names a host responded to during a Censys name-based scan.

from censys.search import CensysHosts

h = CensysHosts()

# Fetch a list of host names for the specified IP address.
names = h.view_host_names("1.1.1.1")
print(names)

Search Certificates

The certificates repository still reflects Censys legacy Search language and features like field specification for search results.

from censys.search import CensysCertificates

c = CensysCertificates()

for page in c.search(
"validation.nss.valid: true and validation.nss.type: intermediate",
max_records=10
):
print(page)

# You can optionally restrict the (resource-specific) fields to be
# returned in the matching results.
fields = [
"fingerprint_sha256",
"parsed.validity.start",
"parsed.validity.end",
"parsed.subject_dn",
"parsed.names",
"parsed.subject.common_name",
]

for page in c.search(
"censys.io and tags: trusted",
fields,
max_records=10,
):
print(page)

More References

You can find the full docs for the Censys Python Library here. Full API documentation is available here.

Related articles