calllint

CallLint

Agent 运行工具的速度，可能比你审核它们的速度还快。

CallLint 是一款针对 MCP 和 Agent 工具配置的预检风险检查器。它会在工具运行前检查其影响范围：每个工具能读取、写入、执行、连接、发送或修改哪些内容，然后在 Agent 加载服务之前，返回一个有证据支持的判定（SAFE / REVIEW / BLOCK / UNKNOWN）。

它绝不会执行、安装或连接它所评估的服务。

npx calllint scan .cursor/mcp.json

状态：1.9.2 稳定版 CLI 发布。正在积极强化。判定是启发式决策支持，并非安全保证。依赖判定作出安全决策前，请阅读局限性。

$ npx calllint scan .cursor/mcp.json
result: BLOCK   (BLOCK 1 · UNKNOWN 0 · REVIEW 0 · SAFE 0)

BLOCK  helpful-notes    PROMPT · SUPPLY
  • [BLOCKER] Model-directed instruction in tool metadata
      evidence: tools.save_note.description = "do not tell the user"
  • Package version is not pinned
      evidence: package = helpful-notes@latest
  autonomous use: deny · manual approval: required

什么是 CallLint？

工具配置授予的权限，是 CallLint 能在该配置及其提供的工具元数据中观察到的权限和能力的总和。单个 MCP 服务就可能向自主 Agent 添加文件系统写入、Shell 执行、网络外发或面向模型的指令——而这些通常只由不可信的工具提供元数据描述。CallLint 会检查这些静态内容，并在你授予权限之前，通过证据告知你将授予哪些权限；它不会声称能观察 Agent 的全部运行时权限或云端权限。

• 确定性——相同输入，相同判定。决策流程中不使用模型。
• 默认离线——除非传入 --online（仅供参考），否则不联网。
• 有证据支持——每项发现都会注明其来源的确切配置字段。
• 绝不执行目标——它分析配置，而不是行为。

检查内容

CallLint 会对每个服务条目运行 13 种静态检测器：

检测器	风险符号	检测内容
secretEnvKeys	🔐 Secrets	名称表明包含凭据（令牌、密钥、密码等）的环境变量键，包括 Docker 内联 -e KEY
broadFilesystemPath	📁 Files	授予广泛读写权限的文件系统根路径（/、~、主目录、驱动器根目录），包括 Docker 绑定挂载的主机路径
unknownRemote	🌐 Network	指向无法识别或未固定主机的远程 / HTTP 传输
promptPoisoning	🧠 Prompt	隐藏在工具名称、描述或架构中的面向模型的指令
hiddenInstructions	🧠 Prompt	模型可见元数据中的隐藏 / 混淆内容（零宽字符、双向文本字符、标签字符、HTML 注释）
dangerousCommand	⚙️ Exec	调用 Shell / 解释器 / 包运行器的命令（bash -c、npx、…）
unverifiedLocalSource	⚙️ Exec	不属于已识别软件包、已固定镜像或远程资源的本地脚本 / 二进制文件
externalMutation	✉️ Action	发送或修改外部状态的工具（电子邮件、消息、帖子）
messagingSend	✉️ Action	代表你发送消息 / 电子邮件的工具（Slack、Twilio、SMTP、…）
oauthScope	✉️ Action	未声明、范围过广或权限过大的 OAuth 作用域（admin、*、repo、…）
gatewayRuntime	✉️ Action	在单个授权下代理多个下游工具的长时间运行网关
financialAction	💸 Money	支付 / 转账 / 不可逆的金融操作
unpinnedPackage	🧩 Supply	未固定的软件包规范（@latest、未指定版本）——存在被恶意替换的风险

发现会汇总为一个风险等级（S0 仅元数据 → S5 金融 / 不可逆）以及每个服务和每份配置的聚合判定。

漂移检测（baseline / verify）会记录已批准的风险范围，并标记恶意替换（🔁）——即风险范围后来发生变化的已批准服务。

不检查的内容

这份列表比功能列表更重要。CallLint 是一种运行前检查， 而不是安全性证明。

