Deploy a security module on your IoT Edge device

Article
04/24/2022

Defender for IoT module provides a comprehensive security solution for your IoT Edge devices. The security module collects, aggregates, and analyzes raw security data from your Operating System and Container system into actionable security recommendations and alerts. To learn more, see Security module for IoT Edge.

In this article, you'll learn how to deploy a security module on your IoT Edge device.

Deploy security module

Use the following steps to deploy a Defender for IoT security module for IoT Edge.

Prerequisites

In your IoT Hub, make sure your device is Register a new device.
Defender for IoT Edge module requires the AuditD framework is installed on the IoT Edge device.
- Install the framework by running the following command on your IoT Edge device:
sudo apt-get install auditd audispd-plugins
- Verify AuditD is active by running the following command:
sudo systemctl status auditd
- Expected response is: active (running)

Deployment using Azure portal

From the Azure portal, open Marketplace.
Select Internet of Things, then search for Azure Security Center for IoT and select it.
Select Create to configure the deployment.
Choose the Azure Subscription of your IoT Hub, then select your IoT Hub.
Select Deploy to a device to target a single device or select Deploy at Scale to target multiple devices, and select Create. For more information about deploying at scale, see How to deploy.

Note

If you selected Deploy at Scale, add the device name and details before continuing to the Add Modules tab in the following instructions.

Complete each step to complete your IoT Edge deployment for Defender for IoT.

Step 1: Modules

Select the AzureSecurityCenterforIoT module.
On the Module Settings tab, change the name to azureiotsecurity.
On the Environment Variables tab, add a variable if needed (for example, you can add debug level and set it to one of the following values: "Fatal", "Error", "Warning", or "Information").

On the Container Create Options tab, add the following configuration:

{
    "NetworkingConfig": {
        "EndpointsConfig": {
            "host": {}
        }
    },
    "HostConfig": {
        "Privileged": true,
        "NetworkMode": "host",
        "PidMode": "host",
        "Binds": [
            "/:/host"
        ]
    }
}

On the Module Twin Settings tab, add the following configuration:

Module Twin Property:
```
  "ms_iotn:urn_azureiot_Security_SecurityAgentConfiguration"
```
Module Twin Property Content:
```
  {

  }
```
For more information about configuring the agent, see Configure security agents.
Select Update.

Step 2: Runtime settings

Select Runtime Settings.
Under Edge Hub, change the Image to mcr.microsoft.com/azureiotedge-hub:1.0.8.3.

Note

Currently, version 1.0.8.3 or older is supported.

Verify Create Options is set to the following configuration:

{
   "HostConfig":{
      "PortBindings":{
         "8883/tcp":[
            {
               "HostPort":"8883"
            }
         ],
         "443/tcp":[
            {
               "HostPort":"443"
            }
         ],
         "5671/tcp":[
            {
               "HostPort":"5671"
            }
         ]
      }
   }
}

Select Save.
Select Next.

Step 3: Specify routes

On the Specify Routes tab, make sure you have a route (explicit or implicit) that will forward messages from the azureiotsecurity module to $upstream according to the following examples. Only when the route is in place, select Next.

Example routes:
```
"route": "FROM /messages/* INTO $upstream"
```
```
"ASCForIoTRoute": "FROM /messages/modules/azureiotsecurity/* INTO $upstream"
```
Select Next.

Step 4: Review deployment

On the Review Deployment tab, review your deployment information, then select Create to complete the deployment.

Diagnostic steps

If you encounter an issue, container logs are the best way to learn about the state of an IoT Edge security module device. Use the commands and tools in this section to gather information.

Verify the required containers are installed and functioning as expected

Run the following command on your IoT Edge device:

sudo docker ps
Verify that the following containers are running:

Name IMAGE

azureiotsecurity mcr.microsoft.com/ascforiot/azureiotsecurity:1.0.2

edgeHub mcr.microsoft.com/azureiotedge-hub:1.0.8.3

edgeAgent mcr.microsoft.com/azureiotedge-agent:1.0.1

If the minimum required containers are not present, check if your IoT Edge deployment manifest is aligned with the recommended settings. For more information, see Deploy IoT Edge module.

Name	IMAGE
azureiotsecurity	mcr.microsoft.com/ascforiot/azureiotsecurity:1.0.2
edgeHub	mcr.microsoft.com/azureiotedge-hub:1.0.8.3
edgeAgent	mcr.microsoft.com/azureiotedge-agent:1.0.1

Inspect the module logs for errors

Run the following command on your IoT Edge device:

sudo docker logs azureiotsecurity
For more verbose logs, add the following environment variable to the azureiotsecurity module deployment: logLevel=Debug.

Next steps

To learn more about configuration options, continue to the how-to guide for module configuration.

Module configuration how-to guide