Schedule scans with Microsoft Defender for Endpoint on macOS

Applies to:

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

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.

Schedule a scan with launchd

You can create a scanning schedule using the launchd daemon on a macOS device.

  1. The following code shows the schema you need to use to schedule a scan. Open a text editor and use this example as a guide for your own scheduled scan file.

    For more information on the .plist file format used here, see About Information Property List Files at the official Apple developer website.

    <?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>Label</key>
        <string>com.microsoft.wdav.schedquickscan</string>
        <key>ProgramArguments</key>
        <array>
            <string>sh</string>
            <string>-c</string>
            <string>/usr/local/bin/mdatp scan quick</string>
        </array>
        <key>RunAtLoad</key>
        <true/>
        <key>StartCalendarInterval</key>
        <dict>
            <key>Day</key>
            <integer>3</integer>
            <key>Hour</key>
            <integer>2</integer>
            <key>Minute</key>
            <integer>0</integer>
            <key>Weekday</key>
            <integer>5</integer>
        </dict>
        <key>WorkingDirectory</key>
        <string>/usr/local/bin/</string>
    </dict>
    </plist>
    
  2. Save the file as com.microsoft.wdav.schedquickscan.plist.

    Tip

    To run a full scan instead of a quick scan, change line 12, <string>/usr/local/bin/mdatp scan quick</string>, to use the full option instead of quick (i.e. <string>/usr/local/bin/mdatp scan full</string>) and save the file as com.microsoft.wdav.schedfullscan.plist instead of com.microsoft.wdav.schedquickscan.plist.

  3. Open Terminal.

  4. Enter the following commands to load your file:

    launchctl load /Library/LaunchDaemons/<your file name.plist>
    launchctl start <your file name>
    
  5. Your scheduled scan will run at the date, time, and frequency you defined in your p-list. In the example, the scan runs at 2:00 AM every Friday.

    The Weekday value of StartCalendarInterval uses an integer to indicate the fifth day of the week, or Friday.

Important

Agents executed with launchd will not run at the scheduled time while the device is asleep. They will instead run once the device resumes from sleep mode.

If the device is turned off, the scan will run at the next scheduled scan time.

Schedule a scan with Intune

You can also schedule scans with Microsoft Intune. The runMDATPQuickScan.sh shell script available at Scripts for Microsoft Defender for Endpoint will persist when the device resumes from sleep mode.

See Use shell scripts on macOS devices in Intune for more detailed instructions on how to use this script in your enterprise.