Search 2.0 Python Library
Introduction
Censys offers a Python library to call the Censys Search 2.0 API directly from code in order 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 guide will show you how to use the library to interact with three popular endpoints:
-
search- Allows searches through Censys hosts and certificates using the same query syntax as the web app. -
view- Returns structured data about a host, virtual host, or certificate, given the resource’s ID. -
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 will 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)
Comments
0 comments
Article is closed for comments.