mvar-security/mvar

# MVAR — AI Agent 的确定性安全 **如果您的 AI agent 能运行 shell 命令、调用 API、读取文件或使用凭证，提示词注入就可能升级为实际执行。** 大多数防御措施试图过滤恶意提示词。一旦模型输出到达特权工具，这种防御就会失效。 **MVAR 通过在 LLM 输出和执行汇之间强制执行确定性策略来防止这种情况。** 它适用于现代 agent runtime，包括 MCP 和 OpenClaw 风格的工具链。请参阅受管 runtime 证明，以获取可复现的良性通过/对抗性拦截演示。 **MVAR 是 AI agent 的执行防火墙。** 不变式：`UNTRUSTED input + CRITICAL sink -> BLOCK` `拦截 50 个攻击向量` · `放行 200 个良性向量` · `CI 门控启动验证` ## 30 秒试用 [30 秒证明](#30-second-proof) · [快速开始](#quick-start) · [受管 MCP 证明](docs/outreach/GOVERNED_MCP_RUNTIME_PROOF.md) · [适配器](docs/FIRST_PARTY_ADAPTERS.md) [](https://github.com/mvar-security/mvar/actions/workflows/launch-gate.yml) [](https://scorecard.dev/viewer/?uri=github.com/mvar-security/mvar) [](./) [](LICENSE.md) ## 30 秒证明 ``` git clone https://github.com/mvar-security/mvar.git cd mvar bash scripts/install.sh bash scripts/run-agent-testbed.sh --scenario rag_injection ``` 预期结果： - 基线 runtime：允许受攻击者影响的命令 - MVAR runtime：在工具运行前拦截执行 - 审计输出：确定性决策 + 密码学见证 ``` Baseline: ALLOW -> executing bash command MVAR: BLOCK -> UNTRUSTED input reaching CRITICAL sink ``` 受管 runtime 演示 (MCP): [docs/outreach/GOVERNED_MCP_RUNTIME_PROOF.md](docs/outreach/GOVERNED_MCP_RUNTIME_PROOF.md) ## 快速开始 ``` from mvar import protect, ExecutionBlocked safe_tool = protect(my_bash_tool) # balanced profile by default try: safe_tool("cat /etc/shadow") except ExecutionBlocked as e: print(e.decision["outcome"]) # BLOCK print(e.decision["reason"]) ``` 配置文件：`balanced`（默认）、`strict`、`permissive`。 ## 什么是 MVAR MVAR 是 LLM agent 的确定性执行安全层。 大多数防御措施试图检测恶意提示词。MVAR 在执行汇处强制执行策略，这是提示词注入攻击导致真实系统影响的地方。 ## 有何不同 - 不是提示词过滤器 - 不是 LLM 评判器 - 执行时的确定性策略 - 感知来源的授权 - 密码学可审计的决策 ## 验证 - 在工具执行前拦截了 50 个提示词注入攻击向量 - 每次更改都进行受管 runtime CI 门控 - 版本化脚本中的可复现性和启动检查 当前指标和快照：[STATUS.md](STATUS.md)，[TRUST.md](TRUST.md) ## 适用对象 MVAR 适用于构建以下能力 agent 的团队： - 执行 shell 命令 - 调用外部 API - 读取或写入文件 - 处理凭证或敏感数据 如果您的 agent 能将模型输出转化为现实世界的行动，MVAR 会在运行时约束这种权限。 ## 部署模式（当前） | 模式 | 组件 | 状态 | 主要用例 | |---|---|---|---| | 独立 MVAR | 仅 MVAR | ✅ 已发布 | 插入式确定性执行边界 | | MVAR + Verify | MVAR + Entry 500 SDK | 🚧 集成路径 | 在汇执行的同时增加信任信号 | | 完整受管 Runtime | MVAR + Entry 500 + EOS + Execution Governor | 🚧 脚手架 / 特性开关 | 统一特权操作控制平面 | ## 适用于 - LangChain - OpenAI tool calling - OpenAI Agents SDK - MCP - Claude tool runtimes - AutoGen - CrewAI - OpenClaw 首先安装：[INSTALL.md#installation](INSTALL.md#installation) 然后选择一个适配器快速入门：[docs/FIRST_PARTY_ADAPTERS.md](docs/FIRST_PARTY_ADAPTERS.md) 需要每个适配器的源码和快速入门：[Adapter Code + Quickstart Map](docs/FIRST_PARTY_ADAPTERS.md#adapter-code--quickstart-map) ## 架构概览 ``` LLM reasoning | v tool request | v MVAR enforcement layer | v shell / APIs / filesystem / secrets ``` ``` flowchart LR A[LLM Agent] --> B[MVAR Runtime Boundary] B --> C[Policy / Provenance / Capability Checks] C --> D[Shell / API / Filesystem / Secrets] ``` 规范链接： - [`spec/execution_intent/v1.schema.json`](spec/execution_intent/v1.schema.json) - [`spec/decision_record/v1.schema.json`](spec/decision_record/v1.schema.json) - 执行契约模型（单页）：[docs/architecture/execution_contract_model.md](docs/architecture/execution_contract_model.md) ## 60 秒验证 快速路径（即使您忘记激活正确的 venv 也有效）： ``` bash scripts/doctor-environment.sh bash scripts/quick-verify.sh ./run_proof_pack.sh ``` 手动路径（从仓库根目录）： ``` bash scripts/run-python.sh -m pytest -q bash scripts/launch-gate.sh bash scripts/run-python.sh scripts/generate_security_scorecard.py bash scripts/run-python.sh scripts/update_status_md.py ``` 这证明了什么： - 启动门控和完整套件在 CI 中均为绿色 - 攻击语料库在当前策略下拦截率为 50/50 - 良性语料库零误拦截 - 确切的当前数值发布在 [STATUS.md](STATUS.md) - 复现工件包在 `artifacts/repro//` 下生成，包含校验和和摘要 JSON ## 执行见证链 MVAR 可以离线验证签名的见证工件，包括签名有效性和前序签名链完整性。 ``` mvar-verify-witness data/mvar_decisions.jsonl --require-chain ``` ## 集成与演示 - 在您的 agent 中使用 MVAR：[docs/integration/USE_MVAR_IN_YOUR_AGENT.md](docs/integration/USE_MVAR_IN_YOUR_AGENT.md) - 演示和测试平台目录：[docs/demos/DEMOS_AND_TESTBEDS.md](docs/demos/DEMOS_AND_TESTBEDS.md) - 适配器快速入门：[docs/FIRST_PARTY_ADAPTERS.md](docs/FIRST_PARTY_ADAPTERS.md) ## MVAR 不是什么 MVAR **不是**： - **不是提示词过滤器** — MVAR 不试图检测或拦截恶意提示词 - **不是 LLM 评判器** — MVAR 不使用次级模型来分类意图 - **不是 OS 沙箱的替代品** — MVAR 补充 Docker/seccomp，并不替代它们 - **不是网络安全的替代品** — 防火墙、主机加固和网络隔离仍然是必要的 - **不是恶意意图检测器** — MVAR 强制执行结构约束，而非行为异常检测 MVAR 是特权执行汇处的**确定性引用监视器**。它假设存在不可信输入，并防止它们到达关键操作，无论检测准确性如何。 ## MVAR 拦截内容 MVAR 已验证针对以下攻击类别的强制执行： - **提示词注入驱动的工具执行** ([tests/test_launch_redteam_gate.py](tests/test_launch_redteam_gate.py)) - **凭证窃取尝试** ([demo/extreme_attack_suite_50.py](demo/extreme_attack_suite_50.py)，向量 22-25) - **编码/混淆的恶意载荷** ([demo/extreme_attack_suite_50.py](demo/extreme_attack_suite_50.py)，类别 3) - **多步组合攻击** ([tests/test_composition_risk.py](tests/test_composition_risk.py)) - **通过缓存/日志/临时文件的污点清洗** ([demo/extreme_attack_suite_50.py](demo/extreme_attack_suite_50.py)，类别 6) 有关确切的当前验证数字，请参阅 [STATUS.md](STATUS.md)。

