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)
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"))