censys.asm package
An easy-to-use and lightweight API wrapper for Censys ASM (app.censys.io).
- class censys.asm.AsmClient(api_key: Optional[str] = None, **kwargs)[source]
Bases:
object
Client ASM API class.
- class censys.asm.Assets(asset_type: str, *args, **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.
- 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_comment(asset_id: str, comment_id: int) dict [source]
Deletes a comment from a specified asset on the ASM platform by comment ID.
- Args:
asset_id (str): Asset ID to delete comment from. comment_id (int): Comment ID to delete.
- Returns:
dict: Deleted comment 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, tag: Optional[List[str]] = None, tag_operator: Optional[str] = None, source: Optional[List[str]] = None, discovery_trail: Optional[bool] = 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. tag (list): Optional; List of tags to search for. tag_operator (str): Optional; Operator to use when searching for tags. source (list): Optional; List of sources to search for. discovery_trail (bool): Optional; Bool indicating whether to return discovery trail.
- 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 = '/v1/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.
- Yields:
dict: The assets result returned.
- class censys.asm.Events(api_key: Optional[str] = None, **kwargs)[source]
Bases:
censys.asm.api.CensysAsmAPI
Events API class.
- base_path = '/v1/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.
- censys.asm.Risks
alias of
censys.asm.risks.v1.Risksv1
- class censys.asm.Risksv1(api_key: Optional[str] = None, **kwargs)[source]
Bases:
censys.asm.api.CensysAsmAPI
Risks v1 API class.
- base_path = '/v1/risks'
- get_risks(cloud: Optional[str] = None, environment: Optional[str] = None, include_accepted_risks: Optional[bool] = None, page_number: int = 1, page_size: int = 100) Iterator[dict] [source]
Retrieve risks.
Returns a full list of all risks that affect any assets in the system, along with a count of assets affected by each risk.
- Args:
cloud (str): The cloud to filter by. environment (str): The environment to filter by. include_accepted_risks (bool): Whether to include accepted risks. page_number (int): The page number to return. page_size (int): The number of items to return per page.
- Yields:
dict: Host count result.
- class censys.asm.Risksv2(api_key: Optional[str] = None, **kwargs)[source]
Bases:
censys.asm.api.CensysAsmAPI
Risks v2 API class.
- base_path = '/v2/risk'
- get_risk_instance(risk_instance_id: int, include_events: Optional[bool] = None) dict [source]
Retrieve a risk instance.
- Args:
risk_instance_id (int): Risk instance ID. include_events (bool): Optional; Whether to include events.
- Returns:
dict: Risk instance result.
- get_risk_instances(include_events: Optional[bool] = None, accept: Optional[str] = None) dict [source]
Retrieve risk instances.
- Args:
include_events (bool): Optional; Whether to include events. accept (str): Optional; Accept header.
- Returns:
dict: Risk instances result.
- get_risk_type(risk_type: str, include_events: Optional[bool] = None) dict [source]
Retrieve a risk type.
- Args:
risk_type (str): Risk type. include_events (bool): Optional; Whether to include events.
- Returns:
dict: Risk type result.
- get_risk_types(sort: Optional[List[str]] = None, include_events: Optional[bool] = None, accept: Optional[str] = None) dict [source]
Retrieve risk types.
- Args:
sort (list): Optional; Sort by field(s). include_events (bool): Optional; Whether to include events. accept (str): Optional; Accept header.
- Returns:
dict: Risk types result.
- patch_risk_instance(risk_instance_id: int, data: dict) dict [source]
Patch a risk instance.
- Args:
risk_instance_id (int): Risk instance ID. data (dict): Risk instance data.
- Returns:
dict: Risk instance result.
- patch_risk_instances(data: dict) dict [source]
Patch risk instances.
- Args:
data (dict): Risk instances data.
- Returns:
dict: Risk instances result.
- patch_risk_type(risk_type: str, data: dict) dict [source]
Patch a risk type.
- Args:
risk_type (str): Risk type. data (dict): Risk type data.
- Returns:
dict: Risk type result.
- risk_instances_path = '/v2/risk-instances'
- risk_types_path = '/v2/risk-types'
- 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 = '/v1/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, label: Optional[str] = None) dict [source]
Requests seed data.
- Args:
- seed_type (str):
Optional; Seed type [‘IP_ADDRESS’, ‘DOMAIN_NAME’, ‘CIDR’, ‘ASN’].
label (str): Optional; Seed label.
- 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.
- DEFAULT_URL: str = 'https://app.censys.io/api'
Default ASM API base URL.