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:
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", }, )
- class censys.search.v2.CensysHosts(api_id: Optional[str] = None, api_secret: Optional[str] = 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'}]
- aggregate(query: str, field: str, num_buckets: Optional[int] = None, virtual_hosts: Optional[str] = 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
- list_hosts_with_tag(tag_id: str) List[str] [source]
Returns a list of hosts which are tagged with the specified tag.
- search(query: str, per_page: Optional[int] = None, cursor: Optional[str] = None, pages: int = 1, virtual_hosts: Optional[str] = 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
- view_host_diff(ip: str, ip_b: Optional[str] = None, at_time: Optional[Union[str, date, datetime]] = None, at_time_b: Optional[Union[str, date, datetime]] = 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
- view_host_events(ip: str, start_time: Optional[Union[str, date, datetime]] = None, end_time: Optional[Union[str, date, 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 (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]
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:
CensysAPIBase
This class is the base class for the Hosts index.
Examples
>>> c = CensysSearchAPIv2()
- class Query(api: CensysSearchAPIv2, query: str, per_page: Optional[int] = None, cursor: Optional[str] = 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
- account() dict [source]
Gets the current account’s query quota.
- Returns
Quota response.
- Return type
- aggregate(query: str, field: str, num_buckets: Optional[int] = None, **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
- Returns
The result set returned.
- Return type
- bulk_view(document_ids: List[str], at_time: Optional[Union[str, date, datetime]] = None, max_workers: int = 20) 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.
at_time ([str, datetime.date, datetime.datetime]) – Optional; Fetches a document at a given point in time.
max_workers (int) – The number of workers to use. Defaults to 20.
- Returns
Dictionary mapping document IDs to that document’s result set.
- Return type
- list_all_tags() List[dict] [source]
List all tags.
- 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
- raw_search(query: str, per_page: Optional[int] = None, cursor: Optional[str] = None, **kwargs: Any) dict [source]
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
- Returns
The raw result set.
- Return type
- search(query: str, per_page: Optional[int] = None, cursor: Optional[str] = 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
- update_comment(document_id: str, comment_id: str, contents: str) dict [source]
Update comment from a document.
- view(document_id: str, at_time: Optional[Union[str, date, 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