guru-connect/docs/specs/SPEC-006-universal-machine-search.md

# SPEC-006: Universal Machine Search ("Everything Is Searchable")

**Status:** Proposed
**Priority:** P2
**Requested By:** Mike (2026-05-30)
**Estimated Effort:** Medium

## Overview

Give the Operator Console a single search box that matches a query against **any**
attribute of any guest machine and returns all matches — OS, logged-on user, IP, company,
site, tag, serial, MAC, version, anything — exactly like ScreenConnect. Today the
dashboard filters only `hostname`/`agent_id` client-side (`MachinesPage.tsx:46`), which
is useless across a ~900-machine fleet. Success = typing "windows 11" finds every Win11
box, "fred" finds every machine where Fred is/was logged on, and "98.97" finds the
machine at that IP — server-side, fast, case-insensitive substring, across the whole
fleet.

**Examples (user-stated):** search an OS string → all machines with that OS; a username →
all machines with that logged-on user; an IP (external or private) → the matching
machine(s).

## Scope

### Included in v1

- **Server-side multi-attribute search** on `GET /api/machines?q=<text>` (extend
  `list_machines`), default = **case-insensitive substring, match-any-field** across:
  `hostname`, `agent_id`/`machine_uid`, `organization` (company), `site`, `department`,
  `device_type`, `tags`, `logged_on_user`, `os_name`/`os_version` (+locale),
  `agent_version` (client version), `manufacturer`, `model`, `serial_number`,
  `machine_description`, `external_ip`, `private_ip`, `mac_address`, `status`.
- **Multi-term AND:** space-separated terms all must match (each term may match a
  different field) — "windows fred" = Win machine where Fred is logged on.
- **Performance:** a Postgres index that supports substring search across all columns
  (see Architecture) so search stays fast at fleet scale.
- **IP/array handling:** `external_ip`/`private_ip` (INET, from SPEC-003) matched as text
  for partial-IP queries ("98.97"); `tags` (TEXT[]) matched per-element.
- Wire the dashboard search box to the server query (debounced), replacing the
  hostname-only client filter; render results through the SPEC-005 list view.

### Nice-to-have (v1 if cheap, else fast-follow)

- **Field-scoped syntax** like ScreenConnect: `os:windows`, `user:fred`, `ip:98.97`,
  `company:"arizona computer"`, `tag:winter`, `version:23.9` — a known-prefix restricts
  the match to that column; unprefixed terms stay match-any-field; quotes group a phrase.

### Explicitly out of scope

- Saved searches / smart groups / search-driven "session groups" (ScreenConnect's
  `+ Create Session Group`) — separate feature.
- Boolean OR / NOT / regex / fuzzy ranking — v1 is AND-of-substring; relevance ranking
  deferred.
- Searching **live-only** state not persisted to the DB (current viewer/host connection)
  — exposed as a secondary structured filter (online/offline), not free-text, since it
  lives in the in-memory `SessionManager`, not `connect_machines`.
- Full event/session-history search — this spec is machine search.

## Architecture

- **Relay-server / DB (the core):** add search to `db::machines` and `list_machines`
  (`main.rs:636`). Query shape:
  - Maintain a searchable-text representation of each `connect_machines` row and index it
    for substring search. Two viable approaches (decide in planning):
    1. **`pg_trgm` GIN index** over a concatenated expression
       (`lower(hostname||' '||coalesce(organization,'')||' '||…||' '||host(external_ip)||…)`).
       Supports `ILIKE '%term%'` on arbitrary substrings with index acceleration. Simple,
       matches ScreenConnect's substring semantics best.
    2. **Generated `search_text` column** (maintained on write / via the same path as
       `update_machine_metadata`/`update_machine_inventory`) + `pg_trgm` GIN on it.
       Slightly more plumbing, cleaner query, easier to weight later.
  - `tags TEXT[]` folded into the text via `array_to_string(tags,' ')`; INET via
    `host(external_ip)`/`host(private_ip)`.
  - Field-scoped terms compile to a targeted `col ILIKE '%v%'` (or `= ANY(tags)` for
    `tag:`); unscoped terms to the concatenated-text match; all terms AND-ed.
