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

Note

Please note that the Censys Search v2 API does not support searching, viewing, or aggregating the Certificates index. Please use the CensysCertificates (v1) index for this functionality.

view

Please note this method is only available only for the CensysHosts index.

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

Please note this method is only available only for the CensysHosts index.

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

Please note this method is only available only for the CensysHosts index.

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(
    "service.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": "service.service_name: HTTP",
#     "field": "services.port",
# }

# You can also specify whether to include virtual hosts in the report.
report = c.v2.hosts.aggregate(
    "service.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", start_time=date(2022, 1, 1), end_time=date(2022, 1, 31)
)
print(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"},
#             ],
#         },
#         "_event": "service_observed",
#     },
#     ...
# ]

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_comments

Below we show an example using the CensysCerts index.

from censys.search import CensysCerts

c = CensysCerts()

# Fetch a list of comments for the specified certificate.
comments = c.get_comments(
    "fb444eb8e68437bae06232b9f5091bccff62a768ca09e92eb5c9c2cf9d17c426"
)
print(comments)

add_comment

Below we show an example using the CensysHosts index.

from censys.search import CensysHosts

h = CensysHosts()

# Add a comment to a host.
comment = h.add_comment("1.1.1.1", "This is a test comment")
print(comment)

update_comment

Below we show an example using the CensysHosts index.

from censys.search import CensysHosts

h = CensysHosts()

# Update a comment to a host.
comment = h.update_comment("1.1.1.1", 101, "This is an updated test comment")

delete_comment

Below we show an example using the CensysCerts index.

from censys.search import CensysCerts

c = CensysCerts()

# Delete a comment for a certificate.
c.delete_comment(
    "fb444eb8e68437bae06232b9f5091bccff62a768ca09e92eb5c9c2cf9d17c426", 102
)

Tags

list_all_tags

Below we show an example using the CensysHosts index.

from censys.search import CensysHosts

h = CensysHosts()

# Fetch a list of all tags.
tags = h.list_all_tags()
print(tags)

create_tag

Below we show an example using the CensysCerts index.

from censys.search import CensysCerts

c = CensysCerts()

# Create a new tag.
tag = c.create_tag("test-tag")
print(tag)

# Optionally you can specify a color for the tag.
tag = c.create_tag("test-tag", color="#00FF00")
print(tag)

get_tag

Below we show an example using the CensysHosts index.

from censys.search import CensysHosts

h = CensysHosts()

# Fetch a tag.
tag = h.get_tag("123")
print(tag)

update_tag

Below we show an example using the CensysCerts index.

from censys.search import CensysCerts

c = CensysCerts()

# Update a tag.
tag = c.update_tag("123", "test-tag")
print(tag)

# Optionally you can specify a color for the tag.
tag = c.update_tag("123", "test-tag", color="#00FF00")
print(tag)

delete_tag

Below we show an example using the CensysHosts index.

from censys.search import CensysHosts

h = CensysHosts()

# Delete a tag.
h.delete_tag("123")

list_tags_on_document

Below we show an example using the CensysCerts index.

from censys.search import CensysCerts

c = CensysCerts()

# Fetch a list of tags for a document.
tags = c.list_tags_on_document(
    "fb444eb8e68437bae06232b9f5091bccff62a768ca09e92eb5c9c2cf9d17c426"
)
print(tags)

add_tag_to_document

Below we show an example using the CensysHosts index.

from censys.search import CensysHosts

h = CensysHosts()

# Add a tag to a document.
h.add_tag_to_document("123")

remove_tag_from_document

Below we show an example using the CensysCerts index.

from censys.search import CensysCerts

c = CensysCerts()

# Remove a tag from a document.
c.remove_tag_from_document(
    "fb444eb8e68437bae06232b9f5091bccff62a768ca09e92eb5c9c2cf9d17c426"
)

list_certs_with_tag

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 certs with the specified tag.
certs = c.list_certs_with_tag("123")
print(certs)

list_hosts_with_tag

Please note this method is only available only for the CensysHosts index.

Below we show an example using the CensysHosts index.

from censys.search import CensysHosts

h = CensysHosts()

# Fetch a list of hosts with the specified tag.
hosts = h.list_hosts_with_tag("123")
print(hosts)