censys.asm package

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

class censys.asm.AsmClient(api_key: str | None = None, **kwargs)[source]

Bases: object

Client ASM API class.

class censys.asm.Assets(asset_type: str, *args, **kwargs)[source]

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

Returns:

Added tag results.

Return type:

dict

asset_type: str

delete_comment(asset_id: str, comment_id: int) → dict[source]

Deletes a comment from a specified asset on the ASM platform by comment ID.

Parameters:

asset_id (str) – Asset ID to delete comment from.
comment_id (int) – Comment ID to delete.

Returns:

Deleted comment 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

Requests assets data.

Parameters:

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.

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: int | None = 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.Beta(api_key: str | None = None, **kwargs)[source]

Bases: CensysAsmAPI

Beta API class.

add_cloud_assets(cloud_connector_uid: str, cloud_assets: List[dict])[source]

Add cloud assets.

Parameters:

cloud_connector_uid (str) – Cloud connector UID.
cloud_assets (List[dict]) – Cloud assets.

Returns:

Add cloud assets result.

Return type:

dict

base_path = '/beta'

get_asset_counts(since: str | date | datetime, environment: str, asset_type: str)[source]

Retrieve asset counts.

Parameters:

since (Datetime) – Date to include assets from.
environment (str) – Environment to include assets from.
asset_type (str) – Asset type to include.

Returns:

Asset count result.

Return type:

dict

get_host_counts_by_country(since: str | date | datetime, environment: str)[source]

Retrieve host counts by country.

Parameters:

since (Datetime) – Date to include hosts from.
environment (str) – Environment to include hosts from.

Returns:

Host count result.

Return type:

dict

get_input_assets(page_number: int = 1, page_size: int | None = None)[source]

Retrieve input assets.

Parameters:

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

Returns:

Input assets result.

Return type:

dict

get_logbook_data(filters: dict | None = None, cursor: str | None = None)[source]

Retrieve logbook data.

Parameters:

filters (dict) – Optional; Filter parameters.
cursor (str) – Optional; Cursor for pagination.

Returns:

Logbook data result.

Return type:

dict

get_user_workspaces(user_uuid: str)[source]

Retrieve user workspaces.

Parameters:: user_uuid (str) – User UUID.
Returns:: User workspaces result.
Return type:: dict

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

Bases: Assets

Certificates Assets API class.

class censys.asm.Clouds(api_key: str | None = None, **kwargs)[source]

Bases: CensysAsmAPI

Clouds API class.

base_path = '/v1/clouds'

get_domain_counts(since: str | date | datetime) → dict[source]

Retrieve domain counts by cloud.

Parameters:: since (Datetime) – Date to include domains from.
Returns:: Domain count result.
Return type:: dict

