Skarn guard：代理插件

为 Skarn 打包的钩子配置、代理技能和本地 MCP 服务器声明，覆盖四个宿主，第五个宿主由独立仓库提供。本仓库在每次 Skarn 发布时生成。它不包含二进制文件、检测规则或引擎代码。

这里有五个单元，其中四个是守卫单元。claude/ 和 codex/ 是本仓库根清单所服务的市场中的插件，分别用于 Claude Code 和 Codex CLI。antigravity/ 是 Antigravity CLI（agy）的插件目录。仓库根目录本身就是一个 Gemini CLI 扩展，因为 Google 的安装器和画廊爬虫从根目录读取清单。根目录下的文件要么是仓库级文件（本 README、LICENSE、SECURITY.md、市场清单），要么是 Gemini 文件（gemini-extension.json、GEMINI.md、hooks/、skills/）；其他每个宿主都有自己的子目录。第五个单元 recall/ 是同一市场中的纯技能插件：一个技能，没有钩子，没有 MCP 服务器。Cursor 单元完全不在此仓库中；它位于 https://github.com/skarn-security/cursor-plugin。

守卫是一个执行前钩子。在你的代理运行 shell 命令、应用补丁、写入文件、获取 URL、调用 MCP 工具或向模型提供商发送提示之前，待执行的操作会由你机器上的 Skarn 检测引擎扫描并得到判定：拒绝（阻止）、询问（升级给你）或允许（静默）。它在本地扫描，不发起网络调用，也从不打印原始机密——判定会指明规则名称和脱敏预览。

安装

先安装 skarn 二进制文件（插件不携带它；钩子会调用你 PATH 上的 skarn guard）：

brew install skarn-security/tap/skarn

Claude Code：

claude plugin marketplace add skarn-security/agent-guard
claude plugin install skarn-guard@skarn

Codex CLI：

codex plugin marketplace add skarn-security/agent-guard
codex plugin add skarn-guard-codex@skarn

两个守卫插件名称不同，因为一个市场不能容纳两个同名插件，而且每个插件都带有其宿主的钩子形态（事件名称、工具匹配器以及守卫路由所依据的 --agent）。安装与你所接线的宿主对应的那个。两者都携带 skarn-audit 技能，该技能在本机上运行 skarn assess 和 skarn vet 并报告脱敏发现。脱敏会遮蔽 Skarn 检测到的凭据值；发现中周围的转录上下文仍然来自会话，因此该技能将整个结果视为会话数据而非安全文本。

Codex 会在你安装后首次启动时要求你信任钩子：在“Hooks need review”提示中选择“Trust all and continue”。在此之前，钩子不会运行，守卫也不会保护你。信任是基于每个钩子的内容哈希，因此之后对钩子的任何更改（版本升级或从审计切换到强制）都会再次询问。Claude Code 不需要信任步骤；钩子会在你的下一个会话中立即可用。

skarn-recall 是同一市场中的第三个插件，上面的市场添加已经覆盖了它。它只携带一个技能，没有钩子，也没有任何宿主特定的内容，因此同一个插件可以服务两个宿主：

claude plugin install skarn-recall@skarn

codex plugin add skarn-recall@skarn

该技能从你的会话转录中重建你处理过的内容，这就是为什么它与守卫分开发布而不是内置其中。它读取的转录内容会离开你的机器，发送给服务该代理的模型提供商；脱敏遮蔽的是 Skarn 检测到的凭据，而不是所有你认为是敏感的内容。当你需要时再安装它，并通过项目和时窗来限定其读取范围。

Gemini CLI 将此仓库作为扩展安装，该扩展以审计模式携带相同的守卫钩子、skarn-audit 技能、GEMINI.md 上下文文件以及下面的 MCP 服务器：

gemini extensions install https://github.com/skarn-security/agent-guard
gemini extensions list
gemini extensions uninstall skarn

安装会请求同意，因为扩展同时声明了钩子和 MCP 服务器，并且会要求你信任该文件夹。两个都同意。