• 它不会执行、安装或连接服务器，因此无法观察 实际运行时行为（服务器实际读取、写入或发送什么）。
• 它不会读取或验证密钥值，只检查配置的结构 （键名），绝不会读取 .env 或凭据存储中的内容。
• 它不会分析服务器源代码，只检查配置，以及你在 x-calllint.tools 下提供的任何工具元数据。
• 除非传入 --online，否则它不会获取任何内容；在线结果仅供参考， 绝不会将判定升级为 SAFE。
• 它不会认证第三方工具、取代人工安全审查，也不保证 Agent 安全。
• 检查通过是必要条件，而非充分条件。 请结合代码审查、 最小权限令牌和运行时控制措施使用。

UNKNOWN 是一种真实的判定：当 CallLint 无法验证服务器将执行什么操作时， 它会如实说明，绝不会悄悄将 UNKNOWN 升级为 SAFE。

CallLint 是什么——又不是什么

CallLint 不是什么	CallLint 是什么
运行时沙箱	面向 Agent 工具配置的运行前风险检查器
密钥扫描器（它绝不会读取密钥值）	配置结构检查器，用于标记形似凭据的键
npm audit（已知软件包 CVE）	对你授予的权限进行影响范围检查
服务器源代码分析器	静态配置 + 工具元数据分析器
安全证书	启发式决策支持，而非安全保证
人工审查的替代品	审查的起点，并附带证据

安装

# run without installing (recommended):
npx calllint scan ./mcp.json

# or install globally:
npm install -g calllint

需要 Node.js ≥ 20。已发布的软件包是一个完全独立的单文件包， 没有任何运行时依赖。latest 标签上的 calllint 是当前稳定版 CLI； @next 包含候选版本，@preview 则包含较早的预览版。

快速开始

零配置扫描——发现并扫描所有 Agent 配置：

# Auto-discover and scan all agents (Cursor, Claude Code, Claude Desktop, VS Code, Windsurf)
calllint scan --auto

# List all discovered agent configs
calllint inventory

# Scan a specific agent type
calllint scan --agent cursor
calllint scan --agent vscode

手动指定路径扫描——扫描特定配置文件：

# scan a config file (auto-detects common locations if no path given)
calllint scan ./mcp.json

# scan from stdin, machine-readable JSON out
cat .cursor/mcp.json | calllint scan --stdin --json

# CI gate: non-zero exit per policy (BLOCK=30, UNKNOWN=20, REVIEW=10 if enabled)
calllint scan ./mcp.json --ci --no-emoji

# synthesize a config for an npm package (offline) or a GitHub repo (--online)
calllint scan npm:[email protected]
calllint scan github:owner/repo --online

# record an approved baseline, then detect drift / rug-pulls later
calllint baseline ./mcp.json
calllint verify ./mcp.json --ci

# explain one server's verdict from the last scan
calllint explain filesystem

# structured diagnostics for editor / agent-host integration
calllint diagnostics ./mcp.json --json

输出格式：默认终端格式、--compact、--json（稳定的架构）、 --sarif（GitHub Code Scanning）、--markdown（PR 评论 / GitHub Step Summary）、--html（独立报告）。diagnostics 命令会单独输出编辑器/Agent 宿主 JSON（calllint.diagnostics.v0）。

查看 CallLint 如何在 CI 中扫描特意设置为高风险的配置—— calllint-demo-risky-mcp 会在每次推送时，为每项发现发布一条 Code Scanning 警报。

超越配置扫描

同一引擎和判定语义也适用于 MCP 配置扫描之外的其他场景， 即 Agent 授予权限的其他环节：

# Preflight a planned external action before the agent runs it
calllint action inspect payment.json          # calllint.action.v0 descriptor
calllint action inspect email-reply.json --json

# Preflight a normalized agent inbox event (delegates to the action analyzer)
calllint inbox inspect gmail-reply.normalized.json

# Record a scan as a local, verifiable receipt, then validate it later
calllint scan ./mcp.json --receipt            # writes calllint-receipt.json
calllint receipt verify calllint-receipt.json

# Attach an external content-scanner report as evidence (joint Trust Packet)
calllint scan ./mcp.json --evidence skillspector-report.json

回执（calllint.receipt.v0）是基于扫描结果生成的报告层—— 它证明了哪个 CallLint 版本依据哪项策略，对哪个输入生成了哪个判定。它不是第二个扫描器，也绝不会重新判定结果。回执可以携带可选的 ed25519 签名；receipt keygen / receipt sign 可在本地生成并签署回执以供开发使用，receipt verify 则会在存在签名时验证签名（离线使用，需传入 --public-key）。签名证明的是来源和完整性，绝不代表安全性。

