VULNEX Agent Security Observer — agent-agnostic security scanner for AI agent deployments.

VASO scans AI agent frameworks, interactive coding agents, desktop AI apps, and MCP server configurations for security misconfigurations, malicious code, and known threats. It runs 251 checks across 18 agents (9 autonomous frameworks + 7 interactive coding agents + Claude Desktop + ChatGPT Desktop) plus MCP-server scanning, using AST-based static analysis (not regex) for accurate results without ever executing scanned code.

VASO is distributed from GitHub. The npm name vaso is held by an unrelated package; do not install that.

# One-liner (Linux / macOS / WSL)
curl -fsSL https://raw.githubusercontent.com/vulnex/vaso/main/install.sh | bash

# Or directly via npm from GitHub
npm install -g github:vulnex/vaso#v0.4.6

Requires Node.js 20+.

For development, or to install from a local checkout:

git clone https://github.com/vulnex/vaso.git
cd vaso
npm install
npm run build           # produces dist/cli.js
npm link                # optional: put `vaso` on PATH globally

Without npm link, run the CLI directly with ./bin/vaso. Other useful scripts: npm run dev (rebuild on change), npm test (unit), npm run test:e2e, npm run lint (tsc --noEmit).

# Scan all detected AI agents
vaso scan

# List installed agents
vaso detect

# Scan MCP server configs
vaso mcp scan

Exit code 1 means critical findings were detected — use this to fail CI pipelines.

VASO can scan remote hosts over SSH or from pre-collected snapshots — no Node.js required on the target. A static Go probe binary is pushed on demand, runs once, and is removed. See doc/network-scanning-guide.md for the full workflow.

# Scan one remote host
vaso scan --host [email protected]

# Scan a fleet (parallel, with retry on transient SSH failures)
vaso scan --inventory hosts.yaml --parallel 20 --ssh-retries 2

# Collect snapshots once, re-scan offline against new baselines
vaso scan --inventory hosts.yaml --save-snapshot ./snapshots/
vaso scan --snapshot ./snapshots/prod-agent-01.json --diff

See doc/user-guide.md for full option reference.

Autonomous frameworks

• OpenClaw — ~/.openclaw, ~/.clawdbot, ~/.moltbot, /etc/openclaw
• NanoClaw — ~/.nanoclaw.env, ~/.config/nanoclaw/
• PicoClaw — ~/.picoclaw/
• IronClaw — ~/.ironclaw/ (TOML, gRPC gateway)
• Nanobot — ~/.nanobot/ (Discord/Slack bot framework)
• ZeroClaw — ~/.zeroclaw/ (Composio integration)
• NemoClaw — ~/.nemoclaw/ (NVIDIA NIM, GPU isolation)
• Hermes — ~/.hermes/ (API-server gateway model)
• Lyrie — ~/.lyrie/ (Bun turborepo, Rust Shield Layer 1, 10-channel gateway)

Coding agents

• Claude Code — ~/.claude/, ~/.claude.json, project-level .claude/
• Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), %APPDATA%\Claude\claude_desktop_config.json (Windows); MCPB extensions
• ChatGPT Desktop — /Applications/ChatGPT.app + ~/Library/Application Support/com.openai.chat/; preferences plist (macOS only)
• Codex — ~/.codex/{config.toml,auth.json}
• OpenCode — XDG paths ($XDG_CONFIG_HOME/opencode/, $XDG_DATA_HOME/opencode/)
• Gemini CLI — ~/.gemini/ (settings.json + OAuth credential files)
• Qwen Code — ~/.qwen/ (multi-provider auth: OpenAI / Anthropic / Gemini / Dashscope / Bailian)
• GitHub Copilot CLI — ~/.copilot/ + workspace .mcp.json + .github/lsp.json
• Cursor CLI — ~/.cursor/ (cli-config.json + mcp.json)

MCP servers — Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, project-level configs

251 checks organized into 16 categories:

Server-only checks (gateway/network/runtime concepts) are automatically excluded for coding agents to avoid false positives — interactive coding CLIs have a different threat model than autonomous server agents.

vaso scan                              # Terminal (default) — color-coded with score
vaso scan --format json -o report.json # JSON — structured, machine-readable
vaso scan --format sarif -o results.sarif  # SARIF — GitHub Code Scanning compatible
vaso scan --format markdown -o report.md   # Markdown — for PR comments
vaso scan --format html -o report.html     # HTML — standalone report
vaso scan --format csv -o results.csv      # CSV — one row per finding, for SIEM ingestion
vaso scan --format junit -o results.xml    # JUnit XML — for CI test-result reporters

VASO produces a 0–100 score with a letter grade (A–F). Critical findings deduct 12 points, warnings deduct 5.

The simplest path — drop one step into any workflow:

- uses: vulnex/vaso@v1
  with:
    fail-on: critical          # or warning, info, none
    format: sarif              # sarif, json, markdown, html, terminal
    # output: vaso-results.sarif  (default: vaso-results.<ext>)
    # agent: claude-code           (default: scan all detected agents)
    # version: v0.4.6               (git ref: tag, branch, or commit SHA)
    # upload-sarif: 'true'          (auto-uploads to Code Scanning)

The action installs the requested VASO version, runs the scan, and (when format: sarif) uploads the report to GitHub Code Scanning. Exit codes follow --fail-on: a critical threshold (default) fails the build only on critical findings; pass none to never fail.

- name: Install VASO
  run: npm install -g github:vulnex/vaso#v0.4.6

- name: Run VASO scan
  run: vaso scan --format sarif -o results.sarif --fail-on critical

- name: Upload SARIF
  if: always()
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Track security posture over time:

vaso scan --save-baseline    # Save after a clean scan
vaso scan --diff             # Compare against baseline on subsequent scans

vaso visualize emits USecVisLib config files (TOML by default; JSON/YAML available) for three diagram types: per-installation attack tree, per-installation privilege gradient (architecture-specific — NemoClaw GPU isolation, Claude Code MCP transport, etc.), and a whole-scan component diagram.

# Run a fresh scan and write the bundle
vaso visualize -o ./vis/

# Or replay a saved scan result
vaso scan -f json -o scan.json
vaso visualize -i scan.json -o ./vis/

# Render with USecVisLib (commands also listed in the bundle README)
usecvis -m 0 -i ./vis/openclaw-attack-tree.toml -o tree -f png
usecvis -m 6 -i ./vis/openclaw-privilege-gradient.toml -o gradient -f png
usecvis -m 7 -i ./vis/topology.toml -o topology -f png

VASO never bundles, sidecars, or calls a USecVisLib server — the contract between the two tools is a static config file. Users render externally with whichever USecVisLib mode (CLI, REST, or MCP) they prefer.

For environments without Node.js, run 5 critical checks with pure Bash:

bash bin/vaso-quick.sh

VASO supports user plugins in ~/.vaso/plugins/. Plugins can add custom checks, output formatters, and agent adapters. See doc/development-guide.md for the plugin API.

• User Guide — full command reference and configuration
• Network Scanning Guide — SSH, inventory, snapshot, and fleet workflows
• Development Guide — contributing and plugin development
• Testing Guide — test suite and CI setup

Apache-2.0 — see LICENSE.