Defender for IoT CLI users and access

This article provides an introduction to the Microsoft Defender for IoT command line interface (CLI). The CLI is a text-based user interface that allows you to access your OT sensors and the on-premises management console for advanced configuration, troubleshooting, and support.

To access the Defender for IoT CLI, you'll need access to the sensor or on-premises management console.

  • For OT sensors or the on-premises management console, you'll need to sign in as a privileged user.
  • For Enterprise IoT sensors, you can sign in as any user.

Caution

Only documented configuration parameters on the OT network sensor and on-premises management console are supported for customer configuration. Do not change any undocumented configuration parameters or system properties, as changes may cause unexpected behavior and system failures.

Removing packages from your sensor without Microsoft approval can cause unexpected results. All packages installed on the sensor are required for correct sensor functionality.

Privileged user access for OT monitoring

Use the admin user when using the Defender for IoT CLI, which is an administrative account with access to all CLI commands. On the on-premises management console, use the cyberx user.

If you're using a legacy software version, you may have one or more of the following users:

Legacy scenario Description
Sensor versions earlier than 23.2.0 In sensor versions earlier than 23.2.0, the default admin user is named support. The support user is available and supported only on versions earlier than 23.2.0.

Documentation refers to the admin user to match the latest version of the software.

Other CLI users cannot be added.

For more information, see On-premises users and roles for OT monitoring with Defender for IoT.

Supported users by CLI actions

The following tables list the activities available by CLI and the privileged users supported for each activity. The cyberx and cyberx_host users are only supported in versions earlier than 23.1.x.

Appliance maintenance commands

Service area Users Actions
Sensor health admin, cyberx Check OT monitoring services health
Reboot and shutdown admin, cyberx, cyberx_host Restart an appliance
Shut down an appliance
Software versions admin, cyberx Show installed software version
Update software version
Date and time admin, cyberx, cyberx_host Show current system date/time
NTP admin, cyberx Turn on NTP time sync
Turn off NTP time sync

Backup and restore commands

Service area Users Actions
List backup files admin, cyberx List current backup files
Start an immediate, unscheduled backup
Restore admin, cyberx Restore data from the most recent backup
Backup disk space cyberx Display backup disk space allocation

Local user management commands

Service area Users Actions
Password management cyberx, cyberx_host Change local user passwords
Sign-in configuration cyberx Define maximum number of failed sign-ins

Network configuration commands

Service area Users Actions
Network setting configuration cyberx_host Change networking configuration or reassign network interface roles
Network setting configuration admin Validate and show network interface configuration
Network connectivity admin, cyberx Check network connectivity from the OT sensor
Physical interfaces management admin Locate a physical port by blinking interface lights
Physical interfaces management admin, cyberx List connected physical interfaces

Traffic capture filter commands

Service area Users Actions
Capture filter management admin, cyberx Create a basic filter for all components
Create an advanced filter for specific components
List current capture filters for specific components
Reset all capture filters

Defender for IoT CLI access

To access the Defender for IoT CLI, sign in to your OT or Enterprise IoT sensor or your on-premises management console using a terminal emulator and SSH.

  • On a Windows system, use PuTTY or another similar application.
  • On a Mac system, use Terminal.
  • On a virtual appliance, access the CLI via SSH, the vSphere client, or Hyper-V Manager. Connect to the virtual appliance's management interface IP address via port 22.

Each CLI command on an OT network sensor or on-premises management console is supported a different set of privileged users, as noted in the relevant CLI descriptions. Make sure you sign in as the user required for the command you want to run. For more information, see Privileged user access for OT monitoring.

Access the system root as an admin user

When signing in as the admin user, run the following command to access the host machine as the root user. Access the host machine as the root user enables you to run CLI commands that aren't available to the admin user.

Run:

system shell

Sign out of the CLI

Make sure to properly sign out of the CLI when you're done using it. You're automatically signed out after an inactive period of 300 seconds.

To sign out manually on an OT sensor or on-premises management console, run one of the following commands:

User Command
admin logout
cyberx cyberx-xsense-logout
cyberx_host logout

Next steps

You can also control and monitor your cloud connected sensors from the Defender for IoT Sites and sensors page. For more information, see Manage sensors with Defender for IoT in the Azure portal.