censys.search package

An easy-to-use and lightweight API wrapper for Censys Search API (search.censys.io).

class censys.search.CensysCerts(api_id: str | None = None, api_secret: str | None = None, **kwargs)[source]

Bases: CensysSearchAPIv2

Interacts with the Certs index.

Please note that this class represents only the v2 API endpoints.

Examples

Inits Censys Certs.

>>> from censys.search import CensysCerts
>>> c = CensysCerts()

Search for hosts by sha256fp.

>>> c.get_hosts_by_cert("fb444eb8e68437bae06232b9f5091bccff62a768ca09e92eb5c9c2cf9d17c426")
(
    [
        {
            "ip": "string",
            "name": "string",
            "observed_at": "2021-08-02T14:56:38.711Z",
            "first_observed_at": "2021-08-02T14:56:38.711Z",
        }
    ],
    {
        "next": "nextCursorToken",
    },
)

INDEX_NAME: str = 'certificates': Name of Censys Index.

aggregate(query: str, field: str, num_buckets: int = 50, **kwargs) → dict[source]

Aggregates certificate records matching a specified query into buckets based on the given field.

Parameters:

query (str) – The query string to search for.
field (str) – The field to aggregate on.
num_buckets (int) – The number of buckets to return. Defaults to 50.
**kwargs – Additional keyword arguments to pass to the underlying HTTP request.

Returns:

Aggregation results.

Return type:

dict

bulk(fingerprints: List[str]) → List[dict][source]

Fetches the certificate records for the specified SHA-256 fingerprints.

By default, this function uses the POST method, which allows for a larger number of fingerprints to be queried at once. If you wish to use the GET method, please use CensysCerts.bulk_get instead.

Parameters:: fingerprints (List[str]) – List of certificate SHA256 fingerprints.
Returns:: Certificate details.
Return type:: dict

bulk_get(fingerprints: List[str]) → List[dict][source]

Fetches the certificate records for the specified SHA-256 fingerprints.

Using the GET method allows for a smaller number of fingerprints to be queried at once.

Parameters:: fingerprints (List[str]) – List of certificate SHA256 fingerprints.
Returns:: Certificate details.
Return type:: dict

bulk_post(fingerprints: List[str]) → List[dict][source]

Fetches the certificate records for the specified SHA-256 fingerprints.

Using the POST method allows for a larger number of fingerprints to be queried at once.

Parameters:: fingerprints (List[str]) – List of certificate SHA256 fingerprints.
Returns:: Certificate details.
Return type:: dict

bulk_view(fingerprints: List[str]) → List[dict][source]

Fetches the certificate records for the specified SHA-256 fingerprints.

By default, this function uses the POST method, which allows for a larger number of fingerprints to be queried at once. If you wish to use the GET method, please use CensysCerts.bulk_get instead.

Parameters:: fingerprints (List[str]) – List of certificate SHA256 fingerprints.
Returns:: Certificate details.
Return type:: dict

get_hosts_by_cert(fingerprint: str, cursor: str | None = None) → dict[source]

Returns a list of hosts which contain services presenting this certificate, including when the certificate was first observed.

Parameters:

fingerprint (str) – The SHA-256 fingerprint of the requested certificate.
cursor (str) – Cursor token from the API response, which fetches the next page of hosts when added to the endpoint URL.

Returns:

A list of hosts which contain services presenting this certificate.

Return type:

dict

list_certs_with_tag(tag_id: str) → List[dict][source]

Returns a list of certs which are tagged with the specified tag.

Parameters:: tag_id (str) – The ID of the tag.
Returns:: A list of certs which are tagged with the specified tag.
Return type:: List[dict]

raw_search(query: str, per_page: int = 50, cursor: str | None = None, fields: List[str] | None = None, sort: str | List[str] | None = None, **kwargs) → dict[source]

Searches the Certs index.

Searches the Certs index for all records that match the given query. This method does no automatic pagination or post processing.

Parameters:

