API Reference

Subpackages

• censys.asm package
  • Submodules
  • censys.asm.api module
  • censys.asm.assets module
  • censys.asm.client module
  • censys.asm.events module
  • censys.asm.seeds module
  • Module contents

Submodules

censys.api module

Base for interacting with the Censys Search API.

class censys.api.CensysSearchAPI(api_id: Optional[str] = None, api_secret: Optional[str] = None, url: Optional[str] = 'https://censys.io/api/v1', **kwargs)

Bases: censys.base.CensysAPIBase

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

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

Default Search API base URL.

INDEX_NAME: Optional[str] = None

Name of Censys Index.

account() → dict

Gets the current account information. Including email and quota.

Returns

Account response.

Return type

dict

metadata(query: str) → dict

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

paged_search(query: str, fields: Optional[List[str]] = None, page: int = 1, flatten: bool = True) → 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

quota() → dict

Gets the current account’s query quota.

Returns

Quota response.

Return type

dict

report(query: str, field: str, buckets: int = 50) → dict

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]

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

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

Base for interacting with the Censys API’s.

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

Bases: object

This is the base class for API queries.

Parameters

• 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

CensysException – Base Exception Class for the Censys API.

DEFAULT_MAX_RETRIES: int = 10

Default max number of API retries.

DEFAULT_TIMEOUT: int = 30

Default API timeout.

DEFAULT_USER_AGENT: str = 'censys/1.1.1'

Default API user agent.

censys.certificates module

Interact with the Censys Search Certificate API.

class censys.certificates.CensysCertificates(*args, **kwargs)

Bases: censys.api.CensysSearchAPI

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

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)

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]

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]

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]

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

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)

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

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

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]

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

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

Returns

Printable

Return type

str

censys.cli.cli_asm_config(_)

config asm subcommand.

Parameters

_ – Argparse Namespace.

censys.cli.cli_config(_)

config subcommand.

Parameters

_ – Argparse Namespace.

censys.cli.get_parser() → argparse.ArgumentParser

Gets ArgumentParser for CLI.

Returns

argparse.ArgumentParser

censys.cli.hnri(args)

hnri subcommand.

Parameters

args (Namespace) – Argparse Namespace.

censys.cli.main()

main cli function

censys.cli.search(args)

search subcommand.

Parameters

args (Namespace) – Argparse Namespace.

censys.config module

Interact with the config file.

censys.config.check_config(config)

Checks config against default config for fields.

Parameters

config – Configuration to write.

censys.config.get_config()

Reads and returns config.

censys.config.write_config(config)

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, url: Optional[str] = 'https://censys.io/api/v1', **kwargs)

Bases: censys.api.CensysSearchAPI

Interacts with the Data index. For more details, see our documentation: https://censys.io/api/v1/docs/data

get_series() → dict

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

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

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, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysException

Base Exception for Censys API’s.

exception censys.exceptions.CensysAppDownForMaintenanceException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the ASM API is down for maintenance.

exception censys.exceptions.CensysAsmException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAPIException

Base Exception for the Censys ASM API.

exception censys.exceptions.CensysAssociatedAssetsThresholdWarningException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the associated asset count is within the warning threshold.

exception censys.exceptions.CensysCLIException

Bases: censys.exceptions.CensysException

Exception raised when the CLI is passed invalid arguments.

exception censys.exceptions.CensysCannotCreateTagWithNewColorException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the specified tag cannot be created with a new color.

exception censys.exceptions.CensysCannotRemoveNonExistentSeedsException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when trying to remove non existent seed nodes.

exception censys.exceptions.CensysCannotRemoveNonSeedsException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when trying to remove non seed nodes.

exception censys.exceptions.CensysCertificateNotFoundException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the certificate is not found.

exception censys.exceptions.CensysCommentNotFoundException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the requested comment is not found.

exception censys.exceptions.CensysDomainNotFoundException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the domain is not found.

exception censys.exceptions.CensysException

Bases: Exception

Base Exception for Censys.

class censys.exceptions.CensysExceptionMapper

Bases: object

Map status code to Exception for the ASM and Search API.

