FeedSOCRadarThreatFeed

Retrieve indicators provided by collections via SOCRadar Threat Intelligence Feeds.

Data Enrichment & Threat Intelligence · SOCRadar ThreatFeed · Feed

Details

IDFeedSOCRadarThreatFeed
ProviderSOCRadar
CategoryData Enrichment & Threat Intelligence
From Version6.0.0
Docker Imagedemisto/python3:3.12.13.11879924
Supported ModulesAgentix XSIAM

README

Retrieve indicators provided by collections via SOCRadar Threat Intelligence Feeds.
This integration was integrated and tested with v21.11 of SOCRadar.

Configure SOCRadar Threat Feed on Cortex XSOAR

  1. Navigate to Settings > Integrations > Servers & Services.
  2. Search for SOCRadarThreatFeed.
  3. Click Add instance to create and configure a new integration instance.

    Parameter Description Required
    API Key The API Key to use for connection to SOCRadar ThreatFusion API. True
    insecure Trust any certificate (not secure). False
    proxy Whether to use XSOAR’s system proxy settings to connect to the API. False
    Feed Name The feed name(s) to fetch. True
    Fetch indicators Whether to fetch indicators. False
    Indicator Reputation Indicators from this integration instance will be marked with this reputation. False
    Traffic Light Protocol Color The Traffic Light Protocol (TLP) designation to apply to indicators fetched from the feed. False
    Tags Supports CSV values. False
    Source Reliability Reliability of the source providing the intelligence data. True
    Feed Fetch Interval The feed fetch interval. False
    Bypass exclusion list When selected, the exclusion list is ignored for indicators from this feed. This means that if an indicator from this feed is on the exclusion list, the indicator might still be added to the system. False
  4. Click Test to validate API key and connection to SOCRadar Threat Feeds/IOC API.

Commands

You can execute these commands from the Cortex XSOAR 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.

How to obtain SOCRadar Threat Feeds/IOC API key?

Every company has a unique API key in SOCRadar platform. This API key can be used to benefit from
various API endpoints that SOCRadar provides.

For the information about the SOCRadar API keys and how to obtain them, please see SOCRadar API documentation.

socradar-get-indicators


Retrieves SOCRadar Recommended Threat Intelligences Collections.

Base Command

socradar-get-indicators

Input

Argument Name Description Required
collections_to_fetch Names of the collections that intended to be retrieved indicators from. Required
limit The maximum number of indicators to retrieve. Optional

Context Output

Path Type Description
SOCRadarThreatFeed.Indicators[0].Indicator String The value of the indicator.
SOCRadarThreatFeed.Indicators[0].Indicator Type String The type of the indicator.
SOCRadarThreatFeed.Indicators[0].Feed Maintainer Name String Name of the maintainer that the indicator found from.
SOCRadarThreatFeed.Indicators[0].First Seen Date Date The date that the indicator was in SOCRadar collections for the first time.
SOCRadarThreatFeed.Indicators[0].Last Seen Date Date The latest date that the indicator was seen in SOCRadar collections.
SOCRadarThreatFeed.Indicators[0].Seen Count Number The feed description.
SOCRadarThreatFeed.Indicators[0].rawJSON JSON Raw JSON object that contains the value and type of the indicator.
SOCRadarThreatFeed.Indicators[0].Geo Location.ASN Number ASN field Geographical location information of the IP type indicator.
SOCRadarThreatFeed.Indicators[0].Geo Location.AsnCode Number ASN code field Geographical location information of the IP type indicator.
SOCRadarThreatFeed.Indicators[0].Geo Location.AsnName String ASN name field Geographical location information of the IP type indicator.
SOCRadarThreatFeed.Indicators[0].Geo Location.Cidr String CIDR field Geographical location information of the IP type indicator.
SOCRadarThreatFeed.Indicators[0].Geo Location.CityName String City name field Geographical location information of the IP type indicator.
SOCRadarThreatFeed.Indicators[0].Geo Location.CountryCode String Country code field Geographical location information of the IP type indicator.
SOCRadarThreatFeed.Indicators[0].Geo Location.CountryName String Country name field Geographical location information of the IP type indicator.
SOCRadarThreatFeed.Indicators[0].Geo Location.Latitude Number Latitude field Geographical location information of the IP type indicator.
SOCRadarThreatFeed.Indicators[0].Geo Location.Longitude Number Longitude field Geographical location information of the IP type indicator.
SOCRadarThreatFeed.Indicators[0].Geo Location.RegionName String Region name field Geographical location information of the IP type indicator.
SOCRadarThreatFeed.Indicators[0].Geo Location.Timezone String Timezone field Geographical location information of the IP type indicator.
SOCRadarThreatFeed.Indicators[0].Geo Location.ZipCode String Zip code field Geographical location information of the IP type indicator.