query (str) – The query string to search for.
per_page (int) – The number of results to return per page. Defaults to 50.
cursor (str, optional) – Cursor token from the API response, which fetches the next page of results when added to the endpoint URL.
fields (List[str], optional) – Additional fields to return in the matched certificates outside of the default returned fields.
sort (List[str], optional) – A list of fields to sort on. By default, fields will be sorted in ascending order.
**kwargs – Additional keyword arguments to pass to the underlying HTTP request.

Returns:

Search results.

Return type:

dict

search(query: str, per_page: int = 50, cursor: str | None = None, pages: int = 1, fields: List[str] | None = None, sort: str | List[str] | None = None, **kwargs) → Query[source]

Searches the Certs index.

By default, this function uses the POST method, which allows for a larger number of fingerprints to be queried at once. If you wish to use the GET method, please use CensysCerts.search_get instead.

Parameters:

query (str) – The query string to search for.
per_page (int) – The number of results to return per page. Defaults to 50.
cursor (str, optional) – Cursor token from the API response, which fetches the next page of results when added to the endpoint URL.
pages (int) – The number of pages to return. Defaults to 1.
fields (List[str], optional) – Additional fields to return in the matched certificates outside of the default returned fields.
sort (List[str], optional) – A list of fields to sort on. By default, fields will be sorted in ascending order.
**kwargs – Additional keyword arguments to pass to the underlying HTTP request.

Returns:

A query object that can be used to iterate over the search results.

Return type:

Query

search_get(query: str, per_page: int = 50, cursor: str | None = None, fields: List[str] | None = None, sort: str | List[str] | None = None, **kwargs) → dict[source]

Searches the Certs index using the GET method.

Parameters:

query (str) – The query string to search for.
per_page (int) – The number of results to return per page. Defaults to 50.
cursor (str, optional) – Cursor token from the API response, which fetches the next page of results when added to the endpoint URL.
fields (List[str], optional) – Additional fields to return in the matched certificates outside of the default returned fields.
sort (List[str], optional) – A list of fields to sort on. By default, fields will be sorted in ascending order.
**kwargs – Arbitrary keyword arguments.

Returns:

Search results.

Return type:

dict

search_post(query: str, per_page: int = 50, cursor: str | None = None, fields: List[str] | None = None, sort: str | List[str] | None = None, **kwargs) → dict[source]

Searches the Certs index using the POST method.

This method returns the result field of the raw response. If you wish to access the raw response, please use CensysCerts.search_post_raw instead.

Parameters:

query (str) – The query string to search for.
per_page (int) – The number of results to return per page. Defaults to 50.
cursor (str, optional) – Cursor token from the API response, which fetches the next page of results when added to the endpoint URL.
fields (List[str], optional) – Additional fields to return in the matched certificates outside of the default returned fields.
sort (List[str], optional) – A list of fields to sort on. By default, fields will be sorted in ascending order.
**kwargs – Arbitrary keyword arguments.

Returns:

Search results.

Return type:

dict

search_post_raw(query: str, per_page: int = 50, cursor: str | None = None, fields: List[str] | None = None, sort: str | List[str] | None = None, **kwargs) → dict[source]

Searches the Certs index using the POST method. Returns the raw response.

Parameters:

query (str) – The query string to search for.
per_page (int) – The number of results to return per page. Defaults to 50.
cursor (str, optional) – Cursor token from the API response, which fetches the next page of results when added to the endpoint URL.
fields (List[str], optional) – Additional fields to return in the matched certificates outside of the default returned fields.
sort (List[str], optional) – A list of fields to sort on. By default, fields will be sorted in ascending order.
**kwargs – Arbitrary keyword arguments.

Returns:

Search results.

Return type:

dict

view(document_id: str, **kwargs) → dict[source]

Fetches the certificate record for the specified SHA-256 fingerprint.

Parameters:

document_id (str) – The SHA-256 fingerprint of the requested certificate.
**kwargs – Arbitrary keyword arguments.

Returns:

Certificate details.

Return type:

dict

