Schedule scans with Microsoft Defender for Endpoint on macOS

  • Article

Applies to:

Want to experience Microsoft Defender for Endpoint? Sign up for a free trial.

Schedule a scan built into 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 samples in this article.

Prerequisites:

Schedule a scan with 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 here, see About Information Property List Files at the official Apple developer website.

The following sample shows the daily and/or weekly configuration for the scheduled scan on macOS.

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.

The following code shows the schema you need to use to schedule scans according to the requirements mentioned earlier.

  1. Open a text editor and use this example as a guide for your own scheduled scan file.

For 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>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>
  1. Save the file as com.microsoft.wdav.mobileconfig.

For JamF and other 3rd-party MDMs

<?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 the following example, an hourly quick scan will run every 6 hours, a daily quick scan configuration is set to run at 885 minutes after midnight (2:45 p.m.), and a weekly full scan will run on Wednesdays at 880 minutes after midnight (2:40 p.m).

For 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>
  1. Save the file as com.microsoft.wdav.mobileconfig.

For JamF and other 3rd-party MDMs

  1. Open a text editor and use this example.
<?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.

  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].

Option 3: Configure scheduled scans through CLI tool

To enable 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.

For other configuration options:

  • 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

Use the following command:

mdatp scan list

Screenshot of schedule ran. \<snip\>

Screenshot of schedule ran successfully.

Important

Scheduled scans do not 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.

Tip

Do you want to learn more? Engage with the Microsoft Security community in our Tech Community: Microsoft Defender for Endpoint Tech Community.