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