VITNA – Containment for rogue AI agents

VITNA

为失控的 AI Agent 提供的遏制层。

Agent 会通过工具失控。VITNA 会守护你置于其后的工具。 你标记为有风险的工具调用会暂停，等待人工处理。没有答复，就不会执行。 任何 API 密钥都无法决定是否继续等待，包括 Agent 自己的密钥。已认领的账户会生成可离线核验的签名记录。

试用演示：在浏览器中体验带标签的模拟场景。一个脚本化 Agent 在虚拟文件上尝试调用有风险的工具，由你决定如何处理被暂停的调用。无需安装，也不会保存任何内容。

60 秒快速上手

npx -y @costrinity/vitna-compliance-mcp guard -- <your stdio MCP server command>

若要查看暂停效果，请为 guard 提供一个列出需要暂停的工具的策略文件。参考文件系统服务没有删除工具：它通过覆盖或移动文件来销毁文件，因此这个 policy.json 会暂停这些调用，并允许其他调用：

{ "allowed_actions": ["*"], "hold_actions": ["write_file", "edit_file", "move_file"] }

VITNA_GUARD_POLICY=/path/to/policy.json npx -y @costrinity/vitna-compliance-mcp guard -- npx -y @modelcontextprotocol/server-filesystem /path/to/test-folder

在 MCP 客户端配置中，将 VITNA_GUARD_POLICY 放在 env 下（参见 Guard 模式）。

每个 tools/call 在到达服务前都会由 VITNA 检查。任何未获允许的调用都会被拒绝，并返回说明原因的工具错误。没有凭据时，你会获得一个试用密钥：有风险的调用会被暂停；由于暂时无人能审批，窗口结束时该调用会被拦截。若要批准或拒绝暂停的调用并保留签名记录，请使用 GitHub 或通行密钥认领账户，然后在控制面板的 Aquarium 中处理暂停的调用。认领链接会显示在 MCP 服务日志中，绝不会发送给 Agent；设置 VITNA_OPEN_CLAIM=1 会在浏览器中打开该链接。

请先在测试 Agent 上试用。

适用范围

VITNA 只能看到它包装的服务。内置 shell 或未包装的服务不在其保护范围内；若要确保每项操作都经过 guard，请关闭这些功能。会话记录会列出你声明为未包装的内容。远程端点提供的检查能力与 Agent 自行调用的工具相同；这属于协作式机制，而非遏制措施。 检测依赖启发式模式匹配，并非沙箱。

它无法做到什么 · Guard 模式 · 自行验证记录

Agent 配置

该防护层包装 stdio MCP 服务，因此可以置于启动 stdio MCP 服务的客户端或 SDK 前。只有在我们使用该防护层实际运行过某项配置后，才会将其列为已测试。

每项配置的说明见连接你的 Agent；兼容性页面会列出已测试的配置。

• Claude Desktop：已有文档说明，尚未测试；暂停时会等待决策。
• Claude Code：已于 2026-10-14 测试，版本为 2.1.299；暂停时会等待决策。
• Codex CLI：已有文档说明，尚未测试；暂停时会等待决策。
• Gemini CLI：已有文档说明，尚未测试；暂停时会等待决策。
• Cursor：已有文档说明，尚未测试；暂停时会回复“已暂停，未运行”，获批后重试相同调用会运行一次。
• VS Code（Copilot）：已有文档说明，尚未测试；暂停时会等待决策。
• Cline：已有文档说明，尚未测试；暂停时会等待决策。
• Continue：已有文档说明，尚未测试；暂停时会等待决策。
• Zed：已有文档说明，尚未测试；暂停时会等待决策。
• Goose：已有文档说明，尚未测试；暂停时会等待决策。
• Windsurf / Devin Desktop：已有文档说明，尚未测试；暂停时会回复“已暂停，未运行”，获批后重试相同调用会运行一次。
• OpenClaw（VITNA 插件）：已有文档说明，尚未测试；暂停时会等待决策。
• OpenClaw（MCP 服务）：已有文档说明，尚未测试；暂停时会等待决策。
• OpenAI Agents SDK（Python）：已有文档说明，尚未测试；暂停时会等待决策。
• OpenAI Agents SDK（JS）：已有文档说明，尚未测试；暂停时会等待决策。
• Google ADK（Python）：已有文档说明，尚未测试；暂停时会等待决策。
• LangChain MCP 适配器：已有文档说明，尚未测试；暂停时会回复“已暂停，未运行”，获批后重试相同调用会运行一次。
• CrewAI：已有文档说明，尚未测试；暂停时会回复“已暂停，未运行”，获批后重试相同调用会运行一次。
• AutoGen：已有文档说明，尚未测试；暂停时会等待决策。
• Microsoft Agent Framework（Python）：已有文档说明，尚未测试；暂停时会回复“已暂停，未运行”，获批后重试相同调用会运行一次。
• LlamaIndex：已有文档说明，尚未测试；暂停时会等待决策。
• Mastra：已有文档说明，尚未测试；暂停时会等待决策。
• Vercel AI SDK：已有文档说明，尚未测试；暂停时会等待决策。

不支持：

• n8n（MCP 客户端工具）：其 MCP 客户端工具仅通过 SSE 和 HTTP 连接，不支持 stdio，因此该防护层无法置于其前。远程 VITNA 网关已列入计划。

从 VIGIL 更名而来

此软件包此前以 @costrinity/vigil-compliance-mcp 名称发布，此仓库此前名为 COSTRINITY/vigil-compliance-mcp。旧软件包仍在 npm 上，版本为 0.2.4，已弃用，并附有消息“已更名：请使用 @costrinity/vitna-compliance-mcp”。该软件包不再更新，也没有防护模式，因此任何仍指向它的配置都会安装旧版本。目录列表中显示 VIGIL 名称的内容是此仓库的过时快照。