Command Example

!socradar-get-indicators collections_to_fetch="SOCRadar-APT-Recommended-Block-Domain" limit=2

Context Example

{
    "SOCRadarThreatFeed": {
        "Indicators": [
            {
              "Feed Maintainer Name": "SOCRadar-APT Feed",
              "First Seen Date": "2021-07-15 07:04:29",
              "Indicator": "dump-indicator.domain", 
              "Indicator Type": "Domain", 
              "Last Seen Date": "2021-07-16 07:04:49",
              "Seen Count": 2,
              "rawJSON": {
                   "value": "dump-indicator.domain",
                   "type": "Domain"  
              }   
            },
            {
              "Feed Maintainer Name": "SOCRadar-APT Feed",
              "First Seen Date": "2021-07-15 07:04:29",
              "Indicator": "yet-another-dump-indicator.domain", 
              "Indicator Type": "Domain", 
              "Last Seen Date": "2021-07-16 07:04:49",
              "Seen Count": 2,
              "rawJSON": {
                   "value": "yet-another-dump-indicator.domain",
                   "type": "Domain"  
              }   
            }
        ]
    }
}

Human Readable Output

Indicators from SOCRadar ThreatFeed Collections (SOCRadar-APT-Recommended-Block-Domain)

Feed Maintainer Name First Seen Date Indicator Indicator Type Last Seen Date Seen Count
SOCRadar-APT Feed 2021-07-15 07:04:29 dump-indicator.domain Domain 2021-07-16 07:04:49 2
SOCRadar-APT Feed 2021-07-15 07:04:29 yet-another-dump-indicator.domain Domain 2021-07-16 07:04:49 2

socradar-reset-fetch-indicators


Resets the indicator fetch history.

Base Command

socradar-reset-fetch-indicators

Input

There are no input arguments for this command.

Context Output

There is no context output for this command.

Command Example

!socradar-reset-fetch-indicators

Human Readable Output

Fetch history has been successfully deleted!

Configuration parameters

  • apikey — API Key (required)
  • insecure — Trust any certificate (not secure)
  • proxy — Use system proxy settings
  • collections_to_fetch — Feed Name (required)
  • feed — Fetch indicators
  • feedReputation — Indicator Reputation
  • feedReliability — Source Reliability (required)
  • feedExpirationPolicy
  • feedExpirationInterval
  • feedFetchInterval — Feed Fetch Interval
  • feedBypassExclusionList — Bypass exclusion list
  • tlp_color — Traffic Light Protocol Color
  • feedTags — Tags
  • feedIncremental — Incremental Feed

Commands (2)

  • socradar-get-indicators

    Retrieves SOCRadar Recommended Threat Intelligences Collections.

  • socradar-reset-fetch-indicators

    Resets the indicator fetch history.

import json

import pytest
from CommonServerPython import CommandResults, DemistoException, FeedIndicatorType

SOCRADAR_API_ENDPOINT = "https://platform.socradar.com/api"


def util_load_json(path):
    with open(path, encoding="utf-8") as f:
        return json.loads(f.read())