get_host_counts(since: str | date | 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 (Datetime) – Date to include hosts from.
Returns:: Host count result.
Return type:: dict

get_object_store_counts(since: str | date | datetime) → dict[source]

Retrieve object store counts by cloud.

Parameters:: since (Datetime) – Date to include object stores from.
Returns:: Object store count result.
Return type:: dict

get_subdomain_counts(since: str | date | datetime) → dict[source]

Retrieve subdomain counts by cloud.

Parameters:: since (Datetime) – 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: Assets

Domains Assets API class.

get_subdomains(domain: str, page_number: int = 1, page_size: int | None = 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.

Yields:

dict – The assets result returned.

censys.asm.Events: alias of Logbook

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

Bases: Assets

Hosts Assets API class.

class censys.asm.InventorySearch(api_key: str | None = None, **kwargs)[source]

Bases: CensysAsmAPI

Inventory Search API class.

aggregate(workspaces: List[str], query: str | None = None, aggregation: dict | None = None) → dict[source]

Aggregate inventory data.

Parameters:

workspaces (List[str]) – List of workspace IDs to search.
query (str, optional) – Query string.
aggregation (dict, optional) – Aggregation object.

Returns:

Inventory aggregation results.

Return type:

dict

base_path = '/inventory/v1'

fields(fields: List[str] | None = None) → dict[source]

List inventory fields.

If no fields are specified, all fields will be returned.

Parameters:: fields (List[str], optional) – List of fields to return.
Returns:: Inventory field results.
Return type:: dict

Search inventory data.

Parameters:

workspaces (List[str]) – List of workspace IDs to search.
query (str, optional) – Query string.
page_size (int, optional) – Number of results to return. Defaults to 50.
cursor (str, optional) – Cursor to start search from.
sort (List[str], optional) – List of fields to sort by.
fields (List[str], optional) – List of fields to return.

Returns:

Inventory search results.

Return type:

dict

class censys.asm.Logbook(api_key: str | None = None, **kwargs)[source]

Bases: CensysAsmAPI

Logbook API class.

base_path = '/v1/logbook'

get_cursor(start: datetime | int | None = None, filters: List[str] | None = 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: str | None = 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.ObjectStoragesAssets(*args, **kwargs)[source]

Bases: Assets

Object Storage Assets API class.

Please note that the Object Storage Assets API is currently in beta and is subject to change.

class censys.asm.Risks(api_key: str | None = None, **kwargs)[source]

Bases: CensysAsmAPI

Risks API class.

base_path = '/v2/risk'

Retrieve risk events.

Parameters:

start (str) – Optional; Starting event time, inclusive (in RFC3339 format).
end (str) – Optional; Ending event time, inclusive (in RFC3339 format).
after_id (int) – Optional; Risk event ID to query for events after.
limit (int) – Optional; Max number of events to return.
cursor (str) – Optional; Cursor value to continue collecting events started in a previous request.
accept (str) – Optional; Accept header.

Returns:

Risk events result.

Return type:

dict

get_risk_instance(risk_instance_id: int, include_events: bool | None = None) → dict[source]

Retrieve a risk instance.

Parameters:

risk_instance_id (int) – Risk instance ID.
include_events (bool) – Optional; Whether to include events.

Returns:

Risk instance result.

Return type:

dict

get_risk_instances(include_events: bool | None = None, accept: str | None = None) → dict[source]

Retrieve risk instances.

Parameters:

include_events (bool) – Optional; Whether to include events.
accept (str) – Optional; Accept header.

Returns:

Risk instances result.

Return type:

dict

get_risk_type(risk_type: str, include_events: bool | None = None) → dict[source]

Retrieve a risk type.

Parameters:

risk_type (str) – Risk type.
include_events (bool) – Optional; Whether to include events.

Returns:

Risk type result.

Return type:

dict

get_risk_types(sort: List[str] | None = None, include_events: bool | None = None, accept: str | None = None) → dict[source]

Retrieve risk types.

Parameters:

sort (list) – Optional; Sort by field(s).
include_events (bool) – Optional; Whether to include events.
accept (str) – Optional; Accept header.

Returns:

Risk types result.

Return type:

dict

patch_risk_instance(risk_instance_id: int, data: dict) → dict[source]

Patch a risk instance.

Parameters:

risk_instance_id (int) – Risk instance ID.
data (dict) – Risk instance data.

Returns:

Risk instance result.

Return type:

dict

patch_risk_instances(data: dict) → dict[source]

Patch risk instances.

Parameters:: data (dict) – Risk instances data.
Returns:: Risk instances result.
Return type:: dict

patch_risk_type(risk_type: str, data: dict) → dict[source]

Patch a risk type.

Parameters:

risk_type (str) – Risk type.
data (dict) – Risk type data.

Returns:

Risk type result.

Return type:

dict

risk_events_path = '/v2/risk-events'

risk_instances_path = '/v2/risk-instances'

risk_types_path = '/v2/risk-types'

search_risk_instances(data: dict, accept: str | None = None) → dict[source]

Search risk instances.

Parameters:

data (dict) – Query data.
accept (str) – Optional; Accept header.

Returns:

Risk instances result.

Return type:

dict

class censys.asm.SavedQueries(api_key: str | None = None, **kwargs)[source]

Bases: CensysAsmAPI

Saved Queries API class.

add_saved_query(query: str, query_name: str) → dict[source]

Add a new saved query to the ASM platform.

Parameters:

query (str) – Query string.
query_name (str) – Saved query name.

Returns:

Added saved query results.

Return type:

dict

base_path = '/inventory/v1/saved-query'

delete_saved_query_by_id(query_id: str) → dict[source]

Delete saved query by query ID.

Parameters:: query_id (str) – The saved query’s ID.
Returns:: Delete results.
Return type:: dict

edit_saved_query_by_id(query_id: str, query: str, query_name: str) → dict[source]

Edit an existing saved query by query ID.

Parameters:

query_id (str) – The saved query’s ID.
query (str) – New query string.
query_name (str) – New saved query name.

Returns:

Edited saved query result.

Return type:

dict

get_saved_queries(query_name_prefix: str | None = None, page_size: int | None = None, page: int | None = None, filter_term: str | None = None) → dict[source]

Get saved queries.

Parameters:

query_name_prefix (str, optional) – Prefix for the saved query name.
page_size (int, optional) – Number of results to return. Defaults to 50.
page (int, optional) – Page number to begin at when searching. Defaults to 1.
filter_term (str, optional) – Term used to filter the list of saved query names and the saved queries.

Returns:

Saved queries results.

Return type:

dict

get_saved_query_by_id(query_id: str) → dict[source]

Get saved query by query ID.

Parameters:: query_id (str) – The saved query’s ID.
Returns:: Saved query result.
Return type:: dict

class censys.asm.Seeds(api_key: str | None = None, **kwargs)[source]

Bases: CensysAsmAPI

Seeds API class.

add_seeds(seeds: list, force: bool | None = 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 = '/v1/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: str | None = None, label: str | None = None) → List[dict][source]

Requests seed data.

Parameters:

seed_type (str) – Optional; Seed type [‘IP_ADDRESS’, ‘DOMAIN_NAME’, ‘CIDR’, ‘ASN’].
label (str) – Optional; Seed label.

Returns:

Seed search results.

Return type:

List[dict]

replace_seeds_by_label(label: str, seeds: list, force: bool | None = 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

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

Bases: Assets

Subdomains Assets API class.

Requests assets data.

Override for subdomains due to it return value in a different key.

Parameters:

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.

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

Bases: Assets

Web Entities Assets API class.

get_assets(*args, **kwargs)[source]

Requests assets data.

This method is not implemented for web entities. Please see the inventory search and aggregation API.

Parameters:

*args – Variable length argument list.
**kwargs – Arbitrary keyword arguments.

Raises:

NotImplementedError – This method is not implemented.

get_instances(name_and_port: str, page_size: int | None = None, cursor: str | None = None) → Iterator[dict][source]

List all instances of the web entity.

Parameters:

name_and_port – (str): Web entity to query.
page_size (int) – Optional; Page size for retrieving assets.
cursor (str) – Optional; Cursor to use for pagination.

Yields:

dict – The assets result returned.

censys.asm.api module

Base for interacting with the Censys ASM API.

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

Bases: 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.