API Reference

censys.base module

Base for interacting with the Censys Search API.

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

Bases: object

This class is the base for API queries.

Parameters
  • api_id (str, optional) – The API ID provided by Censys.

  • api_secret (str, optional) – The API secret provided by Censys.

  • url (str, optional) – The URL to make API requests.

  • timeout (int, optional) – Timeout for API requests in seconds.

  • user_agent (str, optional) – Override User-Agent string.

  • proxies (dict, optional) – Configure HTTP proxies.

Raises

CensysAPIException – Base Exception Class for the Censys API.

DEFAULT_TIMEOUT: int = 30

Default API timeout.

DEFAULT_URL: str = 'https://censys.io/api/v1'

Default API base URL.

DEFAULT_USER_AGENT: str = 'censys/1.0.1'

Default API user agent.

EXCEPTIONS: Dict[int, Type[censys.exceptions.CensysAPIException]] = {401: <class 'censys.exceptions.CensysUnauthorizedException'>, 403: <class 'censys.exceptions.CensysUnauthorizedException'>, 404: <class 'censys.exceptions.CensysNotFoundException'>, 429: <class 'censys.exceptions.CensysRateLimitExceededException'>}

Map of status code to Exception.

account()dict[source]

Gets the current account information. Including email and quota.

Returns

Account response.

Return type

dict

quota()dict[source]

Gets the current account’s query quota.

Returns

Quota response.

Return type

dict

class censys.base.CensysIndex(*args, **kwargs)[source]

Bases: censys.base.CensysAPIBase

This class is the base class for the Data, Certificate, IPv4, and Website index.

INDEX_NAME: Optional[str] = None

Name of Censys Index.

metadata(query: str)dict[source]

Returns metadata of a given search query.

Parameters

query (str) – The query to be executed.

Returns

The metadata of the result set returned.

Return type

dict

Searches the given index for all records that match the given query.

Parameters
  • query (str) – The query to be executed.

  • fields (Fields, optional) – Fields to be returned in the result set.

  • page (int, optional) – The page of the result set. Defaults to 1.

  • flatten (bool, optional) – Flattens fields to dot notation. Defaults to True.

Returns

The result set returned.

Return type

dict

report(query: str, field: str, buckets: int = 50)dict[source]

Creates a report on the breakdown of the values of a field in a result set. For more details, see our documentation: https://censys.io/api/v1/docs/report

Parameters
  • query (str) – The query to be executed.

  • field (str) – The field you are running a breakdown on.

  • buckets (int, optional) – The maximum number of values. Defaults to 50.

Returns

The result set returned.

Return type

dict

search(query: str, fields: Optional[List[str]] = None, page: int = 1, max_records: Optional[int] = None, flatten: bool = True)Generator[dict, None, None][source]

Searches the given index for all records that match the given query. For more details, see our documentation: https://censys.io/api/v1/docs/search

Parameters
  • query (str) – The query to be executed.

  • fields (Fields, optional) – Fields to be returned in the result set.

  • page (int, optional) – The page of the result set. Defaults to 1.

  • max_records (Optional[int], optional) – The maximum number of records.

  • flatten (bool, optional) – Flattens fields to dot notation. Defaults to True.

Yields

dict – The result set returned.

view(document_id: str)dict[source]

View the current structured data we have on a specific document. For more details, see our documentation: https://censys.io/api/v1/docs/view

Parameters

document_id (str) – The ID of the document you are requesting.

Returns

The result set returned.

Return type

dict

censys.certificates module

Interact with the Censys Search Certificate API.

class censys.certificates.CensysCertificates(*args, **kwargs)[source]

Bases: censys.base.CensysIndex

Interacts with the Certificates index.

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 data in bulk.

Parameters

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

Returns

Search results from an API query.

Return type

dict

censys.cli module

Interact with the Censys Search API through the command line.

class censys.cli.CensysAPISearch(**kwargs)[source]

Bases: object

This class searches the Censys API, taking in options from the command line and returning the results to a CSV or JSON file, or to stdout.

Parameters
  • api_id (str, optional) – The API ID provided by Censys.

  • api_secret (str, optional) – The API secret provided by Censys.

  • start_page (int, optional) – Page number to start from. Defaults to 1.

  • max_pages (int, optional) – The maximum number of pages. Defaults to 10.

csv_fields: List[str] = []

A list of fields to be used by the CSV writer.

search_certificates(**kwargs)List[dict][source]

A method to search the Certificates data set via the API.

Parameters
  • query (str) – The string search query.

  • fields (list, optional) – The fields that should be returned with a query.

  • overwrite (bool, optional) – Whether to overwrite or append default fields with user fields. Defaults to False.

Returns

A list of results from the query.

Return type

Results

search_ipv4(**kwargs)List[dict][source]

A method to search the IPv4 data set via the API.

