VirbiusAgent

中文文档

VirbiusAgent is a deep security platform purpose-built for AI Agents. Leveraging eBPF and a four-tier Edge–Gateway–Kernel–Cloud architecture, it provides real-time visibility and precise blocking of Agent behaviors, effectively tackling the challenges of privilege abuse and loss of security control.

The Agent security landscape falls into two categories: endpoint-side controls — DLP and related measures to govern employee usage of AI and Agents, preventing data leaks, shadow AI, and prompt leakage — and server-side protection, which is VirbiusAgent's core focus. As an Agent security platform, VirbiusAgent secures your self-developed intelligent agents against prompt injection, MCP tool abuse, and privilege escalation. It is designed to support enterprise security review and audit workflows; map its controls to the regulations that apply to your jurisdiction. Endpoint controls are largely standardized with low business coupling, whereas VirbiusAgent provides a highly customizable security policy framework on the server side, requiring security engineers who understand both policy and business to tailor configurations for precise, scenario-matched protection.

Operations Console

Main pages: rule registry & rollout, policy-cache hot reload, audit center, Audit Integrity (integrity verification / Decision BOM / audit export / session checkpoints, 4 tabs), Alerts (list / status filter / acknowledge / expand Decision BOM), sessions & traces, delegated credentials, and more.

Architecture

flowchart TD
    A["① Edge — virbius-core<br/>Rust SDK · precheck + DLP · sub-ms"]
    G["② Gateway — Higress + WASM<br/>rate limit · HTTP enforce · challenge"]
    K["③ Kernel — Falco + eBPF<br/>runtime observability · custom rules"]
    C["④ Cloud — virbius-engine + virbius-control<br/>policy · LLM detect · Groovy L3 · audit"]
    MCP["MCP Server / LLM"]

    A -->|tool_call| G
    G -->|forward| C
    C -->|effective_action| G
    G -->|allow| MCP
    G -.->|block| MCP
    K -.->|events| C

    CP["Control Plane — virbius-control<br/>admin UI · rule registry · rollout"]
    COMP["virbius-compiler<br/>rules → per-app manifests"]

    CP -.->|publish| A
    CP -.->|publish| G
    CP -.->|publish| C
    CP -.->|publish| K
    COMP -.->|compile| CP

Features

Why VirbiusAgent

Rules + Models: A Practical Engineering Pattern

Industry security engineering has shown that combining deterministic rules with ML models is an effective defense — neither alone is sufficient. This principle is the foundation of VirbiusAgent's design.

Design philosophy: Not merely using models to fight models, but combining rules and models. Rules are cheap and fast, and new attacks can be addressed more flexibly with targeted rule patches; models generalize well but are expensive to iterate. Combining them achieves high performance, precision and recall at relatively low cost.

We use GLM5.2 as the teacher model and Qwen3Guard as the base student model, performing knowledge distillation to create VirbiusGuard — which covers and optimizes prompt semantic scenarios that Qwen3Guard does not support (such as Agent behavioral safety, multilingual mixed inputs, etc.), progressively expanding the detection scope of Prompt L1.

VirbiusGuard model download: HuggingFace | ModelScope

VirbiusGuard demo: https://www.virbius.cn/demo — paste text in the browser and see the 10 safety categories plus agent-attack samples.

Comparison with Industry Solutions

A high-level comparison as of 2026-11, based on public documentation. These are
different products with different scopes; see docs/COMPARISON.md
for the full matrix and source links. Capabilities may change as upstreams evolve.

Key Differentiators

1. Four-layer defense-in-depth — Prompt-layer guardrails check a single point, and SDK-based peers (e.g. Microsoft Agent Governance Toolkit) add governance layers in-process. VirbiusAgent instead spans four independent layers across the runtime (Edge → Gateway → Kernel → Cloud), so even if one layer is bypassed, others still catch the threat — including syscall-level (eBPF/Falco) observation that SDK-based guardrails typically do not provide. This follows the defense-in-depth principle.

2. Rules and models combined — Rules catch known threats at sub-millisecond latency; models generalize better. Combining them yields high precision/recall and high performance at relatively low cost. This hybrid approach is a practical balance of cost, speed, and coverage.

3. Agent-native, not just LLM-native — Guardrail and scanner peers target the prompt or static analysis; VirbiusAgent secures the entire tool-call lifecycle across layers: pre-execution precheck → on-path gateway enforcement → runtime kernel observation → post-execution audit. This is purpose-built for the MCP era where Agents execute real actions.

