Skip to main content

EDR Agent Health API

Nick
  • Updated

Team: Huntress Managed Endpoint Detection and Response (EDR)
Product: Agent Health API
Environment: Windows (macOS in progress)
Summary:The client-side EDR Agent API provides a local web endpoint on your systems, allowing you to easily check the health, service status, versions, and connectivity of the Huntress agent via a simple web request.

Understanding Your Endpoint's Health with the EDR Agent API

To provide greater transparency and empower our customers and partners, we've introduced a local web endpoint within our EDR (Endpoint Detection and Response) agent. This feature, known as the client-side EDR Agent API, offers a simple way to gather real-time insights into the operational status of the agent directly on your systems.

What is the Client-Side EDR Agent API?

Upon installation of the EDR agent, a local-only web server automatically starts on the endpoint. This server hosts an API that allows you to query the health and status of the running agent and its components. While this API starts automatically, it can be disabled if necessary through a configuration change managed by our EDR engineering team. We are actively working to make this a self-service account configuration option in the near future.

How Can You Use It?

To access this information, you'll need to execute a script or utilize code to make a web request to the Huntress agent. This can be accomplished using various scripting languages. Common methods include PowerShell on Windows and bash on macOS.

The API endpoint is located at the following address:

http://localhost:24799/health

As long as the HuntressUpdater service is installed and running, this endpoint will be active and will return output when queried.

 

Example using PowerShell:

Invoke-RestMethod -Uri "http://localhost:24799/health" | ConvertTo-Json

 

Example using Bash:

Please note the macOS implementation of this feature isn't quite complete but you can preview it using the curl command similar to the below. This first command is easier to read but more difficult to automate, while the shorter command is the opposite.

curl --json '{"tool": "curl"}' http://localhost:24799/health | jq

The exact command you'll use will vary based on how you implement it. If in doubt, starting with a simpler command such as below may make implementation easier.

curl http://localhost:24799/health

 

Interpreting the API Output

The output from the API is structured for easy understanding and can be readily parsed by scripts for automated data extraction. Here's a breakdown of the information you'll find on a healthy system:

Let's delve into each section:

  • Status: This field provides a straightforward answer to the question: "Is the Huntress EDR running correctly?" It will display either "Healthy" or "Degraded"/"Unhealthy". A "Degraded"/"Unhealthy" status indicates an issue with the EDR deployment on that specific machine. (See the Troubleshooting section below for more details).

  • Services: This section lists all the installed EDR services on the endpoint and their current status as reported by the local service manager. Possible states include "Running", "Stopped", "Pending", and others.

  • Versions: Here, you'll find the version numbers for the various EDR components installed on the system. This information is valuable for ensuring your deployment is up-to-date.

  • Connectivity: This section displays the last successful communication timestamps for key EDR components with our backend servers.

Troubleshooting Common Issues

Here's a guide to interpreting the API output and addressing potential problems:

  • The "Status" is showing as "Unhealthy":

    • Examine the other sections of the output for any immediate clues, such as stopped services.
    • If the cause remains unclear, collect the local Huntressagent logs from a path like "C:\Program files\Huntress\HuntressAgent.log" and reach out to our support team via Support@Huntress.com.

  • One or more of the services is showing a "stopped" state:

    • Investigate if other security tools on the endpoint might be interfering with the EDR components.
    • Verify that the recommended exclusions for our binaries and network paths are properly configured within your security solutions.
    • Allow List Huntress in Third Party Security Software. 

  • One of the versions is empty or missing:

    • If the endpoint is configured as a "SIEM Only" deployment or is running an older operating system (pre-Windows 8), the "Rio" and "Huntmon" components will not be present and will therefore be missing from the list.
    • Alternatively, this can mean the corresponding service is not running. I.E. if "agent" version is listed as 0 then the HuntressAgent service is likely experiencing a stoppage or 3rd party interference.

  • One or more of the dates are missing from the "Connectivity" section:

  • You are receiving a "Invoke-RestMethod : Unable to connect to the remote server" prompt:
    • This typically indicates that the Huntress Updater Service (HuntressUpdater) is not running/started.
    • You can try the following command to start up the service (run in the SYSTEM user context) 
      • sc.exe start HuntressUpdater

We hope this information empowers you to better understand the health and connectivity of the Huntress EDR agent on your endpoints. If you have any questions or require further assistance, please don't hesitate to contact our support team.

Related articles