censys.search package

An easy-to-use and lightweight API wrapper for Censys Search API (search.censys.io).

class censys.search.CensysCertificates(**kwargs)[source]

Bases: CensysSearchAPIv1

Interacts with the Certificates index.

See CensysSearchAPIv1 for additional arguments.

Parameters

  • *args – Variable length argument list.

  • **kwargs – Arbitrary keyword arguments.

DEFAULT_TIMEOUT: int = 90

Timeout for the certificates index

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(fingerprints: List[str]) → dict[source]

Requests bulk certificates.

Parameters

fingerprints (List[str]) – List of certificate SHA256 fingerprints.

Returns

Search results from an API query.

Return type

dict

bulk_path = '/bulk/certificates'
class censys.search.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",
    },
)
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.

Parameters

  • 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

A list of hosts and a dictionary of the pagination cursors.

Return type

Tuple[List[str], dict]

list_certs_with_tag(tag_id: str) → List[str][source]

Returns a list of certs which are tagged with the specified tag.

Parameters

tag_id (str) – The ID of the tag.

Returns

A list of certificate SHA 256 fingerprints.

Return type

List[str]

class censys.search.CensysData(api_id: Optional[str] = None, api_secret: Optional[str] = None, **kwargs)[source]

Bases: CensysSearchAPIv1

Interacts with the Data index.

For more details, see our documentation: https://search.censys.io/api

get_series() → dict[source]

Get data on the types of scans we regularly perform (series).

Returns

The result set returned.

Return type

dict

view_result(series_id: str, result_id: str) → dict[source]

View a specific result of a specific series.

Parameters

  • series_id (str) – The ID of the series.

  • result_id (str) – The ID of the result.

Returns

The result set returned.

Return type

dict

view_series(series_id: str) → dict[source]

Get data on a specific series.

Parameters

series_id (str) – The ID of the series.

Returns

The result set returned.

Return type

dict

class censys.search.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'}]
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

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

dict

list_hosts_with_tag(tag_id: str) → List[str][source]

Returns a list of hosts which are tagged with the specified tag.

Parameters

tag_id (str) – The ID of the tag.

Returns

A list of host IP addresses.

Return type

List[str]

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

Query

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

dict

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]

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.

Parameters

  • 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

A list of host names.

Return type

List[str]

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()
>>> hosts = c.v2.hosts # CensysHosts()
>>> certs = c.v2.certs # CensysCerts()