title | description | ms.date | ms.topic | ms.custom |
---|---|---|---|---|
Install the Microsoft Defender for IoT micro agent |
Learn how to install and authenticate the Defender for IoT micro agent. |
04/26/2022 |
tutorial |
mode-other |
This tutorial will help you learn how to install and authenticate the Defender for IoT micro agent.
In this tutorial you'll learn how to:
[!div class="checklist"]
- Download and install the micro agent
- Authenticate the micro agent
- Validate the installation
- Test the system
- Install a specific micro agent version
-
An Azure account with an active subscription. Create an account for free.
-
An IoT hub.
-
Verify you're 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 created a Defender for IoT micro agent module twin.
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.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
-
-
Use the following command to copy the repository configuration to the
sources.list.d
directory: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've updated the apt using the following command:
sudo apt-get update
-
Use 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
This procedure describes how you can connect the Defender for IoT micro agent to the IoT Hub via a proxy.
To configure connections via a proxy:
-
On your micro agent machine, create a
/etc/defender_iot_micro_agent/conf.json
file with the following content:{ "IothubModule_ProxyConfig": "<proxy_ipv4>,<port>,<username>,<password>", "IothubModule_TransportProtocol": "MQTT_WebSocket_Protocol" }
User and password fields are optional. If you don't need them, use the following syntax instead:
{ "IothubModule_ProxyConfig": "<proxy_ipv4>,<port>", "IothubModule_TransportProtocol": "MQTT_WebSocket_Protocol" }
-
Delete any cached file at /var/lib/defender_iot_micro_agent/cache.json.
-
Restart the micro agent. Run:
sudo systemctl restart defender-iot-micro-agent.service
This procedure describes additional steps required to support the AMQP protocol.
To add AMQP protocol support:
-
On your micro agent machine, open the
/etc/defender_iot_micro_agent/conf.json
file and add the following content:{ "IothubModule_TransportProtocol": "AMQP_Protocol" }
-
Delete any cached file at /var/lib/defender_iot_micro_agent/cache.json.
-
Restart the micro agent. Run:
sudo systemctl restart defender-iot-micro-agent.service
To add AMQP over web socket protocol support:
-
On your micro agent machine, open the
/etc/defender_iot_micro_agent/conf.json
file and add the following content:{ "IothubModule_TransportProtocol": "AMQP_WebSocket_Protocol" }
-
Delete any cached file at /var/lib/defender_iot_micro_agent/cache.json.
-
Restart the micro agent. Run:
sudo systemctl restart defender-iot-micro-agent.service
The agent will use this protocol, and communicate with the IoT Hub on port 443. Http Proxy configuration is supported for this protocol, in the case that proxy is also configured, the port of communication with the proxy will be as defined in the proxy configuration.
There are two options that can be used to authenticate the Defender for IoT micro agent:
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.:::image type="content" source="media/quickstart-standalone-agent-binary-installation/iot-devices.png" alt-text="Select IoT devices from the left-hand menu.":::
-
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.
:::image type="content" source="media/quickstart-standalone-agent-binary-installation/module-identities.png" alt-text="Select the module identities tab.":::
-
Copy the Connection string (primary key) by selecting the copy button.
:::image type="content" source="media/quickstart-standalone-agent-binary-installation/copy-button.png" alt-text="Select the copy button to copy the Connection string (primary key).":::
-
Create a file named
connection_string.txt
containing the copied connection string encoded in utf-8 in the Defender for IoT agent directory/etc/defender_iot_micro_agent
path by entering the following command:sudo bash -c 'echo "<connection string>" > /etc/defender_iot_micro_agent/connection_string.txt'
The
connection_string.txt
will now be located in the following path location/etc/defender_iot_micro_agent/connection_string.txt
.[!NOTE] The connection string includes a key that enables direct access to the module itself, therefore includes sensitive information that should only be used and readable by root users.
-
Restart the service using this command:
sudo systemctl restart defender-iot-micro-agent.service
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
/etc/defender_iot_micro_agent
, to files calledcertificate_public.pem
, andcertificate_private.pem
. -
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 for IoT agent to expect a certificate to be provided for authentication.
-
Restart the service using the following command:
sudo systemctl restart defender-iot-micro-agent.service
To validate your installation:
-
Use the following command to ensure the micro agent is running properly:
systemctl status defender-iot-micro-agent.service
-
Ensure that the service is stable by making sure it's
active
, and that the uptime of the process is appropriate.:::image type="content" source="media/quickstart-standalone-agent-binary-installation/active-running.png" alt-text="Check to make sure your service is stable and active.":::
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.txt
-
Make sure that your Log Analytics workspace is attached to your IoT hub. For more information, see Create a log analytics workspace.
-
Restart 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 recommendation called 'IoT_CISBenchmarks_DIoTTest' is created. You can query this recommendation from Log Analytics as follows:
SecurityRecommendation
| where RecommendationName contains "IoT_CISBenchmarks_DIoTTest"
| where DeviceId contains "<device-id>"
| top 1 by TimeGenerated desc
For example:
:::image type="content" source="media/tutorial-standalone-agent-binary-installation/iot_cisbenchmarks_diottest.png" alt-text="Screenshot of the IoT_CISBenchmarks_DIoTTest query run in Log Analytics.":::
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>
There are no resources to clean up.
[!div class="nextstepaction"] Configure Microsoft Defender for IoT agent-based solution