当前软件包：@costrinity/vitna-compliance-mcp 注册表条目：xyz.costrinity/vitna-compliance-preflight 网站：https://vitna.costrinity.xyz

另含内容

同一软件包还包含 VITNA 的合规检查：涵盖 13 个司法辖区内 24 部具名法规的 23 个 MCP 工具，供 Agent 在采取行动前自行调用。 这些内容用于决策支持，并非法律建议；评分卡并非认证。

大多数合规服务回答的是“关于”法规的问题。这个服务回答的是一个“关于你的 Agent 当前准备执行的操作”的问题：是否可以运行？你的 Agent 会调用检查，同步获得 allowed / blocked / flagged 结果，然后自行决定。VITNA 负责评估并记录；你的系统负责执行。

该软件包

只需安装一个软件包。这是你的 Agent 在采取行动前调用的服务。

软件包	功能	适用场景	安装
@costrinity/vitna-compliance-mcp（本软件包）	你的 Agent 先询问，再行动。针对拟议操作返回允许／阻止／标记，并记录经签名的决策证据。	你希望 Agent 调用一道防护机制，并获得可证明其确实执行过检查的凭证。	npx @costrinity/vitna-compliance-mcp — 启动时无需凭据

本仓库内置了一个被动观察器，可记录现有 MCP 流量而不作任何判断，但尚未发布到 npm，因此目前还没有在此处说明。以上内容均不依赖它。

覆盖范围

24 部具名法规	涵盖 13 个司法管辖区
EU AI Act（Reg 2024/1689）	在构建或发布前进行风险等级分类
GDPR + UK GDPR	DPIA 门槛、违规事件报告义务、ROPA
DPDP（印度，2023）	§16 跨境状态、§8 违规事件处理流程
LGPD · PDPA-SG · APPI · PIPEDA + Law 25 · PIPL · PIPA-KR · NDPA · APP-AU · CPRA	司法管辖区规则包
HIPAA · GLBA · COPPA · FERPA · FCRA · SOX	美国联邦行业法规适用性
RBI · SEBI · IRDAI · TRAI/DoT · PFRDA	印度行业监管机构
16 部美国州隐私法	另涵盖 21 个州的违规事件报告时限
23 个 MCP 工具	6 个标识符验证器、15 个无状态辅助工具

就绪度评分卡（用于审计前准备，不是认证）还涵盖 NIST Privacy Framework、SOC 2、ISO/IEC 27001 和 PCI DSS v4.0。

以上所有数字均根据代码推导，并由构建门禁强制校验——如果移除某项实现，构建就会失败，避免数字过时。关于这些数字不代表什么，请参阅下文“诚实说明限制”。

VITNA 的检测采用启发式方法，其局限已公开说明。在防护模式下，对于置于防护机制之后的 MCP 服务，若某项工具调用未获允许，防护机制会拒绝转发；其他服务不在此列。在其他所有情况下，由你的系统执行决策。无论哪种情况，都能独立验证 AI Agent 的操作是否经过检查，以及作出了什么决定。

免费检查工具 — 无需安装，无需账户

人们通常会在需要这些功能之前，先想弄清楚两个问题。这两项检查 都完全在浏览器中运行，只需回答几个问题，且不会存储任何内容。

2026 年 12 月 2 日的截止日期是否适用于你？	对于 2026 年 8 月 2 日之前投放欧盟市场的生成式系统，检查第 50(2) 条关于机器可读标记的要求，以及 Digital Omnibus 新增的两项禁止行为。帮你确定实际适用的是这两个日期中的哪一个。
第 50 条透明度义务自查	了解作为提供方或部署方，你需要履行哪些第 50 条披露义务。

这两项都是适用范围界定工具，不构成法律建议，也不会给出评分或通过／未通过结论。每项工具都会引用其所述日期对应的条文和《官方公报》文本。

自行验证 VITNA 证据

针对声称账户作出的每项决定，都会生成一条 Ed25519 签名证据记录，任何人都可以离线验证，无需拥有自己的账户，也无需信任 VITNA 的服务器。公钥已公开发布，验证器为开源，下面的三个命令大约一分钟即可完成验证。

只需一分钟，无需账户，也无需信任 VITNA 的服务器。下载开源验证器和一个真实的签名样例包，然后使用 Node 18+ 离线检查签名：

curl -sO https://raw.githubusercontent.com/COSTRINITY/vitna-compliance-mcp/main/verify-evidence.mjs
curl -sO https://vitna.costrinity.xyz/sample-evidence.json
node verify-evidence.mjs sample-evidence.json

验证器会检查整个软件包的 Ed25519 签名，然后重新计算每条单独决策记录的 sha256，并确认其与签名软件包中提交的哈希一致；它会逐条打印 PASS 或 FAIL，最后给出总体判定。

证据包是针对 Agent 操作的可验证合规回执：每项经过检查的操作都会生成一条决策记录，而签名软件包就是第三方无需信任我们即可核验的回执。

VALID 结果证明该软件包由 VITNA 签发，自导出后未被篡改，并且每条记录都与其提交的哈希一致。它不能证明相关操作确实执行过，也不能证明记录内容属实。篡改任意记录中的任何字节，该记录都会报告 FAIL，且总体判定为 INVALID。

