Cisco Umbrella Enforcement
Add and remove domains in Cisco OpenDNS.
Network Security · Cisco Umbrella Enforcement
Details
| ID | Cisco Umbrella Enforcement |
|---|---|
| Provider | Cisco Systems |
| Category | Network Security |
| From Version | 5.0.0 |
| Docker Image | demisto/python3:3.12.13.10116658 |
| Supported Modules | Agentix XSIAM |
README
Add and remove domains in Cisco OpenDNS.
This integration was integrated and tested with version 1.0 of Cisco Umbrella Enforcement.
Supported Cortex XSOAR versions: 5.0.0 and later.
Configure Cisco Umbrella Enforcement in Cortex
| Parameter | Description | Required |
|---|---|---|
| url | Server URL (e.g., https://example.net) | True |
| api_key | API Key | True |
| insecure | Trust any certificate (not secure) | False |
| proxy | Use system proxy settings | False |
Commands
You can execute these commands from the CLI, as part of an automation, or in a playbook.
After you successfully execute a command, a DBot message appears in the War Room with the command details.
umbrella-domain-event-add
Posts a malware event to the API for processing and optionally adding to a customer’s domain lists.
Base Command
umbrella-domain-event-add
Input
| Argument Name | Description | Required |
|---|---|---|
| alert_time | Alert time of the new event in datetime format, e.g., 2013-02-08T09:30:26.0Z. | Required |
| device_id | Device ID of the new event. | Required |
| destination_domain | Destination domain of the new event. | Required |
| destination_url | Destination URL of the new event. | Required |
| device_version | Device version for the new event. | Required |
| destination_ip | The destination IP address of the domain, specified in IPv4 dotted-decimal notation e.g., ‘8.8.8.8’. | Optional |
| event_severity | The partner threat level or rating, e.g., severe, bad, high, and so on. | Optional |
| event_type | Common name or classification of the threat. | Optional |
| event_description | Variant or other descriptor of the event type. | Optional |
| file_name | Path to the file exhibiting malicious behavior. | Optional |
| file_hash | SHA-1 of file reported by the appliance. | Optional |
| source | IP/Host of the infected computer/device that was patient 0 for the event. | Optional |
Context Output
There is no context output for this command.
Command Example
!umbrella-domain-event-add alert_time=2013-02-08T09:30:26.0Z device_id=ba6a58f4-e692-4724-ba36-c28132c761de destination_domain=test6.com device_version=13.7a destination_url=test6.com
Context Example
{}
Human Readable Output
New event was added successfully, The Event id is 31bb0adb,8f27,4423,a081-3b5773260f87.
umbrella-domains-list
List of domains.
Base Command
umbrella-domains-list
Input
| Argument Name | Description | Required |
|---|---|---|
| page | Number of page to return. Default is “1”. | Optional |
| limit | The maximum number of queries per page. Default is “50”. Default is 50. | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| UmbrellaEnforcement.Domains.name | String | Name of the domains. |
| UmbrellaEnforcement.Domains.id | Number | ID of the domains. |
| UmbrellaEnforcement.Domains.IsDeleted | Boolean | True if the domain has been deleted from list. |
Command Example
#### Context Example
```json
{
"UmbrellaEnforcement": {
"Domains": [
{
"IsDeleted": false,
"id": 3569571,
"name": "test6.com"
},
{
"IsDeleted": false,
"id": 3790609,
"name": "test7.com"
},
{
"IsDeleted": false,
"id": 3912159,
"name": "test8.com"
},
{
"IsDeleted": false,
"id": 3912161,
"name": "test9.com"
},
{
"IsDeleted": false,
"id": 54637170,
"name": "badinterner4.com"
}
]
}
}
Human Readable Output
List of Domains
id name 3569571 test6.com 3790609 test7.com 3912159 test8.com 3912161 test9.com 54637170 badinterner4.com
umbrella-domain-delete
Delete domain.
Base Command
umbrella-domain-delete
Input
| Argument Name | Description | Required |
|---|---|---|
| id | ID of the domain. | Optional |
| name | Name of the domain. | Optional |
Context Output
There is no context output for this command.
Command Example
!umbrella-domain-delete name=test6.com
Context Example
{}
Human Readable Output
test6.com domain was removed from block list
Configuration parameters
url— Server URL (e.g., https://example.net) (required)api_key— API Keycred_api_key—insecure— Trust any certificate (not secure)proxy— Use system proxy settings
Commands (3)
-
umbrella-domain-deleteDelete domain.
-
umbrella-domain-event-addPosts a malware event to the API for processing and optionally adding to a customer's domain lists.
-
umbrella-domains-listList of domains.
from CiscoUmbrellaEnforcement import prepare_suffix, Client def test_domains_list_suffix(): """Unit test Given - fetch incidents command - command args When - mock the Clients's get token function. - mock the Demisto's getIntegrationContext. - mock the set_shaping function. Then - run the fetch incidents command using the Client Validate when a day has passed since last update of shaping, Then the shaping will be checked again. Validate That the shaping is set to new shaping. """ page = "1" limit = "50" suffix = prepare_suffix(page=page, limit="") assert "page=1" in suffix suffix = prepare_suffix(page=page, limit=limit) assert "page=1" in suffix assert "limit=50" in suffix def test_domain_event_add_command_happy_path(mocker): """ Given: - All required and optional arguments for adding a new event. When: - Calling domain_event_add_command function. Then: - Ensure the function returns the expected result. """ from CiscoUmbrellaEnforcement import domain_event_add_command client = Client(base_url="https://test.com", api_key="123", verify=False, proxy=False) args = { "alert_time": "2022-01-01T00:00:00Z", "device_id": "1234", "destination_domain": "example.com", "destination_url": "https://example.com", "device_version": "1.0", "destination_ip": "1.1.1.1", "event_severity": "high", "event_type": "malware", "event_description": "test event", "file_name": "test.exe", "file_hash": "1234567890abcdef", "source": "test", } mocker.patch.object(client, "_http_request", return_value={"id": 123}) result = domain_event_add_command(client, args) assert result == "New event was added successfully, The Event id is 123." def test_domains_list_command_valid_input_params(mocker): """ Given: - Valid input parameters. When: - Calling domains_list_command function. Then: - Ensure the function returns the expected CommandResults object. """ from CiscoUmbrellaEnforcement import domains_list_command client = Client(base_url="https://test.com", api_key="123", verify=False, proxy=False) mocker.patch.object(client, "get_domains_list", return_value=[{"id": "1", "name": "test.com"}]) args = {"page": "1", "limit": "10"} results = domains_list_command(client, args) assert results.readable_output == "### List of Domains\n|id|name|\n|---|---|\n| 1 | test.com |\n" assert results.outputs_prefix == "UmbrellaEnforcement.Domains" assert results.outputs == [{"id": "1", "name": "test.com"}] def test_domain_delete_command_with_name(mocker): """ Given: - A domain name to delete. - A client object. When: - Calling the domain_delete_command function. Then: - Ensure the domain is deleted successfully. - Ensure the CommandResults object is returned with the correct readable_output and outputs. """ from CiscoUmbrellaEnforcement import domain_delete_command import demistomock as demisto from unittest.mock import Mock client_mock = Mock(Client) client_mock.delete_domains.return_value = Mock(status_code=204) mocker.patch.object(demisto, "dt", return_value={"name": "example.com", "IsDeleted": True}) args = {"name": "example.com"} result = domain_delete_command(client_mock, args) assert result.readable_output == "example.com domain was removed from blacklist" assert result.outputs_prefix == "UmbrellaEnforcement.Domains" assert result.outputs_key_field == "id" assert result.outputs == {"name": "example.com", "IsDeleted": True} def test_module_valid_api_key(mocker): """ Given: - Valid API key. When: - Running the 'test-module' command. Then: - Ensure the function returns 'ok'. """ from CiscoUmbrellaEnforcement import test_module client = Client(base_url="https://test.com/1.0/", api_key="valid_api_key", verify=True, proxy=False) mocker.patch.object(client, "get_domains_list", return_value=[{"id": "1", "name": "test.com"}]) mocker.patch.object(client, "_http_request", return_value={"data": [], "meta": {}}) mocker.patch.object(client, "add_event_to_domain", return_value={"id": "123"}) mocker.patch.object(client, "delete_domains", return_value={"status_code": 204}) assert test_module(client) == "ok" def test_umbrella_domain_event_add_valid_args(mocker): """ Given: - Valid arguments for the 'umbrella-domain-event-add' command. When: - Running the command. Then: - Ensure the function returns a confirmation message. """ import demistomock as demisto from CiscoUmbrellaEnforcement import main mocker.patch.object( demisto, "params", return_value={"url": "https://test.com", "cred_api_key": {"password": "valid_api_key"}} ) mocker.patch.object(demisto, "command", return_value="umbrella-domain-event-add") mocker.patch.object( demisto, "args", return_value={ "alert_time": "2022-01-01T00:00:00Z", "device_id": "123", "destination_domain": "example.com", "destination_url": "https://example.com", "device_version": "1.0", "destination_ip": "1.1.1.1", "event_severity": "high", "event_type": "malware", "event_description": "Malware detected", "file_name": "malware.exe", "file_hash": "1234567890abcdef", "source": "test", }, ) mocker.patch.object(Client, "add_event_to_domain", return_value={"id": "123"}) # mocker.patch('client.add_event_to_domain', return_value={'id': '123'}) mocker.patch.object(demisto, "results") main()