PSA/docs/superpowers/specs/2026-06-09-huntress-integration-design.md

# Huntress Integration — Design

Huntress is a managed security platform whose SOC reviews detections and
publishes incident reports. This integration turns those incident reports into
Alga tickets automatically: an MSP connects a Huntress account with an API key,
maps Huntress organizations to Alga clients, and every SOC-reviewed incident
becomes a routed, self-contained ticket — with no one watching the Huntress
portal.

It is the first security-monitoring integration. It reuses the RMM integration
data model (`rmm_integrations`, `rmm_organization_mappings`, `rmm_alerts`) with
`provider = 'huntress'`, ships EE-only like NinjaOne, and appears in the
integrations settings under a new "Security" section.

## Goals

1. **Incident → ticket, automatic.** Open incident reports become tickets via a
   polling engine; no manual steps after setup.
2. **Org mapping that fails safe.** Huntress organization → Alga client, with a
   mapping screen and exact-name auto-match. Incidents for unmapped
   organizations become tickets on a designated fallback client and triage
   board — never silently dropped.
3. **Routing config.** Severity → priority mapping, target board, and optional
   category/subcategory, so security tickets land on the security board.
4. **Dedup / update-in-place.** One incident = one ticket; later incident
   updates append internal notes to the existing ticket.
5. **Self-contained tickets.** Body contains the SOC summary, indicator types,
   affected host details, remediation steps, and a deep link into the Huntress
   portal.

## Non-goals (deferred)

- **Webhook ingestion.** Huntress webhooks are configured manually in their
  portal and their payloads are not part of the public OpenAPI spec. The poller
  is the sole ingestion path. If a webhook endpoint is added later, it should
  only *trigger* an immediate poll cycle ("poke"), never be trusted as a data
  source.
- **Write-back to Huntress** (`POST /v1/incident_reports/{id}/resolution`).
- **Escalations and signals ingestion** (`/v1/escalations`, `/v1/signals`).
  The poller's processor is structured so a second entity stream can be added.
- **Per-client routing overrides.** Day-one routing is per-integration. The
  existing `rmm_alert_rules` engine
  (`ee/server/src/lib/integrations/ninjaone/alerts/alertProcessor.ts`) is a
  natural future home for this; it is untouched by this work.
- **Huntress agent → asset sync engine.** Agents are looked up on demand for
  ticket context and best-effort asset linking only.

## External API constraints

Source of truth: the Huntress public API (OpenAPI spec, `api.huntress.io`).

- **Auth:** HTTP Basic — `Base64(api_key:api_secret)`. Keys are generated
  per-account at `<subdomain>.huntress.io/account/api_credentials`. There is no
  OAuth and no partner-tier API.
- **Rate limit:** 60 requests/minute per account, sliding window.
- **Incident reports:** `GET /v1/incident_reports` supports `limit` (≤500),
  `page_token`, `sort_field` (`id|created_at|updated_at`), `sort_direction`,
  and filters (`status`, `severity`, `platform`, `organization_id`,
  `agent_id`, `indicator_type`). **There is no "updated since" filter** — the
  poller must walk pages sorted by `updated_at desc` until it passes its
  cursor.
- **Incident fields used:** `id`, `organization_id`, `agent_id`, `severity`
  (`low|high|critical`), `status` (`sent|closed|dismissed|auto_remediating|
  deleting|partner_dismissed`), `subject`, `summary`, `body`,
  `indicator_types`, `indicator_counts`, `platform`, `remediations` (first 10
  inline), `sent_at`, `status_updated_at`, `closed_at`, `updated_at`.
- **Organizations:** `GET /v1/organizations` — `id`, `name`, `key`.
- **Agents:** `GET /v1/agents/{id}` — `hostname`, `platform`, `os`,
  `ipv4_address`, `external_ip`, `serial_number`, `last_callback_at`.
- **Account:** `GET /v1/account` — `name`, `subdomain`. The subdomain is
  captured at connect time to build portal deep links.

## Data model

No new tables. One migration-free reuse of the RMM schema
(`server/migrations/20251124000001_create_rmm_integration_tables.cjs`);
`rmm_integrations.provider` is an unconstrained string, so `'huntress'` needs
no migration.

### `rmm_integrations` (one row per tenant)

- `provider = 'huntress'`, `instance_url` = API base URL (default
  `https://api.huntress.io`), `is_active`, `connected_at`, `sync_status`,
  `sync_error`, `last_incremental_sync_at`.
- `settings` JSONB:

```jsonc
{
  "accountName": "Acme MSP",
  "accountSubdomain": "acmemsp",          // for portal deep links
  "incidentCursor": "2026-06-09T14:00:00Z", // max updated_at fully processed
  "pollIntervalMinutes": 5,
  "backfillDays": 7,
  "severityPriorityMap": {                 // huntress severity -> priority_id
    "critical": "<uuid>",
    "high": "<uuid>",
    "low": "<uuid>"
  },
  "boardId": "<uuid>",                     // required: security board
  "categoryId": "<uuid|null>",
  "subcategoryId": "<uuid|null>",
  "fallbackClientId": "<uuid>",            // required before polling activates
  "fallbackBoardId": "<uuid>",             // required: triage board
  "autoCloseTickets": false,
  "closedStatusId": "<uuid|null>"          // used when autoCloseTickets = true
}
```

