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: str | None = None, timeout: int | None = 30, max_retries: int | None = 5, user_agent: str | None = 'censys-python/2.2.16', proxies: dict | None = None, cookies: dict | None = None, **kwargs)

Bases: object

This is the base class for API queries.

DEFAULT_MAX_RETRIES: int = 5

Default max number of API retries.

DEFAULT_TIMEOUT: int = 30

Default API timeout.

DEFAULT_USER_AGENT: str = 'censys-python/2.2.16'

Default API user agent.

property request_id: str | None

The x-request-id header value for API requests.

The x-request-id header is not set when the value is None. Value is None by default

Returns:

The value of the header.

Return type:

Type[Optional[str]]

censys.common.config module

Interact with the config file.

censys.common.config.get_config() → ConfigParser

Reads and returns config.

Returns:

Config for Censys.

Return type:

configparser.ConfigParser

censys.common.config.get_config_path() → str

Returns the path to the config file.

Returns:

Path to config file.

Return type:

str

censys.common.config.write_config(config: ConfigParser) → None

Writes config to file.

Parameters:

config (configparser.ConfigParser) – Configuration to write.

Raises:

PermissionError – If the config file is not writable.

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_iso8601(time: str | date | datetime) → str

Formats a datetime object into an ISO8601 string.

Parameters:

time (Datetime) – Datetime object to format.

Returns:

ISO8601 formatted string.

Return type:

str

censys.common.utils.format_rfc3339(time: str | date | datetime) → str

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

Bases: CensysException

Base Exception for Censys APIs.

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

Bases: CensysAsmException

Exception raised when the ASM API is down for maintenance.

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

Bases: CensysAPIException

Base Exception for the Censys ASM API.

exception censys.common.exceptions.CensysAsmUnauthorizedException(status_code: int, message: str, body: str | None = None, const: str | None = None, error_code: int | None = None, details: str | None = None)

Bases: CensysAsmException

Exception raised when the ASM API is unauthorized.

exception censys.common.exceptions.CensysAssetExcludedException(status_code: int, message: str, body: str | None = None, const: str | None = None, error_code: int | None = None, details: str | None = None)

Bases: CensysAsmException

Exception raised when the asset is excluded.

exception censys.common.exceptions.CensysAssetNotFoundException(status_code: int, message: str, body: str | None = None, const: str | None = None, error_code: int | None = None, details: str | None = None)

Bases: CensysAsmException

Exception raised when the asset is not found.

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

Bases: CensysAsmException

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

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

Bases: CensysAsmException

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

exception censys.common.exceptions.CensysCLIException

Bases: CensysException

Exception raised when the CLI is passed invalid arguments.

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

Bases: 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: str | None = None, const: str | None = None, error_code: int | None = None, details: str | None = None)

Bases: CensysAsmException

Exception raised when trying to remove non existent seed nodes.

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

Bases: CensysAsmException

Exception raised when trying to remove non seed nodes.

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

Bases: CensysAsmException

Exception raised when the certificate is not found.

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

Bases: CensysAsmException

Exception raised when the requested comment is not found.

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

Bases: CensysAsmException

Exception raised when the domain is not found.

exception censys.common.exceptions.CensysException

Bases: Exception

Base Exception for Censys.

class censys.common.exceptions.CensysExceptionMapper

Bases: object

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

