UBIRCH

Details

ID	`UBIRCH`
Provider	UBIRCH GmbH
Category	Data Enrichment & Threat Intelligence
From Version	5.5.0
Docker Image	`demisto/py3-tools:1.0.0.114656`
Supported Modules	Agentix XSIAM

README

The UBIRCH solution can be seen as an external data certification provider, as a data notary service, giving data receivers the capability to verify data they have received with regard to its authenticity and integrity and correctness of sequence.
This integration was integrated and tested with version v1.0.0 of UBIRCH

Configure UBIRCH in Cortex

Parameter	Description	Required
url	Your MQTT host name	True
port	port	True
credentials	Username	True
longRunning	Long running instance	False
tenantId	Tenant Id	True
stage	Stage	True

Usage

The UBIRCH integration is a long-running implementation. Whenever a verification of ubirched data fails, the incident is created with the following fields:

Field	Type	Description
name	string	Name of the incident to be created.
type	string	Type of the incident to be created. If not provided, the value of the integration parameter *Incident type* will be used.
labels	object	RequestId and deviceId of the incident to be created. For example, `[{"type":"requestId", "value":"94a55743-d285-487a-839f-3005f3f8854a"}, {"type":"hwDeviceId", "value":"ba70ad8b-a564-4e58-9a3b-224ac0f0153f"}]`
severity	string	Severity level of the incident. levels are Critical, High, Medium, Low, Unknown.
occurred	string	Date the incident occurred in ISO-8601 format.
details	object	Details of the incident to be created. For example, `{"field1":"value1","field2":"value2"}`
raw_json	object	Details of the incident to be created. For example, `{"field1":"value1","field2":"value2"}`

The incidents are based on these errors written in this page.

The error codes, NA401 - 4000, have a severity type HIGH because it may indicate that someone is trying to get authorization in an invalid manner OR that our ThingAPI is acting up.
The error codes, ND403 - 1200, have a severity type HIGH because this error would likely mean that the UPP is corrected in some way, which can be a red flag.
The error codes, ND400 - 2300, have a severity type MEDIUM as if the payload of a UPP is null, then no Hash can be processed. This is of course controlled, but it is very strange if the UPP is empty.
The rest of the errors have a severity type UNKNOWN.

create-sample-incidents

Create a list of sample incidents.

Base Command

create-sample-incidents

Input

There are no input arguments for this command.

Context Output

There is no context output for this command.

Configuration parameters

url — Your MQTT host name (required)
port — Port (required)
credentials — Username (required)
longRunning — Long running instance
tenant_id — Tenant Id (required)
stage — Stage (required)

Commands (1)

create-sample-incidents
Create a list of sample incidents.

Source

UBIRCH.py UBIRCH_test.py UBIRCH.yml UBIRCH_description.md

Download History Raw

from UBIRCH import (
    AUTHENTICATION_TYPE,
    AUTHENTICITY_TYPE,
    HIGH_SEVERITY,
    LOW_SEVERITY,
    SEQUENCE_TYPE,
    create_incidents,
    get_error_definition,
)


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


def test_get_error_definition() -> None:
    """Test get_severity function.

    Checks the severity is the expected one.

    No mock is needed here.
    """
    incident_auth_1000 = {"errorCode": "1000", "microservice": "niomon-auth"}
    error_definition_auth_1000 = {
        "meaning": "Authentication error: request malformed. Possible missing header and parameters.",
        "severity": LOW_SEVERITY,
        "type": AUTHENTICATION_TYPE,
    }
    incident_decoder_1300 = {"errorCode": "1300", "microservice": "niomon-decoder"}
    error_definition_decoder_1300 = {
        "meaning": "Invalid verification: signature verification failed. No public key or integrity is compromised.",
        "severity": HIGH_SEVERITY,
        "type": AUTHENTICITY_TYPE,
    }
    incident_enricher_0000 = {"errorCode": "0000", "microservice": "niomon-enricher"}
    error_definition_enricher_0000 = {
        "meaning": "Tenant error: the owner of the device does not exist or cannot be acquired (3rd Party).",
        "severity": HIGH_SEVERITY,
        "type": AUTHENTICITY_TYPE,
    }
    incident_filter_0000 = {"errorCode": "0000", "microservice": "filter-service"}
    error_definition_filter_0000 = {
        "meaning": "Integrity violation: duplicate hash detected. Possible injection, reply attack, or hash collision. ",
        "severity": HIGH_SEVERITY,
        "type": SEQUENCE_TYPE,
    }
    error_definition_unknown = {}
    incident_unknown1 = {}
    incident_unknown2 = {"errorCode": "1000", "microservice": "niomon"}
    incident_unknown3 = {"errorCode": "5000", "microservice": "niomon-auth"}

    assert get_error_definition(incident_auth_1000) == error_definition_auth_1000
    assert get_error_definition(incident_decoder_1300) == error_definition_decoder_1300
    assert get_error_definition(incident_enricher_0000) == error_definition_enricher_0000
    assert get_error_definition(incident_filter_0000) == error_definition_filter_0000
    assert get_error_definition(incident_unknown1) == error_definition_unknown
    assert get_error_definition(incident_unknown2) == error_definition_unknown
    assert get_error_definition(incident_unknown3) == error_definition_unknown


def test_create_incidents() -> None:
    """Test create_incidents function.

    Checks the incidents is the expected one.

    No mock is needed here.
    """
    ERROR_MESSAGE = util_load_json("test_data/raw_json_error_message.json")
    incidents = create_incidents(ERROR_MESSAGE)
    assert incidents == INCIDENT_RESPONSE


INCIDENT_RESPONSE = [
    {
        "name": "Invalid verification: signature verification failed. No public key or integrity is compromised.",
        "type": "UBIRCH Authenticity",
        "labels": [
            {"type": "requestId", "value": "ec15d266-5822-4fa5-ba82-64f1653d46a4"},
            {"type": "hwDeviceId", "value": "ba70ad8b-a564-4e58-9a3b-224ac0f0153f"},
        ],
        "rawJSON": '{"requestId": "ec15d266-5822-4fa5-ba82-64f1653d46a4", "hwDeviceId": '
        '"ba70ad8b-a564-4e58-9a3b-224ac0f0153f", "errorCode": "1300", "error": "SignatureException: Invalid '
        'signature", "microservice": "niomon-decoder", "timestamp": "2021-01-07T18:47:52.025Z"}',
        "details": '{"requestId": "ec15d266-5822-4fa5-ba82-64f1653d46a4", "hwDeviceId": '
        '"ba70ad8b-a564-4e58-9a3b-224ac0f0153f", "errorCode": "1300", "error": "SignatureException: Invalid '
        'signature", "microservice": "niomon-decoder", "timestamp": "2021-01-07T18:47:52.025Z"}',
        "severity": HIGH_SEVERITY,
    }
]