Agent ecosystem security — inventory scan / web sanitize / paste detection.

9 tools exposed via one MCP server, plus a CLI and a Claude Code hook handler.

cargo install agentsec

This places agentsec under ~/.cargo/bin/. Confirm:

agentsec --version

User-scope (recommended — available in every project):

claude mcp add agentsec -s user -- agentsec mcp

Project-scope (only in the current repo):

claude mcp add agentsec -- agentsec mcp

To enable the LLM-backed second sanitize layer (web_fetch → Anthropic Messages API), point the server at a .env that defines ANTHROPIC_API_KEY:

claude mcp add agentsec -s user -e AGENTSEC_DOTENV=/path/to/.env -- agentsec mcp

Restart Claude Code for the new MCP server to appear.

The two hook handlers run agentsec as a short-lived subprocess on specific Claude Code events:

• user-prompt-submit — runs paste_inspect on the prompt; exits non-zero on a Blocked verdict so Claude Code rejects the submission.
• session-start — runs an inventory scan and writes a one-line summary (with a diff-since-last-snapshot field) to <home>/scans/last-session-start.txt.

Add to ~/.claude/settings.json (merge with your existing hooks block; do not overwrite — Claude Code allows multiple commands per matcher):

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "agentsec hook user-prompt-submit", "timeout": 10 }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "agentsec hook session-start", "timeout": 30 }
        ]
      }
    ]
  }
}

Restart Claude Code for the hooks to take effect.

claude mcp list | grep agentsec   # → agentsec: agentsec mcp - ✔ Connected
agentsec info                     # prints the resolved <home>/ paths

In a Claude Code chat, the mcp__agentsec__* tool family (scan / scan_diff / registry_check / plain_enable / plain_restore / plain_status / emergency_stop / paste_inspect / web_fetch) should be available.

agentsec scan         # one-shot inventory scan, prints a Markdown report
agentsec diff         # diff vs latest snapshot, no new snapshot created
agentsec blacklist    # classify installed MCP server names vs the known-good registry
agentsec plain        # plain-mode .mcp.json gate (subcommands: enable / restore / status)
agentsec stop         # emergency stop: SIGTERM Agent / MCP processes by name pattern
agentsec info         # version + resolved paths + env state with provenance
agentsec status       # runtime activity overview (file counts, plain-mode, registry size)
agentsec recent       # tail recent paste_log / web_log audit rows
agentsec doctor       # comprehensive health check (env, paths, hook, MCP register)
agentsec mcp          # start the MCP server (stdio transport)
agentsec install      # 1-cmd setup: patch ~/.claude.json mcpServers + merge ~/.claude/settings.json hooks (dry-run default; --apply to write; auto-backup)
agentsec uninstall    # 1-cmd teardown: remove agentsec MCP entry + agentsec hook entries (dry-run default; --apply to write)
agentsec hook <n>     # Claude Code hook handler (user-prompt-submit | session-start)

The MCP server exposes the same surface as tools (scan, scan_diff, registry_check, plain_enable, plain_restore, plain_status, emergency_stop, paste_inspect, web_fetch, info, status, recent_activity, doctor) plus a small set of resources under agentsec://guides/ (overview / runbook-verify / changelog) so MCP clients can fetch the bundled documentation without leaving the session.

Run agentsec <subcommand> --help for flags.

• crates/agentsec/ — umbrella binary (CLI / MCP / hook adapter).
• crates/agentsec-core/ — pure-logic library (scan / paste / web).
• crates/agentsec-platform-claude/ — probe for Claude Code (CLI).
• crates/agentsec-platform-cursor/ — probe for Cursor.
• crates/agentsec-platform-claude-desktop/ — probe for Claude Desktop (macOS).

See the crate-level RustDoc (cargo doc --open -p agentsec-core) for the threat surface × vector model, runtime data layout, environment variables, and read-only invariants.

AgentSec scans config layouts via the PlatformProbe trait (agentsec_core::platform::PlatformProbe). New AI-agent platforms (Codex, Gemini CLI, Copilot, Windsurf, etc.) can be supported by adding a sibling crate without touching agentsec-core.

Trait surface (5 required + 2 with default impls):

• id() — stable platform identifier ("cursor", "claude-desktop", …).
• target_roots(paths) — (category, path) pairs to walk for inventory.
• mcp_config_paths(paths) — files that may carry an mcpServers block.
• extract_mcp_servers(content, path) — parse declared MCP servers.
• critical_categories() — categories that earn the 🚨 CRITICAL marker.
• decompose_file(...) — optional per-fragment decomposition (default: whole-file).
• McpServerEntry — emitted by extract_mcp_servers.

Naming convention: agentsec-platform-<name>. Use agentsec-platform-cursor (single-OS, no decomposition) or agentsec-platform-claude-desktop (macOS-only sibling) as a template — both implement the trait in roughly 100 lines plus unit tests. External binaries register a probe slice by constructing &[&dyn PlatformProbe] directly; the in-tree default_probes() helper in agentsec shows the pattern.

PRs adding a sibling crate are welcome. Each new crate should ship with: probe impl + unit tests, an entry in crates/agentsec/src/lib.rs default_probes(), and a one-line addition to the Crates list above.

claude mcp remove agentsec -s user
cargo uninstall agentsec

Remove the corresponding UserPromptSubmit / SessionStart entries from ~/.claude/settings.json by hand.

Apache-2.0