Usage v2

The Censys Search API provides functionality for interacting with Censys resources such as Hosts.

There are three API options that this library provides access to:

  • search - Allows searches against the Hosts index using the same search syntax as the web app.

  • view - Returns the structured data we have about a specific Host, given the resource’s natural ID.

  • aggregate - Allows you to view resources as a spectrum based on attributes of the resource, similar to the Report Builder page on the web app.

More details about each option can be found in the Censys API documentation. A list of index fields can be found in the Censys API definitions page.

Python class objects must be initialized for each resource index (Hosts).

view

Below we show an example using the CensysHosts index.

from censys.search import CensysHosts

h = CensysHosts()

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

# You can optionally pass in a RFC3339 timestamp to
# fetch a host at the given point in time.
# Please note historical API access is required.
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)

aggregate

Below we show an example using the CensysHosts index.

from censys.search import CensysHosts

h = CensysHosts()

# The aggregate method constructs a report using a query, an aggregation field, and the
# number of buckets to bin.
report = h.aggregate(
    "service.service_name: HTTP",
    "services.port",
    num_buckets=5,
)
print(report)

view_host_names

Below we show an example using the CensysHosts index.

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)

view_host_events

Below we show an example using the CensysHosts index.

from censys.search import CensysHosts

h = CensysHosts()

# Fetch a list of events for the specified IP address.
events = h.view_host_events("1.1.1.1")
print(events)

# You can also pass in a date or datetime objects.
from datetime import date
events = h.view_host_events("1.1.1.1", start_time=date(2021, 7, 1), end_time=date(2021, 7, 31))
print(events)

metadata

Below we show an example using the CensysHosts index.

from censys.search import CensysHosts

h = CensysHosts()

# Fetch metadata about hosts.
meta = h.metadata()
print(meta.get("services"))