Antigravity CLI 安装克隆的 antigravity/ 目录：

git clone https://github.com/skarn-security/agent-guard
agy plugin install agent-guard/antigravity
agy plugin list
agy plugin uninstall skarn-guard

agy plugin list 会报告该插件的钩子、技能和 MCP 服务器数量。手动将 antigravity/ 复制到 ~/.gemini/config/plugins/skarn-guard/ 也能达到同样效果。

Cursor 有自己的仓库，https://github.com/skarn-security/cursor-plugin，由同一次发布生成。Cursor 的市场及其审核是按仓库进行的，这就是该单元不在此处的原因。

skarn setup 是 Claude Code、Codex CLI、Cursor、Copilot CLI、Gemini CLI 和 Grok Build 的替代安装路径：它将相同的钩子合并到这些宿主的原生配置中，而不使用插件系统。它不认识 Antigravity CLI，因此该宿主安装上面的插件目录或手动合并其钩子文件。

Related MCP server: netallion-mcp-lite

本地 MCP 服务器

四个守卫单元（claude/、codex/、antigravity/ 以及根目录的 Gemini 扩展）都声明了相同的 stdio MCP 服务器，宿主通过从你的 PATH 运行 skarn mcp 来启动它。Cursor 和 VS Code 一键即可：

两个按钮都将服务器注册为 skarn 并从你的 PATH 运行 skarn mcp，所以请先安装二进制文件。如果你不想安装它，固定版本的启动器形式只需有 Node 即可工作：Cursor 或 VS Code——它会在首次运行时下载 @skarn-security/skarn@0.26.0 并在之后复用 npx 缓存；更新的 Skarn 需要更新的链接。

任何客户端的手动配置：

{
  "mcpServers": {
    "skarn": {
      "command": "skarn",
      "args": ["mcp"]
    }
  }
}

它在你机器上运行，不发起网络调用，并暴露四个只读工具：scan_sessions（过去会话的发现，所有预览值均已脱敏）、vet_configs（关于你的助手配置面的掩码报告）、list_sessions 和 session_stats（元数据和聚合数据，绝不包含消息内容）。没有写入工具，也没有返回消息内容的工具。

两个内容工具 search_sessions 和 get_session 仅在你以 skarn mcp --enable-recall 启动服务器时出现。两者都会遮蔽返回内容，且内容仍会离开你的机器发送给服务该会话的模型提供商，因此上面的声明不会设置该标志。search_sessions 会拒绝既不指定 hours 也不指定 project 的调用；get_session 接受一个精确的 session_id，这本身就是其作用域。

如果你不想自己安装二进制文件，固定版本的 npx 形式也可以：

{
  "mcpServers": {
    "skarn": {
      "command": "npx",
      "args": ["-y", "@skarn-security/skarn@0.26.0", "mcp"]
    }
  }
}

npx 会在服务器首次启动时下载包并在之后缓存，因此首次启动更慢且需要网络访问。请固定版本。未固定形式会解析为注册表在启动时提供的任何内容，skarn vet 会将其报告为 vet-mcp-unpinned。不要使用它。

本仓库根目录的 llms-install.md 是以代理可读步骤呈现的相同安装说明，适用于为你接线服务器的客户端。

每个宿主以各自的方式报告缺少二进制文件。claude mcp list 显示 Failed to connect，并带有 Executable not found in $PATH: "skarn"。gemini mcp list 将 skarn 服务器显示为 Disconnected。codex mcp list 不运行健康检查，因此该行保持列出和启用状态，服务器在会话启动它时失败。Cursor 将插件的行显示为 Error - Show Output，输出面板以 spawn skarn ENOENT 结尾。在任何情况下，在终端中运行 skarn --version：command not found 意味着二进制文件未安装或不在该宿主继承的 PATH 上，这通常是从桌面而非 shell 启动的应用程序的答案。

先审计，再强制

