Stamus

[Get Declaration of Compromises from Stamus Security Platform and build Incidents. Then get related artifacts, events and Host Insight information].

Network Security · Stamus

Details

IDStamus
ProviderStamus Networks
CategoryNetwork Security
From Version6.9.0
Docker Imagedemisto/python3:3.12.13.10116658

README

[Get Declaration of Compromises from Stamus Security Platform and build Incidents. Then get related artifacts, events and Host Insight information]
This integration was integrated and tested with version 39.0.1 of Stamus Security Platform

Configure Stamus in Cortex

Parameter Description Required
Stamus Central Server   True
API Key The API Key to use for connection True
Trust any certificate (not secure)   False
Use system proxy settings   False
Incident type   False
Fetch incidents   False
Maximum number of incidents per fetch   False
First fetch time   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.

stamus-check-ioc


[Get events with IOC key/value filter]

Base Command

stamus-check-ioc

Input

Argument Name Description Required
indicator_key [Indicator of Compromise key]. Required
indicator_value [Indicator of Compromise value]. Required

Context Output

Path Type Description
StamusIntegration.IOC String [Fetch events matching an IOC.]
StamusIntegration.IOC.timestamp String [Timestamp of the event]
StamusIntegration.IOC.src_ip String [Source IP of the event]
StamusIntegration.IOC.dest_ip String [Destination IP of the event]
StamusIntegration.IOC.event_type String [Type of the event - can be multitude, example: HTTP,SMB,DNS,Flow,TLS,KRB5,FTP etc]

stamus-get-host-insight


[Get Host Insights information]

Base Command

stamus-get-host-insight

Input

Argument Name Description Required
ip [IP to get Host Insights information]. Required

Context Output

Path Type Description
StamusIntegration.HostInsights String [Fetch information about a host known by Host Insight module]
StamusIntegration.HostInsights.ip String [Stamus Host Insights IP address]
StamusIntegration.HostInsights.host_id.client_service.first_seen String [Timestamp of first time seen]
StamusIntegration.HostInsights.host_id.client_service String [Client network service detected]
StamusIntegration.HostInsights.host_id.services.proto String [Network services protocol]
StamusIntegration.HostInsights.host_id.services.port String [Network services port]
StamusIntegration.HostInsights.host_id.services.values.first_seen String [Network services for the corresponding application protocol first time seen]
StamusIntegration.HostInsights.host_id.services.values.last_seen String [Network services for the corresponding application protocol last time seen]
StamusIntegration.HostInsights.host_id.services.values.app_proto String [Network services application layer protocol]
StamusIntegration.HostInsights.host_id.services.services_count Number [Number of network services detected on the host]
StamusIntegration.HostInsights.host_id.client_service.name String [Type of client network service detected - can be HTTP,KRB5,TLS,DCERPC,SMB etc]
StamusIntegration.HostInsights.host_id.hostname.host String [Hostname detected on the host]
StamusIntegration.HostInsights.host_id.username.user String [Username detected loggin in on the host]
StamusIntegration.HostInsights.host_id.http.user_agent.agent String [HTTP User-Agent detected being used from the host]
StamusIntegration.HostInsights.host_id.tls.ja3.hash String [TLS JA3 hash detected being used from the host]
StamusIntegration.HostInsights.host_id.tls.ja3s.hash String [TLS JA3S hash detected being used from the host]

stamus-get-doc-events


[Get events for a Declaration of Compromise using the Stamus ID]

Base Command

stamus-get-doc-events

Input

Argument Name Description Required
id [Stamus ID used to get related information]. Required

Context Output

Path Type Description
StamusIntegration.RelatedEvents String [Get events for a Declaration of Compromise.]
StamusIntegration.RelatedEvents.timestamp String [Timestamp of the Stamus event]
StamusIntegration.RelatedEvents.stamus.asset String [Stamus asset]
StamusIntegration.RelatedEvents.offender String [Offender, against the Stamus asset]
StamusIntegration.RelatedEvents.killchain String [Killchain stage]
StamusIntegration.RelatedEvents.method String [Stamus method triggered]
StamusIntegration.RelatedEvents.info String [Extra Information]
StamusIntegration.RelatedEvents.src_ip String [Source IP of the event]
StamusIntegration.RelatedEvents.dest_ip String [Destination IP of the event]
StamusIntegration.RelatedEvents.app_proto String [Application protocol of the event]

Configuration parameters

  • url — Stamus Central Server (required)
  • credentials — (required)
  • insecure — Trust any certificate (not secure)
  • proxy — Use system proxy settings
  • incidentType — Incident type
  • incidentFetchInterval — Incidents Fetch Interval
  • isFetch — Fetch incidents
  • max_fetch — Maximum number of incidents per fetch
  • first_fetch — First fetch time

Commands (3)

  • stamus-check-ioc

    [Get events with IOC key/value filter].

  • stamus-get-doc-events

    [Get events for a Declaration of Compromise using the Stamus ID].

  • stamus-get-host-insight

    [Get Host Insights information].

import json


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