### `rmm_organization_mappings` (one row per Huntress organization)

- `external_organization_id` = Huntress org id (stringified),
  `external_organization_name`, `client_id` (null = unmapped),
  `auto_create_tickets` (default true), `metadata.auto_matched` flag.
- Unique on `(tenant, integration_id, external_organization_id)`.

### `rmm_alerts` (one row per incident report)

- `external_alert_id` = Huntress incident id (stringified) — the unique
  constraint `(tenant, integration_id, external_alert_id)` is the dedup
  guarantee.
- `severity` = Huntress severity, `status` = Huntress status, `message` =
  incident `subject`, `device_name` = agent hostname when known,
  `external_device_id` = agent id, `asset_id` when an asset match is found,
  `ticket_id` once a ticket exists, `triggered_at` = `sent_at`.
- `metadata` JSONB: incident snapshot (`summary`, `indicator_types`,
  `indicator_counts`, `platform`, `organization_id`, remediation summaries,
  `status_updated_at`, portal URL, processing-error details when a cycle
  fails on this incident).

### `tenant_external_entity_mappings`

When an incident's agent is matched to an existing Alga asset:
`integration_type = 'huntress'`, `alga_entity_type = 'asset'`,
`external_entity_id` = agent id, `external_realm_id` = org id.

### Tickets

- `source = 'huntress'`, `source_reference` = incident id.
- `board_id`, `priority_id`, `category_id`/`subcategory_id` from routing
  config; `client_id` from the org mapping (or fallback client).

## Components

All new code is EE, under `ee/server/src/lib/integrations/huntress/`,
mirroring the NinjaOne layout (`ee/server/src/lib/integrations/ninjaone/`):

```
huntress/
  huntressClient.ts          REST client: Basic auth, throttle to 60 req/min,
                             429 backoff, page_token pagination
  incidents/
    incidentPoller.ts        cursor walk + dispatch, transport-wrapped
    incidentProcessor.ts     upsert rmm_alerts; create / note / close decisions
    ticketCreator.ts         builds the self-contained ticket (NinjaOne
                             ticketCreator pattern: transaction, default status,
                             ticket number, comment thread + internal note)
  organizations/
    orgSync.ts               org fetch -> mapping upsert + name auto-match
```

Supporting pieces:

- **Server actions:** `ee/server/src/lib/actions/integrations/huntressActions.ts`
  — connect (validate via `GET /v1/account`, store secrets, upsert integration
  row, initial org sync), disconnect, get status, update settings, sync
  organizations, update a mapping row.
- **Secrets:** tenant-scoped via `ISecretProvider`
  (`packages/core/src/lib/secrets/ISecretProvider.ts`):
  `huntress_api_key`, `huntress_api_secret`.
- **Settings UI:**
  `ee/server/src/components/settings/integrations/HuntressIntegrationSettings.tsx`
  (connect card, routing config, poll/auto-close settings) and
  `.../integrations/huntress/OrganizationMappingManager.tsx` (org table,
  client picker, auto-match indicators, per-row ticket toggle, unmapped-count
  badge, re-sync). Wired into
  `packages/integrations/src/components/settings/integrations/RmmIntegrationsSetup.tsx`
  via the `@enterprise` dynamic-import pattern.
- **Provider registry:**
  `packages/integrations/src/lib/rmm/providerRegistry.ts` gains a
  `category: 'rmm' | 'security'` field; Huntress registers with
  `category: 'security'`, `requiresEnterprise: true`. The setup page renders
  one card section per category.
- **Scheduling/transport:** the poll entry point runs through
  `runRmmSyncWithTransport()`
  (`ee/server/src/lib/integrations/rmm/sync/syncOrchestration.ts`):
  `HUNTRESS_SYNC_TRANSPORT` → `RMM_SYNC_TRANSPORT` → `'direct'`. A recurring
  job registered with the existing job scheduler
  (`packages/jobs/src/lib/jobs/jobScheduler.ts`) iterates active Huntress
  integrations on each tick and skips tenants whose `pollIntervalMinutes`
  hasn't elapsed since `last_incremental_sync_at`.

## Flows

### Connect

1. User enters API key + secret (and optionally a base URL) in the Huntress
   settings card.
2. Action calls `GET /v1/account`; on success stores secrets, upserts the
   `rmm_integrations` row with `accountName`/`accountSubdomain`, and runs the
   initial org sync.
3. Polling stays inactive until routing config is complete: `boardId`,
   `fallbackClientId`, `fallbackBoardId`, and a full `severityPriorityMap`
   (pre-filled at connect by case-insensitive name match against the tenant's
   priorities: Critical/Urgent, High, Medium).

### Organization sync & auto-match

1. Fetch all organizations; upsert mapping rows by external org id (names
   refresh on every sync).