- **API:** `list_machines` gains `q` (and reuses the SPEC-005 enriched `MachineInfo`
  payload so results render fully). Same `AuthenticatedUser` admin guard.
- **Dashboard:** the existing search input drives `listMachines({ q })` (debounced ~250ms)
  in `dashboard/src/api/machines.ts`; remove the hostname-only client filter in
  `MachinesPage.tsx`. Show result count + "no matches" empty state.
- **Protobuf:** none — server/dashboard/DB only. Searchability of inventory fields is
  entirely dependent on SPEC-003 persisting them.

## Implementation details

- Files to touch: `server/migrations/` (new migration: `CREATE EXTENSION IF NOT EXISTS
  pg_trgm;` + the GIN index / optional `search_text` column — idempotent, startup-applied
  by `sqlx::migrate!()`, never pre-applied via psql); `server/src/db/machines.rs`
  (`search_machines(q)` or `get_all_machines` gaining a filter; parameterized, never
  string-interpolated); `server/src/main.rs:636` (`list_machines` reads `q`);
  `dashboard/src/features/machines/MachinesPage.tsx:46` (drop local filter, call server),
  `dashboard/src/api/machines.ts` (q param).
- Key logic: tokenize on whitespace (respecting quotes), classify each token as
  scoped/unscoped, build a parameterized `WHERE term1 AND term2 …`. Cap query length and
  term count.

## Security considerations

- **SQL injection:** all terms are bound parameters (`$n`), never concatenated into SQL.
  Column list for scoped search is a fixed allowlist — a `field:` prefix can only map to a
  known column, never arbitrary SQL.
- Admin-authenticated only (`AuthenticatedUser`), same as the existing machines list — no
  new unauthenticated surface; search exposes nothing the list doesn't already.
- **DoS guard:** cap query length, number of terms, and result page size; `pg_trgm` keeps
  worst-case substring scans index-backed so a broad query can't table-scan 900+ rows
  unindexed.
- Treat the query as untrusted text; the response is the same admin-only machine data.

## Testing strategy

- **Unit:** tokenizer (quotes, multi-term, scoped vs. unscoped); query builder emits
  parameterized SQL with the right AND structure; scoped `field:` maps only to allowlisted
  columns (unknown prefix → treated as literal text, not an error/injection).
- **Integration (seeded DB):** "windows 11" returns all Win11 rows; a username returns
  rows with that `logged_on_user`; a partial IP returns rows whose `external_ip`/
  `private_ip` contains it; a tag value returns tagged rows; multi-term ANDs correctly;
  empty `q` returns the full list unchanged.
- **Performance:** with ~1k seeded rows, a broad substring query uses the GIN index
  (EXPLAIN shows index scan, not seq scan) and returns within target latency.
- **Manual:** on the live console, reproduce the user's three examples (OS, username, IP).

## Effort estimate & dependencies

- **Size: Medium.** The query builder + index is the bulk; the API/dashboard wiring is
  small. Field-scoped syntax adds a little parsing.
- **Depends on:** **SPEC-003** — the inventory attributes (OS detail, user, IP, MAC,
  serial, version, device type) must be **persisted** on `connect_machines` to be
  searchable; without it, search covers only the handful of existing columns. Reuses
  **SPEC-005**'s enriched payload to render results; benefits from **SPEC-004** dedup so
  results aren't padded with ghost duplicates. Migration orders after SPEC-003/004's.
- **Unblocks:** fast fleet triage ("who's on this IP / running this OS / logged in as X"),
  and the saved-search / smart-group follow-up.

## Open questions

1. **Index strategy** — concatenated-expression `pg_trgm` GIN vs. a maintained
   `search_text` column. Proposed: start with the expression index (less write plumbing);
   move to `search_text` if weighting/ranking is wanted later.
2. **Field-scoped syntax in v1 or fast-follow?** Default match-any-field covers the stated
   use cases; scoped syntax is polish.
3. **Result cap / pagination** — return all matches, or page (limit/offset)? At ~1k rows a
   cap with "N more" may suffice; confirm.
4. **Include live online/host state as a filter** — free-text can't reach in-memory state;
   offer `status:online` as a structured filter that the server resolves against the
   SessionManager, or keep search DB-only in v1?