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.

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.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

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: 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.

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()