Huntress Connector¶

Slug: huntress Vendor: Huntress Labs Category: edr Auth type: basic (Base64-encoded apiKey:apiSecret) Status: stable API Base URL: https://api.huntress.io

Overview¶

Huntress is a managed detection and response (MDR) platform designed for MSPs. It deploys lightweight agents on endpoints, monitors for persistent threats, and provides a SOC-backed incident response service. For compliance purposes, Huntress provides evidence of EDR coverage, threat detection activity, incident remediation timelines, and multi-organization agent deployment health.

This connector covers four compliance categories: agent health, threat detection, organization coverage, and remediation metrics (MTTD/MTTR).

Credential Schema¶

Field	Required	Secret	Description
`apiKey`	Yes	No	API key from Huntress portal — Account → API Credentials
`apiSecret`	Yes	Yes	API secret — treat like a password, generated alongside the key

{
  "type": "object",
  "required": ["apiKey", "apiSecret"],
  "properties": {
    "apiKey": {
      "type": "string",
      "title": "API Key",
      "description": "From Huntress portal: Account → API Credentials → API Key",
      "secret": false
    },
    "apiSecret": {
      "type": "string",
      "title": "API Secret",
      "description": "From Huntress portal: Account → API Credentials → API Secret. Treat as a password.",
      "secret": true
    }
  }
}

Auth mechanism: HTTP Basic Auth using Base64(apiKey:apiSecret) as the Authorization header value. The connector obtains no token — credentials are used directly on every request.

API Endpoints Used¶

Method	Endpoint	Purpose
`GET`	`/v1/organizations`	List all organizations (paginated)
`GET`	`/v1/agents`	List all agents across all organizations (paginated)
`GET`	`/v1/incident_reports?status=open`	Active/open incidents (paginated)
`GET`	`/v1/incident_reports`	All incidents including resolved (paginated)

All endpoints support cursor-based pagination. The connector follows all pagination cursors to collect complete data sets.

Metrics¶

18 metrics across 4 categories.

Category	metric_key	metric_type	unit	Description
`endpoint_protection`	`agents_total`	count	devices	Total agents registered across all organizations
`endpoint_protection`	`agents_online`	count	devices	Agents with status `online` or `active`
`endpoint_protection`	`agents_offline`	count	devices	Agents with status `offline`
`endpoint_protection`	`agents_missing`	count	devices	Agents with status `missing` (not checking in)
`endpoint_protection`	`agents_online_percentage`	percentage	%	`(agents_online / agents_total) * 100`
`incident_response`	`incidents_total`	count	incidents	All incidents collected in this run
`incident_response`	`incidents_open`	count	incidents	Incidents with no resolution yet
`incident_response`	`incidents_in_progress`	count	incidents	Incidents actively being investigated
`incident_response`	`incidents_resolved`	count	incidents	Incidents marked resolved or closed
`incident_response`	`incidents_critical`	count	incidents	Incidents with severity `critical`
`incident_response`	`incidents_high`	count	incidents	Incidents with severity `high`
`asset_inventory`	`organizations_total`	count	organizations	Total organizations in Huntress account
`asset_inventory`	`organizations_with_agents`	count	organizations	Organizations with at least one active agent
`asset_inventory`	`average_agents_per_org`	number	devices	Mean agent count per organization
`asset_inventory`	`organization_coverage_pct`	percentage	%	`(organizations_with_agents / organizations_total) * 100`
`incident_response`	`mean_time_to_detect_hours`	duration	hours	Average hours from threat creation to detection across resolved incidents
`incident_response`	`mean_time_to_resolve_hours`	duration	hours	Average hours from detection to resolution across resolved incidents
`incident_response`	`incidents_auto_resolved`	count	incidents	Incidents resolved automatically without manual intervention

Raw → Normalized Field Mapping¶

Raw API Field	Normalized metric_key	Notes
`agent['status']` — `'online'`/`'active'`	`agents_online`	Truthy statuses
`agent['status']` — `'offline'`	`agents_offline`
`agent['status']` — `'missing'`	`agents_missing`	Not checking in
`agent['status']` — `'decommissioned'`	excluded from counts	Decommissioned agents are filtered out
`incident['severity']` — `'critical'`	`incidents_critical`
`incident['severity']` — `'high'`	`incidents_high`
`incident['status']` — `'in_progress'`/`'investigating'`	`incidents_in_progress`
`incident['status']` — `'resolved'`/`'closed'`	`incidents_resolved`
`incident['created_at']` + `incident['detected_at']`	`mean_time_to_detect_hours`	Delta in hours, averaged across resolved incidents
`incident['detected_at']` + `incident['resolved_at']`/`incident['closed_at']`	`mean_time_to_resolve_hours`	Delta in hours
`incident['resolution_source']`/`incident['resolved_by']`	`incidents_auto_resolved`	Incidents where resolution source indicates automated remediation

Example Output¶

