Veil

AI 代理可以编排凭证的放置，而无需获取凭证值，同时一个受信任的人类控制界面独立授权该凭证允许去往何处。

这句话就是全部承诺。Veil 是一个 MCP 服务器加上一个安全输入代理：代理说 "将 Stripe 生产密钥放入 Google Secret Manager"，人类看到将写入的确切项目和密钥名称，然后在 Veil 自己的窗口中输入该值，该值直接发送到目的地。模型从未持有它。

根据 SPEC.md 实现。

Veil 解决的问题

它消除了由代理知道密钥所导致的一整类故障。有了 Veil 的介入，凭证不会经过：

• LLM 提示或对话历史

• MCP 工具参数或工具结果

• 代理内存或生成的代码

• shell 命令参数或进程 argv

• 日志、调试跟踪或遥测

• URL

• 模型可见的命令输出

Veil 不解决的问题

Veil 不会使 AI 代理变得可信，也不是“安全 AI”。它不保证代理选择了正确的目的地，不保证它理解了你，不保证它没有提示注入，不保证目的地本身是安全的，不保证你的机器未被入侵，也不保证凭证以后不会被合法接收它的软件滥用。

这里有两个独立的问题：

Veil 回答了这两个问题。它不声称回答了其余问题。

信任模型

Trusted with the credential value:

  The human at the keyboard
  Veil's secure input UI          (loopback only, in your control)
  Veil's secure input broker      (this process)
  The selected destination adapter
  The destination provider        (e.g. Google Secret Manager)

NOT trusted with the credential value:

  The LLM
  The agent / MCP client
  The conversation
  The prompt and any repository content it read
  Generated code
  Logs, telemetry, crash reports

此图并不声称受信任的组件是不可攻破的。它说明了凭证允许存在于何处。Veil 是安全敏感软件：如果 Veil 本身是恶意的或被攻破，边界就消失了。其源代码、依赖项和发布版本值得你给予任何凭证处理工具应有的审查。

两个流程

密钥流程——人类的路径，模型无法观察到：

Human ─▶ Veil secure UI (127.0.0.1) ─▶ Broker ─▶ Adapter ─▶ Destination

代理流程——模型看到的一切：

LLM ─▶ MCP client ─▶ Veil MCP server ─▶ non-sensitive result metadata

MCP 工具模式没有能够携带凭证的属性。这是结构性的，而不是提示指令：没有 value、secret_value、password、token、content 或 raw_secret 字段可供滥用，封闭模式拒绝未知属性，并且在解析参数之前会筛选出类似凭证形状的值。

代理调用的内容

{
  "destination": "gcp-secret-manager",
  "name": "STRIPE_SECRET_KEY",
  "target": { "project": "my-production-project", "secret": "STRIPE_SECRET_KEY" },
  "write_mode": "new-version",
  "environment": "production",
  "description": "Stripe production API key"
}

Veil 回复一个 request_id、一个风险分类和规范化的目的地——并在你的机器上打开自己的授权窗口。代理轮询 secret.status。

代理不会获得授权链接。 该链接是一种能力：任何持有它的人都可以完成流程中人类的那一半，而拥有 shell 或 HTTP 工具的代理正是威胁模型。Veil 将其交给你的浏览器并打印到自己的控制台。如果你的设置需要代理转发链接（例如远程或无头会话），请设置 VEIL_DISCLOSE_AUTHORIZATION_URL=true——并理解这会让被攻破的代理授权自己的请求。

人类看到的内容

阶段 A 在输入值之前显示凭证名称、目的地提供商、项目/账户、资源、操作和风险。高风险操作（生产环境覆盖、明文存储、应用程序数据库、替换凭证）需要在阶段 B 进行第二次确认，在输入之后、写入之前。该值永远不会被回显。

人类阅读的页面和执行器执行的操作是同一个不可变对象——没有单独的“显示目的地”。对目的地、项目、密钥名称、操作、写入模式或适配器的任何更改都会使授权失效，需要新的授权。

