Edit

Schedule scans with Microsoft Defender for Endpoint on macOS

  • Applies to: Microsoft Defender for Endpoint Plan 1, Microsoft Defender for Endpoint Plan 2

This article explains how to configure scheduled scans in Microsoft Defender for Endpoint on macOS using the built-in scheduled scan settings, plist configuration profiles, or the mdatp command-line tool. Review the prerequisites before you begin.

Use the built-in scheduled scan settings in Microsoft Defender for Endpoint on macOS

While you can start a threat scan at any time with Microsoft Defender for Endpoint, your enterprise might benefit from scheduled or timed scans. For example, you can schedule a scan to run at the beginning of every workday or week.

There are three types of scheduled scans that are configurable: hourly, daily, and weekly scans. Hourly and daily scheduled scans are always run as quick scans, weekly scans can be configured to be either quick or full scans. It's possible to have all three types of scheduled scans at the same time. See the daily and weekly scan example and the hourly, daily, and weekly scan example.

Prerequisites:

  • Platform Update version: 101.23122.0005 or newer.

Schedule scans by deploying a plist in Microsoft Defender for Endpoint on macOS

You can create a scheduled scan for your macOS, which is built in to Microsoft Defender for Endpoint on macOS.

For more information on the .plist file format used in these examples, see the Apple Information Property List file reference, which describes the XML key-value structure used to define configuration profiles on macOS.

The daily and weekly scheduled scan plist configuration for macOS uses the parameters described in the following table.

Tip

Schedules are based on the local time zone of the device.

Parameter The acceptable values for this parameter are:
scheduledScan enabled or disabled
scanType quick or full
ignoreExclusions true or false
lowPriorityScheduledScan true or false
dayOfWeek The range is between 0 and 8.
- 0: Everyday
- 1: Sunday
- 2: Monday
- 3: Tuesday
- 4: Wednesday
- 5: Thursday
- 6: Friday
- 7: Saturday
- 8: Never
timeOfDay Specifies the time of day, as the number of minutes after midnight, to perform a scheduled scan. The time refers to the local time on the computer. If you don't specify a value for this parameter, a scheduled scan runs at a default time of two hours after midnight.
interval 0 (never), every 1 (hour) to every 24 (hours, one scan per day)
randomizeScanStartTime Only applicable for daily quick scans or weekly quick/full scans. Randomize the start time of the scan by up to specified number of hours.
For example, if a scan is scheduled for 2 p.m and randomizeScanStartTime is set to 2, the scan commences at a random time between 2 p.m and 4 p.m.

Your scheduled scan runs at the date, time, and frequency you defined in your plist.

Example 1: Schedule a daily quick scan and weekly full scan using a plist

In the following example, the daily quick scan configuration is set to run at 885 minutes after midnight (2:45 p.m.). The weekly configuration is set to run a full scan on Wednesday at 880 minutes after midnight (2:40 p.m.). And it's set to ignore exclusions and run a low-priority scan.

Use the plist schema shown here to configure a daily quick scan and a weekly full scan with the scheduled scan parameters described in the scheduled scan parameter table in this article.

Open a text editor and use the Intune mobileconfig and JamF plist examples that follow as a guide for your own scheduled scan file.

For Intune

The following mobileconfig plist sample defines a complete Intune configuration profile that enables scheduled scanning with a daily quick scan and a weekly full scan.

<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> 
<plist version="1.0"> 
<dict> 
    <key>PayloadUUID</key>
    <string>C4E6A782-0C8D-44AB-A025-EB893987A295</string>
    <key>PayloadType</key>
    <string>Configuration</string>
    <key>PayloadOrganization</key>
    <string>Microsoft</string>
    <key>PayloadIdentifier</key>
    <string>C4E6A782-0C8D-44AB-A025-EB893987A295</string>
    <key>PayloadDisplayName</key>
    <string>Microsoft Defender for Endpoint settings</string>
    <key>PayloadDescription</key>
    <string>Microsoft Defender for Endpoint configuration settings</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
    <key>PayloadEnabled</key>
    <true/>
    <key>PayloadRemovalDisallowed</key>
    <true/>
    <key>PayloadScope</key>
    <string>System</string>
    <key>PayloadContent</key>
    <array>
        <dict>
            <key>PayloadUUID</key>
            <string>99DBC2BC-3B3A-46A2-A413-C8F9BB9A7295</string>
            <key>PayloadType</key>
            <string>com.microsoft.wdav</string>
            <key>PayloadOrganization</key>
            <string>Microsoft</string>
            <key>PayloadIdentifier</key>
            <string>99DBC2BC-3B3A-46A2-A413-C8F9BB9A7295</string>
            <key>PayloadDisplayName</key>
            <string>Microsoft Defender for Endpoint configuration settings</string>
            <key>PayloadDescription</key>
            <string/>
            <key>PayloadVersion</key>
            <integer>1</integer>
            <key>PayloadEnabled</key>
            <true/>
            <key>features</key> 
            <dict>
                <key>scheduledScan</key> 
                <string>enabled</string> 
            </dict> 
            <key>scheduledScan</key> 
            <dict> 
                <key>ignoreExclusions</key> 
                <true/> 
                <key>lowPriorityScheduledScan</key> 
                <true/> 
                <key>dailyConfiguration</key> 
                <dict> 
                    <key>timeOfDay</key> 
                    <integer>880</integer> 
                </dict> 
                <key>weeklyConfiguration</key> 
                <dict> 
                    <key>dayOfWeek</key> 
                    <integer>4</integer> 
                    <key>timeOfDay</key> 
                    <integer>885</integer> 
                    <key>scanType</key> 
                    <string>full</string>
                </dict>
            </dict> 
        </dict>
    </array>
