Quickstart: Install Defender for IoT micro agent (Preview)

This article provides an explanation of how to install, and authenticate the Defender micro agent.

Prerequisites

Before you install the Defender for IoT module, you must create a module identity in the IoT Hub. For more information on how to create a module identity, see Create a Defender IoT micro agent module twin (Preview).

Install the package

To add the appropriate Microsoft package repository:

  1. Download the repository configuration that matches your device operating system.

    • For Ubuntu 18.04

      curl https://packages.microsoft.com/config/ubuntu/18.04/multiarch/prod.list > ./microsoft-prod.list
      
    • For Ubuntu 20.04

          curl https://packages.microsoft.com/config/ubuntu/20.04/prod.list > ./microsoft-prod.list
      
    • For Debian 9 (both AMD64 and ARM64)

      curl https://packages.microsoft.com/config/debian/stretch/multiarch/prod.list > ./microsoft-prod.list
      
  2. Copy the repository configuration to the sources.list.d directory.

    sudo cp ./microsoft-prod.list /etc/apt/sources.list.d/
    
  3. Install the Microsoft GPG public key:

    curl https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg
    sudo cp ./microsoft.gpg /etc/apt/trusted.gpg.d/
    

To install the Defender micro agent package on Debian, and Ubuntu based Linux distributions, use the following command:

sudo apt-get install defender-iot-micro-agent 

Micro agent authentication methods

The two options used to authenticate the Defender for IoT micro agent are:

  • Module identity connection string.

  • Certificate.

Authenticate using a module identity connection string

Ensure the Prerequisites for this article are met, and that you create a module identity before starting these steps.

Get the module identity connection string

To get the module identity connection string from the IoT Hub:

  1. Navigate to the IoT Hub, and select your hub.

  2. In the left-hand menu, under the Explorers section, select IoT devices.

    Select IoT devices from the left-hand menu.

  3. Select a device from the Device ID list to view the Device details page.

  4. Select the Module identities tab.

  5. Select the DefenderIotMicroAgent module from the list of module identities associated with the device.

    Select the module identities tab.

  6. In the Module Identity Details page, copy the Connection string (primary key) by selecting the copy button.

    Select the copy button to copy the Connection string (primary key).

Configure authentication using a module identity connection string

To configure the agent to authenticate using a module identity connection string:

  1. Place a file named connection_string.txt containing the connection string encoded in utf-8 in the defender agent directory /var/defender_iot_micro_agent path by entering the following command:

    sudo bash -c 'echo "<connection string>" > /var/defender_iot_micro_agent/connection_string.txt'
    

    The connection_string.txt should be located in the following path location /var/defender_iot_micro_agent/connection_string.txt.

  2. Restart the service using this command:

    sudo systemctl restart defender-iot-micro-agent.service 
    

Authenticate using a certificate

To authenticate using a certificate:

  1. Procure a certificate by following these instructions.

  2. Place the PEM-encoded public part of the certificate, and the private key, in to the Defender Agent Directory in to the file called certificate_public.pem, and certificate_private.pem.

  3. Place the appropriate connection string in to the connection_string.txt file. the connection string should look like this:

    HostName=<the host name of the iot hub>;DeviceId=<the id of the device>;ModuleId=<the id of the module>;x509=true

    This string alerts the defender agent, to expect a certificate be provided for authentication.

  4. Restart the service using the following command:

    sudo systemctl restart defender-iot-micro-agent.service
    

Validate your installation

To validate your installation:

  1. Making sure the micro agent is running properly with the following command:

    systemctl status defender-iot-micro-agent.service
    
  2. Ensure that the service is stable by making sure it is active and that the uptime of the process is appropriate

    Check to make sure your service is stable and active.

Testing the system end-to-end

You can test the system from end to end by creating a trigger file on the device. The trigger file will cause the baseline scan in the agent to detect the file as a baseline violation.

Create a file on the file system with the following command:

sudo touch /tmp/DefenderForIoTOSBaselineTrigger.txt 

A baseline validation failure recommendation will occur in the hub, with a CceId of CIS-debian-9-DEFENDER_FOR_IOT_TEST_CHECKS-0.0:

The baseline validation failure recommendation that occurs in the hub.

Allow up to one hour for the recommendation to appear in the hub.

Micro agent versioning

To install a specific version of the Defender IoT micro agent, run the following command:

sudo apt-get install defender-iot-micro-agent=<version>

Next steps