PSA/ee/docs/plans/2026-04-06-tanium-rmm-integration-plan/SCRATCHPAD.md

# Scratchpad — Tanium RMM Integration Plan

- Plan slug: `tanium-rmm-integration-plan`
- Created: `2026-04-06`

## What This Is

Working notes for the Tanium RMM planning effort. This is intentionally biased toward repo seams, official Tanium guidance, and concrete implementation consequences.

## Decisions

- (2026-04-06) Tanium should not be implemented by copying NinjaOne or Tactical RMM. The missing seam is a shared provider registry plus shared normalized ingestion pipeline.
- (2026-04-06) `tenant_external_entity_mappings` is the main simplification-cascade seam. Treat external RMM providers as identity sources that feed one shared asset correlation/upsert path.
- (2026-04-06) Tanium v1 is pull-oriented and Gateway-first.
- (2026-04-06) Tanium Connect is a later optional capability for outbound/event-triggered delivery, not a prerequisite for inventory sync.
- (2026-04-06) Tanium Asset API is a fallback for aged-out endpoint coverage, not the primary default integration surface.
- (2026-04-06) Tanium Direct Connect / Threat Response should be capability-flagged later work, not v1 scope.
- (2026-04-06) Feature `F001` is complete: plan artifacts now capture exact documented Gateway query/object/mutation families for inventory, scope discovery, actions, Connect, and Direct Connect, plus Asset API fallback posture and `assetUpsertEndpoints` usage constraints.

## Discoveries / Constraints

- (2026-04-06) Current RMM UI is hard-coded in `packages/integrations/src/components/settings/integrations/RmmIntegrationsSetup.tsx`.
- (2026-04-06) Current public ingress handling is hard-coded in `server/src/middleware.ts` for `/api/integrations/ninjaone/callback`, `/api/webhooks/ninjaone`, and `/api/webhooks/tacticalrmm`.
- (2026-04-06) Shared RMM types already leak provider specifics, for example `ninja_instance_region` inside `ee/server/src/interfaces/rmm.interfaces.ts`.
- (2026-04-06) NinjaOne sync logic is split across provider-specific strategy/orchestration and duplicated persistence logic in Temporal activities.
- (2026-04-06) Tactical RMM keeps orchestration and persistence mostly inside one large action file, which reinforces the need for a shared ingestion seam before adding Tanium.
- (2026-04-06) Official Tanium docs say Gateway is preferred for querying online and offline systems, managing groups, deploying actions, establishing direct endpoint connections, and inserting/updating Asset records.
- (2026-04-06) Official Tanium docs say Connect is best for scheduled or event-triggered outbound delivery, including webhook destinations and detected-event delivery.
- (2026-04-06) Official Tanium docs say Asset API is useful for endpoints that have aged out of TDS.
- (2026-04-06) Feature `F002` implementation detail: provider unions are duplicated across `packages/types`, `server`, and `ee/server`; adding a provider requires touching all three type seams until a single source-of-truth type export is introduced.
- (2026-04-06) Feature `F003`/`F004` implementation detail: provider metadata and capability gating are now centralized in `packages/integrations/src/lib/rmm/providerRegistry.ts`, while provider settings components remain pluggable in UI composition code.
- (2026-04-06) Feature `F005`–`F009` implementation detail: normalized RMM contracts and the shared ingestion engine now live in `packages/integrations/src/lib/rmm/`, allowing provider fetchers to hand off provider-neutral snapshots into a single create/update/delete pipeline.
- (2026-04-06) Feature `F010`–`F018` implementation detail: Tanium v1 is implemented as pull-oriented server actions backed by a Gateway client plus shared ingestion, with no public webhook/callback route additions.

## Gateway Schema Findings

- (2026-04-06) Logged-in Gateway docs expose stable route families under `https://developer.tanium.com/apis/tanium_gateway_schema/{queries|mutations|objects}/...`.
- (2026-04-06) For Tanium inventory, the primary query surface is confirmed in the schema:
  - `endpoints(...args)`
  - `endpointCounts(input)`
  - `endpointIdChanges(...args)`
  - `endpointLastSeen(eids)`