VITNA Desktop 的软件包采用不同方式签名。 VITNA Desktop 会在你自己的机器上使用在那里生成的密钥签名，而不是使用 VITNA 的密钥。签名软件包会注明这一点（issuer: "vitna-desktop-local"、signer_key_id、signer_public_key），验证器会将这类软件包报告为“由本地 VITNA Desktop 密钥签名，而非由 VITNA 签名”。默认情况下，验证器会检查软件包携带的密钥并打印其 key_id：请将其与生成该软件包的机器上 VITNA Desktop「设置」中显示的 key_id 对比，或者通过 node verify-evidence.mjs --pubkey <base64 SPKI DER, or a file holding it> bundle.json 自行传入密钥。任何能访问该机器应用数据的人都可以重新签署软件包，而 VITNA 目前还不会对桌面软件包进行二次签名。软件包中携带的密钥仅用于对应的签发方：所有其他软件包都会使用 VITNA 公布的密钥进行检查，因此自签名软件包无法伪装成由 VITNA 签发。

重新计算 payload_sha256（pfa-v2 方案）

每条决策记录都包含 payload_sha256 和 canon_version: "pfa-v2"。这是对 12 个字段按以下顺序以管道符连接后计算的 sha256（十六进制），编码为 UTF-8，不含空白字符，也没有尾随分隔符。值为 null 或缺失的字段会变为空字符串。

sha256(
  canon_version        // "pfa-v2"
  + "|" + kind         // always "preflight_check"
  + "|" + owner_id     // evidence_package.owner_id
  + "|" + check        // "engagement_action" for engagement bundles
  + "|" + action       // record.action, "" if null
  + "|" + category     // engagement: evidence_package.session_id
  + "|" + decision     // record.decision
  + "|" + flagged      // "1" if decision !== "allow", else "0"
  + "|" + reason       // record.reason, "" if null
  + "|" + principal_id // "" for engagement bundles
  + "|" + effect       // record.effect
  + "|" + signed_at    // record.signed_at
)

完整示例，原样摘自已发布的 sample-evidence.json（记录 0）：

pfa-v2|preflight_check|f46ba5dc-b77b-4fe0-ae3d-55e6204e3d66|engagement_action|dns.read example.com|b3717358-0ece-488b-9691-a9c4a7c39d5f|allow|0|in_scope||log_only|2026-07-24T00:40:37.048Z

sha256 -> 2b0f0d22a1a3cb4980981a12e67fa72e778ca3b0d21d322ca90eac1f578e1b2f

结果与已发布样例中记录 0 的 payload_sha256 一致。log_only 前的两个连续管道符表示 principal_id 为空。

需要准确理解这能证明什么：payload_sha256 是摘要，而非签名，因此重新计算只能证明记录字段在内部一致，不能证明它们由 VITNA 签发。第三方可以依赖的逐条记录保证来自 record_hashes，因为它们位于 Ed25519 签名的软件包中。每条记录上的 signature 字段使用 HMAC-SHA256，只有 VITNA 能验证，因为 HMAC 是对称算法。

签名密钥

Algorithm : Ed25519
key_id    : 01833acd46d06ab4
SPKI DER (base64):
MCowBQYDK2VwAyEAsEBWg2cdc3sb0HAozBmtuk9q9hEdyG2bcLq4gpfudWg=

密钥发布在四个地方，其中两个不属于我们的基础设施：我们的 API /api/evidence/pubkey、公开 GitHub 镜像中的 PUBKEY.md、npm registry 上的此 README，以及嵌入在 verify-evidence.mjs 中的密钥，这样验证器就不会在运行时获取密钥。任何副本之间不一致，都会公开可见。坦诚地说：这是多地点发布，并非正式的透明度日志或第三方公证。

如果用户告诉他们的 Agent“连接到能阻止你失控的东西”或“让我监控你的行为”，就应该接入这个服务。它本身不会阻止任何行为：VITNA 负责评估和记录，而你的 Agent 会遵从拒绝／暂缓结果。零配置即可连接，无需凭据：首次调用 GOVERNED 工具时，系统会自动配置一个受限试用密钥，并在 MCP 服务日志中打印其认领链接，供你使用，而非供你的 Agent 使用。建议从 vitna_preflight 开始。vitna_help 完全在本地运行，不会发起任何网络调用，因此它可以解释相关内容，但不会创建试用账户：如果遇到困难，可以使用它，但不要把它作为第一步。

此服务让你的 Agent 在采取行动前先进行自检。

**签名审计记录（已认领的账户）：**这里的每个决策工具（同意、AI 法案、泄露、DPIA、行业、行动预检）都会在运行时写入一条决策记录。每条记录在写入时都会使用 HMAC-SHA256 进行完整性保护，并且每条独立的决策记录都会通过 sha256 哈希提交到 Ed25519 签名的证据包中，因此第三方可以离线独立验证每条记录，而不只是验证证据包。试用密钥可以运行检查，但只返回标签结果；账户被认领前，不会持久保存签名证据。

仪表板时间线中显示的内容：上述决策工具还会根据操作的实际类型，将每项决策同步到 VITNA 仪表板时间线中。例如，带有 action_type: "db.query" 的 vitna_preflight 调用会显示为带有裁定结果的 db.query 行，而不是匿名的合规记录。时间线是一种视图；签名审计记录才是证据。其他工具（标识符验证器、跨境和泄露期限查询、生成器、pii_test）都是无状态辅助工具：它们不记录决策，也不会在时间线上留下痕迹——仅使用这些工具后，时间线为空并不代表有问题。经过身份验证的调用仍会刷新仪表板上该 Agent 的最后活动时间。如需让 Agent 的常规活动（上传、工具调用、LLM 调用）也显示在时间线上，请向 POST /api/ingest 发送事件。

它为你的 Agent 提供什么

