Threat Manager

Note: To display only the features present on a particular device, select one or more filters from the SmartDocs bar below.

EMDK For Xamarin - 4.0

Overview

The Threat Manager feature allows an application to control security Threats actively monitored by a device, how and whether to respond when a Threat is detected, and which Countermeasure(s) to employ.

Main Functionality

  • Enable/Disable Threat Detection
  • Detect common threats:
    • MDM client removal
    • Microsoft Exchange ActiveSync Threat
    • External Threat detected
    • Device has been rooted
    • Maximum failed password attempts (Multi-user MX lockscreen only)
  • Perform Countermeasures when a Threat is Detected
    • Lock the device
    • Perform a Factory Reset
    • Format the SD card
    • Wipe the Secure Storage Keys
    • Send a custom Threat message
    • Wipe the Secure Storage (encryption) Keys
    • Uninstall an application
    • Send an "Unsolicited" alert
  • Signal the Occurrence of an externally detected Threat
  • Perform Periodic Scans for root-based Threats
  • Set a custom interval for Periodic Scans
  • Define specific folders to monitor for changes
  • Send an Intent when a change occurs in a monitored folder

Threat Action

This is the On/Off switch for Threat Detection on the device. Turning Threat Detection On enables all features and activities that can be triggered whenever a Threat is detected on a device.

Parm Name: ThreatAction

Option Name Description Note Requires
0 Do nothing This value (or the absence of this parm from the XML) will cause no change to the Threat Detection setting; any previously selected setting will be retained.

OSX: 3.5+

MX: 4.3+

1 Turn On Turns On Threat Detection On.

OSX: 3.5+

MX: 4.3+

2 Turn Off Turns Off Threat Detection.

OSX: 3.5+

MX: 4.3+

Threat Name

Used to specify the name of the Threat to detect. Note: Zebra Multi-user MX has been discontinued, rendering the MaxPasswordAttempts feature inoperable on most devices.

Shown if: Shown when the Threat Action is "Turn On" or "Turn Off"

Parm Name: ThreatName

Option Name Description Note Requires
1 Do Nothing This value (or the absence of this parm from the XML) will make no change to the Threat(s) being detected on the device; any previously selected setting will be retained.

OSX: 3.5+

MX: 6.1+

1 MaxPasswordAttempts Detect when the Multi-user MX lockscreen has reached the maximum number of failed password attempts (9). See important note above.

OSX: 3.5+

MX: 4.3+

2 MDMClientRemoval Detects that an MDM client app has been removed from the device.

OSX: 3.5+

MX: 4.3+

3 ExternallyDetected A custom Threat defined by an intent that can be triggered from an application.

OSX: 3.5+

MX: 4.3+

4 ExchangeActiveSyncCommand Detects a Threat encountered while syncing with Microsoft Exchange.

OSX: 3.5+

MX: 4.3+

5 DeviceisRooted Detects that root-level access has been given to one or more device users and/or apps on the device.

OSX: 3.5+

MX: 4.3+

MDM Package Name

Used to specify the Package Name of the MDM client app to be monitored. Removal of the app specified here will trigger a Threat alert.

Note: The Package Name of the application to be monitored must be specified. The Package Name can be acquired from the application developer, a lookup of the Package Name on the device, or extracted from the APK file using developer tools designed for this purpose.

Parm value input rules:

  • String from 1 - 255 characters

Shown if: Shown when the Threat Action is "Turn On" and Threat Name is "MDM Client Package Name"

Parm Name: MDMPackage

Requires:

  • OSX: 3.5+
  • MX: 4.3+

Format SD Card Countermeasure

Formats the external SD Card, erasing all existing data on the card.

Shown if: Shown if Threat Action is "Turn On" and any Threat Action is selected.

Parm Name: FormatSdcard

Option Name Description Note Requires
0 Do not perform This countermeasure will not be executed.

OSX: 3.5+

MX: 4.3+