ASM_EXCEPTIONS: Dict[int, Type[censys.exceptions.CensysAsmException]] = {10001: <class 'censys.exceptions.CensysInvalidAPIKeyException'>, 10002: <class 'censys.exceptions.CensysInvalidAuthTokenException'>, 10007: <class 'censys.exceptions.CensysInvalidSeedDataException'>, 10008: <class 'censys.exceptions.CensysInvalidRequestException'>, 10011: <class 'censys.exceptions.CensysCannotRemoveNonSeedsException'>, 10012: <class 'censys.exceptions.CensysCannotRemoveNonExistentSeedsException'>, 10013: <class 'censys.exceptions.CensysNeedConfirmationToRemoveParentSeedsException'>, 10014: <class 'censys.exceptions.CensysSeedNotFoundException'>, 10015: <class 'censys.exceptions.CensysNotASeedException'>, 10016: <class 'censys.exceptions.CensysTooManyInputNodesException'>, 10017: <class 'censys.exceptions.CensysAssociatedAssetsThresholdWarningException'>, 10018: <class 'censys.exceptions.CensysHostNotFoundException'>, 10019: <class 'censys.exceptions.CensysDomainNotFoundException'>, 10020: <class 'censys.exceptions.CensysCertificateNotFoundException'>, 10021: <class 'censys.exceptions.CensysInvalidIPv4AddressException'>, 10025: <class 'censys.exceptions.CensysTagHasTrailingOrLeadingWhitespaceException'>, 10026: <class 'censys.exceptions.CensysTagIsEmptyStringException'>, 10027: <class 'censys.exceptions.CensysTagLabelsDifferOnlyInCasingException'>, 10028: <class 'censys.exceptions.CensysTagLabelTooLongException'>, 10029: <class 'censys.exceptions.CensysAppDownForMaintenanceException'>, 10034: <class 'censys.exceptions.CensysTagColorTooLongException'>, 10035: <class 'censys.exceptions.CensysCannotCreateTagWithNewColorException'>, 10036: <class 'censys.exceptions.CensysTagColorHasTrailingOrLeadingWhitespaceException'>, 10037: <class 'censys.exceptions.CensysInvalidColorException'>, 10038: <class 'censys.exceptions.CensysInvalidSeedTypeException'>, 10039: <class 'censys.exceptions.CensysTooManyRequestsException'>, 10040: <class 'censys.exceptions.CensysInvalidLogbookCursorException'>, 10050: <class 'censys.exceptions.CensysInvalidPageSizeException'>, 10051: <class 'censys.exceptions.CensysPageNumberOutOfRangeException'>, 10054: <class 'censys.exceptions.CensysInvalidCommentException'>, 10055: <class 'censys.exceptions.CensysCommentNotFoundException'>}

Map of status code to ASM Exception.

SEARCH_EXCEPTIONS: Dict[int, Type[censys.exceptions.CensysSearchException]] = {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 Search Exception.

exception censys.exceptions.CensysHostNotFoundException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the requested host is not found.

exception censys.exceptions.CensysInvalidAPIKeyException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the ASM API key is invalid.

exception censys.exceptions.CensysInvalidAuthTokenException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the auth token is invalid.

exception censys.exceptions.CensysInvalidColorException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the specified color is invalid.

exception censys.exceptions.CensysInvalidCommentException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the comment is invalid.

exception censys.exceptions.CensysInvalidIPv4AddressException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the IPv4 address is invalid.

exception censys.exceptions.CensysInvalidLogbookCursorException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the logbook cursor is invalid.

exception censys.exceptions.CensysInvalidPageSizeException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the page size is invalid.

exception censys.exceptions.CensysInvalidRequestException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the HTTP request is invalid.

exception censys.exceptions.CensysInvalidSeedDataException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the seed data is invalid.

exception censys.exceptions.CensysInvalidSeedTypeException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the seed type is invalid.

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

Bases: censys.exceptions.CensysSearchException

Exception raised when the resource requested is not valid JSON.

exception censys.exceptions.CensysMissingApiKeyException

Bases: censys.exceptions.CensysException

Exception raised when there is no provided ASM API key.

exception censys.exceptions.CensysNeedConfirmationToRemoveParentSeedsException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when confirmation is needed to remove seeds with children.

exception censys.exceptions.CensysNotASeedException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the requested resource is not a seed.

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

Bases: censys.exceptions.CensysSearchException

Exception raised when the resource requested is not found.

exception censys.exceptions.CensysPageNumberOutOfRangeException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the requested page number is out of range [1 - totalPages].

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

Bases: censys.exceptions.CensysSearchException

Exception raised when your Censys rate limit has been exceeded.

exception censys.exceptions.CensysSearchException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAPIException

Base Exception for the Censys search API.

exception censys.exceptions.CensysSeedNotFoundException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the requested seed can not be found.

exception censys.exceptions.CensysTagColorHasTrailingOrLeadingWhitespaceException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the specified tag color has trailing or leading whitespace.

exception censys.exceptions.CensysTagColorTooLongException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the specified tag color is too long.

exception censys.exceptions.CensysTagHasTrailingOrLeadingWhitespaceException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the specified tag has trailing or leading whitespace.

exception censys.exceptions.CensysTagIsEmptyStringException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the specified tag is an empty string.

exception censys.exceptions.CensysTagLabelTooLongException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the specified tag label is too long.

exception censys.exceptions.CensysTagLabelsDifferOnlyInCasingException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the specified tag differs from an existing tag in only casing.

exception censys.exceptions.CensysTooManyInputNodesException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when there are too many input nodes.

exception censys.exceptions.CensysTooManyRequestsException(status_code: int, message: str, body: Optional[str] = None, const: Optional[str] = None, error_code: Optional[int] = None, details: Optional[str] = None)

Bases: censys.exceptions.CensysAsmException

Exception raised when the allowed requests bandwidth is exceeded.

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

Bases: censys.exceptions.CensysSearchException

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(api_id: Optional[str] = None, api_secret: Optional[str] = None, url: Optional[str] = 'https://censys.io/api/v1', **kwargs)

Bases: censys.api.CensysSearchAPI

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(api_id: Optional[str] = None, api_secret: Optional[str] = None, url: Optional[str] = 'https://censys.io/api/v1', **kwargs)

Bases: censys.api.CensysSearchAPI

Interacts with the Websites index.

INDEX_NAME: Optional[str] = 'websites'

Name of Censys Index.