Metadata-Version: 2.4
Name: securevector-ai-monitor
Version: 5.3.0
Summary: Real-time AI threat monitoring. Protect your apps from prompt injection, leaks, and attacks in just a few lines of code.
Home-page: https://github.com/secure-vector/ai-threat-monitor
Author: SecureVector Team
Project-URL: Bug Reports, https://github.com/secure-vector/ai-threat-monitor/issues
Project-URL: Source, https://github.com/secure-vector/ai-threat-monitor
Project-URL: Documentation, https://docs.securevector.io/ai-threat-monitor
Project-URL: Homepage, https://securevector.io
Keywords: ai security llm prompt-injection threat-detection threat-monitoring openai claude securevector
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: PyYAML>=5.1
Requires-Dist: requests>=2.32.4
Requires-Dist: aiohttp>=3.13.5
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: urllib3>=2.6.3
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.23.0; extra == "mcp"
Requires-Dist: fastmcp<4,>=2.13.0; extra == "mcp"
Provides-Extra: app
Requires-Dist: pywebview>=5.0; extra == "app"
Requires-Dist: fastapi>=0.100.0; extra == "app"
Requires-Dist: uvicorn[standard]>=0.20.0; extra == "app"
Requires-Dist: aiosqlite>=0.19.0; extra == "app"
Requires-Dist: sqlalchemy>=2.0.0; extra == "app"
Requires-Dist: watchdog>=3.0.0; extra == "app"
Requires-Dist: platformdirs>=3.0.0; extra == "app"
Requires-Dist: keyring>=23.0.0; extra == "app"
Requires-Dist: httpx>=0.24.0; extra == "app"
Requires-Dist: websockets>=12.0; extra == "app"
Requires-Dist: eval_type_backport>=0.2.0; python_version < "3.10" and extra == "app"
Requires-Dist: securevector-guardian-model<2,>=1.2; python_version >= "3.10" and extra == "app"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0; extra == "dev"
Requires-Dist: pytest-xdist>=2.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: flake8>=4.0; extra == "dev"
Requires-Dist: isort>=5.0; extra == "dev"
Requires-Dist: mypy>=0.900; extra == "dev"
Requires-Dist: safety>=2.0; extra == "dev"
Requires-Dist: bandit>=1.7; extra == "dev"
Requires-Dist: psutil>=5.8; extra == "dev"
Requires-Dist: fastapi>=0.100.0; extra == "dev"
Requires-Dist: httpx>=0.24.0; extra == "dev"
Provides-Extra: benchmark
Requires-Dist: psutil>=5.8; extra == "benchmark"
Requires-Dist: memory-profiler>=0.60; extra == "benchmark"
Provides-Extra: all
Requires-Dist: mcp>=1.23.0; extra == "all"
Requires-Dist: fastmcp>=2.13.0; extra == "all"
Requires-Dist: pywebview>=5.0; extra == "all"
Requires-Dist: fastapi>=0.100.0; extra == "all"
Requires-Dist: uvicorn[standard]>=0.20.0; extra == "all"
Requires-Dist: aiosqlite>=0.19.0; extra == "all"
Requires-Dist: sqlalchemy>=2.0.0; extra == "all"
Requires-Dist: watchdog>=3.0.0; extra == "all"
Requires-Dist: platformdirs>=3.0.0; extra == "all"
Requires-Dist: psutil>=5.8; extra == "all"
Requires-Dist: memory-profiler>=0.60; extra == "all"
Requires-Dist: eval_type_backport>=0.2.0; python_version < "3.10" and extra == "all"
Requires-Dist: securevector-guardian-model<2,>=1.2; python_version >= "3.10" and extra == "all"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<div align="center">

<h1><img src="docs/favicon.png" alt="SecureVector" width="40" height="40"> SecureVector</h1>

<h3>Security and Observability for AI Agents</h3>