信任网关 — 准备、审批、应用、验证

扫描会告诉你影响范围；信任网关会安全地采取行动。它会将 Agent 工具目标解析为不可变、固定摘要的身份，对其进行确定性判断，并生成可逆的安装计划。应用该计划是唯一会写入实时配置的操作：它会重新验证每个摘要、以原子方式写入、验证结果，并在失败时回滚。网关绝不会执行、安装或连接它所判断的目标。

# read-only: resolve + judge a target and emit a reversible plan (touches no live config)
calllint trust prepare github:owner/repo --host claude-code --write-plan
calllint trust show    .calllint/plans/<plan-id>.json
calllint trust explain .calllint/plans/<plan-id>.json

# the only writer of live config — applies an approved plan, atomically and reversibly
calllint trust apply --plan .calllint/plans/<plan-id>.json --approve <plan-digest> --receipt

# validate a decision receipt later (read-only; never re-judges or executes)
calllint trust verify calllint-decision-receipt.json --public-key key.pub

网关是一个确定性、故障关闭的流水线，处理六个封存摘要（工件 → 证据 → 权限 → 决策/策略 → 安装计划 → 回执）。一次审批会同时绑定全部六个摘要；如果准备与应用之间任何摘要发生变化，审批即失效，且不会写入任何内容。UNKNOWN 永远不会变成 SAFE，外部证据可以收紧判定，但不能单独设定判定结果。五种 Tier-A 主机提供经过审计的应用界面 — Claude Code、Cursor、Windsurf、Claude Desktop 和 VS Code。请参阅 CHANGELOG（Trust Gateway Core）和 ADR 0035–0039。

持续防护 — 在审批后发现突然变更

曾经审批过的工具之后可能发生变化。calllint guard 会记录已审批的权限范围并重新判定 — 未发生变化时保持静默；一旦先前审批过的服务风险范围发生变化（即突然变更，🔁），便会发出警报。它不会添加新的判定引擎：它会复用与 baseline / verify 相同的确定性漂移检查和相同的稳定退出码。

# re-assess the current authority surface vs the approved baseline (silent when unchanged)
calllint guard

# install a guard hook into a host — a declarative shim that only shells out to `calllint guard`
calllint guard install --host git       # git pre-commit hook
calllint guard install --host github    # GitHub Actions drift-gate workflow
calllint guard status                   # baseline / disable / installed-hook state
calllint guard disable                  # writes .calllint/guard.json { enabled: false }

Guard 可安装到七种主机：git（pre-commit）、git-pre-push、github （Actions）、claude-code、copilot、gemini 和 vscode。每个钩子仅绑定到提交 / 推送 / CI / 会话开始事件 — 绝不会作为逐次调用的关卡 — 因此 guard 钩子绝不会悄悄阻止工具调用（ADR 0045、ADR 0052）。有专用文件的主机（git、GitHub、Copilot）会被整体写入；钩子位于共享用户配置中的主机（Claude Code、Gemini、VS Code）则会打印出供你合并的片段 — guard install 绝不会覆盖共享文件。

将预检集成到 Agent 中 — integrate 和 Claude 插件

calllint integrate 会将 CallLint 自己的 MCP 服务（calllint-mcp）安装到你已在使用的 Agent 主机中，让 Agent 在审批其他服务之前自行运行预检。它默认仅生成计划：检测已安装的主机，构建可逆的安装计划，连同摘要一起打印出来，不写入任何内容。应用计划是单独、明确且经过审批的步骤，会复用信任网关经过审计的原样写入器（重新验证 → 原子写入 → 验证 → 失败时回滚）。

calllint integrate                       # detect hosts + print an install plan (writes nothing)
calllint integrate --write-plan          # persist each plan to .calllint/plans/<id>.json
calllint integrate --apply --plan <p.json> --approve <plan-digest>   # the only writer

此操作具有幂等性（已存在 calllint 服务的主机不会有任何变更），并且作用于项目范围（仅处理你运行命令所在仓库下的配置，不涉及全局机器状态）。

