censys.asm package¶
An easy-to-use and lightweight API wrapper for Censys ASM (censys.io).
-
class
censys.asm.
AsmClient
(api_key: Optional[str] = None, **kwargs)[source]¶ Bases:
object
Client ASM API class.
- Args:
api_key (str): Optional; The API Key provided by Censys. **kwargs: Arbitrary keyword arguments.
-
class
censys.asm.
Assets
(asset_type: str, *args, **kwargs)[source]¶ Bases:
censys.asm.api.CensysAsmAPI
Assets API class.
- Args:
asset_type (str): Type of asset to interact with. *args: Variable length argument list. **kwargs: Arbitrary keyword arguments.
-
add_comment
(asset_id: str, comment: str) → dict[source]¶ Adds a comment to a specified asset on the ASM platform.
- Args:
asset_id (str): Asset ID to add comment to. comment (str): New comment text.
- Returns:
dict: Added comment results.
-
add_tag
(asset_id: str, name: str, color: Optional[str] = None) → dict[source]¶ Adds a tag to a specified asset on the ASM platform.
- Args:
asset_id (str): Asset ID to add tag to. name (str): New tag name. color (str): Optional; New tag color (hex).
- Returns:
dict: Added tag results.
-
delete_tag
(asset_id: str, name: str) → dict[source]¶ Deletes a tag from a specified asset on the ASM platform by tag name.
- Args:
asset_id (str): Asset ID to delete tag from. name (str): Tag name to delete.
- Returns:
dict: Deleted tag results.
-
get_asset_by_id
(asset_id: str) → dict[source]¶ Requests asset data by ID.
- Args:
asset_id (str): Requested asset ID.
- Returns:
dict: Asset search result.
-
get_assets
(page_number: int = 1, page_size: Optional[int] = None) → Iterator[dict][source]¶ Requests assets data.
- Args:
page_number (int): Optional; Page number to begin at when searching. page_size (int): Optional; Page size for retrieving assets.
- Yields:
dict: The assets result returned.
-
get_comment_by_id
(asset_id: str, comment_id: int) → dict[source]¶ Requests a comment on a specified asset by comment ID.
- Args:
asset_id (str): Asset ID for requested comments. comment_id (int): Requested comment ID.
- Returns:
dict: Comment search result.
-
get_comments
(asset_id: str, page_number: int = 1, page_size: Optional[int] = None) → Iterator[dict][source]¶ Requests comments on a specified asset.
- Args:
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:
generator: Comment search results.
-
class
censys.asm.
CertificatesAssets
(*args, **kwargs)[source]¶ Bases:
censys.asm.assets.assets.Assets
Certificates Assets API class.
-
class
censys.asm.
Clouds
(api_key: Optional[str] = None, **kwargs)[source]¶ Bases:
censys.asm.api.CensysAsmAPI
Clouds API class.
-
base_path
= 'clouds'¶
-
get_domain_counts
(since: Union[str, datetime.date, datetime.datetime]) → dict[source]¶ Retrieve domain counts by cloud.
- Args:
since (Since): Date to include domains from.
- Returns:
dict: Domain count result.
-
get_host_counts
(since: Union[str, datetime.date, datetime.datetime]) → dict[source]¶ Retrieve host counts by cloud.
Hosts found after the date provided in the since parameter will be included in the new asset counts.
- Args:
since (Since): Date to include hosts from.
- Returns:
dict: Host count result.
-
get_object_store_counts
(since: Union[str, datetime.date, datetime.datetime]) → dict[source]¶ Retrieve object store counts by cloud.
- Args:
since (Since): Date to include object stores from.
- Returns:
dict: Object store count result.
-
-
class
censys.asm.
DomainsAssets
(*args, **kwargs)[source]¶ Bases:
censys.asm.assets.assets.Assets
Domains Assets API class.
-
get_subdomains
(domain: str, page_number: int = 1, page_size: Optional[int] = None) → Iterator[dict][source]¶ List all subdomains of the parent domain.
- Args:
domain: (str): Parent domain to query. page_number (int): Optional; Page number to begin at when searching. page_size (int): Optional; Page size for retrieving assets.
- Returns:
generator: Asset search results.
-
-
class
censys.asm.
Events
(api_key: Optional[str] = None, **kwargs)[source]¶ Bases:
censys.asm.api.CensysAsmAPI
Events API class.
-
base_path
= 'logbook'¶
-
get_cursor
(start: Optional[Union[datetime.datetime, int]] = None, filters: Optional[List[str]] = None) → str[source]¶ Requests a logbook cursor.
- Args:
start ([datetime.datetime, int]): Optional; Timestamp or event ID to begin searching. filters (list): Optional; List of filters applied to logbook search results.
- Returns:
str: Cursor result.
-
-
class
censys.asm.
HostsAssets
(*args, **kwargs)[source]¶ Bases:
censys.asm.assets.assets.Assets
Hosts Assets API class.
-
class
censys.asm.
Seeds
(api_key: Optional[str] = None, **kwargs)[source]¶ Bases:
censys.asm.api.CensysAsmAPI
Seeds API class.
-
add_seeds
(seeds: list, force: Optional[bool] = None) → dict[source]¶ Add seeds to the ASM platform.
- Args:
seeds (list): List of seed objects to add. force (bool, optional): Forces replace operation.
- Returns:
dict: Added seeds results.
-
base_path
= 'seeds'¶
-
delete_seed_by_id
(seed_id: int) → dict[source]¶ Delete a seed in the ASM platform by id.
- Args:
seed_id (int): Seed ID to delete by.
- Returns:
dict: Delete results.
-
delete_seeds_by_label
(label: str) → dict[source]¶ Delete seeds in the ASM platform by label.
- Args:
label (str): Label name to delete by.
- Returns:
dict: Delete results.
-
get_seed_by_id
(seed_id: int) → dict[source]¶ Requests seed data by ID.
- Args:
seed_id (int): Seed ID to get.
- Returns:
dict: Seed search result.
-
get_seeds
(seed_type: Optional[str] = None) → dict[source]¶ Requests seed data.
- Args:
- seed_type (str):
Optional; Seed type [‘IP_ADDRESS’, ‘DOMAIN_NAME’, ‘CIDR’, ‘ASN’].
- Returns:
dict: Seed search results.
-
replace_seeds_by_label
(label: str, seeds: list, force: Optional[bool] = None) → dict[source]¶ Replace seeds in the ASM platform by label.
- Args:
label (str): Label name to replace by. seeds (list): List of seed objects to add. force (bool): Optional; Forces replace operation.
- Returns:
dict: Added and removed seeds results.
-
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.common.base.CensysAPIBase
This is the base class for ASM’s Seeds, Assets, and Events classes.
- Args:
api_key (str): Optional; The API Key provided by Censys. **kwargs: Arbitrary keyword arguments.
- Raises:
CensysException: Base Exception Class for the Censys API.
-
DEFAULT_URL
: str = 'https://app.censys.io/api/v1'¶ Default ASM API base URL.