Huntress

Overview

Huntress is a pull-based source that collects Huntress Managed EDR incident reports from the Huntress API (GET /v1/incident_reports). An incident report is what the Huntress SOC sends when it confirms a threat. It covers:

Platform	platform value
Windows, macOS and Linux endpoints	windows, darwin, linux
Microsoft 365 and Google identities (Managed ITDR)	microsoft_365, google
Huntress email security	email_security
Anything else	other

Each report is sent exactly as Huntress returns it: subject, the SOC analyst's summary, the full body, indicator types and counts, PSA ticket IDs and the first ten remediations.

A report is sent when it is created and again every time Huntress updates it (status, remediation approval or completion, closure). Each update is sent once; nothing is sent twice.

Reports from every organization in the Huntress account are collected; each report's body carries its organization_id.

Supported types: Logs

Supported platforms: Linux, Windows, macOS

Minimum collector version: 0.5.73

Authentication

Requires a Huntress account with Managed EDR (or Managed ITDR for identity reports). Attach a Huntress (huntress) credential:

Credential field	Value
API Key	The Huntress API Key
API Secret	The Huntress API Secret Key

The collector sends them on every request as Authorization: Basic base64(api_key:api_secret). The node itself holds no secret, and the secret is never shipped in the pipeline config: the platform writes placeholders that the collector fills in from the credential at load time, as for the CrowdStrike and Duo sources.

Generate an API key pair

1. Sign in at https://<your_account_subdomain>.huntress.io.
2. Open API Credentials (in the account menu) and choose Generate.
3. Copy the API Key and the API Secret Key. The secret is shown only once. The key's user needs a role that can read incident reports.
4. In Praxis, create a Huntress credential with the API key and the API secret.

Configuration

Schedule

Parameter	Type	Default	Description
poll_interval	seconds	300	How often new and updated reports are fetched. 60 to 86400. The Huntress API limit is per account, shared with every integration using its keys.
lookback	seconds	86400	First start only: how far back to fetch when no saved position exists. At most 7776000 (90 days).
persist_offsets	bool	true	Persist Position. Save the read position so a restart resumes instead of fetching the lookback window again.

advanced

Parameter	Type	Default	Description
late_arrival_window	seconds	300	How far behind the current time the saved position stays, so reports Huntress lists shortly after their update time are still collected. Reports already sent are not sent again. 0 to 86400; measured on the earlier of Huntress's clock and the collector's.
page_size	int	500	Reports per request, 1 to 500 (the Huntress maximum).
timeout	seconds	60	Per-request timeout.

Sending to Google SecOps

The source does not set a Google SecOps log type. Add a Google SecOps Standardization processor between this source and the Google SecOps destination and set the log type your Google SecOps instance uses for Huntress incident reports. Records carry no source attribute, so give the Huntress source its own pipeline (or its own standardization processor) rather than sharing one log-type rule with other sources.

Output mapping

Every report version becomes one log record:

Source	OTel destination
(whole report JSON, as Huntress returned it)	LogRecord.Body (string)
updated_at	LogRecord.Timestamp
severity	LogRecord.SeverityText (as is); SeverityNumber: critical → FATAL, high → ERROR, low and others → WARN (every report is a confirmed threat)

No record or resource attributes are added: everything is in the body, untouched.

Example configuration

{
  "poll_interval": 300,       // default: 300
  "lookback": 86400,          // default: 86400 (first start only)
  "persist_offsets": true,    // default: true
  "advanced": {
    "late_arrival_window": 300, // default: 300
    "page_size": 500,           // default: 500
    "timeout": 60               // default: 60
  }
}

Operational notes

• Counting incidents. Because updates are re-sent, records ≠ incidents. Count distinct values of the body's id field for incident counts.
• How it reads. Each poll asks for reports updated at or after the saved position, oldest first. After every page it asks again from the newest second that page reached, so reports that share a second across a page boundary are never skipped; reports already sent are recognised and dropped.
• Late reports and clocks. The saved position trails the earlier of Huntress's clock and the collector's by the late arrival window, so a wrong clock on either side neither misses nor duplicates reports.
• Restarts. With Persist Position on, the position is saved after every page the pipeline accepts. A crash or a downstream refusal replays from there: nothing is skipped and nothing is sent twice.
• Retries. Throttling (429) and server errors (5xx) are retried up to 6 times over about a minute, honoring Retry-After. A failed poll leaves the position unchanged; the next poll retries it.
• A quiet poll is one request. When nothing has changed, the poll makes a single request and sends nothing.
• Incident reports only. Signals, escalations, agents and organizations are separate Huntress data and are not collected.
• Polling, not push. A report arrives up to one Poll Interval (default 5 minutes) after Huntress updates it. Huntress webhooks are not used.
• Draft reports (sent back to the Huntress SOC) are not returned by Huntress's list, so they arrive when Huntress sends them again.
• Undocumented time filter. The source asks Huntress for reports updated since its position with updated_at_min, which Huntress's own CLI uses but its published API reference does not list. If Huntress stopped honouring it, each poll would read the whole list; nothing would be duplicated, but polls would cost more requests.
• Very late reports. A report Huntress lists later than the Late Arrival Window after its update time is missed. Raise the window if that is seen.
• History. The first start fetches at most 90 days (Lookback).
• Timeouts. If Huntress keeps answering 504, lower Page Size (Huntress advises a smaller limit).
• Rate limit. 60 requests per minute per Huntress account, shared with every integration using the same API key.

Troubleshooting

Symptom in the collector log	Cause	Fix
Huntress rejected the API credentials … 401	Wrong or revoked key pair, or the key and secret swapped in the credential.	Fix the Huntress credential (API Key and API Secret).
Huntress refused the incident reports request … 403	The user who generated the key pair cannot read incident reports.	Generate the key pair with a user that has the right role.
huntress request throttled or failed; backing off … 429	Another integration is using the same API key heavily.	Raise Poll Interval, or give the integrations separate keys.
Polls complete with records_delivered: 0	No reports updated since the position.	Check the Huntress portal's Incident Reports for the same period.
Huntress returned incident reports out of updated_at order	The API returned an unsorted page.	The position is kept and the next poll retries; contact Huntress support if it persists.

Metrics

Metric Name	Description
prx_src_records_received_total{signal="logs"}	Report versions sent downstream. Re-read reports that were already sent are not counted.
prx_src_bytes_received_total	Bytes of the reports sent.
prx_src_pipeline_latency_seconds	Arrival to downstream handoff, one sample per page.
prx_src_errors_total{reason="auth"}	401/403 from Huntress.
prx_src_errors_total{reason="io"}	Other failures, including exhausted retries, a repeated page token and an out-of-order page.
prx_src_parse_errors_total{parser="json"}	A response that was not an incident report page, or reports whose fields could not be read (those reports are still sent).
prx_src_records_dropped_total{reason="backpressure"}	Pages refused downstream; they are replayed on the next poll.