Censys Search Python Library
Introduction
Censys offers a Python library to call the Censys Search API directly from code in order to access Internet scan data for IPv4 addresses, websites, and X.509 certificates, in addition to providing account information such as query quota.
There are six API options that this library provides access to:
-
search- Allows searches against the IPv4 addresses, Websites, and Certificates indexes using the same search syntax as the web app. -
view- Returns structured data about an IPv4 address, Website, or Certificate, given the resource’s natural ID. -
report- Creates a breakdown of resources based on an attribute, similar to the Report Builder page on the web app. -
data- Returns collections of scan series whose metadata includes a description of the data collected in the series and links to the individual scan results. -
account- Returns information about your Censys account, including current query quota usage. This function is available for all index types. -
bulk- Returns structured data for certificates in bulk, given a list of SHA-256 fingerprints.
More details about each option can be found in the Censys API documentation. A list of index fields can be found on the Censys API definitions page.
Python class objects must be initialized for each resource index:
-
IP addresses:
CensysIPv4 -
Websites:
CensysWebsites -
Certificates:
CensysCertificates
Examples
An example for each endpoint is provided below.
search
The example below searches the CensysIPv4 index for Apache services in Japan.
from censys.search import CensysIPv4
c = CensysIPv4()
for page in c.search(
"443.https.get.headers.server: Apache AND location.country: Japan",
max_records=10
):
print(page)
fields = [ # (1)
"ip",
"updated_at",
"443.https.get.title",
"443.https.get.headers.server",
"443.https.get.headers.x_powered_by",
"443.https.get.metadata.description",
"443.https.tls.certificate.parsed.subject_dn",
"443.https.tls.certificate.parsed.names",
"443.https.tls.certificate.parsed.subject.common_name",
]
-
You can optionally list the (resource-specific) fields to be returned in any matching results. Default fields are
locationandprotocol.
view
The example below requests a single certificate from the CensysCertificates index.
from censys.search import CensysCertificates
c = CensysCertificates()
cert = c.view("a762bf68f167f6fbdf2ab00fdefeb8b96f91335ad6b483b482dfd42c179be076")
print(cert)
report
The report method constructs a report using a query, an aggregation field, and the number of buckets to bin.
The example below requests a breakdown of HTTP websites using the phrase "welcome to" into five buckets by their reported server using the CensysWebsites index.
from censys.search import CensysWebsites
c = CensysWebsites()
websites = c.report(
""" "welcome to" AND tags.raw: "http" """,
field="80.http.get.headers.server.raw",
buckets=5,
)
print(websites)
data
from censys.search import CensysData
c = CensysData()
result = c.view_result("ipv4_2018", "20210125")
print(result)
account
The example below requests account data and quota usage using the CensysIPv4 index.
from censys.search import CensysIPv4 c = CensysIPv4() account = c.account() # (1) print(account) quota = c.quota() # (2) print(quota)
-
Gets account data
-
Gets account quota
bulk
This method is available only for the certificate index.
The example below requests multiple certificates from the CensysCertificates index.
from censys.search import CensysCertificates
c = CensysCertificates()
fingerprints = [
"fce621c0dc1c666d03d660472f636ce91e66e96460545f0da7eb1a24873e2f70",
"a762bf68f167f6fbdf2ab00fdefeb8b96f91335ad6b483b482dfd42c179be076"
]
certs = c.bulk(fingerprints)
print(certs)
Comments
0 comments
Please sign in to leave a comment.