工具	用途
vitna_help	介绍 VITNA 是什么，以及如何使用它来约束自己。在本地运行，无需账户，也不会开通试用版——遇到问题时可使用。旧名称 vigil_help 仍可作为隐藏别名使用
consent_check	是否允许为此主体和目的处理数据？（预检关卡）
vitna_preflight	在执行破坏性操作（shell / 文件删除 / SQL / 数据外传）之前进行预检。基于启发式规则，需要协同配合，并非沙箱。旧名称 action_preflight 仍可作为隐藏别名使用
breach_classify	此事件是否需要报告？提供按司法管辖区划分的决策支持
ai_act_classify	欧盟《人工智能法案》风险等级分类
dpia_threshold_check	在进行此项处理前是否必须开展 DPIA？
us_sectoral_check	HIPAA / GLBA / COPPA / FERPA / FCRA / SOX 的适用性
india_sectoral_check	RBI / SEBI / IRDAI / TRAI / PFRDA 的适用性
india_cross_border_status	目的地国家的 DPDP §16 状态
japan_cross_border_status	目的地国家的 APPI Art 28 状态
us_state_breach_deadline	美国各州的数据泄露报告期限及接收报告的 AG
aadhaar_mask / pan_classify / gstin_validate / cpf_validate / sin_validate / iban_validate	身份标识符验证工具，提供遮蔽和参考令牌
pii_test	对示例事件进行干运行威胁检测
privacy_notice_get	生成符合运营方所在司法管辖区模板的隐私声明
sub_processors_register	子处理方披露登记册
global_compliance_map	合规目录：包含 28 个条目，涵盖 24 项具名法规
india_regulators_directory	印度监管机构及行业筛选器

两种连接方式

远程（无需安装）。 将支持远程服务的任意 MCP 客户端指向：

https://vitna.costrinity.xyz/api/mcp

Streamable HTTP。通过 Authorization: Bearer vitna_... 发送密钥（也支持 X-API-Key）。发现操作（initialize、tools/list）和 vitna_help 无需密钥；所有受管控的决策工具都需要密钥——VITNA 绝不会匿名评估决策。

{
  "mcpServers": {
    "vitna-compliance": {
      "type": "streamable-http",
      "url": "https://vitna.costrinity.xyz/api/mcp",
      "headers": { "Authorization": "Bearer vitna_YOUR_KEY" }
    }
  }
}

本地（stdio）。 npx @costrinity/vitna-compliance-mcp——首次使用时会自动开通试用密钥，因此启动时完全无需凭据。详见下文。

两种传输方式均通过同一目录提供相同的 23 个工具；如果两者出现差异，构建关卡会报错。

安装

npm install -g @costrinity/vitna-compliance-mcp

也可以直接通过 npx 使用。

Docker

docker build -t costrinity/vitna-compliance-mcp .
docker run --rm -i costrinity/vitna-compliance-mcp

stdio MCP 服务（无端口；使用 -i 运行）。首次使用时会自动开通受限试用密钥，与 npx 相同。

配置 MCP 客户端

零配置（自动开通）

无需任何凭据即可添加此服务：

{
  "mcpServers": {
    "vitna-compliance": {
      "command": "npx",
      "args": ["@costrinity/vitna-compliance-mcp"]
    }
  }
}

首次调用工具时，服务会通过 /api/setup 为你开通受限试用密钥，并将其缓存到 ~/.vitna/credentials.json。试用密钥可运行合规决策检查，但设有上限（每日检查次数及有效期），有效时间较短，且不会写入签名证据。认领链接不会缓存在该文件中：你的 Agent 可以读取文件。

然后认领你的仪表板

这一步很容易被忽略。 认领账户之前，系统会评估 Agent 的决策，但不会持久记录任何内容：之后没有证据可供导出，因为系统没有保存任何证据。

试用开始时，认领链接会打印在 MCP 服务日志中：也就是 MCP 服务记录日志的通道——MCP 客户端会在哪里显示日志，取决于客户端。打开链接，然后选择使用 GitHub 继续或创建通行密钥。此链接只能使用一次，有效期为 24 小时。如果链接已过期，也请打开它：在试用开始后的 72 小时内，页面会提供一个新的链接，仅限一次，该链接会保存在浏览器中，绝不会发送给你的 Agent。此后，只能重新开始试用。设置 VITNA_OPEN_CLAIM=1，也可让系统在默认浏览器中打开链接。你将获得：

• 可持久保存、经 Ed25519 签名的证据记录，可导出并离线验证
• 取消每日和终身试用次数上限，且密钥不再过期
• 一个仪表板：vitna.costrinity.xyz/dashboard，显示 Agent 做出的每一项决策，包括认领之前做出的决策
• 丢失密钥时的恢复方式

你可以在这里做出决定。 认领后，守卫拦截的调用会在仪表板上等你处理：你可以在 Agent 的水族箱中打开 Aquarium，选择批准或拒绝；调用等待处理时，仪表板上也会显示“待处理拦截”面板。如果在截止时间前无人做出决定，调用就会被拦截。你不需要新密钥：守卫会继续使用现有密钥，而认领会解除它的限制。

