1. Censys
  2. Integrations
  3. Censys Data Integrations

Other Articles In This Section

In this article:

Censys Search Python Library

  • Updated

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:

  1. search - Allows searches against the IPv4 addresses, Websites, and Certificates indexes using the same search syntax as the web app.

  2. view - Returns structured data about an IPv4 address, Website, or Certificate, given the resource’s natural ID.

  3. report - Creates a breakdown of resources based on an attribute, similar to the Report Builder page on the web app.

  4. 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.

  5. account - Returns information about your Censys account, including current query quota usage. This function is available for all index types.

  6. 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.

import censys.ipv4

c = censys.ipv4.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",
]

  1. You can optionally list the (resource-specific) fields to be returned in any matching results. Default fields are location and protocol.

view

The example below requests a single certificate from the CensysCertificates index.

import censys.certificates

c = censys.certificates.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.

import censys.websites

c = censys.websites.CensysWebsites()

websites = c.report(
    """ "welcome to" AND tags.raw: "http" """,
    field="80.http.get.headers.server.raw",
    buckets=5,
)
print(websites)

data

The example below requests the scan data series from Jan. 25, 2021 from the `CensysData` index.
import censys.data

c = censys.data.CensysData()

result = c.view_result("ipv4_2018", "20210125")
print(result)

account

The example below requests account data and quota usage using the CensysIPv4 index.

import censys.ipv4

c = censys.ipv4.CensysIPv4()

account = c.account() # (1)
print(account)

quota = c.quota() # (2)
print(quota)

  1. Gets account data

  2. Gets account quota

bulk

This method is available only for the certificate index.

The example below requests multiple certificates from the CensysCertificates index.

import censys.certificates

c = censys.certificates.CensysCertificates()

fingerprints = [
    "fce621c0dc1c666d03d660472f636ce91e66e96460545f0da7eb1a24873e2f70",
    "a762bf68f167f6fbdf2ab00fdefeb8b96f91335ad6b483b482dfd42c179be076"
]

certs = c.bulk(fingerprints)
print(certs)

Related articles

Comments

0 comments

Please sign in to leave a comment.