Defending Linux-based IoT units towards unintended USB entry


The Web of Issues (IoT) business continues to develop at an aggressive tempo. Because the variety of linked units ramps up, managing safety of those units at scale may be difficult. One of many potential dangers that IoT units face is unintended USB entry, which might happen when an unauthorized connection is made via its USB port. For instance, if a consumer good points bodily entry to a safety digicam system, there’s a threat they might plugin an unauthorized USB system that gives entry to the digicam system and its knowledge. This might end in unauthorized entry to delicate knowledge or a disruption in system availability.

Defending IoT units from unintended USB entry requires a multi-layered safety method that features each {hardware} and software program options. {Hardware} options embrace implementing a further layer of safety to the USB ports and limiting bodily entry to units. Software program options embrace implementing firmware and software program updates, in addition to implementing safety protocols that may detect and stop unintended USB entry.

The entry degree for a tool can be totally different relying on whether or not it’s in service or in debug mode. When a tool is in service, it’s your decision its USB ports to be absolutely protected. When it’s in debug mode, you typically have to open up its USB ports to permit a technician to plug in analysis software program. The management over the system’s mode must be securely carried out by a safety or DevOps crew, as proven in Determine 1.

On this weblog, you’ll learn to defend Linux-based IoT units and computer systems towards unintended USB entry with USBGuard and the way to securely change a tool from In-Service mode to Debug mode with AWS IoT Gadget Administration.

Protecting Linux-based IoT devices against unintended USB access use case

Determine 1: Use case rationalization



The next diagram, Determine 2, exhibits an structure of a Linux-based system connecting via AWS IoT Core utilizing MQTT. On the system, the USBGuard service has been put in and enabled. USBGuard is a software program framework that provides an permit/deny -listing mechanism for USB-devices. Inspiration for that is drawn from points like BadUSB. It makes use of a tool blocking infrastructure included within the Linux kernel.

The system has a tool mode attribute outlined. You possibly can set the system mode to both in-service or debug mode via Jobs for AWS IoT. IoT Jobs outline a set of distant operations that may be despatched to and run on a number of units linked to AWS IoT. For this use case, there are two jobs outlined: set-debug-mode-job and set-in-service-mode-job. You possibly can monitor system mode attributes and carry out jobs via AWS IoT Gadget Administration Fleet Hub.

When operating the set-in-service-mode-job, the IoT communication shopper will decide up the job, set a USBGuard coverage to limit USB ports entry solely to designated USB system, block different units with a hidden keyboard interface in a USB flash disk, and set the system shadow attribute with in-service mode . Quite the opposite, when operating the set-debug-mode-job, it loosens the foundations on the USB ports (e.g. a USBGuard coverage to permit all USB ports entry), and units the system shadow attribute with debug mode. This manner, a technician can plug in a mouse and a keyboard and run debugging software program via USB ports.

Protecting Linux-based IoT devices against unintended USB access solution diagram

Determine 2: Resolution structure

This may be achieved via the next procedures:

  1. Configure AWS IoT Core coverage and system attributes
  2. Provision the system
  3. Set up USBGuard on the system
  4. Implement the IoT communication shopper code
  5. Configure job docs in IoT Jobs
  6. Create AWS IoT Gadget Administration Fleet Hub software

Steps 1 and a couple of may be carried out both in AWS IoT Core console or via AWS CLI. We use AWS CLI instructions within the walkthrough. Step 3 and 4 are configured on the IoT system. And step 5 and 6 are carried out in AWS IoT console.

Step 1: Configure AWS IoT Core coverage and system attributes