1 Perform This countermeasure will be executed upon threat detection.

OSX: 3.5+

MX: 4.3+

Factory Reset Countermeasure

Forces a factory reset, returning the device to its original factory settings.

Shown if: Shown if Threat Action is "Turn On" and any Threat Action is selected.

Parm Name: FactoryReset

Option Name Description Note Requires
0 Do not perform Countermeasure will not be executed.

OSX: 3.5+

MX: 4.3+

1 Perform Countermeasure will be executed upon threat detection.

OSX: 3.5+

MX: 4.3+

Wipe Secure Storage Keys Countermeasure

Removes from the device all Secure Storage Keys, which would otherwise be used to access portions of the device protected by encryption. Execution of this countermeasure does not necessarily prevent access to the encrypted data, but prevents the data from being decrypted and thus exploited. Once a threat has been neutralized, Secure Storage Keys can be restored to the device to provide access to the secure storage area as normal.

Shown if: Shown if Threat Action is "Turn On" and any Threat Action is selected.

Parm Name: WipeSecureStorageKeys

Option Name Description Note Requires
0 Do not perform Secure Storage Keys will not be removed.

OSX: 3.5+

MX: 4.3+

1 Perform Secure Storage Keys will be removed upon threat detection.

OSX: 3.5+

MX: 4.3+

Lock Device Countermeasure

Locks the device; requires the user to perform the device unlock procedure configured for the device.

Shown if: Shown if Threat Action is "Turn On" and any Threat Action is selected.

Parm Name: LockDevice

Option Name Description Note Requires
0 Do not perform Countermeasure will not be executed.

OSX: 3.5+

MX: 4.3+

1 Perform Countermeasure will be executed upon threat detection.

OSX: 3.5+

MX: 4.3+

Uninstall Application Countermeasure

Silently removes an application from the device as specified by package name in the UninstallPackage parameter.

Shown if: Shown if Threat Action is "Turn On" and any Threat Action is selected.

Parm Name: UninstallApplication

Option Name Description Note Requires
0 Do not perform Countermeasure will not be executed.

OSX: 3.5+

MX: 4.3+

1 Perform Countermeasure will be executed upon threat detection.

OSX: 3.5+

MX: 4.3+

Uninstall Package Name

Used to specify the package name of the application to uninstall during a countermeasure procedure.

Note: The Package Name of the application to be uninstalled must be specified. The Package Name can be acquired from the application developer, a lookup of the Package Name on the device, or extracted from the APK file using developer tools designed for this purpose.

Parm value input rules:

  • String from 1 - 255 characters

Shown if: Shown if Threat Action is "Turn On" and any Threat Action is selected and countermeasure is "Uninstall Application"

Parm Name: UninstallPackage

Requires:

  • OSX: 3.5+
  • MX: 4.3+

Unsolicited Alert Countermeasure

Used to send an alert to an application on the device in the form of an intent. The intent must include the package name, class name and alert message as specified in the AlertPackage, AlertClass, and AlertMsg parameters. When a Threat is detected, the detection service sends the StartActivityAsUser explicit intent with the message specified in the Alert Message parameter to the specified class of the specified package. See the Examples section for more information.

Shown if: Shown if Threat Action is "Turn On" and any Threat Action is selected.

Parm Name: UnsolicitedAlert

Option Name Description Note Requires
0 Do not perform The alert-message intent will not be sent upon Threat detection.

OSX: 3.5+

MX: 4.3+

1 Perform The alert-message intent will be sent to the specified application and class upon Threat detection.

OSX: 3.5+

MX: 4.3+

Alert Package Name

Used to specify the package name of the application to receive an alert during a countermeasure procedure.

Note: The Package Name of the application to receive the alert must be specified. The Package Name can be acquired from the application developer, a lookup of the Package Name on the device, or extracted from the APK file using developer tools designed for this purpose.

Parm value input rules:

  • String from 1 - 255 characters

