PSA/ee/docs/plans/2026-02-13-tacticalrmm-integration/PRD.md

# PRD — Tactical RMM Integration

- Slug: `tacticalrmm-integration`
- Date: `2026-02-13`
- Status: Draft

## Summary

Add a Tactical RMM integration that works in both Community Edition (CE) and Enterprise Edition (EE). The integration should:

- Connect to a Tactical RMM instance using either API key auth or username/password (Knox token) auth (including optional TOTP).
- Sync Tactical inventory into Alga Assets (clients/sites/agents -> clients/assets + mappings).
- Support near-real-time updates via Tactical alert-action webhooks (alerts only), plus optional alert backfill via the Tactical alerts API.
- Fit the existing multi-provider RMM platform patterns established by the NinjaOne integration (shared DB tables, org mapping, device sync, asset fields).

## Problem

Alga currently has an RMM integration pattern (NinjaOne) that syncs devices and supports webhooks, but it is EE-oriented and provider-specific. We want to support Tactical RMM as an additional provider, available in both CE and EE, and integrate it cleanly into the existing Assets system and the “RMM” Integrations settings tab.

## Goals

1. CE + EE: Tactical RMM appears in Settings -> Integrations -> RMM and can be configured in both editions.
2. Connection management:
   - Support Tactical API key auth.
   - Support Tactical username/password auth with TOTP handling (checkcreds + login).
   - Store credentials securely (tenant secrets) and show masked status in UI.
3. Inventory sync:
   - Sync Tactical Clients into `rmm_organization_mappings`.
   - Map Tactical Clients to Alga Clients (companies) via UI.
   - Sync Tactical Agents into Alga Assets using the beta API at fleet scale.
4. Asset enrichment:
   - Populate core RMM fields on `assets` (`rmm_provider`, `rmm_device_id`, `rmm_organization_id`, `agent_status`, `last_seen_at`, `last_rmm_sync_at`).
   - Populate cached “RMM vitals” fields when available (current user, uptime, LAN/WAN IP).
   - Add support for Tactical’s “overdue” state (distinct from offline).
5. Realtime (alerts):
   - Provide a webhook endpoint for Tactical alert actions with shared-secret header validation.
   - On webhook receive, upsert `rmm_alerts` and trigger a targeted “sync single agent” refresh.
6. Optional: alerts backfill via Tactical alerts API for historical visibility.

## Non-goals

- Remote access (MeshCentral / remote background): explicitly deferred.
- Full “device created/updated/deleted” webhooks (Tactical doesn’t provide them natively; only alerts).
- Patch deployment / remediation (scan + display only, if we even include scan hooks).
- Deep ticket-automation parity with NinjaOne (auto ticket creation/rules) unless explicitly requested later.

## Users and Primary Flows

Primary user: MSP admin / system admin configuring integrations.

Flows:
1. Configure Tactical:
   - On the Tactical server, enable the Beta API: set `BETA_API_ENABLED = True` and restart Tactical.
   - Open Settings -> Integrations -> RMM -> Tactical RMM.
   - Enter the Tactical **API host** as the instance URL: the `api.` subdomain (e.g. `https://api.example.com`), not the dashboard (`rmm.`) URL.
   - Choose auth mode:
     - API key: paste key, save, verify.
     - Username/password: enter creds, if TOTP required prompt for code, login, store token.
2. Sync Tactical Clients:
   - Click “Sync Clients” (organizations).
   - Map Tactical Clients to Alga Clients (companies) in an org mapping table.
3. Sync Assets:
   - Click “Sync Devices”.
   - Alga upserts Assets and extension records and creates external mappings.
4. Realtime alerts:
   - Admin copies webhook URL + secret, configures Tactical alert-action webhook with `X-Alga-Webhook-Secret`.
   - Alerts trigger/resolve -> Alga receives webhook -> stores alert -> refreshes affected asset.
5. Optional: “Sync Alerts” to backfill alerts from Tactical.

## UX / UI Notes

- Tactical RMM should appear next to NinjaOne under the Integrations “RMM” category tab.
- Settings card should match the “feel” of NinjaOne settings:
  - Status panel (connected/disconnected, last sync, counts).
  - Credential management section (masked + update).
  - Sync buttons.
  - Organization mapping section.
  - Webhook section (URL, header name, secret, payload template).
- Since Tactical is CE + EE, the Tactical settings UI must not rely on EE-only dynamic imports.

## Requirements

### Functional Requirements

1. Connection status
   - Show whether Tactical is configured and reachable.
   - Show instance URL and auth mode.
2. Credential storage
   - Store and retrieve per-tenant credentials via secret provider.
   - Mask secrets in UI (show only last 4 chars).
3. Sync clients (organizations)
   - Fetch Tactical Clients via beta API.
   - Upsert `rmm_organization_mappings` for provider `tacticalrmm`.
4. Org mapping management
   - Allow selecting an Alga Client for each Tactical Client mapping.
   - Persist `auto_sync_assets` toggles.
5. Sync devices (agents)
   - For each mapped Tactical Client:
     - fetch sites (paged) and agents (paged and filtered by `client_id`).
     - upsert `assets` + extension data.
     - upsert `tenant_external_entity_mappings` for the agent.
     - mark missing agents as inactive (optional; see Open Questions).
