censys.search package¶
An easy-to-use and lightweight API wrapper for Censys Search API (censys.io).
- class censys.search.CensysCertificates(api_id: Optional[str] = None, api_secret: Optional[str] = None, **kwargs)[source]
Bases:
censys.search.v1.api.CensysSearchAPIv1
Interacts with the Certificates index.
See CensysSearchAPIv1 for additional arguments.
- Parameters
*args – Variable length argument list.
**kwargs – Arbitrary keyword arguments.
- DEFAULT_URL: str = 'https://search.censys.io/api/v1'
Default Search API base URL.
- INDEX_NAME: Optional[str] = 'certificates'
Name of Censys Index.
- MAX_PER_BULK_REQUEST = 50
Max number of bulk requests.
- bulk_path = '/bulk/certificates'
- class censys.search.CensysCerts(api_id: Optional[str] = None, api_secret: Optional[str] = None, **kwargs)[source]
Bases:
censys.search.v2.api.CensysSearchAPIv2
Interacts with the Certs index.
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", } ]
- INDEX_NAME: str = 'certificates'
Name of Censys Index.
- aggregate(query: str, field: str, num_buckets: Optional[int])[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
- 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.
- Parameters
- Returns
A list of hosts and a dictionary of the pagination cursors.
- Return type
- search(query: str, per_page: Optional[int], cursor: Optional[str], pages: int)[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
- Returns
Query object that can be a callable or an iterable.
- Return type
- view(document_id: str)[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
- class censys.search.CensysData(api_id: Optional[str] = None, api_secret: Optional[str] = None, **kwargs)[source]
Bases:
censys.search.v1.api.CensysSearchAPIv1
Interacts with the Data index.
For more details, see our documentation: https://censys.io/api/v1/docs/data
- get_series() dict [source]
Get data on the types of scans we regularly perform (series).
- Returns
The result set returned.
- Return type
- class censys.search.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.
- view_host_events(ip_address: 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.
- Parameters
ip_address (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]
- class censys.search.CensysIPv4(api_id: Optional[str] = None, api_secret: Optional[str] = None, **kwargs)[source]
Bases:
censys.search.v1.api.CensysSearchAPIv1
Interacts with the IPv4 index.
- INDEX_NAME: Optional[str] = 'ipv4'
Name of Censys Index.
- class censys.search.CensysWebsites(api_id: Optional[str] = None, api_secret: Optional[str] = None, **kwargs)[source]
Bases:
censys.search.v1.api.CensysSearchAPIv1
Interacts with the Websites index.
- INDEX_NAME: Optional[str] = 'websites'
Name of Censys Index.
- class censys.search.SearchClient(*args, **kwargs)[source]
Bases:
object
Client for interacting with all Search APIs.
All indexes are passed the args and kwargs that are provided.
Examples
Inits SearchClient.
>>> from censys.search import SearchClient >>> c = SearchClient()
Access both v1 and v2 indexes.
>>> certs = c.v1.certificates # CensysCertificates() >>> data = c.v1.data # CensysData() >>> ipv4 = c.v1.ipv4 # CensysIPv4() >>> websites = c.v1.websites # CensysWebsites() >>> hosts = c.v2.hosts # CensysHosts() >>> certs = c.v2.certs # CensysCerts()