censys.asm package¶

Submodules¶

censys.asm.api module¶

Base for interacting with the Censys ASM API.

class censys.asm.api.CensysAsmAPI(api_key: Optional[str] = None, **kwargs)[source]¶

Bases: censys.base.CensysAPIBase

This is the base class for ASM’s Seeds, Assets, and Events classes

DEFAULT_URL: str = 'https://app.censys.io/api/v1'¶: Default ASM API base URL.

censys.asm.assets module¶

Interact with the Censys Assets API.

class censys.asm.assets.Assets(asset_type, api_key: Optional[str] = None, **kwargs)[source]¶

Bases: censys.asm.api.CensysAsmAPI

Assets API class

add_comment(asset_id: str, comment: str) → dict[source]¶

Adds a comment to a specified asset on the ASM platform.

Parameters

asset_id (str) – Asset ID to add comment to.
comment (str) – New comment text.

Returns

Added comment results.

Return type

dict

add_tag(asset_id: str, name: str, color: Optional[str] = None) → dict[source]¶

Adds a tag to a specified asset on the ASM platform.

Parameters

asset_id (str) – Asset ID to add tag to.
name (str) – New tag name.
color (str, optional) – New tag color.

delete_tag(asset_id: str, name: str) → dict[source]¶

Deletes a tag from a specified asset on the ASM platform by tag name.

Parameters

asset_id (str) – Asset ID to delete tag from.
name (str) – Tag name to delete.

get_asset_by_id(asset_id: str) → dict[source]¶

Requests asset data by ID.

Parameters: asset_id (str) – Requested asset ID.
Returns: Asset search result.
Return type: dict

get_assets(page_number: int = 1, page_size: Optional[int] = None) → Generator[dict, None, None][source]¶

Requests assets data.

Parameters

page_number (int, optional) – Page number to begin at when searching.
page_size (int, optional) – Page size for retrieving assets.

Returns

Asset search results.

Return type

generator

get_comment_by_id(asset_id: str, comment_id: int) → dict[source]¶

Requests a comment on a specified asset by comment ID.

Parameters

asset_id (str) – Asset ID for requested comments.
comment_id (int) – Requested comment ID.

Returns

Comment search result.

Return type

dict

get_comments(asset_id: str, page_number: int = 1, page_size: Optional[int] = None) → Generator[dict, None, None][source]¶

Requests comments on a specified asset.

Parameters

asset_id (str) – Asset ID for requested comments.
page_number (int, optional) – Page number to begin at when searching.
page_size (int, optional) – Page size for retrieving comments.

Returns

Comment search results.

Return type

generator

censys.asm.assets.format_tag(name: str, color: Optional[str] = None) → dict[source]¶

Formats tag name and color request data.

Parameters

name (str) – Tag name.
color (str, optional) – Tag color.

Returns

Formatted tag request data.

Return type

dict

censys.asm.client module¶

Interact with the Censys Seeds, Assets, and Logbook APIs.

class censys.asm.client.AsmClient(api_key: Optional[str] = None, **kwargs)[source]¶

Bases: object

Client ASM API class.

censys.asm.events module¶

Interact with the Censys Logbook API.

class censys.asm.events.Events(api_key: Optional[str] = None, **kwargs)[source]¶

Bases: censys.asm.api.CensysAsmAPI

Events API class

get_cursor(start: Optional[Union[datetime.datetime, int]] = None, filters: Optional[List[str]] = None) → str[source]¶

Requests a logbook cursor.

Parameters

start (datetime or int, optional) – Timestamp or event ID to begin searching.
filters (list, optional) – List of filters applied to logbook search results.

Returns

Cursor result.

Return type

str

get_events(cursor: Optional[str] = None) → Generator[dict, None, None][source]¶

Requests logbook events from inception or from the provided cursor.

Parameters: cursor (str, optional) – Logbook cursor.
Returns: Logbook events results.
Return type: generator

class censys.asm.events.Filters[source]¶

Bases: object

Logbook filters class

CERT = 'CERT'¶

CERT_RISK = 'CERT_RISK'¶

DOMAIN = 'DOMAIN'¶

DOMAIN_EXPIRATION_DATE = 'DOMAIN_EXPIRATION_DATE'¶

DOMAIN_MAIL_EXCHANGE_SERVER = 'DOMAIN_MAIL_EXCHANGE_SERVER'¶

DOMAIN_NAME_SERVER = 'DOMAIN_NAME_SERVER'¶

DOMAIN_REGISTRAR = 'DOMAIN_REGISTRAR'¶

DOMAIN_RISK = 'DOMAIN_RISK'¶

DOMAIN_SUBDOMAIN = 'DOMAIN_SUBDOMAIN'¶

HOST = 'HOST'¶

HOST_CERT = 'HOST_CERT'¶

HOST_PORT = 'HOST_PORT'¶

HOST_PROTOCOL = 'HOST_PROTOCOL'¶

HOST_RISK = 'HOST_RISK'¶

HOST_SOFTWARE = 'HOST_SOFTWARE'¶

HOST_VULNERABILITY = 'HOST_VULNERABILITY'¶

censys.asm.events.format_data(start: Optional[Union[datetime.datetime, int]] = None, filters: Optional[List[str]] = None) → dict[source]¶

Formats cursor request data into a start date/id and filter list

Parameters

start (datetime or int, optional) – Timestamp or event ID to begin searching.
filters (list, optional) – List of filters applied to logbook search results.

Returns

Formatted logbook cursor request data

Return type

dict

censys.asm.seeds module¶

Interact with the Censys Seeds API.

class censys.asm.seeds.Seeds(api_key: Optional[str] = None, **kwargs)[source]¶

Bases: censys.asm.api.CensysAsmAPI

Seeds API class

add_seeds(seeds: list, force: Optional[bool] = False) → dict[source]¶

Add seeds to the ASM platform.

Parameters

seeds (list) – List of seed objects to add.
force (bool, optional) – Forces replace operation.

Returns

Added seeds results.

Return type

dict

delete_seed_by_id(seed_id: int) → dict[source]¶

Delete a seed in the ASM platform by id.

Parameters: seed_id (int) – Seed ID to delete by.

delete_seeds_by_label(label: str) → dict[source]¶

Delete seeds in the ASM platform by label.

Parameters: label (str) – Label name to delete by.

get_seed_by_id(seed_id: int) → dict[source]¶

Requests seed data by ID.

Parameters: seed_id (int) – Seed ID to get.
Returns: Seed search result.
Return type: dict

get_seeds(seed_type: Optional[str] = None) → dict[source]¶

Requests seed data.

Parameters: seed_type (str, optional) – Seed type [‘IP_ADDRESS’, ‘DOMAIN_NAME’, ‘CIDR’, ‘ASN’].
Returns: Seed search results.
Return type: dict

replace_seeds_by_label(label: str, seeds: list, force: Optional[bool] = False) → dict[source]¶

Replace seeds in the ASM platform by label.

Parameters

label (str) – Label name to replace by.
seeds (list) – List of seed objects to add.
force (bool, optional) – Forces replace operation.

Returns

Added and removed seeds results.

Return type

dict

Module contents¶

An easy-to-use and lightweight API wrapper for the Censys ASM platform (censys.io).