Shown if: Shown if Threat Action is "Turn On" and any Threat Action is selected and countermeasure is "Unsolicited Alert"

Parm Name: AlertPackage

Requires:

  • OSX: 3.5+
  • MX: 4.3+

Alert Class Name

Used to specify the Class Name of the application to receive an alert during a countermeasure procedure.

Note: The Package Name of the application to receive the alert also must be specified. The Package Name can be acquired from the application developer, a lookup of the Package Name on the device, or extracted from the APK file using developer tools designed for this purpose.

Parm value input rules:

  • String from 1 - 255 characters

Shown if: Shown if Threat Action is "Turn On" and any Threat Action is selected and countermeasure is "Unsolicited Alert"

Parm Name: AlertClass

Requires:

  • OSX: 3.5+
  • MX: 4.3+

Alert Message

Used to specify a message to send to the application intended to receive the alert during a countermeasure procedure. The message is included as an intent extra named AlertMessage.

Parm value input rules:

  • String from 1-255 characters containing the intent extra AlertMessage

Shown if: Shown if Threat Action is "Turn On" and any Threat Action is selected and countermeasure is "Unsolicited Alert"

Parm Name: AlertMsg

Requires:

  • OSX: 3.5+
  • MX: 4.3+

Signal Occurrence of Threat

Controls whether signaling is triggered by an externally detected threat warning, such as from a Mobile Device Management (MDM) system.

Parm Name: SignalOccurrenceOfThreat

Option Name Description Note Requires
0 Do nothing Performs no signaling when an externally occurring Threat is detected.

OSX: 3.5+

MX: 4.3+

1 Signal Occurrence Signals the occurrence of an externally detected Threat.

OSX: 3.5+

MX: 4.3+

Send Threat Message

Permits a message to be specified describing a custom threat that has occurred.

Parm value input rules:

  • String from 1 - 255 characters

Parm Name: SendThreatMsg

Requires:

  • OSX: 3.5+
  • MX: 4.3+

Periodic Scan

This is the On/Off switch for Periodic Scans on the device, which detect apps with the "super-user" permissions and other characteristics generally associated with root-based malware. When Periodic Scan is disabled, Threat detection scanning occurs each time the device boots. When enabled, scans are performed according to the interval specified in the Periodic Scan Interval parameter. Scan frequency can effect battery life.

Shown if: Shown if Threat Action is "Turn On"

Parm Name: PeriodicScan

Option Name Description Note Requires
0 Do nothing This value (or the absence of this parm from the XML) will make no change to whether the Periodic Scan feature is enabled; any previously selected setting will be retained.

OSX: 3.5+

MX: 6.1+

1 Turn On Enables Periodic Scans to be performed on the device.

OSX: 3.5+

MX: 6.1+

2 Turn Off Disables the Periodic Scan feature on the device.

OSX: 3.5+

MX: 6.1+

Perodic Scan Interval

Used to specify the time, in minutes, to wait between Periodic Scans performed on the device. Minimum scan interval is one minute; maximum is 1440 minutes (24 hrs.). If Periodic Scan is enabled and no scan interval is specified, a value of 30 (min.) will be used. Periodic Scans detect apps with the "super-user" permissions and other characteristics generally associated with root-based malware. Scan frequency can effect battery life.

Parm value input rules:

  • Integer from 1 - 1440 (min.)

Shown if: Shown if Threat Action is "Turn On" and Periodic Scan is "Turn On"

Parm Name: PeriodicScanInterval

Requires:

  • OSX: 3.5+
  • MX: 6.1+

Extra Scan Folders

This is the On/Off switch for folder monitoring. This Extra Scan Folders feature monitors one or more folders on the device (including those in Android-protected areas) as specified in the Extra Scan Folders List parameter. When a change within a monitored folder occurs, ThreatMgr broadcasts an Intent with the folder name and one of the Android FileObserver constants to describe the event.

This parameter does not detect Threats.

Parm Name: ExtraScanFolders

