> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Shadow AI
> Discover, monitor, and control shadow AI clients, MCP servers, skills, and plugins across your organization
## The Shadow AI Problem
When employees install AI clients, configure MCP servers, or add AI skills directly — Cursor, Claude Code, Claude Desktop, VS Code, Codex, and others — these tools and integrations run outside centralized observability and control. The result is a **shadow IT problem for AI tooling**: ungoverned access to your code, data, and systems, with no audit trail.
Runlayer addresses shadow AI through the **AI Watch** agent: one signed package with Detect, configurable endpoint behavior, and Sessions telemetry. Deploy it once through your MDM, then change behavior through configuration.
Install one package, then configure Monitor, Protect, Enforce, and Sessions
Always on — discover AI clients, shadow MCP servers, skills, and plugins via scheduled scans
`Mode` — Monitor activity, Protect with scanner actions and allow-unless-denied MCP governance, or Enforce with deny-by-default governance
Allow MCP sources by default while blocking explicit remote, package, and built-in denylist matches
`Sessions` flag — collect lifecycle telemetry for prompts, tool calls, and responses
Map device usernames to Runlayer users for discoveries, sessions, and audit
***
## Security Risks
### Shadow MCP Servers
Shadow MCP servers pose significant security risks:
* **Data exfiltration** — Risky MCP servers can steal source code, credentials, API keys, and customer data
* **Supply chain attacks** — Compromised or trojanized MCP packages can inject risky behavior into otherwise legitimate tools
* **Prompt injection** — Shadow MCPs may contain tool poisoning attacks that manipulate AI behavior
* **Lateral movement** — MCPs with broad permissions can be exploited to access internal systems
* **Compliance violations** — Uncontrolled access to PII, PHI, or regulated data without audit trails
### Shadow Skills
Skills are instruction files that extend AI coding assistants with specialized knowledge, workflows, and tool integrations — such as SKILL.md files. When these are installed outside organizational control, they become **shadow skills**.
Shadow skills introduce distinct risks:
* **Prompt injection** — Skill instructions can manipulate AI behavior, override safety guidelines, or inject malicious prompts
* **Unauthorized automation** — Skills can define workflows that automate actions beyond what an organization has approved
* **Supply chain risk** — Unvetted community skills may contain instructions that exfiltrate data or introduce vulnerabilities
### Shadow AI Clients
AI clients are inventory artifacts in their own right. Detect reports supported clients such as Cursor and Claude Code even when they have no MCP servers, skills, or plugins configured, giving security teams visibility into unapproved AI software across their device fleet.
New client discoveries start as **Shadow**. Administrators can mark approved clients as **Managed** from the Shadow Overview. Client presence has a **Low** baseline risk because presence alone does not expose the behavior of an integration; use the detected version, device, user, and installation evidence when reviewing it.
### Why This Matters for Security Teams
Unlike traditional shadow IT, shadow AI is particularly dangerous because:
1. **AI amplifies access** — A single MCP or skill can give AI assistants broad access to databases, APIs, and file systems
2. **Actions are automated** — MCPs enable AI to take actions autonomously, not just read data
3. **No audit trail** — Shadow MCPs and skills operate outside your logging and monitoring infrastructure
4. **Difficult to detect** — MCP configurations and skill files are stored in user-space config files, not installed as traditional software
***
## One Package, Three Endpoint Modes
Project and client-config detection is always enabled after AI Watch is installed. Endpoint behavior is selected with `Mode`; Sessions and optional runtime discovery are controlled independently. One organization API key authenticates AI Watch scans, hooks, session events, and macOS updates; no enrollment keys are required.
| Capability | Configuration | What it does |
| --------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Detect** | Always on | Discovers AI clients, shadow MCP servers, skills, and plugins from project and client configuration files |
| **Running processes** | `DetectProcesses` / `AIWATCH_DETECT_PROCESSES` | Discovers AI tooling and configured MCP servers from running processes and listening sockets |
| **Containers** | `DetectContainers` / `AIWATCH_DETECT_CONTAINERS` | Performs read-only MCP config, skill, and agent-definition discovery inside running Docker containers through the Docker CLI or local Engine API socket; on Linux, also scans k3s through root-only `k3s crictl` |
| **Monitor** | `Mode=monitor` / `AIWATCH_MODE=monitor` | Reports endpoint hook activity without applying scanner or governance decisions |
| **Protect** | `Mode=protect` / `AIWATCH_MODE=protect` | Applies scanner-configured Block and Mask decisions plus fail-open, allow-unless-denied MCP source governance; explicit denylist matches are blocked |
| **Enforce** | `Mode=enforce` / `AIWATCH_MODE=enforce` | Applies scanner and local policy decisions to non-MCP tools plus fail-closed, deny-by-default MCP source governance; managed MCP calls scan at the gateway |
| **Sessions** | `Sessions` / `AIWATCH_SESSIONS` | Installs the full event hook set for [Sessions](/platform-sessions) telemetry |
* **Running-process and container discovery** are disabled by default. Set their macOS/Linux keys to `true` or Windows properties to `1` to opt in.
* **Monitor** is the default mode.
* **Sessions** is enabled by default. Set `Sessions=false` (macOS) or `AIWATCH_SESSIONS=0` (Windows) to skip the full event/session hook set.
`Mode` overrides the legacy `Enforcement` boolean when it contains a valid value. If `Mode` is absent or invalid, `Enforcement=true` maps to Enforce and `Enforcement=false` or absent maps to Monitor. Generated deployment artifacts still include `Enforcement` for older AI Watch versions: Monitor writes `false`, while Protect and Enforce write `true`. Mode-aware clients apply the exact selected mode; an older client receiving Protect falls back to Enforce rather than silently monitoring, but does not have Protect's exact direct-MCP scanner path.
Hook installation follows the combined capability state: AI Watch installs hook configs when Mode is Protect/Enforce or Sessions is enabled. Detect-only uses Monitor with Sessions disabled; omitting Sessions uses the default enabled state and installs hooks for Monitor telemetry.
On current macOS and Windows packages, admins can change Mode, Sessions, process/container discovery, project depth, and project timeout from **Settings → MDM configuration → Manage settings**. Devices fetch the complete settings snapshot during the privileged hook reconcile, typically within an hour, without an MDM policy update. The tenant host, organization API key, `AutoUpdate`, CPU/memory limits, and browser-extension settings remain MDM-owned.
**Advanced scan tuning (optional).** Detect scans walk each user's home directory to a bounded depth within a per-scan time budget, and a cooperative in-process governor keeps CPU and memory use within soft caps. The defaults fit most fleets — override them only if scans miss deeply-nested project configs (raise depth), run out of time on very large home directories (raise timeout), or you want to constrain the scan's footprint on constrained hosts (lower the CPU / memory caps).
| Setting | Configuration | Default | Range |
| --------------------- | -------------------------------------------- | ---------------------- | ----------------- |
| **Project depth** | `ProjectDepth` / `AIWATCH_PROJECT_DEPTH` | `7` | `1`–`20` |
| **Project timeout** | `ProjectTimeout` / `AIWATCH_PROJECT_TIMEOUT` | `60`s | `1`–`300`s |
| **CPU cores** | `CpuCores` / `AIWATCH_CPU_CORES` | half the logical cores | `1`–logical cores |
| **Max CPU percent** | `MaxCpuPercent` / `AIWATCH_MAX_CPU_PERCENT` | `50` | `5`–`100` |
| **Memory limit (MB)** | `MemoryLimitMb` / `AIWATCH_MEMORY_LIMIT_MB` | `1024` | `128`–`8192` |
All are integers — macOS `` in the tenant-config profile, Windows `REG_DWORD` via the matching MSI `AIWATCH_*` property. Omit the keys to keep the defaults. Values outside the range are clamped into it; non-integer or non-positive values are ignored and the default applies. The CPU / memory caps are best-effort: the governor throttles the scan to hold the CPU duty cycle (`max(0.05, min(cpu_cores, MaxCpuPercent% × logical_cores))` cores) and aborts the scan if its Python-heap high-water mark exceeds the memory ceiling.
Deploying the default package is not scan-only: if Sessions is left unset, AI Watch installs monitoring hooks for supported local clients. For Detect-only rollout with no hooks, explicitly disable Sessions (`Sessions=false` on macOS or `AIWATCH_SESSIONS=0` on Windows). See the [Intune Detect-only example](/shadow-ai/deploy/intune#phase-1--create-the-app).
Start with [Deploy AI Watch](/shadow-ai/deploy) to install the package and choose Mode / Sessions configuration. Detect scans run by default after deployment.
***
## The Shadow Dashboard
The **Shadow** page in the sidebar brings every discovery into one view:
* **Overview** — per-device Client, MCP, Skill, and Plugin rows with type filters, a managed vs. shadow breakdown, and a **Shadow vs Managed** trend over time
* **Connectors** — most common shadow servers, users running them, top servers to migrate, and which MCP clients are in use
* **Skills** — shadow skill discoveries over time, most common skills, users with shadow skills, and a per-client breakdown
* **Devices** — AI Watch device fleet mode and health, Sessions health, OS versions, and tool versions across enrolled devices
### The Devices tab
Open the **Shadow** page and select the **Devices** tab to answer per-device fleet questions during and after rollout:
* **Which endpoint mode is active** — each row shows a **Mode** badge (`Monitor`, `Protect`, or `Enforce`), an aggregate **Status** badge for Detect and the selected endpoint mode, and an independent **Sessions** status badge. Hover an `Error` or `Drifted` status to see the underlying error message and when it occurred.
* **Which Runlayer version each device runs** — the **Tool version** column shows the installed AI Watch agent version per device, alongside **OS**, **OS version**, and a **Last seen** check-in timestamp. Use this to track upgrade progress across the fleet.
* **Filtering** — narrow the table by Detect, Protect, Enforce, or Sessions status, device, user, OS, or OS version; columns are sortable.
***
## Related Resources
Refresh server and skill classifications after changes
Security team response framework
Common issues and solutions
Pre-deployment, security-review, and operational questions
Remove package-based and legacy script-based deployments