censys.search.v2 package

Interact with the Censys Search v2 APIs.

class censys.search.v2.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. The v1 API endpoints (search, view, and report) are avilable only from CensysCertificates.

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]

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: 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: List[str] | None = None) 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.

Returns:

Search results.

Return type:

dict

search_post(query: str, per_page: int = 50, cursor: str | None = None, fields: List[str] | None = None, sort: 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: 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.v2.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("service.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("service.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': 'service.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(query: str, per_page: int = 100, cursor: str | None = None, pages: int = 1, virtual_hosts: str | None = None, **kwargs: Any) Query[source]

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.

  • virtual_hosts (str) – Optional; Whether to include virtual hosts in the results. Valid values are “EXCLUDE”, “INCLUDE”, and “ONLY”.

  • pages (int) – Optional; The number of pages returned. Defaults to 1.

  • **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_diff(ip: str, ip_b: str | None = None, at_time: str | date | datetime | None = None, at_time_b: str | date | datetime | None = None)[source]

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

view_host_events(ip: str, start_time: str | date | datetime | None = None, end_time: str | date | datetime | None = None, per_page: int | None = None, cursor: str | None = None, reversed: bool | None = None) List[dict][source]

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:

List[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]

censys.search.v2.api module

Base for interacting with the Censys Search API.

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

Bases: CensysAPIBase

This class is the base class for the Hosts index.

Examples

>>> c = CensysSearchAPIv2()
DEFAULT_URL: str = 'https://search.censys.io/api'

Default Search API base URL.

INDEX_NAME: str = ''

Name of Censys Index.

class Query(api: CensysSearchAPIv2, query: str, per_page: int | None = None, cursor: str | None = None, pages: int = 1, **kwargs: Any)[source]

Bases: Iterable

Query class that is callable and iterable.

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

view_all(max_workers: int = 20) Dict[str, dict][source]

View each document returned from query.

Please note that each result returned by the query will be looked up using the view method.

Parameters:

max_workers (int) – The number of workers to use. Defaults to 20.

Returns:

Dictionary mapping documents to that document’s result set.

Return type:

Dict[str, dict]

account() dict[source]

Gets the current account’s query quota.

Returns:

Quota response.

Return type:

dict

add_comment(document_id: str, contents: str) dict[source]

Add comment to a document.

Parameters:
  • document_id (str) – The ID of the document you are requesting.

  • contents (str) – The contents of the comment.

Returns:

The result set returned.

Return type:

dict

add_tag_to_document(document_id: str, tag_id: str)[source]

Add a tag to a document.

Parameters:
  • document_id (str) – The ID of the document.

  • tag_id (str) – The ID of the tag.

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

Aggregate current 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.

  • **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, **kwargs: Any) Dict[str, dict][source]

Bulk view documents from current index.

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

Parameters:
  • document_ids (List[str]) – The IDs of the documents you are requesting.

  • max_workers (int) – The number of workers to use. Defaults to 20.

  • **kwargs (Any) – Optional; Additional arguments to be passed to the query.

Returns:

Dictionary mapping document IDs to that document’s result set.

Return type:

Dict[str, dict]

create_tag(name: str, color: str | None = None) dict[source]

Create a tag.

Parameters:
  • name (str) – The name of the tag.

  • color (str) – Optional; The color of the tag.

Returns:

The result set returned.

Return type:

dict

delete_comment(document_id: str, comment_id: str) dict[source]

Delete comment from a document.

Parameters:
  • document_id (str) – The ID of the document you are requesting.

  • comment_id (str) – The ID of the comment you are requesting.

Returns:

The result set returned.

Return type:

dict

delete_tag(tag_id: str)[source]

Delete a tag.

Parameters:

tag_id (str) – The ID of the tag.

get_comment(document_id: str, comment_id: str) dict[source]

Get comment for a document.

Parameters:
  • document_id (str) – The ID of the document you are requesting.

  • comment_id (str) – The ID of the comment you are requesting.

Returns:

The result set returned.

Return type:

dict

get_comments(document_id: str) List[dict][source]

Get comments for a document.

Parameters:

document_id (str) – The ID of the document you are requesting.

Returns:

The list of comments.

Return type:

List[dict]

get_tag(tag_id: str) dict[source]

Get a tag.

Parameters:

tag_id (str) – The ID of the tag.

Returns:

The result set returned.

Return type:

dict

list_all_tags() List[dict][source]

List all tags.

Returns:

The list of tags.

Return type:

List[dict]

list_tags_on_document(document_id: str) List[dict][source]

List tags on a document.

Parameters:

document_id (str) – The ID of the document.

Returns:

The list of tags.

Return type:

List[dict]

quota() dict[source]

Returns metadata of a given search query.

Returns:

The metadata of the result set returned.

Return type:

dict

Search current index.

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

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.

  • **kwargs (Any) – Optional; Additional arguments to be passed to the query.

Returns:

The raw result set.

Return type:

dict

remove_tag_from_document(document_id: str, tag_id: str)[source]

Remove a tag from a document.

Parameters:
  • document_id (str) – The ID of the document.

  • tag_id (str) – The ID of the tag.

search(query: str, per_page: int = 100, cursor: str | None = None, pages: int = 1, **kwargs: Any) Query[source]

Search current 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.

  • **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

update_comment(document_id: str, comment_id: str, contents: str) dict[source]

Update comment from a document.

Parameters:
  • document_id (str) – The ID of the document you are requesting.

  • comment_id (str) – The ID of the comment you are requesting.

  • contents (str) – The contents of the comment.

Returns:

The result set returned.

Return type:

dict

update_tag(tag_id: str, name: str, color: str | None = None) dict[source]

Update a tag.

Parameters:
  • tag_id (str) – The ID of the tag.

  • name (str) – The name of the tag.

  • color (str) – The color of the tag.

Returns:

The result set returned.

Return type:

dict

view(document_id: str, **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.

  • **kwargs (Any) – Optional; Additional arguments to be passed to the query.

Returns:

The result set returned.

Return type:

dict