censys.search.v2 package

Interact with the Censys Search v2 APIs.

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

Bases: censys.search.v2.api.CensysSearchAPIv2

Interacts with the Certs index.

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: Optional[int])[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.

Returns

The result set returned.

Return type

dict

get_hosts_by_cert(sha256fp: str, cursor: Optional[str] = None) → Tuple[List[str], dict][source]

Returns a list of hosts which contain services presenting this certificate.

Parameters

sha256fp (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 and a dictionary of the pagination cursors.

Return type

Tuple[List[str], dict]

list_certs_with_tag(tag_id: str) → List[str][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 certificate SHA 256 fingerprints.
Return type: List[str]

metadata()[source]

Get current index metadata.

Returns: The result set returned.
Return type: dict

search(query: str, per_page: Optional[int], cursor: Optional[str], pages: int)[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.

Returns

Query object that can be a callable or an iterable.

Return type

Query

v1: censys.search.v1.api.CensysSearchAPIv1: Search V1 Endpoints on V2

view(document_id: str)[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.

Returns

The result set returned.

Return type

dict

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

Bases: censys.search.v2.api.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.

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]

v1: censys.search.v1.api.CensysSearchAPIv1: Search V1 Endpoints on V2

view_host_events(ip_address: str, start_time: Optional[Union[str, datetime.date, datetime.datetime]] = None, end_time: Optional[Union[str, datetime.date, datetime.datetime]] = None, per_page: Optional[int] = None, cursor: Optional[str] = None, reversed: Optional[bool] = None) → List[dict][source]

Fetches a list of events for the specified IP address.

Parameters

ip_address (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_address: str) → List[str][source]

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

Parameters: ip_address (str) – The IP address of the requested host.
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: Optional[str] = None, api_secret: Optional[str] = None, **kwargs)[source]

Bases: censys.common.base.CensysAPIBase

This class is the base class for the Hosts index.

Examples

>>> c = CensysSearchAPIv2()

DEFAULT_URL: str = 'https://search.censys.io/api/v2': Default Search API base URL.

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

class Query(api: censys.search.v2.api.CensysSearchAPIv2, query: str, per_page: Optional[int] = None, cursor: Optional[str] = None, pages: int = 1)[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() → 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.

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: Optional[int] = None) → 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.

Returns

The result set returned.

Return type

dict

create_tag(name: str, color: Optional[str] = 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_tag(tag_id: str)[source]

Delete a tag.

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

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]

metadata() → dict[source]

Get current index metadata.

Returns: The result set returned.
Return type: dict

quota() → dict[source]

Returns metadata of a given search query.

Returns: The metadata of the result set returned.
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: Optional[int] = None, cursor: Optional[str] = None, pages: int = 1) → censys.search.v2.api.CensysSearchAPIv2.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.

Returns

Query object that can be a callable or an iterable.

Return type

Query

update_tag(tag_id: str, name: str, color: Optional[str] = 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

v1: censys.search.v1.api.CensysSearchAPIv1: Search V1 Endpoints on V2

view(document_id: str, at_time: Optional[Union[str, datetime.date, datetime.datetime]] = None) → 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.

Returns

The result set returned.

Return type

dict