class censys.search.CensysData(api_id: str | None = None, api_secret: str | None = None, **kwargs)[source]

Bases: CensysSearchAPIv1

Interacts with the Data index.

For more details, see our documentation: https://search.censys.io/api

get_series() → dict[source]

Get data on the types of scans we regularly perform (series).

Returns:: The result set returned.
Return type:: dict

view_result(series_id: str, result_id: str) → dict[source]

View a specific result of a specific series.

Parameters:

series_id (str) – The ID of the series.
result_id (str) – The ID of the result.

Returns:

The result set returned.

Return type:

dict

view_series(series_id: str) → dict[source]

Get data on a specific series.

Parameters:: series_id (str) – The ID of the series.
Returns:: The result set returned.
Return type:: dict

class censys.search.CensysHosts(api_id: str | None = None, api_secret: str | None = None, **kwargs)[source]

Bases: CensysSearchAPIv2

Interacts with the Hosts index.

Examples

Inits Censys Hosts.

>>> from censys.search import CensysHosts
>>> h = CensysHosts()

Simple host search.

>>> for page in h.search("services.service_name: HTTP"):
>>>     print(page)
[
    {
    'services':
        [
            {'service_name': 'HTTP', 'port': 80},
            {'service_name': 'HTTP', 'port': 443}
        ],
    'ip': '1.0.0.0'
    },
    ...
]

Fetch a specific host and its services

>>> h.view("1.0.0.0")
{
    'ip': '8.8.8.8',
    'services': [{}],
    ...
}

Simple host aggregate.

>>> h.aggregate("services.service_name: HTTP", "services.port", num_buckets=5)
{
    'total_omitted': 591527370,
    'buckets': [
        {'count': 56104072, 'key': '80'},
        {'count': 43527894, 'key': '443'},
        {'count': 23070429, 'key': '7547'},
        {'count': 12970769, 'key': '30005'},
        {'count': 12825150, 'key': '22'}
    ],
    'potential_deviation': 3985101,
    'field': 'services.port',
    'query': 'services.service_name: HTTP',
    'total': 172588754
}

Fetch a list of host names for the specified IP address.

>>> h.view_host_names("1.1.1.1")
['one.one.one.one']

Fetch a list of events for the specified IP address.

>>> h.view_host_events("1.1.1.1")
[{'timestamp': '2019-01-01T00:00:00.000Z'}]

INDEX_NAME: str = 'hosts': Name of Censys Index.

aggregate(query: str, field: str, num_buckets: int = 50, virtual_hosts: str | None = None, **kwargs: Any) → dict[source]

Aggregate host index.

Creates a report on the breakdown of the values of a field in a result set. For more details, see our documentation: https://search.censys.io/api

Parameters:

query (str) – The query to be executed.
field (str) – The field you are running a breakdown on.
num_buckets (int) – Optional; The maximum number of values. Defaults to 50.
virtual_hosts (str) – Optional; Whether to include virtual hosts in the results. Valid values are “EXCLUDE”, “INCLUDE”, and “ONLY”.
**kwargs (Any) – Optional; Additional arguments to be passed to the query.

Returns:

The result set returned.

Return type:

dict

bulk_view(document_ids: List[str], max_workers: int = 20, at_time: str | date | datetime | None = None, **kwargs: Any) → Dict[str, dict][source]

Bulk view documents from current index.

View the current structured data we have on a list of documents.

Parameters:

document_ids (List[str]) – The IDs of the documents you are requesting.
max_workers (int) – Optional; The number of workers to use. Defaults to 20.
at_time ([str, datetime.date, datetime.datetime]) – Optional; Fetches a document at a given point in time.
**kwargs (Any) – Optional; Additional arguments to be passed to the query.

Returns:

The result set returned.

Return type:

Dict[str, dict]

list_hosts_with_tag(tag_id: str) → List[str][source]

Returns a list of hosts which are tagged with the specified tag.

Parameters:: tag_id (str) – The ID of the tag.
Returns:: A list of host IP addresses.
Return type:: List[str]

metadata() → dict[source]