<p><em>Every model call and every tool call your agent makes, on one timeline, with a security verdict on each. On your machine.</em></p>

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=for-the-badge)](https://opensource.org/licenses/Apache-2.0)
[![PyPI](https://img.shields.io/pypi/v/securevector-ai-monitor.svg?style=for-the-badge)](https://pypi.org/project/securevector-ai-monitor)
[![Python](https://img.shields.io/pypi/pyversions/securevector-ai-monitor.svg?style=for-the-badge)](https://pypi.org/project/securevector-ai-monitor)
[![Downloads/month](https://img.shields.io/pypi/dm/securevector-ai-monitor?style=for-the-badge&label=downloads%2Fmonth&color=orange)](https://pypistats.org/packages/securevector-ai-monitor)
[![Downloads total](https://img.shields.io/pepy/dt/securevector-ai-monitor?style=for-the-badge&label=downloads%20total&color=orange)](https://pepy.tech/project/securevector-ai-monitor)
[![Discord](https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/k3bgZuCQBC)


</div>

## Two lines of Python

```bash
pip install "securevector-ai-monitor[app]"
securevector-app --web
```

```python
from securevector import guard, instrument

instrument()   # patches the OpenAI and Anthropic clients you already use

with guard.session("ticket-8812", user_id="u-42"):
    reply = client.chat.completions.create(model="gpt-4o", messages=messages)
```

Open [http://localhost:8741](http://localhost:8741) and every model call is there: model, tokens, cost, duration, finish reason, a verdict, and a redacted preview of the prompt and the response. Every `@guard` tool call nests under the model turn that asked for it.

<p align="center"><img src="docs/screenshots/traces-split-pane.gif" alt="Traces: pick an agent on the left, read its whole run as a waterfall on the right" width="100%"></p>

Any other provider gets one span per call with `guard.generation()`, and anything already instrumented with the OpenTelemetry GenAI conventions can send straight to `/v1/traces`. Details in [docs/TRACING.md](docs/TRACING.md).

## What you get

- **See it.** One trace per agent session. Pick an agent on the left, read its whole run as a waterfall on the right. Live follow, replay, and a costliest-turn mark on every run.
- **Stop it.** Allow, block or log-only per tool, at runtime. Blocked tools become just-in-time requests you approve for fifteen minutes or an hour. Enforce mode blocks a model call before it leaves your process.
- **Catch it.** 72 rules covering the OWASP LLM Top 10 plus 28 agent-attack chains, and an optional offline ML model, applied while the agent is still running.
- **Know where it went.** Every external host an agent reached, when it was first seen, and a policy that decides which ones it may reach.
- **Prove it.** Every tool call in a SHA-256 hash-chained log. Blocked actions get a per-rule evidence ledger.
- **Pay less.** A local scan of your own transcripts shows why sessions cost what they did, with copyable fixes.
- **Keep it.** Apache 2.0. No signup. Nothing leaves your machine unless you connect it.

## Connect an agent

| You run | Do this |
|---|---|
| Python with OpenAI or Anthropic | The two lines above |
| LangChain, LangGraph, CrewAI | One SDK each: [langchain](https://github.com/Secure-Vector/securevector-sdk-langchain), [langgraph](https://github.com/Secure-Vector/securevector-sdk-langgraph), [crewai](https://github.com/Secure-Vector/securevector-sdk-crewai) |
| Claude Code, Codex, Copilot CLI, Cursor, OpenCode | Open the app, **Connect Agents**, pick yours, **Install Plugin** |
| OpenClaw | **Connect Agents**, OpenClaw, **Install Plugin**, restart OpenClaw |
| Anything else with an OpenAI-compatible endpoint | **Connect Agents**, **Start Proxy**, point the base URL at it |

Prefer an installer? [Windows, macOS and Linux builds](https://github.com/Secure-Vector/securevector-ai-threat-monitor/releases/latest) are on the releases page. If ports 8741 or 8742 are taken, pass `--port`.


### Works with every agent

| Agent / runtime | How to add | Audit `runtime_kind` |
|---|---|---|
| **Claude Code** | Native plugin — inline hooks, zero proxy | `claude-code` |
| **OpenAI Codex** *(CLI 0.133+)* | Native plugin | `codex` |
| **GitHub Copilot CLI** | Native plugin | `copilot-cli` |
| **Cursor** | Native plugin | `cursor` |
| **OpenCode** *(1.18+)* | Native plugin — in-process ES module, no subprocess hooks | `opencode` |
| **OpenClaw / ClawdBot** | Native plugin | `openclaw` |
| **LangChain** | SDK — [`securevector-sdk-langchain`](https://github.com/Secure-Vector/securevector-sdk-langchain) (`pip install`) | `langchain` |
| **LangGraph** | SDK — [`securevector-sdk-langgraph`](https://github.com/Secure-Vector/securevector-sdk-langgraph) (`pip install`) | `langgraph` |
| **CrewAI** | SDK — [`securevector-sdk-crewai`](https://github.com/Secure-Vector/securevector-sdk-crewai) (`pip install`) | `crewai` |
| **Hermes (hermes-agent)** | SDK — [`securevector-sdk-hermes`](https://github.com/Secure-Vector/securevector-sdk-hermes) (`pip install`, zero-config plugin) | `hermes` |

<div align="center">

<br>


[Website](https://securevector.io) · [Getting Started](docs/GETTING_STARTED.md) · [Verify your install](SECURITY.md#build-provenance--verifying-your-install) · [Discord](https://discord.gg/k3bgZuCQBC) · [Dashboard Screenshots](#screenshots)

</div>

<br>

<div align="center">
  <h3>▶ Watch the Demo</h3>
  <a href="https://youtu.be/9RByIHSV95s">
    <img src="https://img.youtube.com/vi/9RByIHSV95s/maxresdefault.jpg" alt="SecureVector Demo — Security &amp; Observability for AI Agents, live" width="480">
  </a>
  <p><em>Threat detection, tool permissions, and cost tracking — running locally in real time.</em></p>
</div>

<br>

<div align="center">
  <img src="docs/guardian-bot.gif" width="150" alt="The Guardian bot, cycling through its accent colors">
  <p><em>Meet the Guardian, our new on-device advisor. Pick any of its six colors.</em></p>
</div>

> **What's new in v5.2.0**
> - **Cost / Token Optimizer** — Cost Tracking answers *how much*; the Optimizer answers *why* and *what to change*. An opt-in local scan ranks each session's waste and deep-links every finding to the exact turns in Traces. Copy a fix and it re-measures: only measured wins are celebrated.
> - **Per-run limits** — opt-in tool-call caps, a loop breaker, and per-run cost/token ceilings on the existing deny rails, each with an audit row and a one-click, time-boxed exemption. Ships off.
> - **SecureVector Guard for OpenCode** — the Guard plugin family gains OpenCode (1.18+) as a native in-process module, one-click installed, on the same policy rails as every other harness.
> - **The Guardian assistant** — a docked, advisory character that orients you on whatever page you just opened, announces a blocked egress the moment it happens with one click through to the evidence, and wears whichever of six accent colors you pick (above). It never types into a session or edits your files.
> - **An honest fill gauge** — context-fill percentage now comes from evidence in the transcript, so it can never read "118% full" again.
>
> Also: a redesigned Cost Summary and a full model-pricing re-verification. **Previously:** v5.1.0 shipped Agent Egress Governance, blast-radius inventory, scope-expansion alerting, and counterfactual policy replay.
>
> Full release history in the [CHANGELOG](CHANGELOG.md).

## How It Works

<img src="docs/securevector-architecture.svg" alt="SecureVector Architecture" width="100%">

**SecureVector** protects your AI agents at three layers:

- **Pre-install** — the Skill Scanner checks agent skill packages for shell access, network calls, and hidden risks before you install them.
- **Runtime** — every tool call lands in a SHA-256 hash-chained audit log; prompts, responses, and natural-language tool inputs are scanned for injection, data leaks, and unauthorized access.
- **Observe** — the SIEM Forwarder ships threats + audits to your SOC in OCSF 1.3.0 (Splunk, Datadog, Sentinel, Chronicle, QRadar, OTLP, webhook, NDJSON). Metadata-only by default.

100% local — events only leave the machine when you configure a SIEM destination you control.

<br>


## Screenshots

*All screenshots are from a local app instance.*

**🗺️ Agent Map & Traces**

<table>
<tr>
<td width="58%"><img src="docs/screenshots/agent-map.png" alt="Agent Map" width="100%"><br><em>Agent Map — your whole fleet at a glance: device → harness → agent → tool, across tree / radial / mesh / Sankey views. Blocked calls pop red, secret-touching agents wear a lock. Click any node to drill into its trace.</em></td>
<td width="42%"><img src="docs/screenshots/agent-runs.png" alt="Traces" width="100%"><br><em>Traces — a turn-by-turn waterfall of every tool call with its allow / block verdict, risk, and reason. Here a prompt-injection and a credential-exfiltration attempt are both caught and blocked.</em></td>
</tr>
</table>

<br>

<table>
<tr>
<td width="25%"><img src="docs/screenshots/tool-call-history.png" alt="Tool Call History" width="100%"><br><em>Tool Call History — 4,925 calls in a SHA-256 hash-chained log, every row integrity-verified: 7 blocked, 48 logged</em></td>
<td width="25%"><img src="docs/screenshots/dashboard.png" alt="Dashboard" width="100%"><br><em>Dashboard — threats, secret catches, tool-call volume, and the Optimizer headline across the last 30 days</em></td>
<td width="25%"><img src="docs/screenshots/costs-light.png" alt="Cost / Token Optimizer" width="100%"><br><em>Cost / Token Optimizer — what your sessions used, what they could have used, and the lossless fixes behind the gap</em></td>
<td width="25%"><img src="docs/screenshots/skill-scanner.png" alt="Skill Scanner" width="100%"><br><em>Skill Scanner — static analysis of a skill package before you install it: risk level and findings, per skill</em></td>
</tr>
</table>

<br>

## Features in depth

<table>
<tr>
<th align="left" width="50%">Tool Audit & Permissions</th>
<th align="left" width="50%">Threat Detection</th>
</tr>
<tr>
<td valign="top">

Every tool call is recorded to a SHA-256-linked, tamper-evident audit log (re-verify in one click). Tool inputs are stored *after* secret redaction, up to 8 KB per field, and never leave the device (older plugin hooks cut at 200 characters, so reinstall the plugin and reload after updating). Allow / deny / ask rules per tool, enforced at the agent runtime via PreToolUse hooks or the multi-provider proxy.

</td>
<td valign="top">

Scans every prompt, response, and natural-language tool input for prompt injection (direct + indirect), jailbreaks, PII leaks, credential exfiltration, and tool-result injection. 72 rules covering the OWASP LLM Top 10 + 28 agent-attack chains. Monitor by default; opt-in block mode for hard-stop.

</td>
</tr>
<tr>
<th align="left">Skill Scanner</th>
<th align="left">Cost & Token Tracking</th>
</tr>
<tr>
<td valign="top">

Scan agent skills and tool packages before installing. Static analysis across 10 categories detects shell access, network calls, env var reads, code exec, base64 payloads, symlink escapes, and more. Optional AI review filters false positives automatically.

</td>
<td valign="top">

Per-agent, per-model token and USD spend in real time, with daily budget auto-stop. Plugins read session transcripts locally for a 7-day input/output/cache trend per runtime — no cloud round-trip, no token data leaves your machine.

</td>
</tr>
<tr>
<th align="left">Cost / Token Optimizer</th>
<th align="left">Guardian Assistant</th>
</tr>
<tr>
<td valign="top">

Opt-in local scan that explains the spend: cache waste vs compaction waste, eight detectors with ranked findings that deep-link to the exact turns in Traces, and impact receipts that only resolve when the metric actually moved — measured, never just modeled. Optional per-run limits (tool-call caps, loop breaker, cost/token ceilings) enforce on the existing deny rails; everything ships off.

</td>
<td valign="top">

An ambient character that docks in the corner and speaks only when it helps: context-fill warnings naming the exact agent, copyable fixes whose follow-through is measured from your local transcripts, and a two-sentence orientation of whatever you just opened — answered on the page you are already on. Advisory only: it never types into a session and never edits your files.

</td>
</tr>
<tr>
<th align="left">SIEM Forwarder</th>
<th align="left">Full Visibility</th>
</tr>
<tr>
<td valign="top">

Forward every threat + tool-call audit to your SOC in OCSF 1.3.0. Supports Splunk HEC, Datadog, Microsoft Sentinel, Google Chronicle, IBM QRadar, OpenTelemetry/OTLP, generic webhook, or a local NDJSON file. Metadata-only by default; raw data is opt-in per destination.

</td>
<td valign="top">

Live dashboard showing every LLM request, tool call, token count, and threat event. Per-agent Replay timeline merges threat scans + tool audits + cost into one feed.

</td>
</tr>
<tr>
<th align="left" colspan="2">100% Local by Default</th>
</tr>
<tr>
<td valign="top" colspan="2">

Runs entirely on your machine. No accounts required. No data leaves your infrastructure unless you configure a SIEM destination. Open source under Apache 2.0.

</td>
</tr>
</table>

<br>

**Performance:** Rule-based analysis (default) adds ~10–50ms per request. Optional AI analysis adds 1–3s depending on the model and provider — shown on the dashboard so you can measure it against your actual traffic. Tool-permission decisions (`allow` / `block` / `log_only`): see the [Tool Permissions guide](docs/TOOL_PERMISSIONS.md).

<br>

## Works With Everything

**Your AI Stack** — LangChain · LlamaIndex · CrewAI · AutoGen · LangGraph · n8n · Dify · OpenClaw/ClawdBot — or any framework that makes HTTP calls to an LLM provider.

**LLM Providers** — OpenAI · Anthropic · Ollama · Groq · and any OpenAI-compatible API.

**Run Anywhere** — macOS / Linux / Windows · Docker & Kubernetes · AWS / GCP / Azure · VMs · Lambda / Workers / Vercel.

## Agent Integrations

| Agent/Framework | Integration |
|-----------------|-------------|
| **Any Python agent** (OpenAI, Anthropic, Bedrock, Gemini, plain functions) | [**`@guard` decorator**](#any-python-agent-one-decorator), ships in `pip install securevector-ai-monitor[app]` |
| **LangChain** | [**`securevector-sdk-langchain`**](docs/USECASES.md#langchain) (tool-call SDK, recommended) or LLM Proxy |
| **LangGraph** | [**`securevector-sdk-langgraph`**](docs/USECASES.md#langgraph) (tool-call SDK, recommended) or LLM Proxy |
| **CrewAI** | [**`securevector-sdk-crewai`**](docs/USECASES.md#crewai) (tool-call SDK, recommended) or LLM Proxy |
| **Hermes (hermes-agent)** | [**`securevector-sdk-hermes`**](docs/USECASES.md#hermes) (zero-config tool-call SDK, recommended) |
| **Any OpenAI-compatible** | LLM Proxy — see Integrations in UI |
| **OpenClaw / ClawdBot** *(LLM gateway agent)* | Native plugin (zero latency) — proxy only for block mode |
| **n8n** | [Community Node](docs/USECASES.md#n8n) |
| **Claude Desktop** | [MCP Server Guide](docs/MCP_GUIDE.md) |
| **Any OpenAI-compatible app** | LLM Proxy — set `OPENAI_BASE_URL` to proxy |
| **Any HTTP Client** | `POST http://localhost:8741/analyze` with `{"text": "..."}` |

### Any Python agent (one decorator)

No framework required. Wrap the functions your agent calls and every call lands in Tool Activity, Agent Runs and the tamper-evident audit chain, scanned on the way in and on the way out.

```python
from securevector import guard

@guard
def search_web(query: str) -> str:
    ...

@guard(tool_id="db.query", mode="enforce")   # a finding on the arguments stops the call
async def run_sql(sql: str) -> list[dict]:
    ...

with guard.session("run-42"):                # group one agent run in the app
    search_web("weather in Austin")
```

Fail-open: if the app is not running, the function still runs and one warning is logged. Configure with the same variables as the framework SDKs (`SECUREVECTOR_SDK_MODE=enforce`, `SECUREVECTOR_ENGINE_ENDPOINT=https://...` for a self-hosted engine).

[Full guide](docs/GUARD.md)

**Model calls too.** Add `instrument()` and every OpenAI or Anthropic call joins the same trace with tokens, cost, prompt and response previews, duration and a verdict; `guard.generation()` does the same for Bedrock, Gemini or any other client. The Traces page then shows cost per run, spend per model and the costliest turn.

```python
from securevector import guard, instrument

instrument()                                  # openai and anthropic clients

with guard.session("run-42", user_id="u-1"):
    client.chat.completions.create(model="gpt-4o", messages=messages)   # recorded
    search_web("weather in Austin")                                     # nested under it
```

Already on OpenTelemetry? Point your exporter at `http://127.0.0.1:8741/v1/traces` (OTLP/HTTP JSON) and skip the SDK. [Tracing guide](docs/TRACING.md)

### OpenClaw / ClawdBot

Native plugin with **ZERO latency** — runs inside the agent, no proxy needed. Install from the Integrations tab or `curl -X POST http://localhost:8741/api/hooks/install`. Enable block mode from the dashboard when you want to actively stop threats via proxy.

[Full setup guide](docs/OPENCLAW.md)

### Claude Code

First-class plugin for Anthropic's Claude Code CLI — `PreToolUse` enforces tool-permission rules (allow / deny / ask, cloud-syncable), `PostToolUse` writes a tamper-evident audit row + scans prose tool inputs, `UserPromptSubmit` catches direct prompt-injection. Optional one-line statusline emitter surfaces live findings next to model / cwd / git state. Loopback-only, fail-open.

**Install — two options:**

```bash
# Option A: via the app UI
# Open http://127.0.0.1:8741 → Integrations → Claude Code → Install Plugin

# Option B: via CLI
securevector-app --install-plugin claude-code
# Uninstall: securevector-app --uninstall-plugin claude-code

# Then, in your Claude Code session:
/reload-plugins
```

[Full setup guide](docs/CLAUDE_CODE.md)

<br>

## What It Detects

| Input Threats (User to LLM) | Output Threats (LLM to User) |
|-----------------------------|------------------------------|
| Prompt injection | Credential leakage (API keys, tokens) |
| Jailbreak attempts | System prompt exposure |
| Data exfiltration requests | PII disclosure (SSN, credit cards) |
| Social engineering | Jailbreak success indicators |
| SQL injection patterns | Encoded malicious content |
| Tool result injection (MCP) | — |
| Multi-agent authority spoofing | — |
| Permission scope escalation | — |

Full coverage: [OWASP LLM Top 10](https://owasp.org/www-project-top-10-for-large-language-model-applications/)

### AI Agent Attack Protection (28 new rules · 72 total)

Built from real attack chains observed against production agent frameworks:

- **Tool Result Injection** — injected instructions hidden inside MCP tool responses
- **Multi-Agent Authority Spoofing** — impersonating trusted agents in multi-agent pipelines
- **Permission Scope Escalation** — agents requesting more permissions than granted
- **MCP Tool Call Injection** — malicious payloads delivered through MCP tool calls
- **Evasion techniques** (22 rules) — zero-width characters, encoding tricks, roleplay framing, leetspeak, semantic inversion, emotional manipulation, and more

### Optional ML Detection Layer — SecureVector Guardian

Alongside the 72 regex rules, the app ships an **optional ML detection layer** — [**SecureVector Guardian**](https://github.com/Secure-Vector/securevector-guardian-model), a stdlib-only semantic threat classifier. It runs in parallel with the rule engine and catches obfuscated, paraphrased, buried, or encoded attacks that literal patterns miss, folding its verdict into the same allow / alert / block decision. The model is fully local and runs offline — no cloud round-trip, no prompt text leaves your machine.

**Install — comes with the app.** Guardian is the [`securevector-guardian-model`](https://github.com/Secure-Vector/securevector-guardian-model) package, installed automatically as a dependency: `pip install securevector-ai-monitor[app]` pulls it in (pure Python, zero ML dependencies). `pip install -U securevector-guardian-model` + restart updates the model independently of app releases, and the loaded version is shown in **Settings → Guardian ML Detection**. The model runtime (~1.8 MB) is fetched once on first use and cached locally for offline use thereafter; for air-gapped installs, pre-place it and point `SV_GUARDIAN_RUNTIME` at the file.

**On by default.** Toggle it from **Settings → Guardian ML Detection** (default ON), or force it off globally with the `SECUREVECTOR_ML_ENABLED=false` environment flag. With Guardian disabled the regex rules keep running unchanged, and the layer is fail-open — any model error silently falls back to rules-only so it never breaks the analyze path.

**What to expect when it's on.** The model is pure Python (zero dependencies, no GPU, no network), so it runs on any machine. It analyzes **in parallel** with the regex rules, adding roughly **~0.15 ms per typical analysis** (a prompt, tool call, or response — sub-millisecond), a few ms for ~1 KB of text, and up to ~100 ms only for very large documents (bounded, never unbounded). One-time startup is ~200 ms + ~34 MB RAM. Older/slower CPUs scale proportionally, but everyday inputs stay sub-millisecond. Full benchmark: [model performance](https://github.com/Secure-Vector/securevector-guardian-model#performance--what-to-expect).

<br>

## Device Identity

Every scan and audit row is stamped with a stable `device_id` so a customer running SecureVector across several laptops or agents can answer *"which agent blocked this, which laptop is tampered, which machine spent what?"* — not just *"one of my installs did this"*.

**Why we need it.** A solo developer runs one install. A SOC team runs five to fifty. When an audit chain breaks, or a spike of blocked gmail-send calls shows up, the useful first question is *which machine*. Without a per-device tag, the answer is "some install" — which is useless in a fleet. `device_id` pins every row to a specific machine so dashboards, alerts, and compliance reviews can slice by device.

**How it's generated** (`src/securevector/app/utils/device_id.py`):

1. Read the OS's existing stable machine identifier:
   - macOS → `IOPlatformUUID` via `ioreg`
   - Linux → `/etc/machine-id` (fallback `/var/lib/dbus/machine-id`)
   - Windows → `HKLM\SOFTWARE\Microsoft\Cryptography\MachineGuid`
2. SHA-256 hash it with a namespace prefix (`securevector-device-v1:<raw>`) and truncate to 24 hex chars → `sv-a1b2c3d4e5f6...`
3. Cache the result in `~/Library/Application Support/ThreatMonitor/.device_id` (0o600) so the OS fetch happens once per install.
4. If the OS refuses (rare: locked-down container, unusual Linux image), fall back to a random UUID cached to the same file.

**Stability across reinstalls.** The OS identifier outlives the app install — so uninstalling and reinstalling SecureVector on the same machine gives you the **same `device_id`**. Wiping the app data dir AND having no readable OS ID is the only combination that generates a new one. A new physical machine always gets a new ID.

**Security / privacy posture — what the customer should know:**

| Concern | Reality |
|---|---|
| Is the raw OS machine UUID transmitted? | **No.** It's read locally, SHA-256 hashed with a namespace, and only the hash is stored. The raw value never reaches a log file or outbound event. |
| Can `device_id` be reversed to the OS UUID? | SHA-256 is one-way. An attacker who already has the raw OS UUID can *compute* the `device_id` — but they already have the machine at that point, so there's no incremental leak. |
| Does it track users? | No. It tracks *machines*. Multiple users on one laptop share one `device_id`. It's not tied to email, username, or any identity field. |
| Is it sent to SecureVector Cloud? | Only if Cloud Connect is on AND you trigger an action that reaches the cloud (rule sync, cloud-routed `/analyze`). `device_id` goes in metadata alongside scan results. You can opt out by keeping Cloud Connect off — local-only operation never transmits it. |
| Is it in SIEM forwards? | Yes, when the v4.0+ SIEM forwarder is enabled — travels inside each OCSF event's `unmapped` block so your Splunk/Datadog can group by device. |
| Can the customer reset it? | Yes — delete `.device_id` in the app data dir. Next write will regenerate from the OS identifier (so same ID reappears) OR a fresh random UUID if the OS ID is unavailable. |
| Does it collide across containers cloned from the same image? | Potentially yes (they share `/etc/machine-id`). Not relevant for desktop use; mention it if you're deploying in Kubernetes. |

**In one sentence:** `device_id` is a machine-identifier-per-install, derived locally, hashed before storage, never transmitted except with explicit user opt-in (Cloud Connect or SIEM Forwarder).

<br>

## SIEM Forwarder

Stream every threat detection and tool-call audit into your own SIEM — Splunk HEC, Datadog, Microsoft Sentinel, Google Chronicle, IBM QRadar, an OpenTelemetry collector, a local NDJSON file, or any HTTPS endpoint that accepts JSON. Your data, your pipes.

**Why this is safe to ship with zero monetization:**

| Feature | What leaves your machine |
|---|---|
| Scan verdict | `scan_id`, `verdict`, `threat_score`, `risk_level`, `detected_types[]`, counts, durations |
| Tool-call audit | `seq`, `action`, `risk`, `prev_hash`, `row_hash` (the chain witness — lets your SIEM verify integrity) |
| **Never transmitted** | Prompt text, LLM output, matched patterns, reviewer reasoning, model reasoning |

The allow-list is enforced at enqueue time by `_assert_metadata_only()`. Even if the forwarder code were tampered with, it can't add the forbidden fields back.

**Supported destinations (one code path, OCSF 1.3.0 payload):**

| Kind | Target | Auth header |
|---|---|---|
| `splunk_hec` | `https://<host>/services/collector/event` | `Authorization: Splunk <HEC-token>` |
| `datadog` | `https://http-intake.logs.<site>/api/v2/logs` | `DD-API-KEY: <key>` |
| `otlp_http` | `https://<collector>/v1/logs` | optional `Authorization: Bearer <token>` |
| `webhook` | anything that accepts JSON POST | optional `Authorization: Bearer <token>` |

**Configure in Connect → SIEM Forwarder.** Add SIEM destination → pick type → paste URL + token → Test → Save. Tokens are stored `0o600` in the app data dir, never in SQLite.

**📊 Starter dashboards included:**

| Platform | Template |
|---|---|
| Microsoft Sentinel | [`docs/siem/sentinel/securevector-workbook.json`](docs/siem/sentinel/securevector-workbook.json) |
| Splunk | [`docs/siem/splunk/securevector-dashboard.xml`](docs/siem/splunk/securevector-dashboard.xml) |
| Datadog | [`docs/siem/datadog/securevector-dashboard.json`](docs/siem/datadog/securevector-dashboard.json) |
| Grafana (Loki) | [`docs/siem/grafana/securevector-dashboard.json`](docs/siem/grafana/securevector-dashboard.json) |

Each carries severity counters, events-over-time by severity, actor and MITRE-ish breakdowns, and a recent-high-severity log feed. **MIT-licensed, AS-IS.** Full install steps + field reference in [`docs/siem/README.md`](docs/siem/README.md); trademark + upstream licenses in [`docs/siem/NOTICE`](docs/siem/NOTICE).

> Starter templates — import-test in your own stack and adjust queries / facets / sourcetypes before relying on them for production detections.

**Reliability:**
- Per-destination outbox with at-least-once delivery.
- A failing Datadog destination never blocks a healthy Splunk one.
- Per-destination circuit breaker backs off broken endpoints (1 min → 1 hour cap).
- Rows that fail 10 times are dropped (the health view shows the consecutive-failure count).

**SIEM-side integrity verification.** Every forwarded tool-call audit row carries its `prev_hash` and `row_hash`. Run a nightly search in your SIEM that rebuilds the chain — if a historic row has been tampered with on the local host, the forwarded evidence still tells the true story. That's the *actual* tamper evidence; the local chain alone is only the low bar.

<br>

## Skill Scanner

Scan AI agent skills and tool packages **before** you install them. SecureVector performs static analysis across 10 detection categories, assigns a risk score, and optionally runs an AI review to filter false positives.

```
┌──────────────────────────────────────────────────────────────────────┐
│                        Skill Scanner Flow                           │
│                                                                     │
│   ┌─────────────┐     ┌──────────────────┐     ┌────────────────┐  │
│   │  Skill Dir   │────>│  Static Analysis  │────>│  Risk Scoring  │  │
│   │  or URL      │     │  (10 categories)  │     │  LOW/MED/HIGH  │  │
│   └─────────────┘     └──────────────────┘     └───────┬────────┘  │
│                                                         │           │
│                              ┌───────────────────────── │           │
│                              v                          v           │
│                     ┌─────────────────┐     ┌────────────────────┐  │
│                     │  AI Review      │     │  Policy Engine     │  │
│                     │  (optional LLM) │     │  allow/block rules │  │
│                     │  FP filtering   │     │  trusted publishers│  │
│                     └────────┬────────┘     └─────────┬──────────┘  │
│                              │                        │             │
│                              v                        v             │
│                     ┌──────────────────────────────────────┐        │
│                     │  Verdict: PASS / WARN / BLOCK        │        │
│                     │  + detailed findings per category     │        │
│                     └──────────────────────────────────────┘        │
└──────────────────────────────────────────────────────────────────────┘
```

### Detection Categories

| Category | What It Finds |
|----------|--------------|
| `shell_exec` | Subprocess calls, system commands |
| `network_domain` | HTTP requests, socket connections, DNS lookups |
| `env_var_read` | Access to environment variables (API keys, secrets) |
| `code_exec` | eval, dynamic code generation |
| `dynamic_import` | Runtime module loading |
| `file_write` | Writing to disk outside expected paths |
| `base64_literal` | Obfuscated payloads in base64 strings |
| `compiled_code` | .pyc, .so, .dll binaries embedded in the skill |
| `symlink_escape` | Symlinks pointing outside the skill directory |
| `missing_manifest` | No permissions.yml declaring required capabilities |

### AI-Powered Review

Enable AI analysis (OpenAI, Anthropic, Ollama, Azure, or Bedrock) to automatically review findings and filter false positives. The AI examines each finding in context and adjusts the risk level — reducing noise without hiding real threats.

<br>

## Open Source

SecureVector is fully open source. No cloud required. No accounts. No tracking. Run it, fork it, contribute to it.

**Built for** solo developers and small teams who ship AI agents without a security team or a FinOps budget. If you are building with LangChain, CrewAI, OpenClaw, or any agent framework — and you do not have someone watching your agent traffic and API spend — SecureVector is for you.


## Install

### Option 1: pip

**Requires:** Python 3.9+ (MCP requires 3.10+)

```bash
pip install securevector-ai-monitor[app]
securevector-app --web
```

### Option 2: Binary installers

No Python required. Download and run.

| Platform | Download |
|----------|----------|
| Windows | [SecureVector-v5.3.0-Windows-Setup.exe](https://github.com/Secure-Vector/securevector-ai-threat-monitor/releases/download/v5.3.0/SecureVector-v5.3.0-Windows-Setup.exe) |
| macOS | [SecureVector-5.3.0-macOS.dmg](https://github.com/Secure-Vector/securevector-ai-threat-monitor/releases/download/v5.3.0/SecureVector-5.3.0-macOS.dmg) |
| Linux (AppImage) | [SecureVector-5.3.0-x86_64.AppImage](https://github.com/Secure-Vector/securevector-ai-threat-monitor/releases/download/v5.3.0/SecureVector-5.3.0-x86_64.AppImage) |
| Linux (DEB) | [securevector_5.3.0_amd64.deb](https://github.com/Secure-Vector/securevector-ai-threat-monitor/releases/download/v5.3.0/securevector_5.3.0_amd64.deb) |
| Linux (RPM) | [securevector-5.3.0-1.x86_64.rpm](https://github.com/Secure-Vector/securevector-ai-threat-monitor/releases/download/v5.3.0/securevector-5.3.0-1.x86_64.rpm) |

[All Releases](https://github.com/Secure-Vector/securevector-ai-threat-monitor/releases) · [SHA256 Checksums](https://github.com/Secure-Vector/securevector-ai-threat-monitor/releases/download/v5.3.0/SHA256SUMS.txt)

> **Security:** Only download installers from this official GitHub repository. Always verify SHA256 checksums before installation. SecureVector is not responsible for binaries obtained from third-party sources.

> **macOS binary note:** **Only download from this official GitHub repository** and verify the [SHA256 checksum](https://github.com/Secure-Vector/securevector-ai-threat-monitor/releases/download/v5.3.0/SHA256SUMS.txt) before installing. (Prefer pip? `pip install securevector-ai-monitor[app]` always works too.)

### Other install options

| Install | Use Case | Size |
|---------|----------|------|
| `pip install securevector-ai-monitor` | **SDK only** — lightweight, for programmatic integration | ~18MB |
| `pip install securevector-ai-monitor[app]` | **Full app** — web UI, LLM proxy, cost tracking, tool permissions | 453 KB wheel · ~16 MB total on disk (incl. dependencies) |
| `pip install securevector-ai-monitor[mcp]` | **MCP server** — Claude Desktop, Cursor | ~38MB |

<br>

### Deploy to your own cloud (self-host)

Want it as shared infrastructure instead of one laptop? Run the engine in **your own cloud tenant** — one `terraform apply` stands it up with a live HTTPS dashboard, so a whole team's agents point at a single instance. Open-source modules (Apache 2.0), one per provider:

| Cloud | Terraform module |
|---|---|
| **AWS** | [terraform-aws-securevector](https://github.com/Secure-Vector/terraform-aws-securevector) |
| **Azure** | [terraform-azurerm-securevector](https://github.com/Secure-Vector/terraform-azurerm-securevector) |
| **Google Cloud** | [terraform-google-securevector](https://github.com/Secure-Vector/terraform-google-securevector) |
| **Oracle Cloud** | [terraform-oci-securevector](https://github.com/Secure-Vector/terraform-oci-securevector) |

Your data stays in your tenant. `terraform output` gives you the endpoint URL — then point your agents at it with the lightweight SDK (LangChain / LangGraph / CrewAI / Hermes, `--no-deps` install) and/or the SecureVector Guard plugin. See each SDK / plugin's docs for the one env var to set.

<br>

## Configuration

SecureVector writes `svconfig.yml` to your app data directory on first run with sensible defaults.

The config path is printed at startup — `~/.local/share/securevector/threat-monitor/svconfig.yml` (Linux), `~/Library/Application Support/SecureVector/ThreatMonitor/svconfig.yml` (macOS), `%LOCALAPPDATA%/SecureVector/ThreatMonitor/svconfig.yml` (Windows). Key settings (all editable from the dashboard, which writes back to this file):

```yaml
server:   { host: 127.0.0.1, port: 8741 }        # change port if 8741 is taken
security: { block_mode: false, output_scan: true } # log/warn by default; flip block_mode to hard-stop
budget:   { daily_limit: 5.00, warn: true, block: true }  # USD/day; daily_limit null to disable
tools:    { enforcement: true }                   # apply allow/block tool rules
proxy:    { integration: openclaw, mode: multi-provider, host: 127.0.0.1, port: 8742 }
          # integration: openclaw | langchain | langgraph | crewai | hermes | ollama; port defaults to server.port + 1
```

### MCP Policies — Cloud Sync (optional)

If your org distributes signed MCP tool-policy bundles from SecureVector Cloud, enroll the device once and let the local app long-poll for updates.

**1. Admin mints a token** in the cloud admin UI (`app.securevector.io` → Onboarding → Invite users) and shares the install command.

**2. User enrolls locally:**

```bash
securevector-app enroll svet_<token>
```

The local app POSTs `/api/v1/devices/enroll`, persists `org_id` + signing key + auth credentials to `~/Library/Application Support/.credentials` (macOS — equivalent path on Linux/Windows), and starts the cloud sync loop on next launch.

**3. Set `SECUREVECTOR_API_KEY` for stable sync auth (recommended).**

The local app accepts two auth methods on `/policy/sync`. The API key path is **canonical** — it eliminates the short-lived-JWT refresh fragility that can leave a device unable to sync if the refresh token goes stale.

```bash
export SECUREVECTOR_API_KEY=sk-<long-lived-key>
```

| Auth method | Header sent | Source | Lifetime | Sync stability |
|---|---|---|---|---|
| **API key** ✅ recommended | `X-Api-Key: sk-...` | `SECUREVECTOR_API_KEY` env, then `creds.api_key` | Long-lived | Robust — no refresh path needed |
| JWT (fallback) | `Authorization: Bearer ...` | Stored from enrollment | ~1h, auto-refresh on 401/403 | Breaks if the refresh token expires; requires re-enrollment to recover |

When both are present, the API key wins. `device_id` rides as `X-SecureVector-Device-Id` on every request regardless of auth method; `org_id` is resolved server-side from the auth principal.

You can mint API keys in the cloud admin UI under Access Management. Set the env var in your shell profile or systemd service unit so it survives restarts.

**4. Cloud Sync starts automatically** — no further configuration needed. The local app already defaults to the production cloud endpoints (`auth.securevector.io` and `engine.securevector.io`). Override env vars exist for self-hosted / on-prem deployments only.

Synced rules are read-only on the device — authoring lives in the cloud admin. The MCP Policies page (sidebar → Configure → MCP Policies) shows verification status, applied policies + rules, and a Sync Now button for manual refresh.

### Pointing Your Agent at the Proxy

For **LangChain, CrewAI, Ollama**, and other non-OpenClaw frameworks, point your application to SecureVector's proxy instead of the provider's API. OpenClaw/ClawdBot users only need this when block mode is enabled.

<table>
<tr>
<th align="left" width="50%">🪟 Windows</th>
<th align="left" width="50%">🐧 Linux / macOS</th>
</tr>
<tr>
<td valign="top">

**Command Prompt** (current session)
<pre>set OPENAI_BASE_URL=http://localhost:8742/openai/v1
set ANTHROPIC_BASE_URL=http://localhost:8742/anthropic</pre>

**PowerShell** (current session)
<pre>$env:OPENAI_BASE_URL="http://localhost:8742/openai/v1"
$env:ANTHROPIC_BASE_URL="http://localhost:8742/anthropic"</pre>

**PowerShell** (persistent, per user)
<pre>[Environment]::SetEnvironmentVariable(
  "OPENAI_BASE_URL",
  "http://localhost:8742/openai/v1",
  "User"
)</pre>

</td>
<td valign="top">

**Terminal** (current session)
<pre>export OPENAI_BASE_URL=http://localhost:8742/openai/v1
export ANTHROPIC_BASE_URL=http://localhost:8742/anthropic</pre>

**Persistent** (add to `~/.bashrc` or `~/.zshrc`)
<pre>echo 'export OPENAI_BASE_URL=http://localhost:8742/openai/v1' >> ~/.bashrc
echo 'export ANTHROPIC_BASE_URL=http://localhost:8742/anthropic' >> ~/.bashrc
source ~/.bashrc</pre>

</td>
</tr>
</table>

Every request is scanned for prompt injection. Every response is scanned for data leaks. Every dollar is tracked — whether via native plugin (OpenClaw) or proxy (all other frameworks).

**Supported providers (13):** `openai` `anthropic` `gemini` `ollama` `groq` `deepseek` `mistral` `xai` `together` `cohere` `cerebras` `moonshot` `minimax`

<br>

## Update

| Method | Command |
|--------|---------|
| **PyPI** | `pip install --upgrade securevector-ai-monitor[app]` |
| **Source** | `git pull && pip install -e ".[app]"` |
| **Windows** | Download latest [.exe installer](https://github.com/Secure-Vector/securevector-ai-threat-monitor/releases/latest) and run it (overwrites previous version) |
| **macOS** | Download latest [.dmg](https://github.com/Secure-Vector/securevector-ai-threat-monitor/releases/latest), drag to Applications |
| **Linux AppImage** | Download latest [.AppImage](https://github.com/Secure-Vector/securevector-ai-threat-monitor/releases/latest) and replace the old file |
| **Linux DEB** | `sudo dpkg -i securevector_<version>_amd64.deb` |
| **Linux RPM** | `sudo rpm -U securevector-<version>.x86_64.rpm` |

After updating, restart SecureVector. Then reinstall the Guard plugin for each harness you use (Integrations, or `securevector-app --install-plugin <harness>`) and run `/reload-plugins` in Claude Code, or start a new session. The updated hooks send the full tool input, up to 8 KB per field, so Traces on this device show complete arguments instead of a 200-character cut. Secrets are still redacted, and nothing leaves the device.

<br>

## Documentation

- [Installation Guide](docs/INSTALLATION.md) — Binary installers, pip, service setup
- [Use Cases & Examples](docs/USECASES.md) — LangChain, LangGraph, CrewAI, Hermes, n8n, FastAPI
- [MCP Server Guide](docs/MCP_GUIDE.md) — Claude Desktop, Cursor integration
- [API Reference](docs/API_SPECIFICATION.md) — REST API endpoints
- [Security Policy](.github/SECURITY.md) — Vulnerability disclosure

<br>

## Contributing

```bash
git clone https://github.com/Secure-Vector/securevector-ai-threat-monitor.git
cd securevector-ai-threat-monitor
pip install -e ".[dev]"
pytest tests/ -v
```

[Contributing Guidelines](docs/legal/CONTRIBUTOR_AGREEMENT.md) · [Code of Conduct](.github/CODE_OF_CONDUCT.md)

### Feedback

A wrong detection is the most useful thing you can send. Every detection in the app has a **Report this rule** link that opens a [prefilled false-positive report](https://github.com/Secure-Vector/securevector-ai-threat-monitor/issues/new?template=false_positive.yml) with the rule id, version and platform, and nothing else. Anything else: [open an issue](https://github.com/Secure-Vector/securevector-ai-threat-monitor/issues/new/choose), say hello on [Discord](https://discord.gg/k3bgZuCQBC), or email [contact@securevector.io](mailto:contact@securevector.io). If SecureVector is earning its place on your machine, a star helps others find it.

## Cloud (optional, opt-in)

A separate cloud product handles MCP tool-permission policy sync across enrolled devices, per-org audit attribution, and per-device fleet slicing. It also adds **AI Agent Governance** — your agents' governance posture rolled into a single score across the fleet ([app.securevector.io/governance](https://app.securevector.io/governance)) — plus **EU AI Act orientation** that maps your action-layer logging and tamper-evident tool-call audit to the relevant obligations ([governance/eu-ai-act](https://app.securevector.io/governance/eu-ai-act)); orientation only, not legal advice. Sign in for the fleet-wide view — the local install already gives you the single-device snapshot. Strictly additive — the local install above works standalone without it. Details: [securevector.io](https://securevector.io).

## License

Apache License 2.0 — see [LICENSE](LICENSE).

The starter SIEM dashboard templates under [`docs/siem/`](docs/siem/) (Splunk XML, Sentinel workbook, Datadog + Grafana JSON) are MIT-licensed — see [`docs/siem/LICENSE`](docs/siem/LICENSE) and [`docs/siem/NOTICE`](docs/siem/NOTICE) for trademark disclaimers.

**SecureVector** is a trademark of SecureVector. See [NOTICE](NOTICE).

---

<div align="center">

**[Get Started](#install)** · **[Documentation](https://docs.securevector.io)** · **[Discord](https://discord.gg/k3bgZuCQBC)** · **[GitHub Issues](https://github.com/Secure-Vector/securevector-ai-threat-monitor/issues)** · **[security@securevector.io](mailto:security@securevector.io)**

</div>
