Select your cookie preferences

We use essential cookies and similar tools that are necessary to provide our site and services. We use performance cookies to collect anonymous statistics, so we can understand how customers use our site and make improvements. Essential cookies cannot be deactivated, but you can choose “Customize” or “Decline” to decline performance cookies.

If you agree, AWS and approved third parties will also use cookies to provide useful site features, remember your preferences, and display relevant content, including relevant advertising. To accept or decline all non-essential cookies, choose “Accept” or “Decline.” To make more detailed choices, choose “Customize.”

LibrariesinsideAWS IoT Device Defender

Updated Mar 2025

Integrating the Device Defender Library with the MQTT Agent

Introduction

This example uses the MQTT agent to interact with the AWS IoT Device Defender serviceexternal_link by submitting device defender reports, including custom metricsexternal_link, and verifying that the reports were accepted. The MQTT agent enables the Defender reporting functionality to run in the background and share the MQTT connection with other tasks.

The Device Defender demo code runs as a task in the same demo projectexternal_link as the MQTT agent demo and the OTA demo. Follow the directions on the MQTT agent demo documentation page in order to obtain and configure the project. To use the Device Defender demo task, configure your project to connect to AWS IoT Coreexternal_link, and then perform the additional project and AWS account configurations specified on this page.

See the comments at the top of each C file in the Source Directoryexternal_link for additional information.

Instructions

Getting Started

Start by setting up the project as described on the MQTT agent demo documentation page. Be sure to follow all of the steps starting with:

  1. Learning about the MQTT Agent demo
  2. Obtaining the source code
  3. Configuring FreeRTOS-Plus-TCP
  4. Configuring the MQTT broker
  5. Configuring the MQTT Agent

Follow the instructions to connect using the AWS IoT Core MQTT broker and test the connection using one of the simple MQTT tasks. This will ensure connectivity to AWS IoT Core is working correctly before moving on to enabling the Device Defender task.

Once connectivity is working with a non-Defender demo, the following instructions show you how to:

  • Set up the custom metrics on your AWS account.
  • Configure a security profile to retain submitted reports.
  • Enable and run the demo task.
  • View the submitted metrics.

Creating custom metrics using the AWS IoT console

As the demo submits custom metricsexternal_link, the first step is to configure these metrics on the AWS account. The demo uses two custom metrics, named "stack_high_water_mark" (of type number) and "task_numbers" (of type number list). Start by going to the AWS IoT consoleexternal_link.

In the navigation pane of the AWS IoT console, choose Defend, Detect, and then Metrics.


Click to enlarge.

Click "Create" in the custom metrics section. Under "Name", enter "stack_high_water_mark". Under "Type", select "number". Then click "Create custom metric".


Click to enlarge.

Repeat the prior step, except use "task_numbers" for the name and "number-list" for the type. You should see both metrics as shown below.


Click to enlarge.

Configuring a Security Profile

In order for submitted reports to be retained, a security profile needs to be configured. Start by going to the AWS IoT consoleexternal_link. In the navigation pane of the AWS IoT console, choose Defend, Detect, and then Security Profiles.


Click to enlarge.

Under "Create Security Profile", select "Create Rule-based anomaly Detect profile". Enter a name under "Name". Under the dot menu, click "Delete" to remove the default behavior.


Click to enlarge.

Expand the "Additional Metrics to retain" section, and click the first checkbox in order to select all the metrics. Click next. Then on the Alert targets page, just click "Next".


Click to enlarge.

On the Attach page, select "All things", and then click "Next". Click "Save" on the Confirm page.


Click to enlarge.

Configuring and Running the Demo

In order to run this demo, you'll need to set up your connection to AWS IoT Core. Follow the configuration steps here, and once you've completed those, perform the following steps:

NOTE: Make sure that democonfigCLIENT_IDENTIFIERexternal_link was set to the name of your Thing.

  • Enable the defender demo task by updating democonfigCREATE_DEFENDER_DEMOexternal_link to 1.
  • Run the demo and let it submit some reports. By default, it sends a report every 30 seconds.
  • When a report is successful, the following message will be printed to the console:
1**The defender report was accepted by the service.**

Viewing the metrics on the AWS IoT Console

Once the demo has submitted reports, you can view them to verify they are working as intended. Start by going to the AWS IoT consoleexternal_link.

In the navigation pane of the AWS IoT console, choose Manage, and then Things.

Select the Thing created for the demo, and select the "Defender metrics" tab. Here you can select reported metrics, including custom metrics, and view reported values. Reports may take some time to show up.


Click to enlarge.