- (2026-04-06) The endpoint object family is concrete and broad enough for normalized inventory snapshots:
  - `Endpoint`
  - `EndpointConnection`
  - `EndpointEdge`
  - `EndpointOS`
  - `EndpointUser`
  - `EndpointInstalledApplication`
  - `EndpointMetric`
  - `EndpointCompliance`
- (2026-04-06) The schema exposes a natural scope/group surface for client mapping:
  - queries: `computerGroup(ref)`, `computerGroups(...args)`
  - objects: `ComputerGroup`, `ComputerGroupConnection`, `ComputerGroupEdge`
  - mutations also exist for later admin workflows: `computerGroupCreate(input)`, `computerGroupDelete(ref)`
- (2026-04-06) The schema exposes Connect as a first-class later event/export surface:
  - queries: `connectConnection(ref)`, `connectConnections(...args)`, `connectRun(ref)`, `connectRuns(...args)`
  - objects: `ConnectConnection`, `ConnectGraphConnection`, `ConnectRun`, `ConnectRunConnection`
  - mutations: `connectConnectionStart(input)`, `connectConnectionStop(input)`
- (2026-04-06) The schema exposes Direct Connect as a first-class later remote-action surface:
  - queries: `directConnectConnectionStatus(input)`, `directConnectEndpoint(input)`, `directConnection(connectionID)`, `directEndpoint(input)`
  - mutations: `directConnectOpen(input)`, `directConnectClose(input)`, `directConnectPing(input)`, `directConnectProcessTerminate(input)`
  - objects: `DirectConnect`, `DirectConnectOpenPayload`, `DirectConnectClosePayload`, `DirectConnectConnectionStatusPayload`, `DirectConnectPingPayload`
- (2026-04-06) Legacy direct-connect mutations still exist, but the docs explicitly mark them as not preferred:
  - `closeDirectConnection(input)` is documented as legacy and says to use `directConnectClose` because the `directConnect*` APIs better support tracking slow-to-establish connections.
  - `openDirectConnection(input)` and `pingDirectConnection(input)` still appear alongside the newer `directConnect*` family.
- (2026-04-06) Action and scheduled-action surfaces are confirmed in Gateway and should remain capability-gated later work:
  - queries: `action(ref)`, `actions(...args)`, `actionGroup(ref)`, `actionGroups(...args)`, `scheduledAction(ref)`, `scheduledActions(...args)`
  - mutations: `actionCreate(input)`, `actionPerform(input)`, `actionGroupCreate(input)`, `actionGroupDelete(ref)`, `scheduledActionApprove(ref)`, `scheduledActionCreate(input)`, `scheduledActionDelete(ref)`
  - objects: `Action`, `ActionConnection`, `ActionGroup`, `ActionGroupConnection`, `ActionInfo`, `ScheduledAction`
- (2026-04-06) The logged-in object docs and screenshot evidence show `ScheduledAction` is a real first-class object with approval and scheduling metadata such as `approved`, `approver`, `comment`, `creator`, `distributeSeconds`, and `endTime`.
- (2026-04-06) `assetUpsertEndpoints(input)` is the key Tanium Gateway write surface around Asset-managed endpoint records:
  - return type: `AssetsUpsertPayload!`
  - argument type: `AssetUpsertEndpointsInput!`
  - docs say it upserts endpoint records in the given Asset Import API source using the Asset entity/attribute model
  - docs say source keys must be present as entity values; matching keys update an existing endpoint, otherwise a new endpoint is created
  - docs say TTL is updated for both Asset and TDS
  - docs require the Asset solution and `Asset Api User Write`
- (2026-04-06) `assetsImport(input)` is explicitly deprecated in favor of `assetUpsertEndpoints(input)` because `assetUpsertEndpoints` supports multi-row/reference entities.
- (2026-04-06) Working decision from the schema:
  - v1 scope discovery should target `computerGroups`
  - v1 inventory sync should target `endpoints` and normalize from the `Endpoint*` object family
  - `endpointIdChanges` / `endpointLastSeen` are candidates for incremental sync later, not prerequisites for v1
  - Direct Connect, action execution, scheduled actions, and Connect export jobs are later capability flags, not part of the base Tanium inventory adapter
