Usage v2
The Censys Search API provides functionality for interacting with Censys resources such as Hosts.
There are three main API endpoints 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.
"""Search hosts data set."""
from censys.search import CensysHosts
h = CensysHosts()
# Single page of search results
query = h.search("services.service_name: HTTP", per_page=5)
print(query())
# Multiple pages of search results
query = h.search("services.service_name: HTTP", per_page=5, pages=2)
for page in query:
for host in page:
print(host)
# View all results (this will do a lookup for each host returned by the search)
query = h.search("services.service_name: HTTP", per_page=5, pages=2)
print(query.view_all())
# Search for virtual hosts
query = h.search("not services.service_name: HTTP", per_page=5, virtual_hosts="ONLY")
print(query())
# Search including specific fields
query = h.search(
"not services.service_name: HTTP",
per_page=5,
fields=["ip", "services.port", "services.service_name"],
)
print(query())
view
Below we show an example using the CensysHosts index.
"""View specific host."""
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)
# {
# "ip": "8.8.8.8",
# "services": [
# {
# "dns": {
# "server_type": "FORWARDING",
# "resolves_correctly": False,
# "r_code": "UNKNOWN_CODE",
# },
# "extended_service_name": "DNS",
# "observed_at": "2021-02-28T23:58:55.705035895Z",
# "perspective_id": "PERSPECTIVE_TELIA",
# "port": 53,
# "service_name": "DNS",
# "source_ip": "74.120.14.37",
# "transport_protocol": "UDP",
# "truncated": False,
# },
# ...,
# ],
# "location": {
# "continent": "North America",
# "country": "United States",
# "country_code": "US",
# "postal_code": "",
# "timezone": "America/Chicago",
# "coordinates": {"latitude": 37.751, "longitude": -97.822},
# "registered_country": "United States",
# "registered_country_code": "US",
# },
# "location_updated_at": "2022-01-20T16:08:47.237933Z",
# "autonomous_system": {
# "asn": 15169,
# "description": "GOOGLE",
# "bgp_prefix": "8.8.8.0/24",
# "name": "GOOGLE",
# "country_code": "US",
# },
# "autonomous_system_updated_at": "2022-01-20T16:08:47.237933Z",
# "dns": {},
# "last_updated_at": "2021-02-28T23:58:55.765Z",
# }
bulk_view
Below we show an example using the CensysHosts index.
"""Bulk IP Lookup Example."""
from censys.search import CensysHosts
h = CensysHosts()
IPS = [
"1.1.1.1",
"1.1.1.2",
"1.1.1.3",
]
hosts = h.bulk_view(IPS)
print(hosts)
# {
# "1.1.1.1": {...},
# "1.1.1.2": {...},
# "1.1.1.3": {...},
# }
aggregate
Below we show an example using the CensysHosts index.
"""Aggregate hosts data set."""
from censys.search import SearchClient
c = SearchClient()
# The aggregate method constructs a report using a query, an aggregation field, and the
# number of buckets to bin.
report = c.v2.hosts.aggregate(
"services.service_name: HTTP",
"services.port",
num_buckets=5,
)
print(report)
# {
# "total": 987342156,
# "total_omitted": 836949090,
# "potential_deviation": 3965103,
# "buckets": [
# {"key": "80", "count": 58727150},
# {"key": "443", "count": 46716751},
# {"key": "7547", "count": 19185117},
# {"key": "22", "count": 13276559},
# {"key": "30005", "count": 12487489},
# ],
# "query": "services.service_name: HTTP",
# "field": "services.port",
# }
# You can also specify whether to include virtual hosts in the report.
report = c.v2.hosts.aggregate(
"services.service_name: HTTP",
"services.port",
num_buckets=5,
virtual_hosts="INCLUDE",
)
print(report)
metadata
Please note this method is only available only for the CensysHosts index.
Below we show an example using the CensysHosts index.
"""Metadata on the hosts index."""
from censys.search import CensysHosts
h = CensysHosts()
# Fetch metadata about hosts.
meta = h.metadata()
print(meta)
# {
# "services": [
# "DNS",
# "FTP",
# "HTTP",
# "POP3",
# "SMTP",
# "SSH",
# ...
# ]
# }
view_host_names
Please note this method is only available only for the CensysHosts index.
Below we show an example using the CensysHosts index.
"""View host names."""
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)
# [
# "one.one.one.one",
# ...
# ]
view_host_events
Please note this method is only available only for the CensysHosts index.
Below we show an example using the CensysHosts index.
"""View host events."""
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", per_page=1, start_time=date(2022, 1, 1), end_time=date(2022, 1, 31)
)
print(events)
# {
# 'ip': '1.1.1.1',
# 'events': [
# {
# 'timestamp': '2022-01-01T00:00:01.713Z',
# 'service_observed': {
# 'id': {'port': 80, 'service_name': 'HTTP', 'transport_protocol': 'TCP'},
# 'observed_at': '2021-12-31T23:59:39.910804158Z',
# 'perspective_id': 'PERSPECTIVE_NTT',
# 'changed_fields': [{'field_name': 'http.request.uri'}, {'field_name': 'http.response.headers.Cf-Ray.headers'}, {'field_name': 'http.response.headers.Location.headers'}, {'field_name': 'banner'}, {'field_name': 'banner_hashes'}]
# },
# '_event': 'service_observed'
# }
# ],
# 'links': {
# 'next': 'AS-RtkcKDRPshfT6ojz5ubSuyen_J_J2s9VLmJf9WCg7_jGt0KdU2JvoYW9QXof1Cskvm-b41QyRiR38kWADJuUA_w8rAA5ZNv9llYarhmPv22nIf88JFGGhH0h6dRZ7kDy5RfsiUxNFXeMQQXz0BWYrcQ=='
# }
# }
view_host_diff
Please note this method is only available only for the CensysHosts index.
Below we show an example using the CensysHosts index.
"""View Host Diff."""
from datetime import date
from censys.search import CensysHosts
h = CensysHosts()
# Compare a single host between two timestamps
diff = h.view_host_diff("1.1.1.1", at_time=date(2022, 1, 1), at_time_b=date(2022, 1, 2))
print(diff)
# Compare a single host between its current timestamp and a timestamp
diff = h.view_host_diff("1.1.1.2", at_time=date(2022, 1, 2))
print(diff)
# Compare two hosts
diff = h.view_host_diff("1.1.1.1", ip_b="1.1.1.2")
print(diff)
# Compare two hosts between two timestamps
diff = h.view_host_diff(
ip="1.1.1.1",
ip_b="1.1.1.2",
at_time=date(2022, 1, 1),
at_time_b=date(2022, 1, 2),
)
print(diff)
get_hosts_by_cert
Please note this method is only available only for the CensysCerts index
Below we show an example using the CensysCerts index.
from censys.search import CensysCerts
c = CensysCerts()
# Fetch a list of events for the specified IP address.
hosts, links = c.get_hosts_by_cert(
"fb444eb8e68437bae06232b9f5091bccff62a768ca09e92eb5c9c2cf9d17c426"
)
print(hosts)
Comments
get_commentsBelow we show an example using the
CensysCertsindex.add_commentBelow we show an example using the
CensysHostsindex.update_commentBelow we show an example using the
CensysHostsindex.delete_commentBelow we show an example using the
CensysCertsindex.