Send security messages SDK

Article
03/28/2022

This how-to guide explains the Defender for IoT service capabilities when you choose to collect and send your device security messages without using a Defender for IoT agent, and explains how to do so.

In this guide, you learn how to:

Send security messages using the Azure IoT C SDK
Send security messages using the Azure IoT C# SDK
Send security messages using the Azure IoT Python SDK
Send security messages using the Azure IoT Node.js SDK
Send security messages using the Azure IoT Java SDK

Defender for IoT capabilities

Defender for IoT can process and analyze any kind of security message data as long as the data sent conforms to the Defender for IoT schema and the message is set as a security message.

Security message

Defender for IoT defines a security message using the following criteria:

If the message was sent with Azure IoT SDK
If the message conforms to the security message schema
If the message was set as a security message prior to sending

Each security message includes the metadata of the sender such as AgentId, AgentVersion, MessageSchemaVersion and a list of security events. The schema defines the valid and required properties of the security message including the types of events.

Note

Messages sent that do not comply with the schema are ignored. Make sure to verify the schema before initiating sending data as ignored messages are not currently stored.

Note

Messages sent that were not set as a security message using the Azure IoT SDK will not be routed to the Defender for IoT pipeline.

Valid message example

The example below shows a valid security message object. The example contains the message metadata and one ProcessCreate security event.

Once set as a security message and sent, this message will be processed by Defender for IoT.

"AgentVersion": "0.0.1",
"AgentId": "e89dc5f5-feac-4c3e-87e2-93c16f010c25",
"MessageSchemaVersion": "1.0",
"Events": [
    {
        "EventType": "Security",
        "Category": "Triggered",
        "Name": "ProcessCreate",
        "IsEmpty": false,
        "PayloadSchemaVersion": "1.0",
        "Id": "21a2db0b-44fe-42e9-9cff-bbb2d8fdf874",
        "TimestampLocal": "2019-01-27 15:48:52Z",
        "TimestampUTC": "2019-01-27 13:48:52Z",
        "Payload":
            [
                {
                    "Executable": "/usr/bin/myApp",
                    "ProcessId": 11750,
                    "ParentProcessId": 1593,
                    "UserName": "aUser",
                    "CommandLine": "myApp -a -b"
                }
            ]
    }
]

Send security messages

Send security messages without using Defender for IoT agent, by using the Azure IoT C device SDK, Azure IoT C# device SDK, Azure IoT Node.js SDK, Azure IoT Python SDK, or Azure IoT Java SDK.

To send the device data from your devices for processing by Defender for IoT, use one of the following APIs to mark messages for correct routing to Defender for IoT processing pipeline.

All data that is sent, even if marked with the correct header, must also comply with the Defender for IoT message schema.

Send security message API

The Send security messages API is currently available in C and C#, Python, Node.js, and Java.

C API

bool SendMessageAsync(IoTHubAdapter* iotHubAdapter, const void* data, size_t dataSize) {

    bool success = true;
    IOTHUB_MESSAGE_HANDLE messageHandle = NULL;

    messageHandle = IoTHubMessage_CreateFromByteArray(data, dataSize);

    if (messageHandle == NULL) {
        success = false;
        goto cleanup;
    }

    if (IoTHubMessage_SetAsSecurityMessage(messageHandle) != IOTHUB_MESSAGE_OK) {
        success = false;
        goto cleanup;
    }

    if (IoTHubModuleClient_SendEventAsync(iotHubAdapter->moduleHandle, messageHandle, SendConfirmCallback, iotHubAdapter) != IOTHUB_CLIENT_OK) {
        success = false;
        goto cleanup;
    }

cleanup:
    if (messageHandle != NULL) {
        IoTHubMessage_Destroy(messageHandle);
    }

    return success;
}

static void SendConfirmCallback(IOTHUB_CLIENT_CONFIRMATION_RESULT result, void* userContextCallback) {
    if (userContextCallback == NULL) {
        //error handling
        return;
    }

    if (result != IOTHUB_CLIENT_CONFIRMATION_OK){
        //error handling
    }
}

C# API


private static async Task SendSecurityMessageAsync(string messageContent)
{
    ModuleClient client = ModuleClient.CreateFromConnectionString("<connection_string>");
    Message  securityMessage = new Message(Encoding.UTF8.GetBytes(messageContent));
    securityMessage.SetAsSecurityMessage();
    await client.SendEventAsync(securityMessage);
}

Node.js API

var Protocol = require('azure-iot-device-mqtt').Mqtt

function SendSecurityMessage(messageContent)
{
  var client = Client.fromConnectionString(connectionString, Protocol);

  var connectCallback = function (err) {
    if (err) {
      console.error('Could not connect: ' + err.message);
    } else {
      var message = new Message(messageContent);
      message.setAsSecurityMessage();
      client.sendEvent(message);
  
      client.on('error', function (err) {
        console.error(err.message);
      });
  
      client.on('disconnect', function () {
        clearInterval(sendInterval);
        client.removeAllListeners();
        client.open(connectCallback);
      });
    }
  };

  client.open(connectCallback);
}

Python API

To use the Python API you need to install the package azure-iot-device.

When using the Python API, you can either send the security message through the module or through the device using the unique device or module connection string. When using the following Python script example, with a device, use IoTHubDeviceClient, and with a module, use IoTHubModuleClient.

from azure.iot.device.aio import IoTHubDeviceClient, IoTHubModuleClient
from azure.iot.device import Message

async def send_security_message_async(message_content):
    conn_str = os.getenv("<connection_string>")
    device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)
    await device_client.connect()
    security_message = Message(message_content)
    security_message.set_as_security_message()
    await device_client.send_message(security_message)
    await device_client.disconnect()

Java API

public void SendSecurityMessage(string message)
{
    ModuleClient client = new ModuleClient("<connection_string>", IotHubClientProtocol.MQTT);
    Message msg = new Message(message);
    msg.setAsSecurityMessage();
    EventCallback callback = new EventCallback();
    string context = "<user_context>";
    client.sendEventAsync(msg, callback, context);
}

Next steps

Read the Defender for IoT service Overview
Learn more about Defender for IoT What is agent-based solution for device builders
Enable the service
Read the Microsoft Defender for IoT agent frequently asked questions
Learn how to access raw security data
Understand recommendations
Understand alerts

Share via