- (2026-04-06) Docs-site gotcha: navigating directly to deep links or clicking raw anchors can bounce the browser into Redocly login. Expanding schema sections and changing routes inside the existing authenticated page was reliable; use that workflow if more schema mining is needed.

## Commands / Runbooks

- (2026-04-06) Find the live Tanium docs browser pane:
  - `alga-dev list-browsers --allTabs --pretty`
- (2026-04-06) Pull Tanium doc text from the live pane:
  - `alga-dev browser-eval --paneId=<pane> --script='(() => (document.body.innerText || \"\").slice(0, 10000))()'`
- (2026-04-06) Fetch official markdown docs directly:
  - `python3 - <<'PY'`
  - `import requests`
  - `print(requests.get('https://developer.tanium.com/guides/core-platform/integration_methods.md').text)`
  - `PY`
- (2026-04-06) Scaffold this plan:
  - `python3 /Users/roberisaacs/.codex/skills/alga-plan/scripts/scaffold_plan.py --slug tanium-rmm-integration-plan "Tanium RMM Integration Plan"`
- (2026-04-06) Validate F002 targeted changes:
  - `npx nx test @alga-psa/assets --testFile=packages/assets/src/lib/rmmProviderDisplay.test.ts`
  - `npx nx test @alga-psa/types`
- (2026-04-06) Validate F003/F004 targeted changes:
  - `npx nx typecheck @alga-psa/integrations`
- (2026-04-06) Validate F005-F009 targeted changes:
  - `npx nx typecheck @alga-psa/integrations`
- (2026-04-06) Validate F010-F018/F020 targeted changes:
  - `npx nx typecheck @alga-psa/integrations`
  - `npx nx typecheck sebastian-ee`
- (2026-04-06) Validate Tanium + shared RMM tests:
  - `npx nx test sebastian-ee -- --run src/__tests__/unit/integrations/taniumActions.test.ts src/__tests__/unit/integrations/TaniumIntegrationSettings.ui.test.tsx src/__tests__/unit/integrations/rmm/syncOrchestration.test.ts`
  - `cd server && npx vitest run ../packages/integrations/src/lib/rmm/providerRegistry.test.ts ../packages/integrations/src/components/settings/integrations/RmmIntegrationsSetup.registry.test.tsx ../packages/integrations/src/lib/rmm/sharedAssetIngestionService.test.ts`
  - Note: `@alga-psa/integrations` Nx test target currently points to deprecated `@nx/vite:test` without a config file; targeted package tests were executed via server Vitest harness instead.

## Implementation Log

- (2026-04-06) `F002` completed.
  - Added `tanium` to `RmmProvider` unions in:
    - `packages/types/src/interfaces/asset.interfaces.ts`
    - `server/src/interfaces/asset.interfaces.tsx`
    - `ee/server/src/interfaces/rmm.interfaces.ts`
  - Refactored EE RMM settings typing to separate common settings from provider-specific payloads:
    - introduced `RmmCommonIntegrationSettings`
    - introduced typed provider payloads (`NinjaOneRmmProviderSettings`, `TacticalRmmProviderSettings`, `TaniumRmmProviderSettings`)
    - introduced `RmmProviderConfigurationPayload` and `provider_settings`
    - retained `ninja_instance_region` as a compatibility bridge during migration
  - Updated provider display utilities/tests to include `tanium`:
    - `packages/assets/src/lib/rmmProviderDisplay.ts`
    - `packages/assets/src/lib/rmmProviderDisplay.test.ts`
  - Expanded type-level coverage:
    - `packages/types/src/interfaces/rmmProvider.typecheck.test.ts`

- (2026-04-06) `F003` completed.
  - Added shared provider registry with normalized provider metadata and capability flags:
    - `packages/integrations/src/lib/rmm/providerRegistry.ts`
  - Registry now captures connection/scope/device/events/remote-action capability state per provider and centralizes enterprise/feature-flag availability gates.