对于 Claude Code，CallLint 还提供带有 PreToolUse 钩子的插件。当 Claude 即将写入或编辑 Agent 工具配置时，钩子会提示一条建议，提醒先进行扫描。它仅提供建议，不会阻塞操作：始终以 0 退出，从不否决工具调用，自身不运行扫描，并且钩子和大模型都不会进入判定流程（ADR 0051）。安装该插件不会安装运行时阻止器。

/plugin marketplace add calllint/calllint
/plugin install calllint@calllint

将 CallLint 作为 MCP 服务运行（calllint-mcp）

CallLint 也以独立 MCP 服务的形式提供，因此 Agent 可以自行运行预检——在安装或批准另一个 MCP 服务之前。它只是同一引擎的轻量封装：每个工具都会委托给 calllint，不带任何运行时依赖，也绝不会执行它所判定的服务。

{
  "mcpServers": {
    "calllint": {
      "command": "npx",
      "args": ["-y", "calllint-mcp"]
    }
  }
}

提供的工具：scan_mcp_config_path、scan_mcp_config_json、verify_baseline、 explain_finding、generate_agent_rule、generate_ci_gate_snippet。该服务使用 stdio JSON-RPC，并返回与 CLI 相同、以证据为依据的 SAFE / REVIEW / BLOCK / UNKNOWN 判定。详情请参阅 packages/calllint-mcp。已在 npm 上发布为 calllint-mcp。

示例报告

CallLint scan
config: ./mcp.json
result: BLOCK   (BLOCK 1 · UNKNOWN 0 · REVIEW 0 · SAFE 0)
────────────────────────────────────────────────────────────

BLOCK  helpful-notes    PROMPT
  S2 Sensitive read · reproducibility HIGH · confidence medium
  "helpful-notes" is blocked. Risk: Prompt (S2 Sensitive read).

  • [BLOCKER] Suspicious model-directed instruction in tool metadata
      (prompt.poisoning, observed, confidence medium)
      evidence: tools.save_note.description = do not tell the user
      impact: Tool metadata reaches the model directly and can hijack
              autonomous tool selection or coerce data disclosure.
      fix: Remove model-directed instructions from tool names,
           descriptions, schemas, and server instructions.

  autonomous use: deny · manual approval: required · sandbox: recommended

用例库和发布门禁

CallLint 的判定通过一个可机器检查的用例库进行测试。每个用例都固定了预期判定、必需证据，以及一项“危险输入绝不判定为 SAFE”的策略。用例库作为发布门禁执行： pnpm corpus:test。

• 60 个校准用例
• 38 个真实或脱敏快照
• 0 个危险输入被误判为 SAFE
• UNKNOWN 比率为 10.0%（目标 ≤ 15%）

用例库是回归和校准门禁，并不代表覆盖了完整的 MCP 生态系统。请参阅 project-facts.json（这些数字的唯一事实来源）。网站和 README 文案通过 pnpm check:public-copy 保持同步。

规则列表

每条规则都有一个检测器，并在 packages/risk-engine/rules/ 下提供可供人阅读的文档：

• prompt.poisoning — 工具元数据中面向模型的指令（阻断项）
• prompt.hidden-instructions — 模型可见元数据中的隐藏／混淆内容（零宽字符、双向字符、 标记字符、HTML 注释）（R4 提示词表面，ADR 0014）
• prompt.surface-instructions — 通过 --surface-dir 读取的项目文档中面向模型或隐藏的内容 （README.md / SKILL.md / AGENTS.md / package.json 描述）；非阻断项，ADR 0015
• exec.dangerous-command — 调用 shell／解释器／包运行器的命令
• exec.unverified-local-source — 运行的本地脚本／二进制文件并非已识别的包、固定版本的镜像或远程资源（ADR 0011）
• files.broad-path — 过于宽泛的文件系统授权，包括 Docker 绑定挂载主机 路径（--mount type=bind,src=…、-v host:container；ADR 0012）
• supply.unpinned-package — 未固定版本的包声明（存在被恶意替换的风险）
• 以及 secretEnvKeys、unknownRemote、externalMutation、financialAction 检测器（请参阅检查内容）

判定由策略即代码（calllint.policy.json）管理；运行 calllint policy init 可写入默认值，运行 calllint policy explain 可查看 生效的策略。