4. Runtime visibility at the kernel level — Via eBPF/Falco, VirbiusAgent observes Agent processes at the syscall level (file access, network connections, process spawns). This adds syscall-level runtime observability that application-layer guardrails typically cannot provide.

Agent Security vs Traditional Security

In short: Traditional security defends against "external break-ins"; Agent security must also defend against "the model being led astray and attacking from within" - it must understand business semantics and adapt dynamically to session risk and business change.

Benchmarks

Results for VirbiusGuard v2.1 (the prompt-safety model used by the cloud
layer), measured with a locked auditor prompt, greedy decoding, and parse
failures counted as misses. The harness is in
scripts/benchmarks/; public-set numbers can be
reproduced with the command below.

Notes:

• WildGuardTest and XSTest are public; gold_1000 is an internal bilingual set.
• The AgentDojo agent is deepseek-flash, which is already injection-robust
  (baseline ASR 1.58%); the utility/ASR shift is specific to that setting.
• Quantized Q4 builds did not pass the same gate set (WildGuardTest FPR
  5.2%, XSTest over-refusal 18). Use f16/bf16 for the reported numbers.
• Reproduce the public sets:

pip install torch transformers
python3 scripts/benchmarks/virbiusguard_eval.py --data wildguardtest.jsonl

See scripts/benchmarks/README.md for dataset
export, field mapping, and the adversarial slice.

Quick Start

Prerequisites

Local Development

Recommended — one-command setup:

git clone https://github.com/i1see1you/VirbiusAgent.git && cd VirbiusAgent
bash scripts/run-local.sh      # builds Rust + Java, starts Redis, launches services
bash scripts/smoke-test.sh     # health check + test runner

Manual step-by-step:

# 1. Start Redis
docker run -d -p 6379:6379 redis:7-alpine

# 2. Build Java modules
mvn clean install -DskipTests

# 3. Build Rust modules
cargo build --release -p virbius-core -p virbius-mcp-proxy

# 4. Start control plane (SQLite in-memory, auto schema)
cd virbius-control
mvn spring-boot:run -Dspring-boot.run.profiles=dev

# 5. Verify
curl -s http://localhost:8080/api/v1/health

Docker (Compose)

Start the full stack with a single command (Redis + engine + control plane):

git clone https://github.com/i1see1you/VirbiusAgent.git && cd VirbiusAgent
docker compose build     # build all images (first time only)
docker compose up -d     # start all services
docker compose ps        # check status

# Verify all services are healthy
curl -s http://localhost:8080/api/v1/health
curl -s http://localhost:8082/admin/health

# Follow logs
docker compose logs -f
# Stop
docker compose down

To include the MCP proxy (requires license and upstream server):

docker compose --profile full up -d

Edge SDK Demo

[dependencies]
virbius-core = "1.0"

# Run the end-to-end integration tests (no external services required)
cd virbius-core
cargo test --test e2e_integration -- --nocapture

The suite walks through the full edge-layer security pipeline: License
verification → tool precheck → Prompt Gateway → MCP execution → STI taint
detection → audit trace propagation.

Packages

Published from the same v* tags as GitHub Releases:

Deployment Architecture

flowchart TB
    subgraph AgentProcess["Agent Process"]
        EDGE["① virbius-core (Rust SDK)<br/>precheck · DLP · license"]
    end

    subgraph Gateway["Gateway Layer"]
        HIGRESS["Higress :9080<br/>WASM plugin<br/>rate limit · challenge"]
    end

    subgraph Kernel["Kernel Layer"]
        FALCO["Falco DaemonSet<br/>eBPF · custom rules"]
        SUB["config-subscriber<br/>Redis → rules.d reload"]
    end

    subgraph Cloud["Cloud Layer"]
        ENGINE["virbius-engine :8082<br/>Spring Boot<br/>Prompt detection · Groovy L3"]
        CONTROL["virbius-control :8080<br/>Spring Boot<br/>admin UI · rule registry"]
    end

    subgraph Infra["Infrastructure"]
        REDIS[("Redis :6379<br/>audit stream · counters")]
        DB[("SQLite / MySQL<br/>rules · traces · events")]
    end

    EDGE -->|HTTP| HIGRESS
    HIGRESS -->|evaluate| ENGINE
    HIGRESS -->|allow| MCP["MCP Server"]
    FALCO -.->|audit events| REDIS
    CONTROL --- DB
    ENGINE --- REDIS
    CONTROL -.->|publish| EDGE
    CONTROL -.->|publish| HIGRESS
    CONTROL -.->|publish| FALCO

