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.
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.
- 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.
- Args:
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:
Tuple[List[str], dict]: A list of hosts and a dictionary of the pagination cursors.
- 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.
- 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
- 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. 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:
dict: The result set returned.
- list_hosts_with_tag(tag_id: str) List[str] [source]
Returns a list of hosts which are tagged with the specified tag.
- Args:
tag_id (str): The ID of the tag.
- Returns:
List[str]: A list of host IP addresses.
- search(query: str, per_page: Optional[int] = None, cursor: Optional[str] = None, pages: int = 1, virtual_hosts: Optional[str] = None, **kwargs: Any) censys.search.v2.api.CensysSearchAPIv2.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
- 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. 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: Query object that can be a callable or an iterable.
- view_host_diff(ip: str, ip_b: Optional[str] = None, at_time: Optional[Union[str, datetime.date, datetime.datetime]] = None, at_time_b: Optional[Union[str, datetime.date, datetime.datetime]] = None)[source]
Fetches a diff of the specified IP address.
- Args:
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:
dict: A diff of the hosts.
- view_host_events(ip: 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.
- Args:
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:
List[dict]: A list of events.
- view_host_names(ip: str, per_page: Optional[int] = None, cursor: Optional[str] = None) List[str] [source]
Fetches a list of host names for the specified IP address.
- Args:
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:
List[str]: A list of host names.
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'
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, **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.
- Args:
max_workers (int): The number of workers to use. Defaults to 20.
- Returns:
Dict[str, dict]: Dictionary mapping documents to that document’s result set.
- add_comment(document_id: str, contents: str) dict [source]
Add comment to a document.
- Args:
document_id (str): The ID of the document you are requesting. contents (str): The contents of the comment.
- Returns:
dict: The result set returned.
- add_tag_to_document(document_id: str, tag_id: str)[source]
Add a tag to a document.
- Args:
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, **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
- 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. **kwargs (Any): Optional; Additional arguments to be passed to the query.
- Returns:
dict: The result set returned.
- bulk_view(document_ids: List[str], at_time: Optional[Union[str, datetime.date, datetime.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
- Args:
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:
Dict[str, dict]: Dictionary mapping document IDs to that document’s result set.
- create_tag(name: str, color: Optional[str] = None) dict [source]
Create a tag.
- Args:
name (str): The name of the tag. color (str): Optional; The color of the tag.
- Returns:
dict: The result set returned.
- delete_comment(document_id: str, comment_id: str) dict [source]
Delete comment from a document.
- Args:
document_id (str): The ID of the document you are requesting. comment_id (str): The ID of the comment you are requesting.
- Returns:
dict: The result set returned.
- get_comments(document_id: str) List[dict] [source]
Get comments for a document.
- Args:
document_id (str): The ID of the document you are requesting.
- Returns:
List[dict]: The list of comments.
- get_tag(tag_id: str) dict [source]
Get a tag.
- Args:
tag_id (str): The ID of the tag.
- Returns:
dict: The result set returned.
- list_tags_on_document(document_id: str) List[dict] [source]
List tags on a document.
- Args:
document_id (str): The ID of the document.
- Returns:
List[dict]: The list of tags.
- quota() dict [source]
Returns metadata of a given search query.
- Returns:
dict: The metadata of the result set returned.
- 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.
- 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. **kwargs (Any): Optional; Additional arguments to be passed to the query.
- Returns:
dict: The raw result set.
- remove_tag_from_document(document_id: str, tag_id: str)[source]
Remove a tag from a document.
- Args:
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, **kwargs: Any) 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. **kwargs (Any): Optional; Additional arguments to be passed to the query.
- Returns:
Query: Query object that can be a callable or an iterable.
- update_comment(document_id: str, comment_id: str, contents: str) dict [source]
Update comment from a document.
- Args:
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:
dict: The result set returned.
- update_tag(tag_id: str, name: str, color: Optional[str] = None) dict [source]
Update a tag.
- Args:
tag_id (str): The ID of the tag. name (str): The name of the tag. color (str): The color of the tag.
- Returns:
dict: The result set returned.
- 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.