censys.search.v2 package

Interact with the Censys Search v2 APIs.

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'
    },
    ...
]

View specific host.

>>> 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
}
INDEX_NAME: str = 'hosts'

Name of Censys Index.

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.

See CensysAPIBase for additional arguments.

Args:

*args: Variable length argument list. **kwargs: Arbitrary keyword arguments.

Raises:

CensysException: Base Exception Class for the Censys API.

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

Args:

api (CensysSearchAPIv2): Parent API object. 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.

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:

Dict[str, dict]: Dictionary mapping documents to that document’s result set.

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

Args:

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:

dict: The result set returned.

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

Args:

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: Query object that can be a callable or an iterable.

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

Args:

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:

dict: The result set returned.