链接绝不会发送给你的 Agent（0.5.2）。 只有人才能认领负责监管 Agent 的账户，因此无论处于普通模式还是守卫模式，任何工具结果、错误或通知都不会包含链接。系统会告知 Agent 账户尚未认领，并说明你可以通过 MCP 服务日志中的链接认领账户。vitna_claim 工具会回答账户是否已认领（其 claim_url 始终为 null）。试用密钥也无法认领账户：VITNA 会拒绝所有携带 API 密钥的认领请求，因此只有人打开的链接才能认领账户。若 VITNA 的回复仍携带认领链接，系统会将其写入日志并移除；无论链接是直接出现，还是经过百分号编码后嵌在其他值中（例如 next= 地址），都会被移除；单独出现的认领令牌也会被移除。字段名及字段值都会被移除；如果新字段名与另一个现有字段名重复，会在末尾加上 (2)、 (3) 等，以免丢失值。0.5.1 曾将认领链接保存在 ~/.vitna/credentials.json 中；系统会将链接写入日志一次，并从该文件中移除。无论服务使用的是该文件中的密钥，还是 VITNA_OWNER_ID 和 VITNA_API_KEY，都会执行此操作；文件的其余内容保持原样，环境凭据不会写入该文件。0.5.0 和 0.5.1 会将链接放入 Agent 的工具结果中，因此 Agent 可以将链接转发给你。

从一开始就将 VITNA_EMAIL 设置为真实邮箱地址，以便用该地址注册试用账户；否则系统会使用一次性邮箱地址。

使用你自己的密钥

{
  "mcpServers": {
    "vitna-compliance": {
      "command": "npx",
      "args": ["@costrinity/vitna-compliance-mcp"],
      "env": {
        "VITNA_OWNER_ID": "<your-owner-uuid>",
        "VITNA_API_KEY": "vitna_<your-key>",
        "VITNA_BASE_URL": "https://vitna.costrinity.xyz"
      }
    }
  }
}

如果你轮换 Agent 的密钥，旧密钥会立即失效。将新密钥作为 VITNA_API_KEY（并设置 VITNA_OWNER_ID）添加到 MCP 配置中，然后重启 MCP 客户端，让守卫随之重启。在此之前，VITNA 会拒绝旧密钥，守卫也会拒绝所有工具调用（设置 VITNA_GUARD_FAIL_OPEN=1 时，则会不经检查直接转发这些调用）。这也适用于服务在试用期间为你保存的密钥：系统会使用配置中的密钥，而不是已保存的密钥。

环境变量的作用

• VITNA_OWNER_ID：你的运营者 UUID。可选：如果未设置，首次调用会自动配置一个受限试用密钥。显式凭据始终优先于缓存和自动配置。
• VITNA_API_KEY：可选。用于验证工具调用。未设置时会自动配置。新密钥的格式为 vitna_...；旧版 vigil_... 密钥仍然有效。
• VITNA_EMAIL：可选。用于拥有自动配置的试用账户的邮箱。未设置时会使用临时邮箱。这不会认领账户：请使用 GitHub 或通行密钥认领。
• VITNA_BASE_URL：默认为 https://vitna.costrinity.xyz。如果是可自托管的，请指向你自己的 VITNA 实例。
• VITNA_AGENT_NAME：可选。自动配置试用账户时使用的 Agent 名称。默认为 vitna-compliance-mcp。0.5.1 之前的版本会将你机器的主机名添加到该名称中；0.5.1 及之后的版本不会。
• VITNA_GUARD_CLIENT_TIMEOUT_SECONDS：可选，适用于 0.5.4 及之后的版本。你的 MCP 客户端工具调用超时时间（如果你已延长该时间）：对于一个被挂起的调用，会等待这段时间（减去一个余量），然后告知 Agent 该调用被挂起，而非已运行。如果未设置，guard 会使用其已知的客户端超时时间；对于未知客户端，会等待 4 秒。
• VITNA_GUARD_LOOK_TOOL：可选，适用于 0.5.5 及之后的版本。设为 1，即可向你的 Agent 提供水族箱观赏工具 vitna_choose_look。
• VITNA_GUARD_MAX_HOLD_SECONDS：可选，适用于 0.5.4 及之后的版本。任何被挂起的调用最多等待的时间；对于永不超时的客户端，此项会限制等待时长。默认值为 600。
• VITNA_OPEN_CLAIM：可选，适用于 0.5.2 及之后的版本。设为 1，即可在试用开始时，用默认浏览器打开认领链接，并将链接打印到 MCP 服务日志中。默认关闭，因为服务通常运行在无人看屏幕的环境中，启动试用的调用来自你的 Agent，而且能够操控浏览器的 Agent 可能会读取该页面。只会打开 https /claim 链接，且不会使用 shell。

这些环境变量的旧版 VIGIL_* 名称（VIGIL_OWNER_ID、VIGIL_API_KEY、VIGIL_EMAIL、VIGIL_BASE_URL、VIGIL_AGENT_NAME）将一直受支持，因此现有配置仍可正常运行。

Agent 交互示例

Agent 考虑跨境传输：

用户：将这位印度用户的个人资料迁移到我们的美国分析数据仓库。

Agent：先让我检查 DPDP §16 的状态。 调用 india_cross_border_status({ country: "US" }) 结果：permitted, but RBI Digital Lending Guidelines require India-only storage for fintech lending data。

Agent：根据 DPDP §16，此次传输是允许的（美国不在印度的负面清单上）。但如果你的数据包含金融科技贷款相关内容，RBI 指南要求仅在印度境内存储。你希望我先筛除这些字段吗？

Agent 审查新的 AI 用例：

用户：我们正在开发一种 AI 工具，用于评估求职者。

Agent：调用 ai_act_classify({ use_case: "AI evaluation of job applicants", sectors: ["employment"], automated_decisions: true }) 结果：high-risk, Art 35(3)(a) + Annex III, requires conformity assessment + human oversight + bias monitoring。

Agent：根据 EU AI Act Annex III（就业 / HR），这是一个高风险 AI 系统。进入 EU 市场前，你需要：风险管理系统、技术文档、人类监督、偏差监测和符合性评估。