- (2026-04-06) `F004` completed.
  - Refactored settings selector UI to render provider cards from registry output instead of hard-coded provider branches:
    - `packages/integrations/src/components/settings/integrations/RmmIntegrationsSetup.tsx`
  - Added Tanium placeholder settings component wiring behind the `tanium-rmm-integration` feature flag so registry-driven rendering can include Tanium metadata without breaking current behavior.

- (2026-04-06) `F005` completed.
  - Added normalized provider contracts for scopes and device snapshots:
    - `packages/integrations/src/lib/rmm/contracts.ts`

- (2026-04-06) `F006` completed.
  - Added shared RMM asset correlation/upsert ingestion service centered on `tenant_external_entity_mappings`:
    - `packages/integrations/src/lib/rmm/sharedAssetIngestionService.ts`

- (2026-04-06) `F007` completed.
  - Shared ingestion create path now provisions:
    - base `assets` row
    - extension row (`workstation_assets` / `server_assets` when applicable)
    - `tenant_external_entity_mappings` link
  - Creation is driven from normalized snapshots and resolved client mapping.

- (2026-04-06) `F008` completed.
  - Shared ingestion update path now:
    - updates mapped assets
    - upserts extension fields
    - refreshes mapping metadata/sync timestamps
  - Includes fallback correlation to an existing asset by `rmm_provider + rmm_device_id` when an external mapping row is missing.

- (2026-04-06) `F009` completed.
  - Shared ingestion now handles lifecycle states `deleted`/`tombstoned` with a single path that marks asset inactive/offline and updates mapping status/metadata (`deleted`, `deletedAt`).

- (2026-04-06) `F010` completed.
  - Added transport-agnostic sync orchestration seam:
    - `ee/server/src/lib/integrations/rmm/sync/syncOrchestration.ts`
  - Tanium full sync now executes through this seam (`runRmmSyncWithTransport`) with direct transport active by default and temporal transport hook points available via env configuration.

- (2026-04-06) `F011` completed.
  - Added Tanium Gateway client/query runner:
    - `ee/server/src/lib/integrations/tanium/taniumGatewayClient.ts`
  - Includes authenticated GraphQL query runner, connection test, scope discovery (`computerGroups`), endpoint inventory (`endpoints`), and optional Asset API fallback fetcher.

- (2026-04-06) `F012` completed.
  - Added tenant-scoped Tanium connection lifecycle actions:
    - `ee/server/src/lib/actions/integrations/taniumActions.ts`
  - Implements settings retrieval, configuration save, connection test (state transition to active on success), and disconnect (secret cleanup + inactive row state).

- (2026-04-06) `F013` completed.
  - Added Tanium provider settings UI:
    - Enterprise implementation: `ee/server/src/components/settings/integrations/TaniumIntegrationSettings.tsx`
    - CE stub path for shared alias resolution: `packages/ee/src/components/settings/integrations/TaniumIntegrationSettings.tsx`
  - Selector wiring updated via shared provider registry rendering:
    - `packages/integrations/src/components/settings/integrations/RmmIntegrationsSetup.tsx`

- (2026-04-06) `F014` completed.
  - Implemented Tanium scope discovery action (`syncTaniumScopes`) with `rmm_organization_mappings` upsert/refresh behavior.

- (2026-04-06) `F015` completed.
  - Tanium settings now exposes mapping management using existing `rmm_organization_mappings` flow and client assignment updates (`updateTaniumOrganizationMapping`).

- (2026-04-06) `F016` completed.
  - Implemented Tanium full inventory sync action (`triggerTaniumFullSync`) that fetches endpoint inventory, normalizes snapshots, and calls shared ingestion (`ingestNormalizedRmmDeviceSnapshot`).

- (2026-04-06) `F017` completed.
  - Implemented constrained Asset API fallback path in full sync when a mapped scope has no Gateway endpoints and fallback is enabled.

- (2026-04-06) `F018` completed.
  - Tanium phase-1 implementation remains pull-only: no new `/api/webhooks/*` or callback ingress routes added.

- (2026-04-06) `F020` completed.
  - Tanium actions reuse existing `rmm_integrations` sync lifecycle fields (`sync_status`, `sync_error`, `last_sync_at`, `last_full_sync_at`) rather than introducing a separate status subsystem.