# TODO: ADD HERE unit tests for every command
def test_fetch_incidents(requests_mock):
    """
    Tests the fetch-incidents command function.

        Given:
            - requests_mock instance to generate the appropriate get_alert API response,
              loaded from a local JSON file.

        When:
            - Running the 'fetch_incidents' command.

        Then:
            - Checks the output of the command function with the expected output.
    """
    from Stamus import Client, fetch_incidents

    url = "https://stamus-test.com/rest/appliances/threat_history_incident/?timestamp=1689340848&page_size=200"
    mock_response = util_load_json("test_data/fetch_incidents.json")
    requests_mock.get(url, json=mock_response)

    client = Client(base_url="https://stamus-test.com", verify=False, headers={"Authentication": "Bearer some_api_key"})

    _, new_incidents = fetch_incidents(client=client, timestamp=1689340848)

    assert new_incidents == [
        {
            "name": "10.11.13.101_incident_0",
            "dbotMirrorId": "283115",
            "rawJSON": json.dumps(mock_response["results"][0]),
            "details": "description of my custom threat",
            "occurred": "2023-07-14T15:20:48.231617+02:00",
            "type": "ip",
        }
    ]


def test_fetch_by_ioc(requests_mock):
    """
    Given:
        - key/value to check.

    When:
        - Running the 'fetch_by_ioc'.

    Then:
        - Checks that results are the same than the ones built in tests.
    """
    from Stamus import Client, CommandResults, fetch_by_ioc, get_command_results, tableToMarkdown

    filter = ("src_ip", "10.7.5.101")
    url = f"https://stamus-test.com/rest/rules/es/events_tail/?qfilter={filter[0]}%3A{filter[1]}"
    mock_response = util_load_json("test_data/fetch_by_ioc.json")
    requests_mock.get(url, json=mock_response)

    client = Client(base_url="https://stamus-test.com", verify=False, headers={"Authentication": "Bearer some_api_key"})

    events = fetch_by_ioc(client, args={"indicator_key": filter[0], "indicator_value": filter[1]})
    results = mock_response.get("results", [])
    table = tableToMarkdown("IOC Matches", results, headers=["timestamp", "src_ip", "dest_ip", "event_type"])

    cmd_results = get_command_results(results, table, "IOC")

    for key in cmd_results.__dict__:
        assert cmd_results.__dict__.get(key) == events.__dict__.get(key)
    assert events.raw_response == mock_response["results"]
    assert isinstance(events, CommandResults)
    assert events.outputs_prefix == "StamusIntegration.IOC"


def test_fetch_events(requests_mock):
    """
    Given:
        - An id address to check.

    When:
        - Running the 'fetch_events'.

    Then:
        - Checks that results are the same than the ones built in tests.
    """
    from Stamus import Client, CommandResults, fetch_events, get_command_results, tableToMarkdown

    id_to_check = 3
    url = f"https://stamus-test.com/rest/appliances/threat_history_incident/{id_to_check}/get_events"
    mock_response = util_load_json("test_data/fetch_events.json")
    requests_mock.get(url, json=mock_response)

    client = Client(base_url="https://stamus-test.com", verify=False, headers={"Authentication": "Bearer some_api_key"})

    events = fetch_events(client, args={"id": id_to_check})
    results = mock_response.get("results", [])
    for result in results:
        result["method"] = result.get("alert", {}).get("signature", "algorithmic detection")
        result["info"] = ""
        if result.get("hostname_info"):
            result["info"] = f"Hostname: {result.get('hostname_info', {}).get('host', 'unknown')}"
        result["asset"] = result.get("stamus", {}).get("asset", "unknown")
        result["offender"] = result.get("stamus", {}).get("source", "unknown")
        result["killchain"] = result.get("stamus", {}).get("kill_chain", "unknown")
    headers = ["timestamp", "asset", "offender", "killchain", "method", "info", "src_ip", "dest_ip", "app_proto"]
    table = tableToMarkdown("Individual Events List", results, headers=headers)

    cmd_results = get_command_results(results, table, "RelatedEvents")

    for key in cmd_results.__dict__:
        assert cmd_results.__dict__.get(key) == events.__dict__.get(key)
    assert events.raw_response == mock_response["results"]
    assert isinstance(events, CommandResults)
    assert events.outputs_prefix == "StamusIntegration.RelatedEvents"


def test_fetch_host_id(requests_mock):
    """
    Given:
        - An ip address to check.

    When:
        - Running the 'fetch_host_id'.

    Then:
        - Checks that results are the same than the ones built in tests.
    """
    from Stamus import Client, CommandResults, fetch_host_id, get_command_results, linearize_host_id, tableToMarkdown

    ip = "217.116.0.227"
    url = f"https://stamus-test.com/rest/appliances/host_id/{ip}"
    mock_response = util_load_json("test_data/fetch_host_id.json")
    requests_mock.get(url, json=mock_response)

    client = Client(base_url="https://stamus-test.com", verify=False, headers={"Authentication": "Bearer some_api_key"})

    events = fetch_host_id(client, args={"ip": ip})
    results = mock_response
    headers = ["timestamp", "ip", "type", "value"]
    host_info = linearize_host_id(results)
    table = tableToMarkdown("Host Insight", host_info, headers=headers)

    cmd_results = get_command_results(results, table, "HostInsights")

    for key in cmd_results.__dict__:
        assert cmd_results.__dict__.get(key) == events.__dict__.get(key)
    assert cmd_results.readable_output == table
    assert cmd_results.outputs == results
    assert events.raw_response == results
    assert isinstance(events, CommandResults)
    assert events.outputs_prefix == "StamusIntegration.HostInsights"