def test_test_module(requests_mock):
    """Tests the test_module validation command."""
    from FeedSOCRadarThreatFeed import Client, test_module

    mock_socradar_api_key = "APIKey"
    auth_suffix = f"threat/intelligence/check/auth?key={mock_socradar_api_key}"
    mock_response = util_load_json("test_data/check_auth_response.json")
    requests_mock.get(f"{SOCRADAR_API_ENDPOINT}/{auth_suffix}", json=mock_response)

    collection_name_list = ["MockCollectionName"]
    indicator_suffix = (
        f"threat/intelligence/socradar_collections?key={mock_socradar_api_key}"
        f"&collection_names={collection_name_list[0]}"
        f"&limit=1"
        f"&offset=0"
    )
    mock_response = util_load_json("test_data/get_indicators_response.json")
    requests_mock.get(f"{SOCRADAR_API_ENDPOINT}/{indicator_suffix}", json=mock_response)

    client = Client(
        base_url=SOCRADAR_API_ENDPOINT, api_key=mock_socradar_api_key, tlp_color="", tags="", verify=False, proxy=False
    )

    response = test_module(client, collection_name_list)

    assert response == "ok"


def test_test_module_handles_authorization_error(requests_mock):
    """Tests the test_module validation command authorization error."""
    from FeedSOCRadarThreatFeed import MESSAGES, Client, test_module

    mock_socradar_api_key = "WrongAPIKey"
    suffix = f"threat/intelligence/check/auth?key={mock_socradar_api_key}"
    mock_response = util_load_json("test_data/check_auth_response_auth_error.json")
    requests_mock.get(f"{SOCRADAR_API_ENDPOINT}/{suffix}", json=mock_response, status_code=401)
    client = Client(
        base_url=SOCRADAR_API_ENDPOINT, api_key=mock_socradar_api_key, tlp_color="", tags="", verify=False, proxy=False
    )
    with pytest.raises(DemistoException, match=MESSAGES["AUTHORIZATION_ERROR"]):
        test_module(client, [])


def test_fetch_indicators(requests_mock):
    """Tests the fetch-indicators function.

    Configures requests_mock instance to generate the appropriate
    SOCRadar Threat Intelligence Collections API response, loaded from a local JSON file. Checks
    the output of the command function with the expected output.
    """
    from FeedSOCRadarThreatFeed import Client, fetch_indicators

    mock_socradar_api_key = "APIKey"
    mock_response = util_load_json("test_data/fetch_indicators_response.json")
    suffix = f"threat/intelligence/socradar_collections?key={mock_socradar_api_key}&collection_names=MockCollectionName"
    requests_mock.get(f"{SOCRADAR_API_ENDPOINT}/{suffix}", json=mock_response)

    client = Client(
        base_url=SOCRADAR_API_ENDPOINT, api_key=mock_socradar_api_key, tlp_color="GREEN", tags=["TEST"], verify=False, proxy=False
    )

    collections_to_fetch = ["MockCollectionName"]

    indicators = fetch_indicators(client=client, collections_to_fetch=collections_to_fetch, limit=1)

    expected_output = util_load_json("test_data/fetch_indicators_expected_output.json")

    assert indicators == expected_output
    assert len(indicators) == 1


def test_fetch_indicators_handles_error(requests_mock):
    """Tests the fetch_indicators function.

    Configures requests_mock instance to generate the appropriate
    SOCRadar SOCRadar Threat Intelligence Collections API response, loaded from a local JSON file. Checks
    the output of the command function with the expected output.
    """
    from FeedSOCRadarThreatFeed import Client, fetch_indicators

    mock_socradar_api_key = "APIKey"
    mock_response = util_load_json("test_data/fetch_indicators_response_error.json")
    suffix = f"threat/intelligence/socradar_collections?key={mock_socradar_api_key}&collection_names=MockCollectionName"
    requests_mock.get(f"{SOCRADAR_API_ENDPOINT}/{suffix}", json=mock_response)

    client = Client(
        base_url=SOCRADAR_API_ENDPOINT, api_key=mock_socradar_api_key, tlp_color="GREEN", tags=["TEST"], verify=False, proxy=False
    )

    collections_to_fetch = ["MockCollectionName"]
    indicators = fetch_indicators(client=client, collections_to_fetch=collections_to_fetch, limit=1)
    assert len(indicators) == 0