</dict> 
</plist>
  • Save the file as com.microsoft.wdav.mobileconfig.

For JamF and other third-party MDMs

The following plist sample configures the same daily quick scan and weekly full scan settings for JamF and other third-party MDM solutions. Save this content as com.microsoft.wdav.plist.

<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> 
<plist version="1.0"> 
<dict> 
    <key>features</key> 
    <dict> 
        <key>scheduledScan</key> 
        <string>enabled</string> 
    </dict> 
    <key>scheduledScan</key> 
    <dict> 
        <key>ignoreExclusions</key> 
        <true/> 
        <key>lowPriorityScheduledScan</key> 
        <true/> 
        <key>dailyConfiguration</key> 
        <dict> 
            <key>timeOfDay</key> 
            <integer>885</integer> 
        </dict> 
        <key>weeklyConfiguration</key> 
        <dict> 
            <key>dayOfWeek</key> 
            <integer>4</integer> 
            <key>timeOfDay</key> 
            <integer>880</integer> 
            <key>scanType</key> 
            <string>full</string> 
        </dict> 
    </dict> 
</dict> 
</plist>

  1. Save the file as com.microsoft.wdav.plist.

  2. Check that the scheduled scan is configured via a "Set Preference"

    mdatp health --details scheduled_scan

In the results, you should be able to see [managed].

Example 2: Schedule an hourly quick scan, a daily quick scan, and weekly full scan using a plist

In this hourly, daily, and weekly scheduled scan example, an hourly quick scan runs every 6 hours, a daily quick scan is set to run at 885 minutes after midnight (2:45 p.m.), and a weekly full scan runs on Wednesdays at 880 minutes after midnight (2:40 p.m.).

Open a text editor and use the Intune mobileconfig and JamF plist examples that follow as a guide for your own scheduled scan file.

For Intune:

The following mobileconfig plist sample packages the hourly, daily, and weekly Defender scheduled scan settings into a complete Intune configuration profile. Use this sample to deploy the scheduled scan configuration through Intune.

<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> 
<plist version="1.0"> 
<dict> 
     <key>PayloadUUID</key>
     <string>C4E6A782-0C8D-44AB-A025-EB893987A295</string>
     <key>PayloadType</key>
     <string>Configuration</string>
     <key>PayloadOrganization</key>
     <string>Microsoft</string>
     <key>PayloadIdentifier</key>
     <string>C4E6A782-0C8D-44AB-A025-EB893987A295</string>
     <key>PayloadDisplayName</key>
     <string>Microsoft Defender for Endpoint settings</string>
     <key>PayloadDescription</key>
     <string>Microsoft Defender for Endpoint configuration settings</string>
     <key>PayloadVersion</key>
     <integer>1</integer>
     <key>PayloadEnabled</key>
     <true/>
     <key>PayloadRemovalDisallowed</key>
     <true/>
     <key>PayloadScope</key>
     <string>System</string>
     <key>PayloadContent</key>
     <array>
       <dict>
           <key>PayloadUUID</key>
           <string>99DBC2BC-3B3A-46A2-A413-C8F9BB9A7295</string>
           <key>PayloadType</key>
           <string>com.microsoft.wdav</string>
           <key>PayloadOrganization</key>
           <string>Microsoft</string>
           <key>PayloadIdentifier</key>
           <string>99DBC2BC-3B3A-46A2-A413-C8F9BB9A7295</string>
           <key>PayloadDisplayName</key>
           <string>Microsoft Defender for Endpoint configuration settings</string>
           <key>PayloadDescription</key>
           <string/>
           <key>PayloadVersion</key>
           <integer>1</integer>
           <key>PayloadEnabled</key>
           <true/>
    <key>features</key> 
    <dict> 
        <key>scheduledScan</key> 
        <string>enabled</string> 
    </dict> 
