censys.common package

Common Code for the Censys Python SDK.

censys.common.base module

Base for interacting with the Censys APIs.

class censys.common.base.CensysAPIBase(url: Optional[str] = None, timeout: Optional[int] = 30, max_retries: Optional[int] = 10, user_agent: Optional[str] = 'censys/2.0.6b1', proxies: Optional[dict] = None, cookies: Optional[dict] = None, **kwargs)[source]

Bases: object

This is the base class for API queries.

DEFAULT_MAX_RETRIES: int = 10

Default max number of API retries.

DEFAULT_TIMEOUT: int = 30

Default API timeout.

DEFAULT_USER_AGENT: str = 'censys/2.0.6b1'

Default API user agent.

censys.common.config module

Interact with the config file.

censys.common.config.check_config(config: configparser.ConfigParser)[source]

Checks config against default config for fields.

Parameters

config (configparser.ConfigParser) – Configuration to write.

censys.common.config.get_config() configparser.ConfigParser[source]

Reads and returns config.

Returns

Config for Censys.

Return type

configparser.ConfigParser

censys.common.config.write_config(config: configparser.ConfigParser) None[source]

Writes config to file.

Parameters

config – Configuration to write.

censys.common.types module

Common types for the Censys Python SDK.

censys.common.utils module

Common utilities for the Censys Python SDK.

censys.common.utils.format_rfc3339(time: Union[str, datetime.date, datetime.datetime]) str[source]

Formats a datetime object into an RFC3339 string.

Parameters

time (Datetime) – Datetime object to format.

Returns

RFC3339 formatted string.

Return type

str

censys.common.exceptions module

Exceptions for Censys.

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

Bases: censys.common.exceptions.CensysException

Base Exception for Censys APIs.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when the ASM API is down for maintenance.

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

Bases: censys.common.exceptions.CensysAPIException

Base Exception for the Censys ASM API.

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

Bases: censys.common.exceptions.CensysAsmException

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

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when a bad JSON string is in the body.

exception censys.common.exceptions.CensysCLIException[source]

Bases: censys.common.exceptions.CensysException

Exception raised when the CLI is passed invalid arguments.

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

Bases: censys.common.exceptions.CensysAsmException

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

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when trying to remove non existent seed nodes.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when trying to remove non seed nodes.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when the certificate is not found.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when the requested comment is not found.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when the domain is not found.

exception censys.common.exceptions.CensysException[source]

Bases: Exception

Base Exception for Censys.

class censys.common.exceptions.CensysExceptionMapper[source]

Bases: object

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

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

Map of status code to ASM Exception.

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

Map of status code to Search Exception.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when the requested host is not found.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when the ASM API key is invalid.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when the auth token is invalid.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when invalid cloud asset data is submitted.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when an invalid cloud is submitted.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when the specified color is invalid.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when the comment is invalid.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when an invalid date is submitted.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when the IPv4 address is invalid.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when the logbook cursor is invalid.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when object storage name is not a valid asset URL.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when no object storage assets with given URL were found.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when the page size is invalid.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when the HTTP request is invalid.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when the seed data is invalid.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when the seed type is invalid.

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

Bases: censys.common.exceptions.CensysSearchException

Exception raised when the resource requested is not valid JSON.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when there is no provided ASM API key.

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

Bases: censys.common.exceptions.CensysAsmException

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

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when the requested resource is not a seed.

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

Bases: censys.common.exceptions.CensysSearchException

Exception raised when the resource requested is not found.

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

Bases: censys.common.exceptions.CensysAsmException

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

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

Bases: censys.common.exceptions.CensysSearchException

Exception raised when your Censys rate limit has been exceeded.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when no risks are found with given risk_id.

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

Bases: censys.common.exceptions.CensysAPIException

Base Exception for the Censys search API.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when the requested seed can not be found.

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

Bases: censys.common.exceptions.CensysAsmException

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

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when the specified tag color is too long.

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

Bases: censys.common.exceptions.CensysAsmException

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

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when the specified tag is an empty string.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when the specified tag label is too long.

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

Bases: censys.common.exceptions.CensysAsmException

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

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when there are too many input nodes.

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

Bases: censys.common.exceptions.CensysAsmException

Exception raised when the allowed requests bandwidth is exceeded.

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

Bases: censys.common.exceptions.CensysSearchException

Exception raised when you doesn’t have access to the requested resource.

censys.common.deprecation module

Warns on deprecated class and functions.

class censys.common.deprecation.DeprecationDecorator(message: Optional[str] = None)[source]

Bases: object

Deprecation Decorator for classes and functions.