Edit

Tutorial: Configure security agents

  • Article

This article explains Defender for IoT security agents, and details how to change and configure them.

  • Configure security agents
  • Change agent behavior by editing twin properties
  • Discover default configuration

Agents

Defender for IoT security agents collect data from IoT devices and perform security actions to mitigate the detected vulnerabilities. Security agent configuration is controllable using a set of module twin properties you can customize. In general, secondary updates to these properties are infrequent.

Defender for IoT's security agent twin configuration object is a JSON format object. The configuration object is a set of controllable properties that you can define to control the behavior of the agent.

These configurations help you customize the agent for each scenario required. For example, automatically excluding some events, or keeping power consumption to a minimal level are possible by configuring these properties.

Use the Defender for IoT security agent configuration schema to make changes.

Configuration objects

Properties related to every Defender for IoT security agent are located in the agent configuration object, within the desired properties section, of the azureiotsecurity module.

To modify the configuration, create and modify this object inside the azureiotsecurity module twin identity.

If the agent configuration object does not exist in the azureiotsecurity module twin, all security agent property values are set to default.

"desired": {
  "ms_iotn:urn_azureiot_Security_SecurityAgentConfiguration": {
  }
}

Configuration schema and validation

Make sure to validate your agent configuration against this schema. An agent will not launch if the configuration object doesn't match the schema.

If, while the agent is running, the configuration object is changed to a non-valid configuration (the configuration doesn't match the schema), the agent will ignore the invalid configuration and will continue using the current configuration.

Configuration validation

Defender for IoT security agent reports its current configuration inside the reported properties section of the azureiotsecurity module twin identity. The agent reports all the available properties, if a property was not set by the user, the agent reports the default configuration.

In order to validate your configuration, compare the values set on the desired section with the values reported in the reported section.

If there is a mismatch between the desired and the reported properties, then the agent was not able to parse the configuration.

Validate your desired properties against the schema, fix the errors and set your desired properties again!

Note

A configuration error alert will be fired from the agent in case that the agent was not able to parse the desired configuration. Compare the reported and desired section to understand if the alert still applies

Editing a property

All custom properties must be set inside the agent configuration object within the azureiotsecurity module twin. To use a default property value, remove the property from the configuration object.

Setting a property

  1. In your IoT Hub, locate and select the device you wish to change.

  2. Click on your device, and then on azureiotsecurity module.

  3. Click on Module Identity Twin.

  4. Edit the properties you wish to change in the Defender-IoT-micro-agent.

    For example, to configure connection events as high priority and collect high priority events every 7 minutes, use the following configuration.

    "desired": {
    "ms_iotn:urn_azureiot_Security_SecurityAgentConfiguration": {
        "highPriorityMessageFrequency": {
            "value": "PT7M"
        },
        "eventPriorityConnectionCreate": {
            "value": "High"
        }
    }
}

  5. Click Save.

Using a default value

To use a default property value, remove the property from the configuration object.

Default properties

The following table contains the controllable properties of Defender for IoT security agents.

Default values are available in the proper schema in GitHub.

Name Status Valid values Default values Description
highPriorityMessageFrequency Required: false Valid values: Duration in ISO 8601 Format Default value: PT7M Max time interval before high priority messages are sent.
lowPriorityMessageFrequency Required: false Valid values: Duration in ISO 8601 Format Default value: PT5H Max time before low-priority messages are sent.
snapshotFrequency Require: false Valid values: Duration in ISO 8601 Format Default value PT13H Time interval for the creation of device status snapshots.
maxLocalCacheSizeInBytes Required: false Valid values: Default value: 2560000, larger than 8192 Maximum storage (in bytes) allowed for the message cache of an agent. Maximum amount of space allowed to store messages on the device, before messages are sent.
maxMessageSizeInBytes Required: false Valid values: A positive number, larger than 8192, less than 262144 Default value: 204800 Maximum allowed size of an agent to cloud message. This setting controls the amount of maximum data sent in each message.
eventPriority${EventName} Required: false Valid values: High, Low, Off Default values: Priority of every agent-generated event

Supported security events

Event name PropertyName Default Value Snapshot Event Details Status
Diagnostic event eventPriorityDiagnostic Off False Agent related diagnostic events. Use this event for verbose logging.
Configuration error eventPriorityConfigurationError Low False Agent failed to parse the configuration. Verify the configuration against the schema.
Dropped events statistics eventPriorityDroppedEventsStatistics Low True Agent related event statistics.
Connected hardware eventPriorityConnectedHardware Low True Snapshot of all hardware connected to the device.
Listening ports eventPriorityListeningPorts High True Snapshot of all open listening ports on the device.
Process create eventPriorityProcessCreate Low False Audits process creation on the device.
Process terminate eventPriorityProcessTerminate Low False Audits process termination on the device.
System information eventPrioritySystemInformation Low True A snapshot of system information (for example: OS or CPU).
Local users eventPriorityLocalUsers High True A snapshot of the registered local users within the system.
Login eventPriorityLogin High False Audit the login events to the device (local and remote logins).
Connection create eventPriorityConnectionCreate Low False Audits TCP connections created to and from the device.
Firewall configuration eventPriorityFirewallConfiguration Low True Snapshot of device firewall configuration (firewall rules).
OS baseline eventPriorityOSBaseline Low True Snapshot of device OS baseline check.

Next steps