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.

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

Schedule a quick scan

The following code shows the schema you need to use to schedule a quick scan.

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

    <?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 to the /Library/LaunchDaemons directory.

Schedule a full scan

  1. Open a text editor and use this example for a 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>Label</key>
        <string>com.microsoft.wdav.schedfullscan</string>
        <key>ProgramArguments</key>
        <array>
            <string>sh</string>
            <string>-c</string>
            <string>/usr/local/bin/mdatp scan full</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>50</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.schedfullscan.plist to the /Library/LaunchDaemons directory.

Load your file

  1. Open Terminal.

  2. Enter the following commands to load your file:

    chown root:wheel /Library/LaunchDaemons/com.microsoft.wdav.sched*
    chmod 644 /Library/LaunchDaemons/com.microsoft.wdav.sched*
    xattr -c /Library/LaunchDaemons/com.microsoft.wdav.sched*     
    launchctl load -w /Library/LaunchDaemons/<your file name.plist>
    
  3. Your scheduled scan will run at the date, time, and frequency you defined in your p-list. In the previous examples, the scan runs at 2:50 AM every Friday.

    • The Weekday value of StartCalendarInterval uses an integer to indicate the fifth day of the week, or Friday. The range is between 1 and 7 with 7 representing Sunday.
    • The Day value of StartCalendarInterval uses an integer to indicate the third day of the month. The range is between 1 and 31.
    • The Hour value of StartCalendarInterval uses an integer to indicate the second hour of the day. The range is between 0 and 23. The Minute value of StartCalendarInterval uses an integer to indicate fifty minutes of the hour. The range is between 0 and 59.

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.