支持的适配器

arbitrary-network 目的地（通用 HTTP POST、webhook）未实现，并且适配器注册表拒绝注册此类适配器。

安全假设与限制

坦率地说，因为一个过度推销自己的安全工具比没有更糟糕：

• 代理进程会看到密钥。 这就是重点：必须有人看到，否则无法存储。保证是只有最小的受信任传输和目的地组件看到。

• CPython 无法可靠地擦除内存。 SecretBuffer 会擦除其拥有的可变缓冲区，但百分比解码、str/bytes 转换和提供商 SDK 会创建不可变副本，解释器可能会保留这些副本直到垃圾回收。Veil 最小化且不虚构此保证。

• UI 是回环 HTTP。 任何以你的用户身份在你的机器上运行的进程都可以访问它，并且任何此类进程也可以模仿它。每个 Veil 进程都会打印一个随机身份短语，其页面会显示该短语（反欺骗辅助，不是加密控制）。对代理隐藏链接提高了门槛；它不能阻止能够读取 Veil 控制台输出、列出浏览器 argv 或扫描回环端口的进程。

• Veil 不审计目的地。 如果你授权将凭证写入 Firestore 文档，Veil 会将其写入那里并告诉你这是个坏主意；它不会阻止你。

• 预检是尽力而为。 在预检时无法到达的提供商会报告为不可用，而不是猜测。

• 崩溃语义。 在提供商写入和响应之间发生崩溃可能导致凭证已写入但本地没有成功记录。Veil 将请求报告为失败；目的地是真相来源。

本地开发

uv venv
uv pip install -e ".[dev]"

# run the server the way an MCP client would
uv run veil serve

# with optional providers
uv pip install -e ".[dev,gcp,firestore]"

配置从 Veil 自己的环境变量中读取——绝不从工具参数中读取：

MCP 客户端配置

{
  "mcpServers": {
    "veil": { "command": "uv", "args": ["run", "veil", "serve"] }
  }
}

测试

uv run pytest                  # everything
uv run pytest tests/security   # the adversarial suite only
uv run ruff check .
uv run mypy

安全套件是产品需求，而不是锦上添花。它包含跨每个可观察通道的金丝雀泄漏检测、恶意代理测试、提示注入测试用例、TOCTOU 和重放测试、100 路并发压力测试、竞态条件、崩溃路径、提供商故障模拟、UI 检查和模糊测试。如果任何金丝雀泄漏、任何授权绕过成功、任何批准后篡改成功、任何已完成的请求可重放、任何密钥跨越请求边界、任何原始提供商错误到达 MCP，或任何高风险操作跳过确认，则阻止发布。

请参阅 docs/SECURITY_MODEL.md 了解不变量到测试的映射。

项目状态

版本 0.1.0，根据 SPEC.md 构建，该文件保留在仓库中作为预期行为的权威描述。每个重要模块和测试都引用了其实现的章节，因此审查者可以对照需求检查代码，而不是对照其摘要。

MVP 已完成，完整套件（包括对抗性套件）已通过。在任何人应该认真依赖它之前还需要做的是：独立审查、确认 UI 的人因测试（SPEC.md §35）以及签名发布工件（§43）。

贡献

这里的产品是安全性，因此变更的门槛是具体的而不是官僚的：

• 涉及凭证处理、授权或 MCP 表面的变更需要有一个试图破坏其影响的不变量的测试，而不仅仅是展示其正常工作的测试。

• 永远不要为了通过套件而削弱安全测试。如果测试揭示了架构缺陷，那么改变的是架构。

• 核心中的新运行时依赖默认被反对。代理是凭证材料的可信计算基础；提供商 SDK 属于可选的额外依赖。

• 在提交拉取请求之前，运行 ruff check .、ruff format --check .、mypy 和 pytest。

发现漏洞？请通过 GitHub 的安全公告私下报告，而不是打开公开问题。

许可证

Apache License 2.0 © 2026 Eduardo Rosostolato。