6. Agent status mapping
   - Compute `online|offline|overdue` using the provided deterministic rules from `last_seen`, `offline_time`, `overdue_time`.
   - Persist status to `assets.agent_status`.
7. Realtime alerts via webhooks
   - Provide `POST /api/webhooks/tacticalrmm`.
   - Validate `X-Alga-Webhook-Secret`.
   - Accept a small JSON contract (required: `agent_id`; optional: `alert_id`, `event`, `severity`, `message`, `alert_time`, `client_id`, `site_id`).
   - Upsert `rmm_alerts` and associate to an asset when possible.
   - Trigger “sync single agent” after alert receives/resolves.
8. Alert backfill (optional but planned)
   - Use Tactical alerts endpoint to fetch active/recent alerts and upsert into `rmm_alerts`.
9. Software inventory ingestion (bulk, cached)
   - Use Tactical `GET /software/` to ingest cached software inventory without per-agent refresh.

### Non-functional Requirements

- Fleet-scale pagination: use beta endpoints with `page_size=1000` and loop pages.
- Resilience:
  - Handle 401 by re-authing (username/password mode) or failing with actionable error (API key mode).
  - Avoid per-agent “refresh” calls by default (software refresh is expensive).
- Multi-provider safety: Tactical must not break NinjaOne; providers must co-exist in the same tenant.

## Data / API / Integrations

Point the integration at the Tactical **API host** (the `api.` subdomain), for example `https://api.example.com`. Do not use the dashboard host (`rmm.`). The dashboard serves the single-page app and returns its HTML with a `200` for every path, so sync reads zero records and silently does nothing.

Tactical's **Beta API must be enabled** for inventory sync. Set `BETA_API_ENABLED = True` in Tactical and restart it. While it is off, the `/beta/v1/*` endpoints return `404` and both the connection test and sync fail.

Tactical endpoints (base URL `https://<tactical-api-host>`, served at the root with no `/api` prefix):

- Auth (username/password):
  - `POST /v2/checkcreds/` `{ username, password }` -> `{ totp: true }` or short-lived token
  - `POST /v2/login/` `{ username, password, twofactor? }` -> Knox token response
  - Auth header: `Authorization: Token <knox_token>`
- Auth (api key):
  - Auth header: `X-API-KEY: <key>`
- Inventory (beta API, requires `BETA_API_ENABLED`):
  - `GET /beta/v1/client/`
  - `GET /beta/v1/site/?page_size=1000&page=N`
  - `GET /beta/v1/agent/?client_id=<client_pk>&page_size=1000&page=N`
- Alerts:
  - `PATCH /alerts/` with filter body for backfill/top-N
- Software:
  - `GET /software/` bulk cached software inventory
  - `PUT /software/<agent_id>/` per-agent refresh (non-goal by default)

Alga DB tables involved:
- `rmm_integrations` (one row per tenant+provider; store instance_url, is_active, settings JSON including webhook secret and auth mode).
- `rmm_organization_mappings` (Tactical Client PK mapped to Alga Client).
- `assets` + extension tables (workstation/server fields; cached “vitals” fields already exist).
- `tenant_external_entity_mappings` (agent_id crosswalk; store client/site in metadata).
- `rmm_alerts` for alert ingestion and association.

## Security / Permissions

- Configuration actions require settings permissions (same posture as NinjaOne).
- Secrets stored in tenant secret store (never in plaintext in DB tables).
- Webhook endpoint is unauthenticated but must require shared-secret header and be explicitly enabled/configured by admin.

## Observability

- Minimal: structured logs for sync start/finish/errors and webhook receives.
- (Optional) publish existing event-bus events where appropriate (RMM_WEBHOOK_RECEIVED, RMM_DEVICE_UPDATED, etc.) to align with NinjaOne patterns.

## Rollout / Migration

- Add `tacticalrmm` provider to RMM provider unions in Typescript.
- Potential migration if we choose to add new agent status value (`overdue`) to UI filters and any code expecting only online/offline/unknown.
- Ensure `/api/webhooks/tacticalrmm` is added to API auth middleware skip paths.

## Open Questions

- Should we treat Tactical “overdue” as a first-class `agent_status` enum value everywhere (recommended), or map it to `offline`?
- Do we support marking assets as inactive when agents disappear from Tactical (requires a “full inventory snapshot” delete detection)?
- Asset type mapping: do we classify Tactical agents as workstation vs server based on OS string heuristics, or introduce a Tactical-specific mapping override?
- Should alert backfill be limited to “active only” or allow recent resolved (time window)?

## Acceptance Criteria (Definition of Done)

1. Tactical RMM is visible and configurable in CE and EE under Integrations -> RMM.
2. Admin can connect using API key or username/password (with TOTP when required), and connection status is shown.
3. Admin can sync Tactical Clients and map them to Alga Clients.
4. Admin can sync Tactical Agents into Alga Assets; assets show provider + agent status + last seen where available.
5. Tactical alert-action webhook can be configured with custom headers; Alga validates `X-Alga-Webhook-Secret`, records alerts, and refreshes the affected asset.
6. Optional: alerts backfill and bulk software inventory ingestion work without per-agent refresh calls.