2. For rows with `client_id IS NULL`, compare normalized names
   (lowercase, collapse whitespace, strip punctuation) against the tenant's
   clients. An exact normalized match links the client and sets
   `metadata.auto_matched = true`; anything weaker is left unmapped for the
   user. Auto-matched rows are visibly flagged in the UI and editable.

### Poll cycle (per integration)

1. List `/v1/incident_reports` sorted `updated_at desc`, page size 500,
   collecting rows until one is older than `incidentCursor − 60s` (overlap
   absorbs clock skew; dedup makes reprocessing harmless). First run instead
   collects back to `now − backfillDays`.
2. Process collected incidents in ascending `updated_at` order through the
   incident processor.
3. Advance `incidentCursor` past each successfully processed incident; stop
   advancing at the first failure (that incident and everything newer is
   retried next cycle) and record the error on the alert row's metadata.
4. On auth or API failure: `sync_status = 'error'`, `sync_error` set, banner
   in the settings UI. Nothing is lost — incidents remain in Huntress and the
   cursor resumes when the credential is fixed.

### Incident processing

For each incident, upsert the `rmm_alerts` row, then:

- **New, status open (`sent`, `auto_remediating`):** resolve the org mapping.
  - Mapped client and `auto_create_tickets` on → create ticket with routing
    config.
  - Unmapped org (no row, or `client_id IS NULL`) → fetch and upsert the org
    mapping row if it's unknown, then create the ticket on
    `fallbackClientId`/`fallbackBoardId` with an `[Unmapped Org]` title prefix
    and a note explaining how to map the organization.
  - `auto_create_tickets` explicitly off on the mapping row (mapped or not) →
    record the alert row only; the user opted that organization out.
- **New, status already closed/dismissed** (backfill case): record the alert
  row without a ticket.
- **Status `deleting`:** skip.
- **Existing row, changed** (`updated_at`, status, or remediation state):
  append an internal note to the linked ticket describing what changed. If the
  new status is `closed`, `dismissed`, or `partner_dismissed` and
  `autoCloseTickets` is on, also move the ticket to `closedStatusId`.

Ticket creation and the alert-row `ticket_id` update happen in one
transaction; the dedup constraint plus the `ticket_id` check make creation
idempotent across overlapping polls.

### Ticket content

Title: `[Huntress] <severity> — <subject>` (fallback tickets additionally get
the `[Unmapped Org]` prefix). Body sections:

1. **Incident** — severity, status, SOC analyst summary, indicator types and
   counts, platform, sent/updated timestamps.
2. **Affected host** — hostname, OS, internal/external IPs, serial number,
   last callback (from `GET /v1/agents/{id}`; omitted for host-less incidents
   such as `microsoft_365` identity cases, which show the org context
   instead).
3. **Remediations** — the inline remediation steps with status.
4. **Links** — deep link to the incident in the Huntress portal, built from
   `accountSubdomain`. The exact portal path is confirmed against a live
   account during implementation; the builder is isolated in one function so
   a path correction is a one-line change.

An internal note (NinjaOne `ticketCreator.ts` pattern: comment thread first,
then the internal-note comment) records the raw incident identifiers for
audit.

### Asset linking (best effort)

If the incident has an `agent_id` and the org is mapped: look up the agent,
match `hostname` case-insensitively (tie-break on `serial_number`) against
the mapped client's assets. A unique match links the ticket via
`asset_associations`, sets `rmm_alerts.asset_id`, and upserts the
`tenant_external_entity_mappings` row. Ambiguous or missing matches skip
linking — host details are already in the body.

## Error handling summary

| Failure | Behavior |
| --- | --- |
| Huntress 401/403 | Integration `sync_status='error'` + UI banner; poll resumes on fix; no data loss |
| Huntress 429 | Client-side throttle should prevent it; on occurrence, back off and finish the cycle late |
| Per-incident processing error | Cursor stops before it; error stored in alert metadata; retried next cycle |
| Unmapped organization | Ticket on fallback client/triage board, flagged — never dropped |
| Unknown org id mid-poll | Org fetched on demand, unmapped mapping row created, fallback routing |
| Fallback config missing | Polling refuses to activate; settings UI requires it during setup |
| Agent lookup failure | Ticket still created; host section omitted with a note |

## Testing

- **Unit (mocked client interface):** cursor walker — pagination, overlap
  window, backfill, failure-stops-cursor; incident processor — every state
  transition (new/update/close × mapped/unmapped/auto-create-off ×
  auto-close on/off); severity→priority resolution; name-normalization
  auto-match; ticket-body builder (host-less incidents, remediation
  rendering, deep link).
- **Integration (repo harness, seeded tenant):** connect → org sync →
  poll → ticket created with correct board/priority/category → second poll
  with an updated incident appends a note, not a ticket → closed incident
  with auto-close on resolves the ticket; unmapped-org incident lands on the
  fallback client/board.
- **Manual smoke:** against a real Huntress account — verify the portal deep
  link path and the 60 req/min throttle behavior.