徽章

calllint scan <config> --badge 会生成一个 shields.io 端点 JSON 对象，让 MCP 作者可以在 README 中展示真实的 CallLint 判定。该徽章旨在提高透明度：它会显示实际判定结果，并且只有 SAFE 显示为绿色——REVIEW、UNKNOWN 和 BLOCK 各自使用不同的非绿色。它是对综合判定结果的呈现（不更改架构），而 SAFE 表示未发现阻断项，并不证明运行时安全。有关接入方式和判定结果到颜色的映射，请参阅 badge.md。

安全模型

CallLint 是一款安全工具，因此其自身的边界明确且可审计。

• 不在主机上执行。 它只解析配置并进行推理，从不运行它所评估的服务。（参见 ADR 0003。）
• 将所有配置视为攻击者控制的内容。 工具名称、描述和架构均为不可信输入；报告渲染时会对其进行转义。
• 默认离线。 --online 仅会添加咨询性的注册表查询，绝不会让判定变得更宽松。
• 确定且可复现。 判定流程不涉及模型、时钟或网络；JSON 输出架构稳定（calllint.report.v0）。

完整声明：SECURITY.md · 信任边界：LIMITATIONS.md。请将问题报告至 [email protected]。

匿名使用情况遥测 — 选择加入，默认关闭

除非你明确同意，否则 CallLint 不会收集任何信息。关闭遥测时，扫描可完全离线运行，且遥测绝不会影响任何判定。

• 默认关闭。 首次在交互式终端中运行时，CallLint 会询问一次。只有明确输入 y/yes 才会启用；直接按 Enter、超时、输入 n 或遇到 EOF 都会保持关闭，并会记住你的选择，因此最多询问一次。
• 非交互模式下绝不询问。 在 CI 中、输入通过管道传入时、使用 --json/--sarif 时，或设置了紧急关闭开关时，都不会询问，也不会收集数据。
• 紧急关闭开关。 CALLLINT_TELEMETRY=0（也可以是 false/off）会禁用所有级别的遥测，无论已保存的状态如何。
• 随时查看或更改： calllint telemetry status · enable · disable · reset（轮换安装 ID）。

事件可能包含的内容：事件名称、主机系列（例如 cursor）、结果类别（例如 BLOCK）、耗时、输入类型、发现来源、CallLint 版本以及随机生成的安装 ID。有效载荷通过允许列表构建——未列出的字段会被丢弃，不会转发。

绝不会发送： 配置内容 · 文件路径 · 命令 · 参数 · 密钥值 · 提示词 · 发现项证据 · 服务名称 · 任何可识别你或你的机器的信息。

在服务端，请求 IP 和 User-Agent 仅用于速率限制，绝不会被持久化；安装 ID 在接收时会经过 HMAC 处理，原始值随即丢弃。不存在原始事件日志。

局限性

CallLint 检查的是配置，而非行为。它可能漏掉只有在运行时才会显现的服务风险，也可能将最终证明无害的表层特征标记出来。它依赖你提供的工具元数据准确无误，而且服务可能在你批准后发生变化（使用 baseline / verify 检测变化）。它采用启发式方法：既可能误报，也可能漏报；应将 REVIEW/BLOCK 视为审查的起点，而非完整的威胁评估。完整的信任边界文档请参见 LIMITATIONS.md。

路线图

• 扩大配置格式覆盖范围（支持更多 Agent/主机配置方言）
• 提供更丰富的在线供应链信号（仍仅供参考，绝不自动判定为 SAFE）
• 增加更多检测器和可调策略包
• 增加 SARIF 以外的编辑器/CI 集成

CallLint 将继续专注于 Agent-工具配置的运行前风险检查。 托管注册表、网关和运行时强制执行不在当前版本的范围内。

项目

CallLint 是官方的 Apache-2.0 开源项目，发布于 calllint.com、 github.com/calllint/calllint 和 npm 软件包 calllint（CLI）以及 calllint-mcp（MCP 服务）。项目由维护者主导——参见 GOVERNANCE.md 和 CONTRIBUTING.md。

许可证

Apache-2.0——参见 LICENSE 和 NOTICE。CallLint 名称和 徽标不随代码一同授权；参见 TRADEMARKS.md。