Skip to main content

EDR Agent Health API (localhost)

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 (via localhost), 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". A "Degraded" 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", or “missing”.
  • Versions: Here, you'll find the version numbers for the various Huntress 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.
    • "errors": refers to agent roadblocks like connection or service/process errors from HuntressUpdater
    • "events": represents the last time an EDR survey was uploaded by Rio. This data is used to populate Process Insights pages in your Huntress portal.
    • "survey": represents the last time a survey was uploaded by HuntressAgent. This data is used to populate the endpoints info in your Huntress portal.
    • "tasks": the last time the HuntressAgent ran a task initiated by the Huntress portal.
    • "update": the last time the HuntressUpdater checked for a new update.

Troubleshooting Common Issues

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

  • The "Status" is showing as "degraded"

    • 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. Allow List Huntress in Third Party Security Software. 
    • Verify that the recommended exclusions for our binaries and network paths are properly configured within your security solutions.
    • Reboot to clear any file locks that could be preventing updates. If that fails, please reach out to our Support team.

  • One of the versions is empty or missing:

    • If the endpoint is running an older operating system (pre-Windows 8/pre-Server 2012), the "Rio" and "Huntmon" components will not be present and will therefore be missing from the list.  The status will be in “degraded”.

  • 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. Reboots will often fix this as it resolves conflicts and releases file locks.
    • You can try the following command to start up the service (run in the SYSTEM user context)

    Windows PoSh/CMD

    sc.exe start HuntressUpdater

    macOS Bash

    sudo launchctl enable system/com.huntress.HuntressUpdater
    sudo launchctl kickstart system/com.huntress.HuntressUpdater

    Linux Bash

    sudo systemctl enable --now huntress-updater.service

     

    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 support@huntress.com 

Related articles