Native tool integration (Mode A observe / Mode B enforce for LangChain native tools, with coverage classification and warnings) — see NATIVE_TOOL_INTEGRATION.md.

Layer Responsibilities

Building on the four-tier architecture, each layer has distinct responsibilities, coordinated through the rule pipeline (Edge precheck → Gateway enforce → Kernel observe → Cloud adjudicate).

Layer overview

Request main path: Agent tool call → Edge (L0 precheck + DLP + STI) → Gateway (rate limit + enforcement) → Cloud (Prompt L1 + Groovy L3 + PolicyMerger) → MCP Server execution. Kernel passive observation spans all phases.

① Edge: lightweight pre-execution protection

The edge is the first defense point before any tool execution. It performs local filtering and security checks without adding noticeable latency.

• Tool precheck: validates tool_name against allowlist, checks License permissions, verifies request integrity
• DLP desensitization: masks PII (phone, ID, email, bank card) in tool arguments before they leave the client
• STI Taint tracking: marks untrusted tool return values, prevents injection into subsequent tool calls or Agent memory
• Fast path: bypasses cloud layer for low-risk tools, optimizing latency to < 1ms

Boundary: Does not perform semantic jailbreak detection; relies on allowlist matching. Can be bypassed via direct API calls and must not serve as the sole defense line.

② Gateway: on-path real-time enforcement

The gateway is the mandatory checkpoint on the tool_call HTTP path, executing decisions from the cloud engine.

• Rate limiting: per-user/per-app cumulative counters for tool call frequency
• HTTP enforcement: blocks/allow based on engine decision; validates challenge approval tokens
• Protocol validation: validates MCP request/response format and parameter integrity
• On-demand engine call: forwards to cloud engine only when needed (risk-based routing, configurable per scene)

Relationship with the cloud: The gateway handles fast-path execution (rate limiting, list matching); the cloud handles slower-path semantic decision. Not every request needs to RPC to the engine — fast path bypasses when risk is low.

③ Kernel: runtime observability & sandbox isolation

The kernel layer operates at the OS level, providing visibility and isolation that application-layer defenses cannot achieve. It is passive by default and does not block the request path unless a sandbox rule is triggered.

• eBPF/Falco monitoring: real-time syscall-level observation of file access (open/read/write), network connections (connect/accept), process spawns (execve)
• Custom Falco rules: managed through control plane, supports canary deployment, hot-reload without restart
• Sandbox isolation: Landlock (file path restrictions via kernel LSM) and gVisor (full userspace kernel) for high-risk tool execution — blocks at syscall level before any damage occurs
• Audit events: all kernel events correlated with trace_id and fed into the audit pipeline for session-level risk scoring

Difference from application layers: Kernel observation cannot be bypassed by the Agent process — even if the Agent is compromised, syscalls are still visible to eBPF. Sandbox restrictions apply regardless of Agent behavior.

④ Cloud: policy computation & terminal adjudication

The cloud is the central decision-making layer, aggregating signals from all layers and computing the final disposition.

• Policy management: rule authoring, versioning, progressive rollout (draft → dry_run → canary → full)
• LLM-based detection: Prompt L1 safety classification (VirbiusGuard, 9 safety categories), multi-category jailbreak/injection detection
• Groovy L3 adjudication: terminal policy decision merging signals from all layers, calling external ML models via mlPredict, outputting effective_action (allow / deny / challenge)
• Decision trace: full-chain tool_call/tool_result tracing with causal chain visualization
• Audit dashboard: session risk, tool calls, alerts, approval queue, tamper-proof hash chain audit
• Human-in-the-loop: challenge approval flow for high-risk tool calls — engine issues challenge → console approves → token-gated execution

Request Main Path

A typical request flows through the layers as follows:

Agent tool call
  → virbius-core (Edge: precheck + DLP + STI + license verify)
    │
    ├── Fast path (low-risk tool)
    │   └── Direct to MCP Server (bypasses Gateway + Cloud)
    │
    └── Normal path (medium/high-risk tool)
        → virbius-mcp-proxy (security pipeline + trace init)
          → Higress WASM (Gateway: rate limit + access-list)
            → virbius-engine (Cloud)
              ├─ Ollama / vLLM (Prompt L1 safety classification)
              ├─ ML Serving (Groovy mlPredict)
              └─ PolicyMerger → effective_action
                ├── allow  → MCP Server executes tool
                ├── deny   → blocked with reason code
                └── challenge → human approval → token → execute
          ← effective_action + risk_score + trace_id
        ← tool_result (with audit context)
  ← final tool_result to Agent
  → Kernel (Falco) passive observation throughout all phases