MVAR 拦截什么？ 50 个攻击向量 · 9 个类别 · 每次提交 CI 门控

MVAR 的汇策略针对包含 9 个攻击类别的 50 个向量对抗性语料库进行了评估： | 类别 | 向量数 | 结果 | |----------|---------|--------| | 直接命令注入 | 6 | ✅ 6/6 已拦截 | | 环境变量攻击 | 5 | ✅ 5/5 已拦截 | | 编码/混淆 (Base64, Unicode, hex) | 8 | ✅ 8/8 已拦截 | | Shell 操作（管道、eval、替换） | 7 | ✅ 7/7 已拦截 | | 多阶段攻击（下载+执行） | 6 | ✅ 6/6 已拦截 | | 污点清洗（缓存、日志、临时文件） | 5 | ✅ 5/5 已拦截 | | 模板转义 (JSON, XML, Markdown) | 5 | ✅ 5/5 已拦截 | | 凭证窃取 (AWS, SSH keys) | 4 | ✅ 4/4 已拦截 | | 新颖语料库变体 | 4 | ✅ 4/4 已拦截 | **结果：** 在测试的策略和汇配置下，拦截了当前验证语料库中的每一个向量。 **范围：** 这展示了对该验证语料库的一致强制执行。并非针对所有可能攻击的完整性证明。

