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).
search
¶
Below we show an example using the CensysHosts
index.
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)
# 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
¶
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)