两个守卫插件都以审计模式发布（skarn-recall 没有钩子，因此没有模式）：守卫报告它本会返回的判定，绝不改变你的代理的行为。先以这种方式运行并测量你真实的会阻止率。在你代理继承的环境中设置 SKARN_GUARD_LOG=<path>，守卫会为每次被标记的调用追加一条脱敏的 JSONL 记录（ts、verdict、tool、rule、severity、脱敏原因、session、cwd、latency_ms）；干净的调用不会被记录。

当日志看起来干净时，将钩子命令中的 --guard-mode audit 切换为 --guard-mode enforce，或运行 skarn setup --update --mode enforce。强制模式需要 Skarn 许可证；没有许可证时守卫保持审计模式并报告而非阻止，因此过期的许可证永远不会破坏你的编辑器。

随着 Skarn 发布扩展宿主的钩子事件集，保持钩子最新是下面的插件更新，而不是 Skarn 命令：这些插件携带自己的钩子文件，skarn setup --update 只刷新 skarn setup 本身写入的 Skarn 拥有的条目，在其写入的作用域内（默认按用户，或在 --scope project 下为仓库配置）。对于以另一种方式接线的配置，--update 将这些条目重写为已安装二进制文件写入的任何内容，整体替换每个条目，但你自己调整的钩子调用超时（timeout，或 Copilot 上的 timeoutSec）除外——当它与替换项明确配对且值合理时会被保留，因此每台机器的预算能在刷新中存活；你添加到此类条目的任何其他字段都会被丢弃。在终端运行 skarn guard report 和 skarn assess 会指出已落后的 setup 接线的按用户钩子，每次发布一次，并给出该宿主的精确更新命令。

更新

Claude Code：

claude plugin marketplace update skarn
claude plugin update skarn-guard@skarn

Codex CLI（它没有更新动词；重新添加会安装新版本）：

codex plugin marketplace upgrade
codex plugin add skarn-guard-codex@skarn

插件更新和二进制更新是独立的：钩子命令调用 PATH 上的 skarn guard，因此仅 brew upgrade skarn 就能给你更新的检测引擎。当插件本身携带的任何内容发生变化时，插件更新才重要：钩子形态（新事件、新标志、新匹配器）、技能文本或清单元数据。

安全性

守卫只会收紧决策，绝不会放宽。守卫本身失败时会发生什么取决于宿主，因为每个宿主决定钩子崩溃、超时或格式错误输出意味着什么。

Claude Code、Codex CLI 和 Gemini CLI 失败开放：格式错误的事件、超出范围的工具或任何守卫错误都会产生允许，守卫永远不会让你的代理瘫痪。这些宿主上唯一的失败关闭路径是带有许可强制模式的 --strict，每个宿主的 README 都有文档说明。

Antigravity CLI 对除明确允许外的每个钩子结果都失败关闭：崩溃、超时、无效 JSON 和空的 {} 都会阻止匹配的调用，在审计模式和强制模式下都是如此，而且接线的钩子在没有 skarn 二进制文件在 PATH 上时会阻止每个匹配的调用。守卫对收到的每个事件都给出明确决策，且随附的匹配器只命名其作用域内的工具，这样匹配器之外的步骤永远不会被守卫失败阻止。在接线该钩子之前安装 skarn，在卸载 skarn 之前移除该条目。文档：https://getskarn.com/?utm_source=agent-guard-readme&utm_medium=referral&utm_campaign=home&utm_content=documentation

许可证、隐私和支持

本仓库采用 MIT 许可证；见 LICENSE。它只携带配置，因此这涵盖其中的插件清单、钩子、技能和 MCP 服务器声明。

这些文件调用的 skarn 二进制文件是单独下载的，并非开源。它根据 Skarn 最终用户许可协议（https://getskarn.com/terms/）授权，运行即表示接受该协议。它读取什么、保留什么、以及从不向任何地方发送什么：https://getskarn.com/privacy/。

支持：hello@getskarn.com。漏洞报告请发送至 security@getskarn.com；请参阅本仓库中的 SECURITY.md。