Cisco Umbrella Integration¶
Overview¶
This integration allows you to connect to Cisco Umbrella (Investigate API) to query domain and IP reputation, manage domain block lists, and retrieve related domain information.
Configuration¶
To configure this integration within the SOAR platform, you typically need the following Cisco Umbrella Investigate API details:
API Token: Your Cisco Umbrella Investigate API token.
(Note: The exact parameter names might vary slightly depending on the specific SOAR platform configuration interface.)
Actions¶
Get Whois¶
Get domain WhoIs details.
Arguments:
case_id(string, required): The ID of the case.alert_group_identifiers(List[string], required): Identifiers for the alert groups.target_entities(List[TargetEntity], optional): Optional list of specific target entities (Identifier, EntityType) to run the action on. Supports Domain and Hostname entities.scope(string, optional): Defines the scope for the action. Defaults to “All entities”.
Returns:
dict: A dictionary containing the WHOIS information for the specified domain(s).
Add Domain¶
Add domain to the OpenDNS block list (specifically, the Umbrella default block list associated with the API key’s organization).
Arguments:
case_id(string, required): The ID of the case.alert_group_identifiers(List[string], required): Identifiers for the alert groups.target_entities(List[TargetEntity], optional): Optional list of specific target entities (Identifier, EntityType) to run the action on. Supports Domain and Hostname entities.scope(string, optional): Defines the scope for the action. Defaults to “All entities”.
Returns:
dict: A dictionary containing the result of the block operation.
Get Domain Security Info¶
Provide security information about a domain (as an attachment).
Arguments:
case_id(string, required): The ID of the case.alert_group_identifiers(List[string], required): Identifiers for the alert groups.target_entities(List[TargetEntity], optional): Optional list of specific target entities (Identifier, EntityType) to run the action on. Supports Domain and Hostname entities.scope(string, optional): Defines the scope for the action. Defaults to “All entities”.
Returns:
dict: A dictionary containing the result, typically including a file attachment with security details.
Get Domain Status¶
Provide domain status, its content categories, and security categories. Supported entities: Hostname, URL.
Arguments:
case_id(string, required): The ID of the case.alert_group_identifiers(List[string], required): Identifiers for the alert groups.target_entities(List[TargetEntity], optional): Optional list of specific target entities (Identifier, EntityType) to run the action on. Supports Hostname and URL entities (domain is extracted from URL).scope(string, optional): Defines the scope for the action. Defaults to “All entities”.
Returns:
dict: A dictionary containing the status and categorization for the specified domain(s).
Get Associated Domains¶
Get associated domains for a particular hostname (domain).
Arguments:
case_id(string, required): The ID of the case.alert_group_identifiers(List[string], required): Identifiers for the alert groups.target_entities(List[TargetEntity], optional): Optional list of specific target entities (Identifier, EntityType) to run the action on. Supports Domain and Hostname entities.scope(string, optional): Defines the scope for the action. Defaults to “All entities”.
Returns:
dict: A dictionary containing domains associated (e.g., co-occurring, related) with the input domain(s).
Ping¶
Test Connectivity to Cisco Umbrella Investigate API.
Arguments:
case_id(string, required): The ID of the case.alert_group_identifiers(List[string], required): Identifiers for the alert groups.target_entities(List[TargetEntity], optional): Optional list of specific target entities (Identifier, EntityType) to run the action on.scope(string, optional): Defines the scope for the action. Defaults to “All entities”.
Returns:
dict: A dictionary containing the result of the ping action.
Delete Domain¶
Delete domain from the OpenDNS block list (specifically, the Umbrella default block list associated with the API key’s organization).
Arguments:
case_id(string, required): The ID of the case.alert_group_identifiers(List[string], required): Identifiers for the alert groups.target_entities(List[TargetEntity], optional): Optional list of specific target entities (Identifier, EntityType) to run the action on. Supports Domain and Hostname entities.scope(string, optional): Defines the scope for the action. Defaults to “All entities”.
Returns:
dict: A dictionary containing the result of the deletion operation.
Get Malicious Domains¶
Get malicious domains associated with an IP address.
Arguments:
case_id(string, required): The ID of the case.alert_group_identifiers(List[string], required): Identifiers for the alert groups.target_entities(List[TargetEntity], optional): Optional list of specific target entities (Identifier, EntityType) to run the action on. Supports IP Address entities.scope(string, optional): Defines the scope for the action. Defaults to “All entities”.
Returns:
dict: A dictionary containing the list of malicious domains associated with the specified IP address(es).
Notes¶
Ensure the Cisco Umbrella integration is properly configured in the SOAR Marketplace tab with a valid Investigate API Token.
The API token requires appropriate permissions within Cisco Umbrella Investigate.
Blocking/Unblocking actions (
Add Domain,Delete Domain) typically affect the default block list for the organization tied to the API token.