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.

Parameters
  • 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.

Parameters
  • 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.

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.

Returns

Added tag results.

Return type

dict

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.

Returns

Deleted tag results.

Return type

dict

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)Iterator[dict][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.

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.

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)Iterator[dict][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

class censys.asm.CertificatesAssets(*args, **kwargs)[source]

Bases: censys.asm.assets.assets.Assets

Certificates Assets API class.

Parameters
  • *args – Variable length argument list.

  • **kwargs – Arbitrary keyword arguments.

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.

Parameters

since (Since) – Date to include domains from.

Returns

Domain count result.

Return type

dict

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.

Parameters

since (Since) – Date to include hosts from.

Returns

Host count result.

Return type

dict

get_object_store_counts(since: Union[str, datetime.date, datetime.datetime])dict[source]

Retrieve object store counts by cloud.

Parameters

since (Since) – Date to include object stores from.

Returns

Object store count result.

Return type

dict

get_subdomain_counts(since: Union[str, datetime.date, datetime.datetime])dict[source]

Retrieve subdomain counts by cloud.

Parameters

since (Since) – Date to include subdomains from.

Returns

Subdomain count result.

Return type

dict

get_unknown_counts()dict[source]

Retrieve known and unknown counts for hosts by cloud.

Returns

Unknown count result.

Return type

dict

class censys.asm.DomainsAssets(*args, **kwargs)[source]

Bases: censys.asm.assets.assets.Assets

Domains Assets API class.

Parameters
  • *args – Variable length argument list.

  • **kwargs – Arbitrary keyword arguments.

get_subdomains(domain: str, page_number: int = 1, page_size: Optional[int] = None)Iterator[dict][source]

List all subdomains of the parent domain.

Parameters
  • 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

Asset search results.

Return type

generator

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.

Parameters
  • start ([datetime.datetime, 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)Iterator[dict][source]

Requests logbook events from inception or from the provided cursor.

Parameters

cursor (str) – Optional; Logbook cursor.

Yields

dict – Logbook event.

class censys.asm.HostsAssets(*args, **kwargs)[source]

Bases: censys.asm.assets.assets.Assets

Hosts Assets API class.

Parameters
  • *args – Variable length argument list.

  • **kwargs – Arbitrary keyword arguments.

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.

Parameters
  • seeds (list) – List of seed objects to add.

  • force (bool, optional) – Forces replace operation.

Returns

Added seeds results.

Return type

dict

base_path = 'seeds'
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.

Returns

Delete results.

Return type

dict

delete_seeds_by_label(label: str)dict[source]

Delete seeds in the ASM platform by label.

Parameters

label (str) – Label name to delete by.

Returns

Delete results.

Return type

dict

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] = None)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

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.

Parameters
  • 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.