def test_get_indicators_command(requests_mock):
    """Tests the get_indicators_command function.

    Configures requests_mock instance to generate the appropriate
    SOCRadar Threat Intelligence Collections API response, loaded from a local JSON file. Checks
    the output of the command function with the expected output.
    """
    from FeedSOCRadarThreatFeed import Client, get_indicators_command

    mock_socradar_api_key = "APIKey"
    mock_response = util_load_json("test_data/get_indicators_response.json")
    suffix = f"threat/intelligence/socradar_collections?key={mock_socradar_api_key}&collection_names=MockCollectionName"
    requests_mock.get(f"{SOCRADAR_API_ENDPOINT}/{suffix}", json=mock_response)

    client = Client(
        base_url=SOCRADAR_API_ENDPOINT, api_key=mock_socradar_api_key, tlp_color="GREEN", tags=["TEST"], verify=False, proxy=False
    )

    mock_args = {"limit": 1, "collections_to_fetch": "MockCollectionName"}

    result = get_indicators_command(client, mock_args)

    expected_output = util_load_json("test_data/get_indicators_expected_output.json")
    expected_context = util_load_json("test_data/get_indicators_expected_context.json")

    assert isinstance(result, CommandResults)
    assert "Indicators from SOCRadar ThreatFeed Collections (MockCollectionName):" in result.readable_output
    assert result.outputs == expected_context
    assert result.raw_response == expected_output


def test_get_indicators_command_handles_error(requests_mock):
    """Tests the get_indicators_command function.

    Configures requests_mock instance to generate the appropriate
    SOCRadar SOCRadar Threat Intelligence Collections API response, loaded from a local JSON file. Checks
    the output of the command function with the expected output.
    """
    from FeedSOCRadarThreatFeed import Client, get_indicators_command

    mock_socradar_api_key = "APIKey"
    mock_response = util_load_json("test_data/get_indicators_response_error.json")
    suffix = f"threat/intelligence/socradar_collections?key={mock_socradar_api_key}&collection_names=MockCollectionName"
    requests_mock.get(f"{SOCRADAR_API_ENDPOINT}/{suffix}", json=mock_response)

    client = Client(
        base_url=SOCRADAR_API_ENDPOINT, api_key=mock_socradar_api_key, tlp_color="GREEN", tags=["TEST"], verify=False, proxy=False
    )
    mock_args = {"limit": 1, "collections_to_fetch": "MockCollectionName"}
    result = get_indicators_command(client, mock_args)
    assert isinstance(result, CommandResults)
    assert len(result.outputs) == 0


def test_date_string_to_iso_format_parsing():
    """Tests the date_string_to_iso_format_parsing function."""
    from FeedSOCRadarThreatFeed import date_string_to_iso_format_parsing

    mock_date_str = "1111-11-11 11:11:11"
    formatted_date = date_string_to_iso_format_parsing(mock_date_str)

    assert formatted_date


def test_build_entry_context():
    """Tests the build_entry_context function."""
    from FeedSOCRadarThreatFeed import build_entry_context

    mock_indicators = util_load_json("test_data/build_entry_context_input.json")
    context_entry = build_entry_context(mock_indicators)
    expected_context_entry = util_load_json("test_data/build_entry_context_expected_entry.json")

    assert context_entry == expected_context_entry


def test_reset_last_fetch_dict():
    """Tests the reset_last_fetch_dict function."""
    from FeedSOCRadarThreatFeed import reset_last_fetch_dict

    result = reset_last_fetch_dict()

    assert isinstance(result, CommandResults)
    assert "Fetch history has been successfully deleted!" in result.readable_output


CONVERT_DEMISTO_INDICATOR_TYPE_INPUTS = [
    ("hostname", FeedIndicatorType.Domain),
    ("url", FeedIndicatorType.URL),
    ("ip", FeedIndicatorType.IP),
    ("hash", FeedIndicatorType.File),
]


@pytest.mark.parametrize("socradar_indicator_type, demisto_indicator_type", CONVERT_DEMISTO_INDICATOR_TYPE_INPUTS)
def test_convert_to_demisto_indicator_type(socradar_indicator_type, demisto_indicator_type):
    from FeedSOCRadarThreatFeed import convert_to_demisto_indicator_type

    assert convert_to_demisto_indicator_type(socradar_indicator_type) == demisto_indicator_type