Get metadata for the host index.

Returns:: The result set returned.
Return type:: dict

Search host index.

Searches the given index for all records that match the given query. For more details, see our documentation: https://search.censys.io/api

Parameters:

query (str) – The query to be executed.
per_page (int) – Optional; The number of results to be returned for each page. Defaults to 100.
cursor (int) – Optional; The cursor of the desired result set.
pages (int) – Optional; The number of pages returned. Defaults to 1.
fields (List[str]) – Optional; The fields to return. Defaults to all fields.
sort (str) – Optional; The method used to sort results. Valid values are “RELEVANCE”, “DESCENDING”, and “ASCENDING”.
virtual_hosts (str) – Optional; Whether to include virtual hosts in the results. Valid values are “EXCLUDE”, “INCLUDE”, and “ONLY”.
**kwargs (Any) – Optional; Additional arguments to be passed to the query.

Returns:

Query object that can be a callable or an iterable.

Return type:

Query

view(document_id: str, at_time: str | date | datetime | None = None, **kwargs: Any) → dict[source]

View document from current index.

View the current structured data we have on a specific document. For more details, see our documentation: https://search.censys.io/api

Parameters:

document_id (str) – The ID of the document you are requesting.
at_time ([str, datetime.date, datetime.datetime]) – Optional; Fetches a document at a given point in time.
**kwargs (Any) – Optional; Additional arguments to be passed to the query.

Returns:

The result set returned.

Return type:

dict

view_host_certificates(ip: str, per_page: int = 100, start_time: str | date | datetime | None = None, cursor: str | None = None) → dict[source]

Returns a list of certificates for the specified host.

Parameters:

ip (str) – The IP address of the requested host.
per_page (int) – Optional; The number of results to be returned for each page. Defaults to 100.
start_time (Datetime) – Optional; An RFC3339 timestamp which represents the beginning chronological point-in-time (inclusive) from which events are returned.
cursor (str) – Optional; Cursor token from the API response.

Returns:

A list of certificates.

Return type:

dict

Fetches a diff of the specified IP address.

Parameters:

ip (str) – The IP address of the requested host.
ip_b (str) – Optional; The IP address of the second host.
at_time (Datetime) – Optional; An RFC3339 timestamp which represents the point-in-time used as the basis for Host A.
at_time_b (Datetime) – Optional; An RFC3339 timestamp which represents the point-in-time used as the basis for Host B.

Returns:

A diff of the hosts.

Return type:

dict

Fetches a list of events for the specified IP address.

Parameters:

ip (str) – The IP address of the requested host.
start_time (Datetime) – Optional; An RFC3339 timestamp which represents the beginning chronological point-in-time (inclusive) from which events are returned.
end_time (Datetime) – Optional; An RFC3339 timestamp which represents the ending chronological point-in-time (exclusive) from which events are returned.
per_page (int) – Optional; The maximum number of hits to return in each response (minimum of 1, maximum of 50).
cursor (str) – Optional; Cursor token from the API response.
reversed (bool) – Optional; Reverse the order of the return events, that is, return events in reversed chronological order.

Returns:

A list of events.

Return type:

dict

view_host_names(ip: str, per_page: int | None = None, cursor: str | None = None) → List[str][source]

Fetches a list of host names for the specified IP address.

Parameters:

ip (str) – The IP address of the requested host.
per_page (int) – Optional; The number of results to be returned for each page. Defaults to 100.
cursor (int) – Optional; The cursor of the desired result set.

Returns:

A list of host names.

Return type:

List[str]

class censys.search.SearchClient(*args, **kwargs)[source]

Bases: object

Client for interacting with all Search APIs.

All indexes are passed the args and kwargs that are provided.

Examples

Inits SearchClient.

>>> from censys.search import SearchClient
>>> c = SearchClient()

Access both v1 and v2 indexes.

>>> data = c.v1.data # CensysData()
>>> hosts = c.v2.hosts # CensysHosts()
>>> certs = c.v2.certs # CensysCerts()