Tutorial: Install the Defender for IoT micro agent (Preview)
This tutorial will help you learn how to install and authenticate the Defender for IoT micro agent.
In this tutorial you will learn how to:
- Download and install the micro agent
- Authenticate the micro agent
- Validate the installation
- Test the system
- Install a specific micro agent version
Prerequisites
An Azure account with an active subscription. Create an account for free.
An IoT hub.
Verify you are running one of the following operating systems.
You must have enabled Microsoft Defender for IoT on your Azure IoT Hub.
You must have added a resource group to your IoT solution
You must have Create a Defender for IoT micro agent module twin (Preview).
Download and install the micro agent
Depending on your setup, the appropriate Microsoft package will need to be installed.
To add the appropriate Microsoft package repository:
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.listFor Ubuntu 20.04
curl https://packages.microsoft.com/config/ubuntu/20.04/prod.list > ./microsoft-prod.listFor Debian 9 (both AMD64 and ARM64)
curl https://packages.microsoft.com/config/debian/stretch/multiarch/prod.list > ./microsoft-prod.list
Use the following command to copy the repository configuration to the
sources.list.ddirectory:sudo cp ./microsoft-prod.list /etc/apt/sources.list.d/Install the Microsoft GPG public key with the following command:
curl https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg sudo cp ./microsoft.gpg /etc/apt/trusted.gpg.d/Ensure that you have updated the apt using the following command:
sudo apt-get updateUse the following command to install the Defender for IoT micro agent package on Debian, or Ubuntu based Linux distributions:
sudo apt-get install defender-iot-micro-agent
Authenticate the micro agent
There are two options that can be used to authenticate the Defender for IoT micro agent:
Authenticate using a module identity connection string
You will need to copy the module identity connection string from the DefenderIoTMicroAgent module identity details.
To copy the module identity's connection string:
Navigate to the IoT Hub >
Your hub> Device management > Devices .
Select a device from the Device ID list.
Select the Module Identities tab.
Select the DefenderIotMicroAgent module from the list of module identities associated with the device.
Copy the Connection string (primary key) by selecting the copy button.
Configure authentication using the module identity connection string
To configure the agent to authenticate using a module identity connection string:
Create a file named
connection_string.txtcontaining the copied connection string encoded in utf-8 in the Defender for Cloud agent directory/var/defender_iot_micro_agentpath by entering the following command:sudo bash -c 'echo "<connection string>" > /var/defender_iot_micro_agent/connection_string.txt'The
connection_string.txtwill now be located in the following path location/var/defender_iot_micro_agent/connection_string.txt.Restart the service using this command:
sudo systemctl restart defender-iot-micro-agent.service
Authenticate using a certificate
To authenticate using a certificate:
Procure a certificate by following these instructions.
Place the PEM-encoded public part of the certificate, and the private key, in to the Defender for Cloud Agent Directory in to the file called
certificate_public.pem, andcertificate_private.pem.Place the appropriate connection string in to the
connection_string.txtfile. 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=trueThis string alerts the Defender for Cloud agent, to expect a certificate be provided for authentication.
Restart the service using the following command:
sudo systemctl restart defender-iot-micro-agent.service
Validate the installation
To validate your installation:
Use the following command to ensure the micro agent is running properly with:
systemctl status defender-iot-micro-agent.serviceEnsure that the service is stable by making sure it is
active, and that the uptime of the process is appropriate.
Test the system
You can test the system 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.txtRestart the agent using the command:
sudo systemctl restart defender-iot-micro-agent.service
Allow up to one hour for the recommendation to appear in the hub.
A baseline validation failure recommendation will occur in the hub, with a CceId of CIS-debian-9-DEFENDER_FOR_IOT_TEST_CHECKS-0.0:
Install a specific micro agent version
You can install a specific version of the micro agent using a specific command.
To install a specific version of the Defender for IoT micro agent:
Open a terminal.
Run the following command:
sudo apt-get install defender-iot-micro-agent=<version>
Clean up resources
There are no resources to clean up.