Source code for censys.search.v2.certs

"""Interact with the Censys Search Cert API."""
from typing import List, Optional, Tuple

from .api import CensysSearchAPIv2


[docs]class CensysCerts(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 = "certificates" """Name of Censys Index.""" def view(self, document_id: str): # type: ignore # noqa: D102 """This function acts as a placeholder for the upcoming Censys Search Cert v2 API. To view a certificate, please use `CensysCertificates`. Raises: NotImplementedError: CensysCerts.view is not implemented yet. Please use CensysCertificates.view instead. :meta private: """ raise NotImplementedError( "CensysCerts.view is not implemented yet. Please use CensysCertificates.view instead." ) def search( # type: ignore # noqa: D102 self, query: str, per_page: Optional[int], cursor: Optional[str], pages: int ): """This function acts as a placeholder for the upcoming Censys Search Cert v2 API. To search for certificates, please use `CensysCertificates`. Raises: NotImplementedError: CensysCerts.search is not implemented yet. Please use CensysCertificates.search instead. :meta private: """ raise NotImplementedError( "CensysCerts.search is not implemented yet. Please use CensysCertificates.search instead." ) def aggregate(self, query: str, field: str, num_buckets: Optional[int]): # type: ignore # noqa: D102 """This function acts as a placeholder for the upcoming Censys Search Cert v2 API. To aggregate/report certificates, please use `CensysCertificates`. Raises: NotImplementedError: CensysCerts.aggregate is not implemented yet. Please use CensysCertificates.report instead. :meta private: """ raise NotImplementedError( "CensysCerts.aggregate is not implemented yet. Please use CensysCertificates.report instead." ) def metadata(self): # noqa: D102 """This function acts as a placeholder for the upcoming Censys Search Cert v2 API. Raises: NotImplementedError: CensysCerts.metadata is not implemented yet. :meta private: """ raise NotImplementedError("CensysCerts.metadata is not implemented yet.")
[docs] def get_hosts_by_cert( self, sha256fp: str, cursor: Optional[str] = None ) -> Tuple[List[str], dict]: """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. """ args = {"cursor": cursor} result = self._get(self.view_path + sha256fp + "/hosts", args)["result"] return result["hosts"], result["links"]
[docs] def list_certs_with_tag(self, tag_id: str) -> List[str]: """Returns a list of certs which are tagged with the specified tag. Args: tag_id (str): The ID of the tag. Returns: List[str]: A list of certificate SHA 256 fingerprints. """ certs = self._list_documents_with_tag(tag_id, "certificates", "certs") return [cert["fingerprint"] for cert in certs]