Key design points:

• Fast path: Low-risk tools (classified by tb_tool_registry.risk_class) skip Gateway + Cloud entirely, achieving < 1ms end-to-end latency
• On-demand cloud call: The gateway decides per-request whether to invoke the engine, based on scene configuration and risk level
• Kernel is passive: Falco never blocks the request path; it emits events for risk scoring. Sandbox (Landlock/gVisor) blocks at syscall level independently
• All phases carry trace_id: Edge, Gateway, Kernel, and Cloud events are correlated by trace_id for end-to-end audit

Rule Runtimes

Each layer supports specific rule types, compiled by virbius-compiler into layer-specific artifacts:

Edge–Gateway–Kernel–Cloud Rule Selection

The four layers differ in execution location, latency, and purpose. Guiding principle: push deterministic rules forward; defer high-latency rules to the back; keep observation layers passive.

Capability boundaries:

Selection guide:

Recommended combinations:

• Low-latency (mobile/desktop Agent) → Edge + Cloud, skip Gateway and Kernel
• Web/API without Proxy → Gateway + Cloud, skip Edge and Kernel
• Production defense-in-depth → Edge + Gateway + Cloud; Kernel on-demand
• High-compliance / Finance / Gov → All four layers

Project Structure

VirbiusAgent/
├── virbius-core/          # Rust SDK — prechecks, DLP, license
├── virbius-mcp-proxy/     # Rust MCP proxy server
├── virbius-mcp-python/    # Python (PyO3) — native-tool enforcement SDK (Mode B)
├── virbius-mcp-node/      # Rust (napi-rs) — Node.js MCP bindings
├── virbius-integrate/     # Python — LangChain callback observation plugin (Mode A)
├── virbius-review-sdk/    # Python — input/output review SDK (engine /v1/evaluate)
├── virbius-kernel/        # Go (plugin) + Rust (sidecar) — Falco plugin, sandbox
├── virbius-gateway/       # Go WASM plugin for Higress
├── virbius-expr/          # Go — expression evaluator/compiler
├── virbius-control/       # Java Spring Boot control plane
├── virbius-engine/        # Java Spring Boot security engine
├── virbius-auth/          # Java Spring Boot — operator login (local password + JWT)
├── virbius-compiler/      # Java bundle compiler
├── virbius-policy/        # Java policy domain model
├── virbius-groovy-l3/     # Java Groovy L3 adjudicator
└── virbius-demo/          # Demo / red-team playground (LLM SecRange)

Documentation

Contributing

See CONTRIBUTING.md for contribution guidelines.

Commercial Evaluation Extension (Optional)

The Operations Console exposes an optional entry to VirbiusEvaluation, a separately
licensed closed-source assessment module (on-prem or cloud). This repository does not
contain it and does not depend on it — builds, images, CI and the default stack work
without it.

• Not connected (default): the entry is hidden — the console stays clean for
  open-source users who have not installed the commercial module.
• After the evaluation service is connected (base URL saved), the entry appears
  automatically on the next status refresh — no console restart needed.
• Platform admins configure it via /ui/evaluation (direct URL) or the entry's
  Settings panel: base URL, service token, connection test, license upload —
  applied immediately, no restart.
• VIRBIUS_EVALUATION_ENABLED=false (seed) or the Settings toggle hides the entry
  even when configured.
• VIRBIUS_EVALUATION_* env is a first-start seed only; afterwards the DB row
  is authoritative.
• Reports support one-click rule generation: finding → preview (variables,
  evidence binding, executability) → dry_run rule; idempotent, never overwrites an
  existing rule, and app binding requires explicit confirmation.
• No telemetry: nothing is reported; links open only on user click.

Security

See SECURITY.md for vulnerability reporting.

Contact

• Website: https://www.virbius.cn
• VirbiusGuard demo: https://www.virbius.cn/demo
• Issues / Discussions: https://github.com/i1see1you/VirbiusAgent/issues
• Business: [email protected]
• Security reports: GitHub Security Advisories (see SECURITY.md)

License

MIT — Copyright (c) 2026 i1see1you