## 深入文档 本 README 专为快速评估而设计，内容前置。详细材料被拆分为专题文档： - 为什么进行边界强制执行（而非提示词过滤）：[docs/WHY_CONTROL_PLANE_NOT_FILTERS.md](docs/WHY_CONTROL_PLANE_NOT_FILTERS.md) - 完整架构和设计谱系：[ARCHITECTURE.md](ARCHITECTURE.md)，[DESIGN_LINEAGE.md](DESIGN_LINEAGE.md) - 执行契约模型（当前与计划范围）：[docs/architecture/execution_contract_model.md](docs/architecture/execution_contract_model.md) - 验证展示和攻击三部曲：[docs/ATTACK_VALIDATION_SHOWCASE.md](docs/ATTACK_VALIDATION_SHOWCASE.md)，[docs/AGENT_TESTBED.md](docs/AGENT_TESTBED.md) - 集成示例：[docs/integration/USE_MVAR_IN_YOUR_AGENT.md](docs/integration/USE_MVAR_IN_YOUR_AGENT.md) - 演示和可复现测试平台：[docs/demos/DEMOS_AND_TESTBEDS.md](docs/demos/DEMOS_AND_TESTBEDS.md) - 适配器契约和集成剧本：[docs/ADAPTER_SPEC.md](docs/ADAPTER_SPEC.md)，[docs/AGENT_INTEGRATION_PLAYBOOK.md](docs/AGENT_INTEGRATION_PLAYBOOK.md)，[conformance/README.md](conformance/README.md) - 安全配置、信任姿态和可观测性：[docs/SECURITY_PROFILES.md](docs/SECURITY_PROFILES.md)，[TRUST.md](TRUST.md)，[docs/OBSERVABILITY.md](docs/OBSERVABILITY.md) - Agent 运行时风险类别说明：[docs/security/AGENT_RUNTIME_INCIDENT_CLASS.md](docs/security/AGENT_RUNTIME_INCIDENT_CLASS.md) - 性能、非目标和威胁模型：[docs/PERFORMANCE_AND_THREAT_MODEL.md](docs/PERFORMANCE_AND_THREAT_MODEL.md) - 研究论文：[docs/papers/execution-witness-binding.pdf](docs/papers/execution-witness-binding.pdf) ## 参与其中 - 运行验证：`bash scripts/launch-gate.sh` - 提交对抗性向量：[docs/ATTACK_VECTOR_SUBMISSIONS.md](docs/ATTACK_VECTOR_SUBMISSIONS.md) - 构建适配器和集成：[docs/BUILD_WITH_US.md](docs/BUILD_WITH_US.md) - 使用置顶的 30 秒证明帖子：[docs/outreach/GITHUB_PINNED_POST_30S_PROOF.md](docs/outreach/GITHUB_PINNED_POST_30S_PROOF.md) ## 贡献 **MVAR 从设计上是开源的。** 我们欢迎适配器集成、安全加固、测试以及保留安全不变性的文档改进。 有关贡献通道、要求、一致性期望和安全报告工作流，请参阅 [docs/BUILD_WITH_US.md](docs/BUILD_WITH_US.md)。 ## 声明 - [NOTICE.md](NOTICE.md) - [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) - [DISCLAIMERS.md](DISCLAIMERS.md) ## 许可证 Apache License 2.0 — 参见 [LICENSE.md](LICENSE.md) **专利：** 已提交美国临时专利（2026 年 2 月 24 日） ## 引用 机器可读的引用元数据：[CITATION.cff](CITATION.cff) ``` @software{mvar2026, author = {Cohen, Shawn}, title = {MVAR: MIRRA Verified Agent Runtime}, year = {2026}, url = {https://github.com/mvar-security/mvar}, note = {Deterministic prompt injection defense via information flow control} } ``` ## 联系方式 **Shawn Cohen** Email: security@mvar.io GitHub: [@mvar-security](https://github.com/mvar-security) *MVAR：通过信息流控制和密码学来源追踪，针对提示词注入驱动的工具滥用实施确定性汇强制执行。*

标签：AI Agent防火墙, Apache 2.0, API调用控制, DNS 反向解析, LLM运行时防护, MCP安全, Shell命令过滤, XSS注入, 信息流控制, 双格IFC, 大语言模型安全, 密码学溯源, 执行阻断, 提示词注入防御, 机密管理, 确定性安全, 软件供应链安全, 远程方法调用, 逆向工具