- (2026-04-06) `F019` completed.
  - Legacy NinjaOne and Tactical settings flows remain operable and are now selected via registry-driven adapter wiring in `RmmIntegrationsSetup` (`providerSettingsComponents`) instead of bespoke top-level branching, allowing transition without rewriting either provider stack.

## Test Implementation Log

- (2026-04-06) `T001` completed.
  - Added provider registry capability test:
    - `packages/integrations/src/lib/rmm/providerRegistry.test.ts`
  - Added selector registry-rendering test:
    - `packages/integrations/src/components/settings/integrations/RmmIntegrationsSetup.registry.test.tsx`

- (2026-04-06) `T002` completed.
  - Added shared ingestion create-path test:
    - `packages/integrations/src/lib/rmm/sharedAssetIngestionService.test.ts`

- (2026-04-06) `T003` completed.
  - Added shared ingestion update/no-duplicate test:
    - `packages/integrations/src/lib/rmm/sharedAssetIngestionService.test.ts`

- (2026-04-06) `T004` completed.
  - Added scope-discovery mapping preservation test in Tanium actions suite:
    - `ee/server/src/__tests__/unit/integrations/taniumActions.test.ts`

- (2026-04-06) `T005` completed.
  - Added Tanium full-sync happy-path test asserting Gateway fetch + shared ingestion invocation + completed sync status:
    - `ee/server/src/__tests__/unit/integrations/taniumActions.test.ts`

- (2026-04-06) `T006` completed.
  - Added Tanium fallback test asserting Asset API path ingestion when Gateway scope returns zero endpoints:
    - `ee/server/src/__tests__/unit/integrations/taniumActions.test.ts`

- (2026-04-06) `T007` completed.
  - Added connection failure test asserting inactive integration and actionable auth error:
    - `ee/server/src/__tests__/unit/integrations/taniumActions.test.ts`

- (2026-04-06) `T008` completed.
  - Added UI integration-style test for Tanium settings configuration/test/scope-discovery flow:
    - `ee/server/src/__tests__/unit/integrations/TaniumIntegrationSettings.ui.test.tsx`

- (2026-04-06) `T009` completed.
  - Added shared sync orchestration seam tests:
    - `ee/server/src/__tests__/unit/integrations/rmm/syncOrchestration.test.ts`

## Links / References

- Official docs:
  - https://developer.tanium.com/guides/core-platform/integration_methods
  - https://developer.tanium.com/guides/core-platform/integration_methods.md
  - https://developer.tanium.com/apis/api_intro
  - https://help.tanium.com/bundle/ug_gateway_cloud/page/gateway/index.html
  - https://help.tanium.com/bundle/ug_gateway_cloud/page/gateway/gateway.html
- Alga repo references:
  - `server/migrations/20251124000001_create_rmm_integration_tables.cjs`
  - `server/migrations/20250502173321_create_tenant_external_entity_mappings.cjs`
  - `packages/integrations/src/components/settings/integrations/RmmIntegrationsSetup.tsx`
  - `server/src/middleware.ts`
  - `ee/server/src/interfaces/rmm.interfaces.ts`
  - `ee/server/src/lib/integrations/ninjaone/sync/syncStrategy.ts`
  - `ee/server/src/lib/integrations/ninjaone/sync/syncEngine.ts`
  - `ee/temporal-workflows/src/activities/ninjaone-sync-activities.ts`
  - `packages/integrations/src/actions/integrations/tacticalRmmActions.ts`
  - `packages/integrations/src/lib/rmm/tacticalrmm/tacticalApiClient.ts`

## Open Questions

- What exact Tanium auth material should Alga store per tenant for Gateway access?
- Do we need incremental sync in Tanium v1, or is full inventory sync enough until real-world volume proves otherwise?
- Is there an officially documented programmatic management surface for Tanium Connect destinations/jobs, or would later Connect event delivery be console-configured?
- Does `ComputerGroup` map cleanly enough to `rmm_organization_mappings` for real MSP tenant usage, or do we need a provider-specific scope-normalization rule on top of Tanium groups?
- Which exact `Endpoint` fields and nested objects are sufficient for Alga’s normalized device snapshot without overspecifying the first adapter?