Inviare l'SDK dei messaggi di sicurezza

  • Articolo

Questa guida pratica illustra le funzionalità del servizio Defender per IoT quando si sceglie di raccogliere e inviare messaggi di sicurezza del dispositivo senza usare un agente Defender per IoT e spiega come eseguire questa operazione.

Questa guida illustra come eseguire queste operazioni:

  • Inviare messaggi di sicurezza con Azure IoT C SDK
  • Inviare messaggi di sicurezza con Azure IoT C# SDK
  • Inviare messaggi di sicurezza con Azure IoT Python SDK
  • Inviare messaggi di sicurezza con Azure IoT Node.js SDK
  • Inviare messaggi di sicurezza con Azure IoT Java SDK

Funzionalità di Defender per IoT

Defender per IoT può elaborare e analizzare qualsiasi tipo di dati dei messaggi di sicurezza purché i dati inviati siano conformi allo schema di Defender per IoT e il messaggio sia impostato come messaggio di sicurezza.

Messaggio di sicurezza

Defender per IoT definisce un messaggio di sicurezza usando i criteri seguenti:

  • Se il messaggio è stato inviato con Azure IoT SDK
  • Se il messaggio è conforme allo schema dei messaggi di sicurezza
  • Se il messaggio è stato impostato come messaggio di sicurezza prima dell'invio

Ogni messaggio di sicurezza include i metadati del mittente, ad AgentIdesempio , AgentVersionMessageSchemaVersion e un elenco di eventi di sicurezza. Lo schema definisce le proprietà valide e obbligatorie del messaggio di sicurezza, inclusi i tipi di eventi.

Nota

I messaggi inviati che non sono conformi allo schema vengono ignorati. Assicurarsi di verificare lo schema prima di avviare l'invio di dati, perché i messaggi ignorati non vengono attualmente archiviati.

Nota

I messaggi inviati che non sono stati impostati come messaggio di sicurezza tramite Azure IoT SDK non verranno instradati alla pipeline di Defender per IoT.

Esempio di messaggio valido

L'esempio seguente mostra un oggetto messaggio di sicurezza valido. L'esempio contiene i metadati del messaggio e un ProcessCreate evento di sicurezza.

Dopo aver impostato come messaggio di sicurezza e inviato, questo messaggio verrà elaborato da Defender per 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"
                }
            ]
    }
]

Inviare messaggi di sicurezza

Inviare messaggi di sicurezza senza usare l'agente Defender per IoT usando Azure IoT C SDK per dispositivi, Azure IoT C# SDK per dispositivi, Azure IoT Node.js SDK, Azure IoT Python SDK o Azure IoT Java SDK.

Per inviare i dati del dispositivo dai dispositivi per l'elaborazione da Defender per IoT, usare una delle API seguenti per contrassegnare i messaggi per il routing corretto alla pipeline di elaborazione di Defender per IoT.

Tutti i dati inviati, anche se contrassegnati con l'intestazione corretta, devono essere conformi allo schema dei messaggi di Defender per IoT.

API di invio messaggio di sicurezza

L'API Invia messaggi di sicurezza è attualmente disponibile in C e C#, Python, Node.js e Java.

API C

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
    }
}

API C#


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);
}

API Node.js

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);​
}

API Python

Per usare l'API Python è necessario installare il pacchetto azure-iot-device.

Quando si usa l'API Python, è possibile inviare il messaggio di sicurezza tramite il modulo o tramite il dispositivo usando il dispositivo o il modulo univoco stringa di connessione. Quando si usa l'esempio di script Python seguente, con un dispositivo, usare IoTHubDeviceClient e con un modulo usare 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()

API Java

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);
}

Passaggi successivi