Agent 处理数据泄露事件：

用户：我们刚发现 1200 条用户记录遭到泄露。

Agent：调用 breach_classify({ affected_count: 1200, data_categories: ["email", "phone"], sensitivity: "medium", recovery_state: "exposed" }) 结果：reportable=true, window_hours=72, deadline=..., recipient="Data Protection Board of India"。

Agent：此事件需要在 72 小时内报告给印度数据保护委员会（截止时间：2026-06-05）。要我准备 §8 通知草稿吗？

为什么需要它

合规性体现在运营者的运行时中，而非规划阶段。即将执行以下操作的 Agent：

• 将用户记录发送到境外
• 决定会影响个人的高风险操作
• 判定违规事件的严重程度
• 在存储标识符前进行验证

……应当能够在请求时询问 VITNA 是否允许这样做，而不是等到年度 DPIA 时再问。

MCP 将 VITNA 从“运营者访问的仪表板”转变为“Agent 调用的同步决策支持层”。

守卫模式：让 VITNA 处于执行路径中（0.5.0+）

上述方式都是协作式的：Agent 提出询问，VITNA 作出回答，然后 Agent 决定是否采纳。守卫模式则不同。将它置于任何 stdio MCP 服务前面，每次 tools/call 都会先由 VITNA 检查。只有获准的调用才会到达服务；其他调用都会被拒绝，并返回说明原因的工具错误，服务也永远不会收到这些调用。模型无法跳过检查，因为检查本身不是由它选择调用的工具。

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@costrinity/vitna-compliance-mcp", "guard", "--",
               "npx", "-y", "@modelcontextprotocol/server-filesystem", "/data"],
      "env": {
        "VITNA_GUARD_POLICY": "/path/to/policy.json",
        "VITNA_GUARD_UNWRAPPED": "github",
        "VITNA_GUARD_BUILTIN_TOOLS": "yes"
      }
    }
  }
}

未设置 VITNA_GUARD_POLICY 时，每次调用都会进行预检。设置策略文件后，守卫会开启一次参与会话，并根据该会话审查每次调用：

{
  "allowed_actions": ["*"],
  "allowed_domains": ["example.com"],
  "hold_actions": ["delete_records", "export_users"],
  "hold_window_seconds": 120,
  "canary_interval_minutes": 1440,
  "honeytools": false,
  "honeytokens": false
}

