Skip to main content

Critical Steps for Complete macOS EDR Deployment

Melissa
  • Updated

Team: Huntress Managed Managed Endpoint Detection and Response (EDR)
Product: Huntress Agent for macOS
Environment: macOS
Summary: Using Huntress EDR on a macOS endpoint has some additional setup needed for the system extension and network content filter, which are both required for endpoint isolation.

 

Huntress Managed EDR is available for macOS endpoints. While most of the macOS experience is similar to Windows, there are some differences in the installation process for macOS endpoints. For the full Huntress management capabilities, including endpoint isolation - there are three additional parts to installation:

  • The Huntress Agent requires Full Disk Access (FDA)
  • The Huntress system extension needs FDA and end user approval
  • The network content filter needs end user approval

Fortunately, we’ve put together some scripts, packages, and mobilconfig policies to make this easier and streamline the deployment of the Huntress Agent to many endpoints through automation tools.

You can still install the Huntress Agent manually,  if you want. However, this method presents several prompts to the user that must be manually approved, and so must be planned to avoid surprising the user with dialogs asking for their permission.

In this article

Before You Begin

Installation Methods

Install with MDM

Install with MDM and RMM

Install with RMM

Install Manually

Troubleshooting UI prompts (Manual install)

Verify Agent Communication

Before You Begin

Make sure your endpoints are ready:

It is possible that there might be a split second where the endpoint loses network connectivity. This shouldn’t be noticeable in most cases, but if there are any programs that need an uninterrupted network connection, plan the installation for a time when this is acceptable.

Installation Methods

Decide if you’re going to install manually or use a tool like an MDM or RMM.

  • We recommend manual installs for individual endpoints. This is best when you’re doing a proof-of-concept project or have a very small set of endpoints.
  • For larger groups of endpoints, an automated installation is the way to go. There are three options:
    • MDM only - does everything silently in the same tool
    • MDM and RMM - grant FDA and approval in the MDM policy and deploy the Agent script through an RMM
    • RMM only - large-scale deployment, but requires manual approvals and granting of FDA on each endpoint

You can see the process in action by watching this video.

Install with MDM

Using an MDM installs the Huntress Agent on your macOS endpoints without being visible to the end user. The MDM policy bundles the necessary FDA and approvals for the Agent, the system extension, and the network content filter.

  1. Log in to Huntress and go to the Agent Setup page.Screenshot 2024-06-26 at 10.22.06 AM.png
  2. Get your Account and Organization keys. If you use Agent tags, have those ready as well. Screenshot 2024-06-25 at 6.03.46 PM.png
  3. Configure the MDM policy for your specific tool:
    • Addigy
    • General MDM instructions
      • Use the Huntress macOS MDM mobileconfig file to configure your policy to allow the installation of the Huntress Agent, system extension, and the network content filter.
      • If you need to create a policy manually, follow the unsupported MDM policy instructions.
  4. Deploy the MDM policy configuration that you made in step 2 out to the endpoints. 

    This will include the Huntress Agent, system extension, and the network content filter, as well as enabling FDA and approving the changes.

  5. Check that all Agents have been installed properly on the endpoints, with FDA and necessary approvals for the Huntress system extension and the network content filter.

    These profile settings are at the device level and always override changes made by the user in the System Settings app. This might result in FDA appearing to be disabled when viewed by the end user but actually enabled due to the device-level settings profile. Do not make changes at the user level.

With a properly configured MDM policy, the Agent and the system extension should install silently, with FDA and the network content filter, without prompting the user for approval.

If the user is asked to approve the extension or allow control of network traffic, double-check that you have created the necessary profiles for the system extension and network content filter, entered everything correctly in the MDM policy, and deployed that policy out to the endpoints.

Install with MDM and RMM

If you prefer to use an RMM to deploy the Agent, you can still achieve a silent install by using an MDM for the endpoint policy first.

  1. Log in to Huntress and go to the Agent Setup page.Screenshot 2024-06-26 at 10.22.06 AM.png
  2. Get your Account and Organization keys. If you use Agent tags, have those ready as well. Screenshot 2024-06-25 at 6.03.46 PM.png
  3. Create the MDM profile or policy for approvals and FDA. Deploy the policy to your endpoints.
    • Addigy
    • General MDM instructions
      • Use the Huntress macOS MDM mobileconfig file to configure your policy to allow the installation of the Huntress Agent, system extension, and the network content filter.
      • If you need to do it manually, follow the unsupported MDM instructions.
  4. Use your RMM to install the Agent on your endpoints.
  5. Check that all Agents have been installed properly on the endpoints, with FDA and necessary approvals for the Huntress system extension and the network content filter.

 

Install with RMM

Using an RMM to deploy the Agent to many endpoints still requires installing the system extension, providing FDA to the Agent and the system extension, and providing the necessary approvals for each endpoint.

  1. Log in to Huntress and go to the Agent Setup page.Screenshot 2024-06-26 at 10.22.06 AM.png
  2. Get your Account and Organization keys. If you use Agent tags, have those ready as well. Screenshot 2024-06-25 at 6.03.46 PM.png
  3. Configure the Agent deployment for your specific RMM:
  4. Install the system extension one of two ways:
    • From the Huntress platform, install it in the Incomplete macOS Installation table. You can install it in bulk from here. d4502c1a-7d76-4dea-aaea-db42ac67129d
    • Or from the command line, you can run: 
      sudo /Applications/Huntress.app/Contents/MacOS/Huntress extensionctl install --preauthorize
  5. On each endpoint, allow Huntress to install the system extension. 
    1. When prompted, select Open System Settings.

      Apple Open System Settings dialog

    2. For macOS Sonoma 14 and below, select App Store and identified developers and click Allow.

      Apple Allow App Downloads from Huntress dialog


      For macOS Sequoia 15.1 and above, go the General pane, click on Login Items & Extensions, and then Endpoint Security Extensions. From there toggle  the extension On.

      Note: Sequoia 15.0 will not work as expected and is not considered supported. Please update to 15.1. 



  6. Allow Huntress to Filter Network Content. 