ASM_EXCEPTIONS: Dict[int, Type[CensysAsmException]] = {10000: <class 'censys.common.exceptions.CensysMissingApiKeyException'>, 10001: <class 'censys.common.exceptions.CensysInvalidAPIKeyException'>, 10002: <class 'censys.common.exceptions.CensysInvalidAuthTokenException'>, 10006: <class 'censys.common.exceptions.CensysAsmUnauthorizedException'>, 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'>, 10022: <class 'censys.common.exceptions.CensysAssetExcludedException'>, 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'>, 10045: <class 'censys.common.exceptions.CensysTeamNotFoundException'>, 10050: <class 'censys.common.exceptions.CensysInvalidPageSizeException'>, 10051: <class 'censys.common.exceptions.CensysPageNumberOutOfRangeException'>, 10054: <class 'censys.common.exceptions.CensysInvalidCommentException'>, 10055: <class 'censys.common.exceptions.CensysCommentNotFoundException'>, 10057: <class 'censys.common.exceptions.CensysSubdomainNotFoundException'>, 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'>, 10086: <class 'censys.common.exceptions.CensysAssetNotFoundException'>, 10091: <class 'censys.common.exceptions.CensysInvalidKeywordsInBodyException'>, 10096: <class 'censys.common.exceptions.CensysSearchAPITimeoutException'>, 10097: <class 'censys.common.exceptions.CensysSearchAPIErrorException'>, 10098: <class 'censys.common.exceptions.CensysInternalServerErrorException'>, 10099: <class 'censys.common.exceptions.CensysInvalidCommentHTMLException'>, 10107: <class 'censys.common.exceptions.CensysInvalidSearchAPIResponseException'>, 10120: <class 'censys.common.exceptions.CensysTooSoonToResendInviteException'>}

Map of status code to ASM Exception.

SEARCH_EXCEPTIONS: Dict[int, Type[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'>, 500: <class 'censys.common.exceptions.CensysInternalServerException'>}

Map of status code to Search Exception.

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

Bases: CensysAsmException

Exception raised when the requested host is not found.

exception censys.common.exceptions.CensysInternalServerErrorException(status_code: int, message: str, body: str | None = None, const: str | None = None, error_code: int | None = None, details: str | None = None)

Bases: CensysAsmException

Exception raised when the search API returns an error.

exception censys.common.exceptions.CensysInternalServerException(status_code: int, message: str, body: str | None = None, const: str | None = None, error_code: int | None = None, details: str | None = None)

Bases: CensysSearchException

Exception raised when the server encountered an internal error.

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

Bases: CensysAsmException

Exception raised when the ASM API key is invalid.

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

Bases: CensysAsmException

Exception raised when the auth token is invalid.

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

Bases: CensysAsmException

Exception raised when invalid cloud asset data is submitted.

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

Bases: CensysAsmException

Exception raised when an invalid cloud is submitted.

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

Bases: CensysAsmException

Exception raised when the specified color is invalid.

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

Bases: CensysAsmException

Exception raised when the comment is invalid.

exception censys.common.exceptions.CensysInvalidCommentHTMLException(status_code: int, message: str, body: str | None = None, const: str | None = None, error_code: int | None = None, details: str | None = None)

Bases: CensysAsmException

Exception raised when the comment contains invalid HTML.

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

Bases: CensysAsmException

Exception raised when an invalid date is submitted.

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

Bases: CensysAsmException

Exception raised when the IPv4 address is invalid.

exception censys.common.exceptions.CensysInvalidKeywordsInBodyException(status_code: int, message: str, body: str | None = None, const: str | None = None, error_code: int | None = None, details: str | None = None)

Bases: CensysAsmException

Exception raised when invalid keywords are in the body.

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

Bases: CensysAsmException

Exception raised when the logbook cursor is invalid.

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

Bases: CensysAsmException

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

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

Bases: CensysAsmException

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

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

Bases: CensysAsmException

Exception raised when the page size is invalid.

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

Bases: CensysAsmException

Exception raised when the HTTP request is invalid.

exception censys.common.exceptions.CensysInvalidSearchAPIResponseException(status_code: int, message: str, body: str | None = None, const: str | None = None, error_code: int | None = None, details: str | None = None)

Bases: CensysAsmException

Exception raised when the search API returns an error.

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

Bases: CensysAsmException

Exception raised when the seed data is invalid.

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

Bases: CensysAsmException

Exception raised when the seed type is invalid.

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

Bases: CensysSearchException

Exception raised when the resource requested is not valid JSON.

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

Bases: CensysAsmException

Exception raised when there is no provided ASM API key.

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

Bases: CensysAsmException

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

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

Bases: CensysAsmException

Exception raised when the requested resource is not a seed.

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

Bases: CensysSearchException

Exception raised when the resource requested is not found.

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

Bases: CensysAsmException

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

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

Bases: CensysSearchException

Exception raised when your Censys rate limit has been exceeded.

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

Bases: CensysAsmException

Exception raised when no risks are found with given risk_id.

exception censys.common.exceptions.CensysSearchAPIErrorException(status_code: int, message: str, body: str | None = None, const: str | None = None, error_code: int | None = None, details: str | None = None)

Bases: CensysAsmException

Exception raised when the search API returns an error.

exception censys.common.exceptions.CensysSearchAPITimeoutException(status_code: int, message: str, body: str | None = None, const: str | None = None, error_code: int | None = None, details: str | None = None)

Bases: CensysAsmException

Exception raised when the search API times out.

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

Bases: CensysAPIException

Base Exception for the Censys search API.

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

Bases: CensysAsmException

Exception raised when the requested seed can not be found.

exception censys.common.exceptions.CensysSubdomainNotFoundException(status_code: int, message: str, body: str | None = None, const: str | None = None, error_code: int | None = None, details: str | None = None)

Bases: CensysAsmException

Exception raised when the requested subdomain is not found.

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

Bases: CensysAsmException

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

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

Bases: CensysAsmException

Exception raised when the specified tag color is too long.

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

Bases: CensysAsmException

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

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

Bases: CensysAsmException

Exception raised when the specified tag is an empty string.

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

Bases: CensysAsmException

Exception raised when the specified tag label is too long.

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

Bases: CensysAsmException

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

exception censys.common.exceptions.CensysTeamNotFoundException(status_code: int, message: str, body: str | None = None, const: str | None = None, error_code: int | None = None, details: str | None = None)

Bases: CensysAsmException

Exception raised when the team is not found.

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

Bases: CensysAsmException

Exception raised when there are too many input nodes.

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

Bases: CensysAsmException

Exception raised when the allowed requests bandwidth is exceeded.

exception censys.common.exceptions.CensysTooSoonToResendInviteException(status_code: int, message: str, body: str | None = None, const: str | None = None, error_code: int | None = None, details: str | None = None)

Bases: CensysAsmException

Exception raised when it is too soon to resend the invite.

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

Bases: 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: str | None = None)

Bases: object

Deprecation Decorator for classes and functions.