{
  "connector_type_id": "huntress",
  "collected_at": "2026-03-22T12:00:00Z",
  "tenant": {
    "company_id": "msp-acme",
    "client_id": "client-acme-corp"
  },
  "metrics": [
    {
      "category": "endpoint_protection",
      "metric_key": "agents_total",
      "metric_value": "87",
      "metric_type": "count",
      "unit": "devices"
    },
    {
      "category": "endpoint_protection",
      "metric_key": "agents_online",
      "metric_value": "85",
      "metric_type": "count",
      "unit": "devices"
    },
    {
      "category": "endpoint_protection",
      "metric_key": "agents_offline",
      "metric_value": "1",
      "metric_type": "count",
      "unit": "devices"
    },
    {
      "category": "endpoint_protection",
      "metric_key": "agents_missing",
      "metric_value": "1",
      "metric_type": "count",
      "unit": "devices"
    },
    {
      "category": "endpoint_protection",
      "metric_key": "agents_online_percentage",
      "metric_value": "97.7",
      "metric_type": "percentage",
      "unit": "%"
    },
    {
      "category": "incident_response",
      "metric_key": "incidents_total",
      "metric_value": "14",
      "metric_type": "count",
      "unit": "incidents"
    },
    {
      "category": "incident_response",
      "metric_key": "incidents_open",
      "metric_value": "2",
      "metric_type": "count",
      "unit": "incidents"
    },
    {
      "category": "incident_response",
      "metric_key": "incidents_in_progress",
      "metric_value": "1",
      "metric_type": "count",
      "unit": "incidents"
    },
    {
      "category": "incident_response",
      "metric_key": "incidents_resolved",
      "metric_value": "11",
      "metric_type": "count",
      "unit": "incidents"
    },
    {
      "category": "incident_response",
      "metric_key": "incidents_critical",
      "metric_value": "0",
      "metric_type": "count",
      "unit": "incidents"
    },
    {
      "category": "incident_response",
      "metric_key": "incidents_high",
      "metric_value": "2",
      "metric_type": "count",
      "unit": "incidents"
    },
    {
      "category": "asset_inventory",
      "metric_key": "organizations_total",
      "metric_value": "12",
      "metric_type": "count",
      "unit": "organizations"
    },
    {
      "category": "asset_inventory",
      "metric_key": "organizations_with_agents",
      "metric_value": "11",
      "metric_type": "count",
      "unit": "organizations"
    },
    {
      "category": "asset_inventory",
      "metric_key": "average_agents_per_org",
      "metric_value": "7.25",
      "metric_type": "number",
      "unit": "devices"
    },
    {
      "category": "asset_inventory",
      "metric_key": "organization_coverage_pct",
      "metric_value": "91.7",
      "metric_type": "percentage",
      "unit": "%"
    },
    {
      "category": "incident_response",
      "metric_key": "mean_time_to_detect_hours",
      "metric_value": "4.2",
      "metric_type": "duration",
      "unit": "hours"
    },
    {
      "category": "incident_response",
      "metric_key": "mean_time_to_resolve_hours",
      "metric_value": "18.5",
      "metric_type": "duration",
      "unit": "hours"
    },
    {
      "category": "incident_response",
      "metric_key": "incidents_auto_resolved",
      "metric_value": "8",
      "metric_type": "count",
      "unit": "incidents"
    }
  ],
  "metadata": {
    "api_calls_made": 6,
    "collection_duration_ms": 2340,
    "collection_method": "collectAll"
  }
}

Framework Mappings¶

Evidence from this connector is relevant to the following ACES framework controls. Exact control mapping is performed by the consuming platform — this table indicates which frameworks benefit from Huntress data.

ACES Framework Key	Coverage	Relevant Controls
`cis-v8`	Partial	CIS Control 10 (Malware Defenses), CIS Control 17 (Incident Response)
`cmmc-level2`	Partial	SI.1.210 (malicious code protection), IR.2.092 (incident handling)
`nist-800-171`	Partial	3.14.2 (malicious code protection), 3.6.1 (incident handling capability)
`nist-csf-2`	Partial	DE.CM (continuous monitoring), RS.AN (incident analysis)
`soc-2`	Partial	CC7.2 (system anomalies), CC7.3 (incident evaluation)

Notes¶

Decommissioned agents: Agents with status decommissioned are excluded from all counts. They are not counted in agents_total, agents_online, or agents_offline. This matches the intent of coverage metrics — decommissioned endpoints are no longer managed.

MTTD/MTTR calculation: Mean time metrics are calculated only over incidents that have both detected_at and resolved_at/closed_at timestamps. Incidents still open are excluded from these averages.

Auto-resolved detection: The incidents_auto_resolved metric is derived from the resolution_source or resolved_by field. Exact field names may vary by Huntress API version — connectors should handle both.

Pagination: All three collection endpoints (/v1/agents, /v1/incident_reports) use cursor-based pagination. The connector follows all pages. For large MSPs with thousands of agents, collection duration may exceed 5 seconds.

Rate limits: Huntress API rate limits are not published. If you encounter 429 responses, implement exponential backoff. Document your findings in a GitHub issue.

API documentation: https://api.huntress.io/docs (requires Huntress account)