We migrated ticketing systems!

If you would like to check on the status of a ticket, please visit huntress.zendesk.com.

For the time being, our documentation will stay the same, we will make a hard cutover when all the documentation is ready. The Huntress Support site will continue to be support.huntress.io, it will just come with a new look and feel.

Click here to check the status of a ticket


Ransomware Canaries Technical Details

This article will be receiving updates as new features become available. Please refer back to this doc for the latest information. We maintain a changelog found at the bottom of this page.

The Huntress "Ransomware Canaries" service is designed to detect ransomware activity on an endpoint. Similar to how miners used canaries in the coal mines to detect harmful gases like carbon monoxide, this feature works by deploying canary files in various directories and monitoring them for changes. When the Huntress Agent detects that a canary file has been altered, renamed, or deleted (such as when it gets encrypted by ransomware), it will alert our Threat Operations Team. Our team will review the conditions causing the alert and notify the Huntress partner of the incident details. 

NOTE: The ransomware canaries feature is part of a detection and alert platform and does not prevent ransomware from detonating or spreading. This warning capability allows for early alerting, leading to a faster response, and ideally better containment of an incident. It also allows for the easy identification of endpoints that were affected in a ransomware outbreak, assisting our partners in discovering the scope of an attack. 

This article covers the technical details of Huntress' Ransomware Canaries. if you are looking for a less-detailed version to pass to end-users, see our other version here: https://support.huntress.io/article/135-ransomware-canaries

In this article

Note on testing Ransomware Canaries: Partners often try to change the contents of a single canary file or delete it entirely. This is not the normal behavior of an actual ransomware event and may have delayed reporting (or no report at all) if only a single file is modified. 

Removing Ransomware Canaries: if you enable canaries and later decide to turn them off or uninstall Huntress, the canary files will automatically be removed from the host(s).

To enable Ransomware Canaries, click the "birdcage" icon from the left side of the home page and click "Enable"

Ransomware Canaries must be enabled by a user who is an Administrator on the account. Canaries must also be enabled from the Account level, if a user attempts to enable Canaries from the Organization home page they will receive a message to contact the Account Administrator.

Viewing Ransomware Canaries from the Huntress Portal

There are two places in the Huntress Portal, where you can find canary information, the Dashboard, and the "Monitored Files" view at the Agent level. 

The Dashboard View: Ransomware Canaries

To see the summary of all ransomware canary data for your account, click on the bird in the cage in the left-hand menu bar to see the dashboard view for your account's canaries.

In this view, you can see three states of a canary file: Armed, Pending, and Tripped. When viewing the agent details (see below), these states match to a variety of individual canary file states. 

Armed - Indicates the number of canaries that have been successfully deployed in your environment and are being monitored. (See the "Monitored" state below.)

Pending - Indicates the canary file has been queued to be placed on the Host and will be added the next time the Agent checks in. This is typical when a Huntress agent is initially deployed.

Tripped -  Indicates a canary file that is in either the "Modified" or "Missing" state (see below.) The Huntress Threat Ops team will investigate the canaries in this state, and incident reports will be generated if we find signs of ransomware activity. 

Agent Details View: Monitored Files

To view information on the ransomware canaries for a machine, log into the Huntress Dashboard, select the Agent, and click "Monitored Files" on the left side. 

Individual canary files will be in one of 4 states: 

Pending - Indicates the canary file has been queued to be placed on the Host and will be added the next time the Agent checks in. This is typical when a Huntress agent is initially deployed.

Monitored - Indicates the canary file has successfully been placed and the file is being monitored for ransomware activity.

Modified - Indicates the canary file has been modified but retains the same file name as its original state. If a canary is in this state, an investigation has been triggered and may result in an incident report. 

Missing - Indicates the canary file has been deleted or renamed. If a canary is in this state, an investigation has been triggered and may result in an incident report. 

Failed - Indicates Huntress was unable to place a canary file on an endpoint, depending on the reason why, we may try to replace this file. If this condition persists, contact Huntress support for assistance in resolution. 

Viewing the Ransomware Canaries on a Host

Canary files will be placed in several locations across a system commonly attacked by ransomware, such as %USERPROFILE%\Documents. The files, and the hidden directories they are placed in, are randomly named. The files are a mix of common file types targeted by ransomware such as .docx. These files are small and shouldn't have any measurable impact on disk usage. 

While most users shouldn't be aware the canary files are present, as they're hidden, some power users and administrators may have "Show Hidden Files" enabled in Windows Explorer. In that case, this is an example of what those files may look like: 

If the user decides they're still curious and opens the file, they will be presented with a document that looks similar to the one below. This is an example of a .docx canary file, but all file formats will have a similar message in them and open with their respective application. Each of the canary files contains a URL to our non-technical description of the canary file which you can review here.

Remediating Tripped Canaries

Ransomware Canaries act like mousetraps in that when one is tripped (possibly by ransomware) the canary needs to be reset. After receiving an incident report and approving assisted remediation, or completing the manual steps, the Canary will be deleted and will automatically replicate itself on the host. This new Canary file will have the same file name as the former one. 

After remediation, the incident will remain open. The report needs to be manually closed by Huntress. Reach out to us at support@huntress.io to close the incident. Please include the URL link to the Host and/or Incident report in your email.


  • Performance (resource consumption) - Do the Canaries use up more local resources? The Ransomware Canaries will not use any more resources than what the Huntress Agent already does. On initial rollout, the canaries will be dropped to each user profile folder on the machines (each file is a really small .docx file). From there, each time the Huntress Agent does a survey, it looks to see if the Canary file is there and sends the information to the Huntress Console--there is no computer-side processing.
  • Can canaries be installed on shared/network drives? Ransomware Canaries currently reside in users' documents. We do not have the ability to add canary files to network drives (that may change in the future, here's a link to the feature request.
  • Roaming profiles - Does the Ransomware Canaries Service support Roaming Profiles/Redirected Folders/etc.? Canaries are tied to the user profile GUID. If roaming profiles are being used, the canary associated with the roaming profile will travel across machines with it (and the Agent will know to match a canary to a specific user). If the canary is not present on the new host that the user logs into, it will be added.