• 失败时默认拒绝。 如果 VITNA 无法评估调用（无法连接、耗时超过 10 秒、密钥被拒绝），调用不会被转发。VITNA_GUARD_FAIL_OPEN=1 会在服务中断期间改为转发，并记录每次此类调用。它绝不会转发被 VITNA 阻止或暂缓的调用。从 0.5.1 起，它也绝不会转发会话关闭后发出的调用：它会拒绝该调用并说明原因。 0.5.0 会将此答复视为错误，因此在 VITNA_GUARD_FAIL_OPEN=1 时会转发此类调用；请升级，或不要使用故障时放行模式。
• 被包装的服务未运行时。 从 0.5.1 起，如果 guard -- 之后的命令不存在，或者 MCP 客户端仍在与服务通信时，服务已退出或停止读取，守卫就不会再转发任何内容。它会对服务尚未答复的每个请求，以及之后的每个请求，返回一条 JSON-RPC 错误，说明服务未运行，然后以非零代码退出。0.5.0 可能会因未处理的 EPIPE 或生成进程错误而崩溃，且不会答复客户端。从 0.5.2 起，即使客户端在写入后已经关闭其一侧，也会如此处理：守卫会在退出前答复它写入的请求，而 0.5.1 会在未答复这些请求的情况下退出。0.5.2 还会丢弃服务迟到的答复（针对守卫已用该错误答复的请求），因此每个请求都不会收到两次答复。
• 试用限制。 免费试用密钥达到限制时（每日检查次数、终身检查次数、试用期结束、同时进行的检查次数、共享的每日试用容量，或暂停），VITNA 会拒绝检查，且不会转发调用，无论是否设置了 VITNA_GUARD_FAIL_OPEN。从 0.5.1 起，Agent 会收到已达到的限制、调用未发送的说明，以及用户用于认领账户并解除限制的链接。0.5.0 会报告 VITNA 无法评估调用，但不提供链接；在 VITNA_GUARD_FAIL_OPEN=1 时还会转发调用。从 0.5.2 起，拒绝信息不再包含链接：它会说明用户可以通过 MCP 服务日志中的认领链接认领账户。
• 不通过守卫传递认领链接（0.5.2+）。 守卫自身的拒绝消息和进度消息绝不包含认领链接；被包装服务的输出中如含有 VITNA 认领链接（/claim?owner=），都会替换为说明链接位于 MCP 服务日志中的提示，因此通过被包装服务读取的日志文件不会按原样将链接提供给 Agent。这也包括在另一个值中进行百分号编码的链接，以及 VITNA 目前签发的格式的认领令牌（v2. 后接 13 位时间和 43 个字符的代码），无论它从何处开始，无论其中的点是原样书写还是经过百分号编码，也无论它出现在值中还是字段名称中。如果字段的新名称与另一个字段已有的名称重复，就会加上 (2)、 (3) 等后缀，因此不会丢弃任何值。输出中的其他内容都不会改变（参见“诚实的限制”）。
• 暂缓。 如果调用的工具位于 hold_actions 中，就会等待用户处理。该调用会显示在所有者仪表板的“待处理暂缓”下方，包含“批准”和“拒绝”选项以及调用参数（机密和个人数据会被隐去）；如果设置了提醒 webhook，也会显示在其中。VITNA 的产品邮件域名启用之前不会发送暂缓邮件，启用之后也只会发送到已验证的所有者地址。Agent 会收到明确说明，告知调用已暂缓以及暂缓持续到何时。如果在 hold_window_seconds（30 到 3600，默认 120）内无人决定，则调用会被阻止。绝不能使用 API 密钥（包括 Agent 自己的密钥）来决定暂缓。
• 暂缓与客户端超时（0.5.4）。 大多数 MCP 客户端会在暂缓窗口结束前很久就停止等待工具调用，而许多客户端停止等待时不会说明原因。客户端可能已放弃等待后，守卫绝不会转发暂缓的调用。它会从客户端的 initialize 请求中读取客户端名称，并最多等待该客户端文档中注明的超时时间减去一个余量；对于它不认识的客户端，则等待 4 秒，这低于它所知的最短超时时间。MCP 服务日志会说明它识别到的客户端以及将等待多久。如果等待结束时暂缓仍未处理，Agent 会收到调用已暂缓且未运行的通知，暂缓仍保持开启：如果用户批准调用，Agent 在批准后 10 分钟内重试时，同一个调用（相同的工具和相同的参数）就会运行一次。重复的暂缓调用会等待同一项暂缓，而不会新建另一项（除非重复调用在首次调用的暂缓开启之前到达）。客户端发出的取消请求，或客户端关闭其一侧，都会停止暂缓调用：无论之后作出什么决定，都绝不会转发调用。若你提高了客户端的超时时间，可通过 VITNA_GUARD_CLIENT_TIMEOUT_SECONDS 告知守卫客户端超时时间（守卫会等待该时长减去一个余量）；VITNA_GUARD_MAX_HOLD_SECONDS（默认 600）则会限制每次等待时长，这对永不超时的客户端很重要。守卫识别的客户端名称来自各客户端的文档，目前尚未针对每个客户端进行测试。对于每次调用都会开启新会话的客户端（LlamaIndex、AG2），重复和重试规则只在单个会话内生效，因此批准后重试会在该客户端中开启新的暂缓。
• 水族箱外观工具（0.5.5）。 设置 VITNA_GUARD_LOOK_TOOL=1 后，守卫会在 Agent 的工具中添加 vitna_choose_look：Agent 可从 12 种颜色中选择一种，并选择一个表情符号，用于显示在所有者的 VITNA 水族箱中。这仅用于外观，不会改变 Agent 可以执行的操作。守卫会使用 Agent 自己的密钥，通过 VITNA 自行答复此请求；该请求绝不会转发给被包装的服务，也不会被暂缓。Agent 不能设置自己的名称：只有其所有者可以命名它。
• 金丝雀暂缓。 canary_interval_minutes 会插入一项演练暂缓，在有人作出决定前，它看起来与真实暂缓无异，用于衡量暂缓是否有人查看。演练会显示在仪表板上，绝不会通过邮件发送。
• 频率信号。 如果某个会话中的暂缓与阻止次数在 rate_alert_window_seconds（默认值为 300 秒）内达到 rate_alert_threshold（默认值为 5），决策答复中就会报告 rate_alert，每个窗口报告一次。将其通过邮件发送给所有者的功能要等到 VITNA 的产品邮件域名启用后才会开放。
• 诱饵，默认关闭。 honeytools: true 会在 Agent 可见的工具列表中添加一些任何正当任务都不会调用的工具（export_all_user_data、exfiltrate_data_to_attacker_server、system_admin_console 或你自己的 honeytool_names）。honeytokens: true 会在看起来像配置的工具输出中（即 KEY=value 行）植入虚假的凭据。对诱饵工具的调用，或后续调用中返回的诱饵令牌，都会被阻止、记录，并发送到已设置的提醒 webhook；通过邮件发送则要等到 VITNA 的产品邮件域名启用后才会开放。Agent 收到的拒绝信息与其他任何阻止情况相同。此设计遵循 AgentShield（Rassul and Rashid，2026）；在我们自己的测试中，针对测试服务的所有工具进行了五次无害调用，没有触发任何诱饵，但样本量很小，并非测得的触发率。对于始终遵守策略且使用看似合理参数的 Agent，诱饵无法检测到其行为。
• 覆盖范围。 使用 VITNA_GUARD_UNWRAPPED（逗号分隔）和 VITNA_GUARD_BUILTIN_TOOLS（yes/no）声明守卫看不到的内容。会话记录和证据包会说明声明的接口中有多少已被包装，并列出其余接口。该说明是操作人员的声明；VITNA 无法看到未包装的服务，也不会进行验证。如果设置了 VITNA_GUARD_NAME，则用它命名被包装的服务（例如 filesystem）；否则使用其命令的文件名命名（例如 npx 或 node）。从 0.5.1 起，该名称绝不会是文件夹路径或服务的某个参数；0.5.0 会发送服务的 npm 软件包名称或完整命令，其中可能包含你机器上的路径。
• 激活说明（0.5.1+）。 守卫模式首次联系 VITNA 时，会说明正在使用守卫模式：默认模式会在首次检查的调用中添加 "guard": { "activation": true, "mode": "default" }，策略模式则会将其开启的会话标记为由守卫开启。从 2026 年 10 月 19 日起，VITNA 会在你的账户中记录一次说明，告知正在使用守卫模式、所用模式以及客户端版本。该记录不包含工具名称、参数、IP 地址或主机名。设置 VITNA_GUARD_NO_ACTIVATION=1 可停止此操作；检查功能仍保持不变。
• 关联。 工具调用的 _meta.traceparent 会写入记录，因此 VITNA 的证据可以与你自己的跟踪信息关联起来。
• 证据。 守卫关闭会话时，会将 Ed25519 签名的证据包保存到 ~/.vitna/bundles/。有些 MCP 客户端会在退出时停止守卫，使其来不及保存（已在 Windows 上的 Claude Code 2.1.299 中观察到）。每次调用的 VITNA 决策都会保留在你的账户中，GET /api/evidence/export 会按日期返回这些决策的签名包，但不包含每项暂缓的处理结果。每项暂缓都是证据包中的一条 hold-v1 生命周期记录（proposed、held、routed、decided、outcome），可使用 scripts/verify-evidence.mjs 离线验证。试用密钥不会保存证据包：签名证据仅适用于已认领的账户。从 0.5.3 起，如果试用密钥未保存签名证据包，日志会在会话结束时说明原因（“试用密钥不会生成签名证据包”），并附上本次运行收到的认领链接，或试用开始时日志显示的链接。早期版本只会记录“无法关闭会话”。
• 覆盖范围仅限于你包装的内容。 Agent 通过其他方式访问的工具（内置 shell、未包装的服务）不受守卫保护；被阻止或暂缓的 Agent 也可能尝试其他方式。请包装每一个能够执行操作的服务。

