CyVisGuard

English | 中文

An open-source, self-contained security control plane for AI agents. It sits between an agent — anything that holds credentials and calls tools on someone's behalf — and everything it can reach, and on every action answers: who is calling, on behalf of whom, and is this still within what they're allowed to do?

Agents are becoming the identity that actually touches production: they read tickets, query warehouses, call internal APIs, and act on content nobody reviewed. The interesting controls are no longer at the model, they're at the action — identity and delegation, capability policy, data-flow taint, and an audit trail you can replay. CyVisGuard enforces those over MCP, so they apply to any agent that speaks it.

Coding agents are the sharpest version of the problem — full filesystem, shell, network, sub-agents, and untrusted repo content in the same context — so they're the reference integration. Point it at a real Claude Code and it guards every tool call, refuses a prompt-injected exfiltration, catches a poisoned CLAUDE.md or skill, and even refuses a settings change that would remove the guard itself — all streamed to a live audit console.

Every row is a real GuardedSession call and every verdict comes from the real policy engine — token exchange, taint tracking, arbitration, circuit-break. The capture is reload-paced, not a real-time recording.

Clicking a row opens the request and response the guard actually saw:

Not demo-ware. What's live vs. scripted is labelled honestly, and a non-deterministic miss is reported as a miss.

Two ways in

1 · See the whole thing running — one command, no API key, no network

docker compose -f docker/compose.yml up --build

Brings up the dashboard and exercises the control plane end to end: a real MCP client gets its exfil attempt blocked, and two employees get different tool views through one gateway. Open http://localhost:4300/audit to watch every call land. Replay with docker compose -f docker/compose.yml run --rm flow. (Optional --profile llm bakes a real weak model into the image so the live-injection scenario runs offline.)

No Docker? The same flow runs on the host:

pnpm install
pnpm dev                                    # dashboard → http://localhost:4300
pnpm --filter @cyvisguard/demo-flow start   # exercise the control plane

2 · Put it in front of your own agent — see INTEGRATIONS.md.

What it guards

Four interception points, each writing to one live audit trail. The first three are agent-agnostic; the fourth is how deep it goes when you can integrate with the agent itself:

The proxy is the shape most orgs need: the agent connects only to CyVisGuard, which fronts your downstream MCP servers — a business an employee can't reach isn't denied, it's invisible — and token-exchange means the downstream sees the real employee, not the proxy.

Where the agent lets you hook it, the guard also defends its own attack surface. On Claude Code that means (each verified against the docs and empirically):

• scope is anchored to the session's start dir and doesn't follow cd;
• a poisoned CLAUDE.md is scanned and taints the session;
• a poisoned skill is refused at invocation (fingerprint whitelist + content scan);
• a settings change that removes the guard's own hook is refused;
• sub-agent derivation mints a real delegated child token (revoke cascades).

The control plane

The enforcement logic lives in small, pure packages behind four replaceable seams:

The seams an adopter replaces to wire this to a real platform, in @cyvisguard/shared: IdentityBackend, PolicySource, IntentProvider, EnforcementAdapter. The demo ships in-memory/cooperative implementations.

Plugging in a model

Two of the guard's judgements sit behind seams, so you can back them with a model instead of the built-in heuristics — an existing open weight, or one of ours when we publish it:

Any local Ollama model works today. Point it at one and run the harness:

CYVISGUARD_JUDGE_MODEL=gemma4:e2b-it-q4_K_M \
  pnpm --filter @cyvisguard/model-eval eval:judge

demo-flow act 4 shows the difference on a real case — an agent that reads credentials and posts them to a C2 address slips past the rules (too few denials to trip the breaker) and is caught once a judge is attached.

A model can only ever add suspicion, never remove it. The rule baseline always runs and the results are combined one-directionally, so a model that is absent, wrong, or fooled leaves the guard exactly as strong as it is without one. The seams and the combiners live in @cyvisguard/shared; the eval harness and its honest caveats are in @cyvisguard/model-eval.

Guided scenarios (S0–S4)

The dashboard also has scripted-but-real scenarios that exercise the same control plane in isolation. Open /docs for a bilingual visual tour:

• S0/S1 — a poisoned skill is rejected at attestation; verified agents form a traceable delegation chain.
• S2 — an injection taints the context; the exfil is blocked by data-flow rules (or, with structural partitioning, the egress tool never exists). S2 live drives a real weak model (qwen2.5:0.5b) that genuinely takes the bait — and is blocked.
• S3 — a mid-task resource request is arbitrated: auto-approve / human / reject.
• S4 — a hijacked agent's alignment drops until the circuit breaker trips, cascade-revokes its tokens, and the SOC reconstructs the attack chain.

Documentation

• INTEGRATIONS.md — connect Claude Code: hooks, MCP gateway/proxy, model gateway
• packages/model-eval — plugging a model into the guard, and how it is evaluated
• apps/mcp-proxy — the aggregating proxy: per-employee tool views
• docker/README.md — run the whole stack in containers
• AGENTS.md · CONTRIBUTING.md · SECURITY.md
• CHANGELOG.md — what shipped and why · docs/TODO.md — what's next

Use at your own risk

This is a reference implementation — use at your own risk. The demo credentials (user:demo, a literal demo-secret) are placeholders; supply your own keys and identity backend before running it anywhere real. The implementation's simplifications are recorded in SECURITY.md.

License

Apache-2.0.