Cisco Umbrella Enforcement

Add and remove domains in Cisco OpenDNS.

Network Security · Cisco Umbrella Enforcement

Details

IDCisco Umbrella Enforcement
ProviderCisco Systems
CategoryNetwork Security
From Version5.0.0
Docker Imagedemisto/python3:3.12.13.10116658
Supported ModulesAgentix 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 Key
  • cred_api_key
  • insecure — Trust any certificate (not secure)
  • proxy — Use system proxy settings

Commands (3)

  • umbrella-domain-delete

    Delete domain.

  • umbrella-domain-event-add

    Posts a malware event to the API for processing and optionally adding to a customer's domain lists.

  • umbrella-domains-list

    List 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()