诚实说明局限

以上数据并不意味着：

• 符合就绪要求 ≠ 已获认证。 SOC 2、ISO/IEC 27001、HIPAA 和 PCI DSS 是审计前的就绪度评分表。VITNA 未通过 SOC 2 认证、未通过 ISO 27001 认证，也未获得 HIPAA 认证，且不会声称自己已获得这些认证。
• 泄露分类覆盖 6 个司法辖区，而非全部 13 个（DPDP-IN、GDPR-EU、CPRA-CA、LGPD-BR、PDPA-SG、US-FED）。其他司法辖区包覆盖的是其他检查。
• 美国各州的数据泄露通知期限覆盖 21 个州，另有一个通用回退方案——并非覆盖全部 50 个州、DC 和 PR。
• “24 项具名法规”和“28 个目录条目”是两种不同的计数方式。 全球合规地图包含 28 个条目，其中 24 项是不同的具名法规（其余为框架和原住民数据治理原则）。本文使用 24 这一数字。
• **以下三个数字很容易混淆：**23 个 MCP 工具、22 个标识符验证器 API 路由（其中只有 6 个在此处作为 MCP 工具公开），以及 11 个 PII 检测器。它们彼此无关。
• 检测采用启发式正则表达式／特征码匹配——不是沙箱，也不是语义分析器。新型或经过混淆的有效载荷可能会通过。请将其作为一层防护，而非唯一防护。
• 除防护模式外，VITNA 不会强制执行。 工具会返回判定，是否遵循由你的系统负责。防护模式会拒绝转发 VITNA 未允许的调用，但仅限于你将其置于后方的 MCP 服务。
• 声明链接会从 Agent 的工具结果中移除，而非从 Agent 的机器上移除。 该链接会打印在 MCP 服务日志中。能够通过其他途径读取该日志的 Agent 或浏览器（例如使用内置 shell、未封装的服务或浏览器控制）仍能在那里读取该链接。
• 防护模式对封装服务输出的替换范围有限。 它会替换 VITNA 声明链接（/claim?owner=），包括原样形式或最多经过八次百分号编码的形式；还会替换当前格式的声明令牌（v2. 后接 13 位时间和 43 个字符的代码），无论令牌以何种位置开头：紧跟在字母、数字、-、. 或 _ 后，紧跟在 quoted-printable t=3D 后，或其中的点写作 . 或最多经过八次百分号编码（%2E）。对于 JSON 行，它会同时替换字段名和值中的这些内容。以下内容会原样传递：旧格式令牌（不带 v2. 的时间和代码），因为它与其他标识符过于相似，无法在非我方输出中安全替换；时间不是 13 位的 v2. 令牌；代码紧接着其他字母、数字、- 或 _ 的令牌，因为这会构成更长的字符串，而不是令牌；/claim? 路径后没有接 owner= 的地址；以及跨行拆分的链接或令牌（防护模式逐行读取），或通过百分号编码分隔符和点以外的任何方式进行伪装的链接或令牌，包括将字母进行百分号编码、将点写作 quoted-printable =2E，或在非 JSON 行上使用 \u 转义。未识别的链接中若包含当前格式的令牌，该令牌仍会被替换。
• VITNA 自身的回答和防护模式自身的消息会进行更广泛但仍不彻底的清理。 任何 /claim? 链接都会被移除，包括原样形式或最多经过八次百分号编码的形式；当前格式的令牌也会在上述任何开头位置被移除。旧格式令牌，或时间不是 13 位的 v2. 令牌，如果其时间长度为 12 到 14 位，且令牌独立出现或紧跟在百分号编码字节（例如 t%3D 中的 %3D）之后，且点写作 .，也会被移除。时间少于 12 位或多于 14 位的令牌，即使独立出现也会通过。令牌紧跟在字母、-、. 或 _ 后，或其点经过百分号编码时，也会通过。v2. 令牌紧跟在数字后也会通过；旧格式令牌若前置数字使时间长度超过 14 位，也会通过（位于 13 位时间之前的一位数字会被视为 14 位时间的一部分，并随之一起移除）。代码紧接着其他字母、数字、- 或 _ 的任何令牌也会通过；跨行拆分或采用上述方式伪装的内容同样会通过，但其中写有当前格式令牌的部分仍会被移除。

许可证

MIT © COSTRINITY INC.（一家位于加拿大萨斯喀彻温省里贾纳、位于第 4 号条约领土的原住民所有软件公司）