Grant Full Disk Access to the Huntress Agent and the system extension.

Note: Sequoia 15.0 will not work as expected and is not considered supported. Please update to 15.1. 

For macOS Ventura 13 and  newer

    1. From the endpoint, go to System Settings > Privacy & Security.
    2. Open the Full Disk Access list.
    3. Enable Huntress, which is the Agent, and the Huntress System Extension.

For macOS Monterey 12

Note: Legacy install only, please update to a newer OS as this is no longer considered supported and may not receive further fixes

    1. From the endpoint, go to System Preferences > Security & Privacy.
    2. Click the lock at the bottom left and provide your Mac password.
    3. Go to Privacy > Full Disk Access.
    4. Enable Huntress, which is the Agent, and the Huntress System Extension.


Check that all Agents have been installed properly on the endpoints, with FDA and necessary approvals for the Huntress system extension and the network content filter.

Install Manually

If you're doing a proof-of-concept test or have a small number of macOS endpoints, you might want to install the Huntress Agent without automation.

  1. Log in to Huntress and go to the Agent Setup page.Screenshot 2024-06-26 at 10.22.06 AM.png
  2. Get your Account and Organization keys. If you use Agent tags, have those ready as well. Screenshot 2024-06-25 at 6.03.46 PM.png
  3. Install the Huntress Agent with the GUI or from the command line:
    • From the Huntress platform, get the GUI installer PKG, making sure to select the Include System Extension option.

      Screenshot 2024-06-07 at 3.25.48 PM.png

    • Or download the macOS install script and run: 
      sudo zsh HuntressMacInstall.sh -a ACCOUNTKEY -o ORGNAME
  4. On each endpoint, allow Huntress to install the system extension. 
    1. When prompted, select Open System Settings.

      Apple Open System Settings dialog

    2. For macOS Sonoma 14 and below, select App Store and identified developers and click Allow.

      Apple Allow App Downloads from Huntress dialog

      For macOS Sequoia 15.1 and above, go the General pane, click on Login Items & Extensions, and then Endpoint Security Extensions. From there toggle  the extension On.

      Note: Sequoia 15.0 will not work as expected and is not considered supported. Please update to 15.1. 


  5. Allow Huntress to Filter Network Content. 

  6. Grant Full Disk Access to the Huntress Agent and the system extension.

    Note: Sequoia 15.0 will not work as expected and is not considered supported. Please update to 15.1. 

    For macOS Ventura 13 and newer

      1. From the endpoint, go to System Settings > Privacy & Security.
      2. Open the Full Disk Access list.
      3. Enable Huntress, which is the Agent, and the Huntress System Extension.

    For macOS Monterey 12

    Note: Legacy install only, please update to a newer OS as this is no longer considered supported and may not receive further fixes

      1. From the endpoint, go to System Preferences > Security & Privacy.
      2. Click the lock at the bottom left and provide your Mac password.
      3. Go to Privacy > Full Disk Access.
      4. Enable Huntress, which is the Agent, and the Huntress System Extension.

  7. Check that all Agents have been installed properly on the endpoints, with FDA and necessary approvals for the Huntress system extension and the network content filter.

 

Troubleshooting UI Prompts (non-MDM)

If you've granted Full Disk Access to both the Huntress Agent and Huntress System Extension, but the System Extension or Network Content Filter are stuck at "Requires User Approval" or "Not Installed" the OS may be hiding the prompt. Example screenshot:

When macOS prompts for permissions, if the user rejects that prompt then usually the OS will not ever display it again. Instead you'll need to go into Settings > Privacy & Security and look towards the bottom for a prompt about Huntress or System Extension application or activity being blocked (in older versions of macOS this may be under Settings > Privacy & Security > General)

Verify Agent Communication

After you've installed the Agent, the system extension, and the network content filter, there are a few ways to check that everything got set up properly. It might take 15-20 minutes for updates to appear in the platform, as the Agent sends its status with the next scan.

You can verify from Huntress or from the command line.

From Huntress

Several parts of the Huntress platform show the status and allow you to verify that things are set up and working as expected.

Command Center

The macOS Status card shows a quick count of endpoints that need setup. When you click the card, it opens the macOS Endpoint Installation page.

macOS Status card showing endpoint counts

macOS Endpoint Installation page

This is where you can filter the Incomplete macOS Installations table for different statuses.

Filters for the Incomplete macOS Installations table

From that same table, you can send bulk actions to multiple endpoints. The bulk actions available from the platform are:

  • Install System Extension
  • Approve the Huntress System Extension
  • Approve the Network Content Filter

Full Disk Access can only be granted from the System Settings for that endpoint or through an MDM policy.

 

Agents page

You can filter the table for macOS to open individual endpoints.

Filters available for the Agents page

Endpoint Overview page

Here, you can find more details in the macOS Agent Readiness panel for that specific endpoint.

macOS Agent Readiness panel

From Command line

You can also verify from the command line with administrator privileges by using these commands:

sudo /Applications/Huntress.app/Contents/MacOS/Huntress extensionctl status

If the extension and network content filter has been properly installed, the first two lines of the output should look like this:

Extension Status: installed 
Preauthorization Status: granted

 

 

 

 

Related articles