# Create an IoT coverage
# NOTE: This coverage is for demonstration objective solely! Please don't use in manufacturing setting.
# Substitute us-east-1:123456789012 along with your AWS_REGION:AWS_ACCOUNT_ID
# Substitute uniqueThingName along with your IoT system factor title
aws iot create-policy --policy-name $POLICY_NAME --policy-document '{
  "Model": "2012-10-17",
  "Assertion": [
      "Effect": "Allow",
      "Action": "iot:Connect",
      "Resource": "arn:aws:iot:us-east-1:123456789012:client/uniqueThingName"
      "Effect": "Allow",
      "Action": "iot:Publish",
      "Resource": [
      "Impact": "Enable",
      "Motion": "iot:Subscribe",
      "Useful resource": "arn:aws:iot:us-east-1:123456789012:*"
      "Impact": "Enable",
      "Motion": "iot:Obtain",
      "Useful resource": [
      "Impact": "Enable",
      "Motion": [
      "Useful resource": "arn:aws:iot:us-east-1:123456789012:matter/$aws/issues/uniqueThingName"

# Create factor sort
aws iot create-thing-type --thing-type-name $THING_TYPE_NAME

# Create dynamic factor teams
aws iot create-dynamic-thing-group --thing-group-name "Debug" --query-string "shadow.title.device-mode.reported.mode:Debug" > /dev/null
aws iot create-dynamic-thing-group --thing-group-name "InService" --query-string "shadow.title.device-mode.reported.mode:InService" > /dev/null

Step 2: Provision the system

THING_NAME="<your system distinctive identifier>"
THING_PATH="<your work listing>/$THING_NAME"

aws iot create-thing --thing-name $THING_NAME --thing-type-name $THING_TYPE_NAME 

# Create keys and certificates
aws iot create-keys-and-certificate --set-as-active 
    --private-key-outfile $THING_PATH/personal.key 
--certificate-pem-outfile $THING_PATH/certificates.pem > $THING_PATH/keys_response

# Get Root CA
wget -O $THING_PATH/rootCA.pem

# Parse output for certificates ARN and ID
CERTIFICATE_ARN=$(jq -r ".certificateArn" $THING_PATH/keys_response)
CERTIFICATE_ID=$(jq -r ".certificateId" $THING_PATH/keys_response)
# Connect coverage to certificates
aws iot attach-policy --policy-name $POLICY_NAME --target $CERTIFICATE_ARN
# Connect certificates to factor
aws iot attach-thing-principal --thing-name $THING_NAME --principal $CERTIFICATE_ARN

Step 3: Set up USBGuard on the system

Comply with the public documentation to put in USBGuard.

Generate two USBGuard insurance policies, debug-rules.conf and in-service-rules.conf. in-service-rules.conf accommodates strict guidelines and shall be utilized in system’s in-service mode. debug-rules.conf loosens the foundations on the USB ports and shall be utilized in system’s debug mode.

For instance, a debug-rules.conf could be a coverage permitting all entry to all USB ports:

echo "permit id *:*" > debug-rules.conf

in-service-rules.conf can include guidelines to reject any USB flash disk which implements a keyboard or a community interface.

permit with-interface equals { 08:*:* }
reject with-interface all-of { 08:*:* 03:00:* }
reject with-interface all-of { 08:*:* 03:01:* }
reject with-interface all-of { 08:*:* e0:*:* }
reject with-interface all-of { 08:*:* 02:*:* }

Step 4: Implement the IoT communication shopper code

On the IoT system itself, create a piece listing:

WORKDIR="<your work listing>"
mkdir -p $THING_PATH

Put the certificates.pem, personal.key, rootCA.pem from Step 2 below the $THING_PATH.

We use the AWS IoT Gadget Consumer on the system. The AWS IoT Gadget Consumer is free, open-source, modular software program written in C++ you could compile and set up in your Embedded Linux based mostly IoT units to entry AWS IoT Core, AWS IoT Gadget Administration, and AWS IoT Gadget Defender options by default. To put in and configure the shopper:

# Constructing
git clone
cd aws-iot-device-client
mkdir construct
cd construct
cmake ../
cmake --build . --target aws-iot-device-client

# Setup
cd ../

At this level you’ll want to answer prompts for info, together with paths to your factor certs:

Do you wish to interactively generate a configuration file for the AWS IoT Gadget Consumer? y/n
Specify AWS IoT endpoint to make use of:
<That is the iot:Information-ATS endpoint. Try>
Specify path to public PEM certificates:
Specify path to non-public key:
Specify path to ROOT CA certificates:
Specify factor title (Additionally used as Consumer ID):
Would you prefer to configure the logger? y/n
Allow Jobs function? y/n
Specify absolute path to Job handler listing:
Allow Pattern Shadow function? y/n
Specify a shadow title for the function to create or replace:
Specify the trail of a file for the function to learn from:
Specify a the trail of a file for the function to jot down shadow doc to:
Do you wish to set up AWS IoT Gadget Consumer as a service? y/n

Within the $WORKDIR/.aws-iot-device-client/jobs, create a usbguard-policy listing and put the debug-rules.conf and in-service-rules.conf generated from step 3 in there.

Create two corresponding job handler scripts within the $WORKDIR/.aws-iot-device-client/jobs to deal with set system mode. They are going to be triggered by IoT Job docs.

The script to set system to debug mode:

#!/usr/bin/env sh
set -e

BASEDIR=$(dirname $0)
echo '{"mode": "Debug"}' > $BASEDIR/../device-mode-input.json
cat $BASEDIR/usbguard-policy/debug-rules.conf > /and so forth/usbguard/guidelines.conf
systemctl restart usbguard.service

The script to set system to in-service mode:

#!/usr/bin/env sh
set -e

BASEDIR=$(dirname $0)
echo '{"mode": "InService"}' > $BASEDIR/../device-mode-input.json
cat $BASEDIR/usbguard-policy/in-service-rules.conf > /and so forth/usbguard/guidelines.conf
systemctl restart usbguard.service

Now, the whole lot has been configured on the system, we will run the system shopper by:

cd $WORKDIR/aws-iot-device-client
sudo ./construct/aws-iot-device-client

Step 5: Configure job docs in IoT Jobs

Two job docs must be created in IoT Jobs. set_debug_mode.json and set_in_sevice_mode.json. They are going to set off the and handlers that we wrote in Step 4 respectfully.

Instance of set_debug_mode.json:

  "_comment": "This pattern JSON file can be utilized for set debug mode.",
  "model": "1.0",
  "steps": [
      "action": {
        "name": "Set Device Mode to Debug",
        "type": "runHandler",
        "input": {
          "handler": ""
        "runAsUser": "root"

Create an Amazon S3 bucket and add the job docs. In AWS IoT Jobs console, configure the Job templates with the 2 job docs:

AWS IoT Job templates

Step 6: Create AWS IoT Gadget Administration Fleet Hub software

Comply with the weblog publish Get Began with Fleet Hub for AWS IoT Gadget Administration to arrange Fleet Hub. In your Fleet Hub software, you must be capable of see your system and its mode.

AWS IoT FleetHub Dashboard

It’s also possible to management to vary the mode by run jobs from the dashboard.

AWS IoT Job: Run Jobs

On the system, you must be capable of observe that entry to any USB port is equivalent to the foundations you’ve set for the system mode.

Cleansing up

To keep away from incurring future costs, delete all assets that you’ve got created.

The Fleet Hub software may be deleted by first navigating to Fleet Hub within the AWS IoT console after which deciding on purposes. Choose your software and select delete.

AWS IoT Core Fleet indexing may be turned off by navigating to the AWS IoT Core console, deciding on Settings, then navigating to Handle fleet Indexing after which Factor indexing and group indexing.

Within the AWS IoT Core console, delete Issues, Factor teams and Factor varieties below All units. Detach ‘factor’ and IoT coverage from registered certificates. Delete system certificates, ‘factor,’ and IoT coverage.


On this publish, we confirmed you the way to defend Linux-based IoT units and computer systems towards unintended USB entry with USBGuard and securely management USB entry based mostly on the system mode. View and management units’ modes in AWS IoT Gadget Administration Fleet Hub software. The answer is versatile and may be tailored to different use circumstances. For instance, when the system is in debug mode, seize debug logs and ship them to the cloud for additional examination.

To study extra about the way to use AWS IoT Core, you possibly can seek advice from the documentation.

Writer bio

Sharon Li

Sharon Li is a options architect at AWS, based mostly within the Boston, MA space. She works with enterprise prospects serving to them resolve tough issues and construct on AWS. Exterior of labor, she likes to spend time together with her household and discover native eating places.

Leave a Reply

Your email address will not be published. Required fields are marked *