Node Messaging Format

All Security Flow message objects passing between Nevelex Labs nodes conform to a common format to simplify message content navigation. The messages themselves are in JSON (JavaScript Object Notation). The following sections define the message formats used throughout the flows within Security Flow.

Plugin Node Messaging

DXL Request/Event Message

Typically, this is handled automatically by all nodes prefixed with "NL-DXL-*". However, direct use of the NL DXL Request Out or NL DXL Event Out nodes require the dxlTopic and dxlMsg attributes be set in the payload.

{
    "payload" : {
        "dxlTopic": "string",
        "dxlMsg": {
            "key1" : "value1",
            "key2" : "value2",
            ...
        }
    }
}

Success Response

If the plugin (PLUGIN_NAME) has a unique ID (UNIQUE_ID) associated with it, the success message has the following structure.

{
    "payload" : {
        "PLUGIN_NAME": {
            "UNIQUE_ID": {
                "action" : "[Optional, typically the operation performed] string",
                "topic" : "[Optional] string",
                "resource" : "[Optional, typically an IoC] string",
                "response": {
                    "key1" : "value1",
                    "key2" : "value2",
                    ...
                }
            }
        }
    }
}

If the plugin (PLUGIN_NAME) does not have a unique ID associated with it, the success message has the following structure.

{
    "payload" : {
        "PLUGIN_NAME": {
            "action" : "[Optional, typically the operation performed] string",
            "topic" : "[Optional] string",
            "resource" : "[Optional, typically an IoC] string",
            "response": {
                "key1" : "value1",
                "key2" : "value2",
                ...
            }
        }
    }
}

Error Response

If the plugin (PLUGIN_NAME) has a unique ID (UNIQUE_ID) associated with it, the error message has the following structure.

{
    "payload" : {
        "PLUGIN_NAME": {
            "UNIQUE_ID": {
                "action" : "[Optional, typically the operation performed] string",
                "topic" : "[Optional] string",
                "resource" : "[Optional, typically an IoC] string",
                "error": {
                    "error_code": [number],
                    "error_message" : "string"
                }
            }   
        }   
    }   
}

If the plugin (PLUGIN_NAME) does not have a unique ID associated with it, the error message has the following structure.

{
    "payload" : {
        "PLUGIN_NAME": {
            "action" : "[Optional, typically the operation performed] string",
            "topic" : "[Optional] string",
            "resource" : "[Optional, typically an IoC] string",
            "error": {
                "error_code": [number],
                "error_message" : "string"
            }
        }
    }
}

Success Example

The following shows a sample VirusTotal URL report that does not have a unique ID.

{
    "payload": {
        "virustotal": {
            "action": "url-report",
            "topic": "/nevelexlabs/service/virustotal/url/report",
            "resource": "http://some.random.url/", 
            "response": {
                "url": "http://some.random.url/",
                "scans": {},
                ...
                "total": 68,
                "positives": 3,
                "scan_date": "2018-09-14 19:42:34",
                "verbose_msg": "Scan finished, scan information embedded in this object",
                "response_code": 1
            },
        }
    }
}