Option Name Description Note Requires
0 Do nothing This value (or the absence of this parm from the XML) will make no change to Folder Monitoring; any previously selected setting will be retained.

OSX: 3.5+

MX: 6.1+

1 Turn On Enables folder monitoring, and sends an Intent when changes occur to the specified folder(s).

OSX: 3.5+

MX: 6.1+

2 Turn Off Disables folder monitoring, and causes the device to ignore changes to the specified folder(s).

OSX: 3.5+

MX: 6.1+

Extra Scan Folders List

Used to specify one or more folders on the device to monitor for changes, including folders in protected areas of an Android device. Folder(s) specified in this parameter replace any previously specified folder(s). To add a folder to an existing folder list, specify the entire (comma-separated) list including the new folder.

This parameter does not detect Threats.

Parm value input rules:

  • String from 1 - 255 characters containing comma-separated list of fully qualified path(s) to folder(s) on the device. Replaces any previously specified folder list.

Parm Name: ExtraScanFoldersList

Requires:

  • OSX: 3.5+
  • MX: 6.1+

Examples

Turn On externally detected Threat


<wap-provisioningdoc>
<characteristic type="ThreatMgr" version="4.3">
   <parm name="ThreatAction" value="1" />
   <parm name="ThreatName" value="ExternallyDetected" />
<characteristic type="CounterMeasure">
   <parm name="FormatSdcard" value="1" />
   <parm name="FactoryReset" value="1" />
   <parm name="WipeSecureStorageKeys" value="1" />
   <parm name="LockDevice" value="1" />
 </characteristic>
</characteristic>
</wap-provisioningdoc>

Turn Off externally detected Threat


<wap-provisioningdoc>
<characteristic type="ThreatMgr" version="4.3">
   <parm name="ThreatAction" value="2" />
   <parm name="ThreatName" value="ExternallyDetected" />
</wap-provisioningdoc>

Query the current Threat configuration


<wap-provisioningdoc>
    <characteristic-query type="ThreatMgr"/>
</wap-provisioningdoc>

Generate an Unsolicited Alert


<wap-provisioningdoc>
   <characteristic type="ThreatMgr" version="4.3">
      <parm name="ThreatAction" value="1" />
      <parm name="ThreatName" value="MaxPasswordAttempts" />
      <characteristic type="CounterMeasure">
         <parm name="UnsolicitedAlert" value="1" />
         <parm name="AlertPackage" value="com.example.testapp" />
         <parm name="AlertClass" value="com.example.testapp.testactivity" />
         <parm name="AlertMsg" value="MaxPasswordAttempts has been reached" />
      </characteristic>
   </characteristic>
</wap-provisioningdoc>

The XML above enables detection of the “MaxPasswordAttempts" threat on devices running Zebra Multi-user MX, and sets the countermeasure to trigger an unsolicited alert, an explicit intent sent to the package and class defined in the “AlertPackage" and “AlertClass" parameters. In this example, the intent is sent to the "testactivity" class of the "com.example.testapp" package, and includes an “AlertMessage" extra with the value of “MaxPasswordAttempts has been reached."

Note: Zebra Multi-user MX has been discontinued, rendering the MaxPasswordAttempts feature inoperable on most devices.

Assuming that the “testactivity" class has already been created, this explicit intent can be handled by overriding the onNewIntent method. The following JavaScript code illustrates how this could be done:


@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);

    if (intent.hasExtra("AlertMessage")) {
        String AlertMessage = intent.getStringExtra("AlertMessage");
        if (AlertMessage.equalsIgnoreCase("MaxPasswordAttempts has been reached")) {
           // Perform an action
        }
        // Additional if statement could be used to handle other messages
    }
}

Important: For the onNewIntent method to be called, the activity must use the android:launchMode="singleTop" modifier for the corresponding activity in the Android manifest. If the “testactivity" has not yet been created, then onNewIntent will NOT be called, and handling of this intent must be done in the onCreate method.