Parameters
  • query (str) – The string search query.

  • fields (list, optional) – The fields that should be returned with a query.

  • overwrite (bool, optional) – Whether to overwrite or append default fields with user fields. Defaults to False.

Returns

A list of results from the query.

Return type

Results

search_websites(**kwargs)List[dict][source]

A method to search the Websites (Alexa Top 1M) data set via the API.

Parameters
  • query (str) – The string search query.

  • fields (list, optional) – The fields that should be returned with a query.

  • overwrite (bool, optional) – Whether to overwrite or append default fields with user fields. Defaults to False.

Returns

A list of results from the query.

Return type

Results

write_file(results_list: List[dict], file_format: str = 'screen', file_path: Optional[str] = None)bool[source]

This method just sorts which format will be used to store the results of the query.

Parameters
  • results_list (Results) – A list of results from the API query.

  • file_format (str, optional) – The format of the output.

  • file_path (str optional) – A path to write results to.

Returns

True if wrote out successfully.

Return type

bool

class censys.cli.CensysHNRI(api_id: str, api_secret: str)[source]

Bases: object

This class searches the Censys API, check the user’s current IP for risks.

Parameters
  • api_id (str, optional) – The API ID provided by Censys.

  • api_secret (str, optional) – The API secret provided by Censys.

HIGH_RISK_DEFINITION: List[str] = ['telnet', 'redis', 'postgres', 'vnc']
MEDIUM_RISK_DEFINITION: List[str] = ['ssh', 'http', 'https']
static get_current_ip()str[source]

Uses ipify.org to get the current IP address.

Returns

IP address.

Return type

str

static risks_to_string(high_risk: list, medium_risk: list)str[source]

Risks to printable string.

Parameters
  • high_risk (list) – Lists of high risks.

  • medium_risk (list) – Lists of medium risks.

Raises

CensysCLIException – No information/risks found.

Returns

Printable string for CLI.

Return type

str

translate_risk(protocols: list)Tuple[list, list][source]

Interpret protocols to risks.

Parameters

protocols (list) – List of slash divided ports/protocols.

Returns

Lists of high and medium risks.

Return type

Tuple[list, list]

view_current_ip_risks()str[source]

Gets protocol information for the current IP and returns any risks.

Returns

Printable

Return type

str

censys.cli.cli_config(_)[source]

config subcommand.

Parameters

_ – Argparse Namespace.

censys.cli.get_parser()argparse.ArgumentParser[source]

Gets ArgumentParser for CLI.

Returns

argparse.ArgumentParser

censys.cli.hnri(args)[source]

hnri subcommand.

Parameters

args (Namespace) – Argparse Namespace.

censys.cli.main()[source]

main cli function

censys.cli.search(args)[source]

search subcommand.

Parameters

args (Namespace) – Argparse Namespace.

censys.config module

Interact with the config file.

censys.config.check_config(config)[source]

Checks config against default config for fields.

Parameters

config – Configuration to write.

censys.config.get_config()[source]

Reads and returns config.

censys.config.write_config(config)[source]

Writes config to file.

Parameters

config – Configuration to write.

censys.data module

Interact with the Censys Search Data API.

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

Bases: censys.base.CensysAPIBase

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

censys.exceptions module

Exceptions for Censys.

exception censys.exceptions.CensysAPIException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None)[source]

Bases: censys.exceptions.CensysException

Base Exception for the Censys API.

exception censys.exceptions.CensysCLIException[source]

Bases: censys.exceptions.CensysException

Exception raised when the CLI is passed invalid arguments.

exception censys.exceptions.CensysException[source]

Bases: Exception

Base Exception for Censys.

exception censys.exceptions.CensysJSONDecodeException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None)[source]

Bases: censys.exceptions.CensysAPIException

Exception raised when the resource requested is not valid JSON.

exception censys.exceptions.CensysNotFoundException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None)[source]

Bases: censys.exceptions.CensysAPIException

Exception raised when the resource requested is not found.

exception censys.exceptions.CensysRateLimitExceededException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None)[source]

Bases: censys.exceptions.CensysAPIException

Exception raised when your Censys rate limit has been exceeded.

exception censys.exceptions.CensysUnauthorizedException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None)[source]

Bases: censys.exceptions.CensysAPIException

Exception raised when your Censys account doesn’t have access to the requested resource.

censys.ipv4 module

Interact with the Censys Search IPv4 API.

class censys.ipv4.CensysIPv4(*args, **kwargs)[source]

Bases: censys.base.CensysIndex

Interacts with the IPv4 index.

INDEX_NAME: Optional[str] = 'ipv4'

Name of Censys Index.

censys.websites module

Interact with the Censys Search Website API.

class censys.websites.CensysWebsites(*args, **kwargs)[source]

Bases: censys.base.CensysIndex

Interacts with the IPv4 index.

INDEX_NAME: Optional[str] = 'websites'

Name of Censys Index.