optimus-discovery

Daily shadow-AI discovery scan for macOS endpoints. Finds AI agents by tells alone (no registry, no known-agent list): filesystem markers, app bundles, IDE/browser extensions, content signatures, packages, running processes, listening model-server ports, and shell/browser history corroboration.

Provenance

src/discover.ts and src/test/discover.test.ts were moved from the discovery R&D repo (itself a faithful TypeScript port of discover.py). Detection logic is unchanged; the R&D repo remains the home for methodology docs and the Python reference. Package-specific additions:

• src/rules.ts — the tell tables grouped behind an injectable DiscoveryRules object (backend-served rules become possible later without collector changes).
• src/index.ts — endpoint integration bin (discovery-staging): darwin guard, TTL cadence re-check, borderline findings dropped from the report, atomic local storage, non-zero exit on failure.
• src/storage.ts — atomic report writes + 7-day history pruning.
• vendor/rg/ — pinned ripgrep binaries for darwin-arm64/darwin-x64 (refresh with npm run fetch-rg; provenance in vendor/rg/manifest.json). Missing/broken binary is a hard error — no $PATH lookup, no JS fallback in production scans.

Behavior

• Runs only on macOS; exits 0 elsewhere.
• Report: ~/.optimuslabs/management/discovery/latest-report.json (envelope: schema_version, generated_at, scanner_version, hostname, result), plus history/<date>.json pruned to the last 7.
• Cadence: skips if the last successful run is within OPTIMUS_DISCOVERY_TTL_SECONDS (default 86400) — the same env var the shell hook's TTL gate uses. OPTIMUS_SKIP_DISCOVERY skips entirely.
• No network I/O: the scan is a pure producer of the local report file. Transport to the backend ships later via the agent-inventory mechanism.

Usage

# endpoint bin (what the hook runs)
npx --yes --package=@optimuslabs/optimus-discovery-staging discovery-staging

# manual scan with human-readable / JSON output
node dist/discover.js
node dist/discover.js --json --out results.json

Development

npm install
npm test          # builds, then runs the frozen detection suite + integration tests

The detection tests in src/test/discover.test.ts are frozen: only mechanical import-path changes are allowed. New endpoint behavior belongs in src/test/integration.test.ts.