<key>scheduledScan</key> 
<dict> 
    <key>ignoreExclusions</key> 
    <true/> 
    <key>lowPriorityScheduledScan</key> 
    <true/> 
    <key>dailyConfiguration</key> 
    <dict> 
        <key>timeOfDay</key> 
        <integer>885</integer> 
        <key>interval</key> 
        <string>1</string> 
    </dict> 
    <key>weeklyConfiguration</key> 
    <dict> 
        <key>dayOfWeek</key> 
        <integer>4</integer> 
        <key>timeOfDay</key> 
        <integer>880</integer> 
        <key>scanType</key> 
        <string>full</string> 
        </dict> 
        </dict> 
    </dict> 
</array>
</dict>
</plist>
  • Save the file as com.microsoft.wdav.mobileconfig.

For JamF and other third-party MDMs

The following plist sample configures the same hourly, daily, and weekly scheduled scan settings for JamF and other third-party MDM solutions. Save this content as com.microsoft.wdav.plist.

    <?xml version="1.0" encoding="UTF-8"?> 
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.  dtd"> 
    <plist version="1.0"> 
    <dict> 
        <key>features</key> 
        <dict> 
            <key>scheduledScan</key> 
            <string>enabled</string> 
        </dict> 
    <key>scheduledScan</key> 
    <dict> 
        <key>ignoreExclusions</key> 
        <true/> 
        <key>lowPriorityScheduledScan</key> 
        <true/> 
        <key>dailyConfiguration</key> 
        <dict> 
            <key>timeOfDay</key> 
            <integer>885</integer> 
            <key>interval</key> 
            <string>1</string> 
        </dict> 
        <key>weeklyConfiguration</key> 
        <dict> 
            <key>dayOfWeek</key> 
            <integer>4</integer> 
            <key>timeOfDay</key> 
            <integer>880</integer> 
            <key>scanType</key> 
            <string>full</string> 
            </dict> 
            </dict> 
        </dict> 
    </plist>
  1. Save the file as com.microsoft.wdav.plist.

Upload the plist file to Jamf Pro

Use these steps to upload either of the JamF plist examples from Example 1 or Example 2 to Jamf Pro:

  1. Go to Computers > Configuration Profiles.

  2. Create a new profile.

  3. Add Application & Custom Settings.

  4. Set the Preference Domain to com.microsoft.wdav.

  5. Paste the contents of the .plist file into the configuration field.

  6. Check that the scheduled scan is configured via a "Set Preference"

    mdatp health --details scheduled_scan

    In the results, you should be able to see [managed].

Configure scheduled scans using the mdatp CLI

The Microsoft Defender for Endpoint command-line tool (mdatp) provides commands to configure scheduled scans directly from the terminal.

To enable the scheduled scan feature:

Version Command
Version 101.23122.x or later sudo mdatp config scheduled-scan settings feature --value enabled

To schedule hourly quick scans:

Version Command
Version 101.23122.x or later sudo mdatp config scheduled-scan quick-scan hourly-interval --value \<arg\>

Screenshot of schedule hourly scan.

To schedule daily quick scans:

Version Command
Version 101.23122.x or later sudo mdatp config scheduled-scan quick-scan time-of-day --value \<arg\>

Screenshot of schedule daily quick scan.

To schedule weekly scans:

Version Command
Version 101.23122.x or later sudo mdatp config scheduled-scan weekly-scan --day-of-week \<arg\> --time-of-day \<arg\>--scan-type \<arg\>

Screenshot of schedule weekly scan.

You can also configure definition updates and low-priority threading for scheduled scans:

  • To check for definitions update before scheduled scans:

    sudo mdatp config scheduled-scan settings check-for-definitions --value true

  • To use low priority threads for scheduled scanning:

    sudo mdatp config scheduled-scan settings low-priority --value true

Check that the scheduled scan ran

To list completed scheduled scans and their results, run mdatp scan list:

Screenshot of schedule ran. \<snip\>

Screenshot of schedule ran successfully.

Important

Scheduled scans don't run at the scheduled time while the device is asleep. Instead, scheduled scans run when the device resumes from sleep mode. If the device is turned off, the scan runs at the next scheduled scan time.

  • Last updated on