Daily Defender News
Aboutmerill.net
Microsoft Defender for Endpoint
Endpoint protection

Configure offline security intelligence updates for Microsoft Defender for Endpoint on macOS

4 September 2026Doc update+30 / −21 lines

In brief

The article now lists key prerequisites, clarifies the mirror-server and macOS update flows, improves script descriptions and links, and explains how to verify the configured offline update source.

What Defender admins need to know

Administrators should use the updated prerequisites and revised setup and verification instructions when configuring offline updates.

Summaries are generated from the documentation change itself.

Documentation change

View full page diffView on Microsoft Learn

The comparison below shows only the changed extract. Use the full-page view for complete context.

Configure offline security intelligence updates for Microsoft Defender for Endpoint on macOS

[!INCLUDE Microsoft 365 Defender rebranding]

Overview

This document describes the Offline Security Intelligence Update feature of Microsoft Defender for Endpoint on macOS.

A mirror server is any server in the customer's environment that can connect to the Microsoft cloud to download the signatures. Other macOS endpoints pull the signatures from the mirror server at a predefined interval.

Before you begin, reviewmake sure Defender for Endpoint version 101.25012.0003 or later is installed on the Prerequisites for bothmacOS endpoints, the endpoints can reach the mirror server, and the mirror server andhas internet access to download signatures. For the macOS endpoints.full list, see the prerequisites for offline security intelligence updates section later in this article.

Key benefits

The status of the offline security intelligence update can be seen on the mdatp CLI.

The process flow for downloadingfollowing diagram shows how security intelligence updates are downloaded from the Microsoft cloud to the mirror server is illustrated in the following diagram.server.

:::image type="content" source="./media/offline-update-diag-1.png" alt-text="Process flow diagram on the Mirror Server for downloading the security intelligence updates" lightbox="./media/offline-update-diag-1.png":::

The process flow forfollowing diagram shows how macOS endpoints pull and verify security intelligence updates onfrom the macOS endpoint is illustrated in the following diagram.mirror server.

:::image type="content" source="./media/offline-update-diag-2.png" alt-text="Process flow diagram on the macOS endpoint for security intelligence updates" lightbox="./media/offline-update-diag-2.png":::

Any HTTP server can be used as a mirror server. The mirror server doesn't need to have Defender for Endpoint installed.

While management and ownership of the mirror server lies solely with the customer, this section presentsthe following two sample Bash scripts that demonstrate how to use Python 3 and Caddy to set up a basic HTTP file server on macOS. These scripts are given for purposes of illustration only and should be adapted to your own specific needs and environment.

To check that the HTTP file server is set up correctly, navigate to "https://localhost:8080".

For production or advanced use cases, refer to the official documentation for each server:Python HTTP server and Caddy documentation:

Sample script: Setting up a basic HTTP file server on macOS using Python 3

The following script starts a lightweight Python 3 HTTP server that can host the downloaded offline update files from a specified directory. 

#!/bin/bash
# python_http_server.sh

<a id="caddy"></a>**Sample script: Setting up a basic HTTP file server on macOS using using Caddy**

The following script installs and configures the Caddy web server on macOS to host the downloaded offline update files.

```bash
#!/bin/bash
# caddy_http_server.sh

### Option 1: Clone the repo (preferred)

[Install git]Git on your mirror server](https://kinsta.com/knowledgebase/install-git/) on the mirror server..

Navigate to the directory where you want to clone the repo.

After cloning the repo or downloading the zipped file, the local directory structure should match the following example, which shows the downloader script and its configuration files: 

user@vm:~/mdatp-xplat$ tree linux/definition_downloader/

## Execute the offline security intelligence downloader script

To manually execute the downloader script, configure the parameters in the settings.json file (such as `downloadFolder`, `downloadMacUpdates`, and `backupPreviousUpdates`) using the field descriptions in the [downloader script settings.json field descriptions](#get-the-offline-security-intelligence-downloader-script), and use one of the following commands based on the OS of the mirror server:

On a Bash-based mirror server (Linux or macOS), run the shell script to download the latest offline definition package:
```bash
./xplat_offline_updates_download.sh

On a Windows-based mirror server, use the PowerShell version of the script to download the offline definition package: 

./xplat_offline_updates_download.ps1

We can also use the absolute path of directory (local/remote mount point) like /tmp/wdav-update/mac/production.

Once the mirror server is set up, propagate this URL to the Mac endpoints by setting it as the offlineDefinitionUpdateUrl value in the managed configuration file (mdatp_managed.json) as described in Configure the macOS endpoints for offline updates.

Configure the endpoints

Verify the configuration

To test if the settings are applied correctly on the macOS endpoints, runuse the following command:command to display the definition update status fields, including the configured offline URL and update source: 

mdatp health --details definitions

A sample output would look like the following code snippet:snippet. Verify that definitions_status shows up_to_date and definitions_update_fail_reason is empty, which indicates the offline update configuration is working correctly: 

user@vm:~$ mdatp health --details definitions

* **Automatic update**

   If the fields `automaticDefinitionUpdateEnabled` field (which controls whether Defender for Endpoint attempts automatic definition updates, as configured in the [managed JSON file](#configure-the-endpoints)) and the `offline_definition_update` (the reported status name for the `offlineDefinitionUpdate` managed config field) in the managed json are set to `true`, then the "offline security intelligence updates" are triggered automatically at periodic intervals.

   By default, this periodic interval is **8 hours**. It can be configured by setting the `definitionUpdatesInterval` parameter in the managed json.


After triggering the "offline security intelligence update" by either the automatic or manual method, verify that the update was successful by running the command: `mdatp health --details --definitions`.

VerifyThe following sample output shows the following fields:key definition health fields. Confirm that `definitions_status` is `up_to_date` and `definitions_update_fail_reason` is empty:

```Console
user@vm:~$ mdatp health --details definitions

Common troubleshooting steps

If offline security intelligence updates aren't working as expected, use the following steps to diagnose and resolve the issue.

  • Check the status of the "offline security intelligence update" feature by using the following command: 

    * `definitions_update_source_uri` is the source from where the signatures were downloaded.
* `offline_definition_url_configured` is the source from where signatures should be downloaded, the one mentioned in the managed config file.

  • Try performing theRun a connectivity test to check ifconfirm the endpoint can reach the configured mirror server is reachable from the host:and other required services: 

    mdatp connectivity test

  • Try to trigger a manualIf connectivity succeeds but definitions are still outdated, retry the definition update using the following command:manually: 

    mdatp definitions update

See also

For more details, see the following articles.