Skip to main content

Install the Huntress Agent for macOS - Critical Steps for Complete 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 requires additional setup to ensure Host Isolation and full EDR functionality.

 

Huntress Managed EDR is available for macOS endpoints. While parts 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 Host 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

Get Your Keys First

Install with MDM

Install with RMM

Install Manually

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 during the network content filter installation. 
This shouldn’t be noticeable in most cases, but special attention should be paid when using VPN's, RDP, and other remote access tooling which may lose connection and require you to reconnect. We highly recommend you plan the installation for a time when this network disconnect is acceptable.

 

Get Your Keys First

There are three primary avenues of installation: MDM, RMM, and Manually.

  • For groups of endpoints (greater than 5), an automated installation is the way to go. There are two options:
    • MDM only - Recommended: does everything silently in the same tool
    • RMM only - large-scale deployment, but requires manual approvals and granting of FDA on each endpoint
  • 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.

 

Regardless of your installation method, you need your Huntress Account key.

 

  1. Log in to Huntress and go to the Agent Setup page.
    Screenshot 2024-06-26 at 10.22.06 AM.png
  2. Expand the Get Your Keys section and copy your Account key. Existing organization keys can be found on your Organizations tab. If you use Agent tags, have those ready as well.
mceclip0.png


 

Then, choose your install method:

Install with MDM

Install with RMM

Install Manually

 

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. Configure the MDM policy for your specific tool:
    • 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. Download the Huntress mobileconfig and then upload into the Profile section of your MDM (sometimes called PPPC, Profile, or Policy).
      • Specific MDM Installation Instructions below.
  2. Deploy the policy to your endpoints. This allows for a “silent” install of the Huntress software after the following steps.
  3. Add the generic deployment script for the Huntress software to the Software section of your MDM (or from the supported software pages below).
    • Update Line 43 with your Account Key.
    • Update Line 47 with an assigned Organization Key.
    • Update Line 51 with the name of your management solution (i.e. Jamf Pro). This value is used for support.
  4. Deploy the Huntress software to 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.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 presented with any prompts, double-check that you have the most up-to-date version of the Huntress-provided mobileconfig and 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.

 

Specific MDM Installation Instructions

 

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. Upload a Huntress deployment script in your RMM to your automation library or software of your RMM. If your RMM is not in our list below, you can leverage the Generic RMM instructions.
    • Update Line 43 with your Account Key.
    • Update Line 47 with an assigned Organization Key.
    • Update Line 51 with the name of your management solution (i.e. NinjaOne). This value is used for support.
  2. Deploy the Huntress agent to your endpoints.

  3. Open the Huntress Installation Wizard on the endpoint by double-clicking the Huntress app in the /Applications directory.

    It can also be opened directly from the command line by running the following:

    /Applications/Huntress/Contents/MacOS/Huntress
  4. Step through the Huntress Installation Wizard prompts: this will install the system extension and approve FDA for both the system extension and Huntress agent, as well as approve the network content filter.

For more information on using the Wizard, please review our Huntress Configuration Wizard for macOS article.

 

Specific RMM Installation Instructions:

 

Install Manually

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

  1. Install the Huntress Agent with the GUI or from the command line:
  2. If the Huntress Configuration Wizard for macOS does not automatically display after install completes, you can manually open the Wizard on the endpoint by double-clicking the Huntress app in the /Applications directory.
    • It can also be opened directly from the command line by running the following:
      • /Applications/Huntress/Contents/MacOS/Huntress
  3. Step through the Huntress Installation Wizard prompts: this will install the system extension and approve FDA for both the system extension and Huntress agent, as well as approve the network content filter.

For more information on using the Wizard, please review our Huntress Configuration Wizard for macOS article.

 

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.

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

Filters available for the Agents page

Agent Overview page

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

macOS Agent Readiness panel

From Command line

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

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

For versions before 0.14.26 you can use this command:

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

If everything has been properly installed and provisioned, the output should look similar to this (0.14.26+):

Full Disk Access for Agent: true
Extension Status: installed
Full Disk Access for Extension: true
EDR status: enabled
Preauthorization Status: granted

 

 

 

Related articles