shellward

用途

ShellWard 是「为中国监管而生的 AI Agent 安全合规工具 / AI 应用合规网关」，目标是在 AI 应用的两个阶段提供支持：一是项目层面的合规风险体检，二是运行时的安全防护。按官方说明，它面向网安法、PIPL、等保2.0、数据出境与 AI 标识（GB45438）等监管语境，中文优先、零依赖、开源。

主要能力

合规扫描（scan）

官方描述为：零安装、只读、不上传任何数据，一行命令（npx shellward scan）扫出 AI 项目的合规红线，输出一张映射到网安法 / PIPL / 等保2.0 / 数据出境 / AI 标识的红黄绿评分卡，并精确到文件:行。检测重点包括：境外大模型端点与 SDK 依赖（数据出境）、硬编码密钥、文件中的中文 PII、.env 暴露。扫到境外模型时会给出境内合规替代（通义千问 / DeepSeek / Kimi / 智谱）及其 OpenAI 兼容 base_url；官方提示 base_url 为各厂商公开的 OpenAI 兼容端点，可能随官方调整，迁移前以官方文档为准。境外识别覆盖 OpenAI / Anthropic / Gemini / Azure / Bedrock / Cohere / Mistral / Groq / Together / Perplexity / OpenRouter / HuggingFace / xAI / Replicate / AI21 / Fireworks / DeepInfra / Cerebras / Voyage / NVIDIA NIM 的端点，以及 npm / pip / Go 的 SDK 依赖（含 LangChain、LlamaIndex、Vercel AI SDK 适配包）。

Agent 合规审计（Skill）

官方指出 scan 是确定性扫描：能报告「项目里有境外模型端点」，但判断不了个人信息是否真的流过去，14 个法规控制项中有 11 个只能标「需人工确认」。这部分可交给支持 Agent Skills 的编码 agent（Claude Code、Cursor、Codex 等），安装命令为 npx skills add jnMetaCode/shellward --skill china-ai-compliance-audit。它会先跑 shellward scan 拿确定性基线，再顺着数据流逐项取证，最后产出 .compliance/COMPLIANCE-REPORT.md。官方说明其与「让 AI 随便看看合不合规」的区别在于三道闸：

证据闸：每条发现需要 file:line 加逐字引用，并由零依赖校验器打开文件核对引用确实存在；编造的引用会导致运行失败。
验证闸：每个「缺口」和每个「已发现的措施」都交给未见过审计推理过程的新 agent 去反驳，被推翻的发现会保留记录而非删除。
诚实闸：仓库里没有的事实（备案、影响评估、实际日志留存）不能猜测，agent 必须提出一个具体、可由人回答的问题，且不附带严重程度。官方还说明：14 个控制项必须全部有结论，不许悄悄跳过；报告本身不得包含完整密钥、手机号、身份证号。

运行时防护（8 层防御）

官方列出 8 个防御层：prompt guard、input auditor、tool blocker、output scanner、security gate、outbound guard、data flow guard、session guard，默认零配置全部启用。具体机制包括：

DLP 模型：数据完整返回（不脱敏），最近访问过 PII 时拦截外发发送。
PII 检测：SSN、信用卡、API 密钥（OpenAI/GitHub/AWS）、JWT、密码，加上中文身份证（GB 11643 校验位）、运营商校验手机号、银联银行卡（Luhn）。
注入规则：官方中英文文档给出的数量不一致（中文称 18 条中文 + 14 条英文；英文称 37 条注入规则：20 条中文 + 17 条英文），均支持风险评分与中英混合检测。
MCP 工具投毒扫描：检测工具描述/参数中的隐藏指令、不可见字符、「对用户隐瞒」类隐蔽指令、敏感文件访问与外泄提示。
MCP rug-pull 检测：首次见到工具时记录描述指纹，后续被偷改即告警。
数据外泄链：读敏感数据后接 send_email / HTTP POST / curl 外发即拦截。
Bash 绕过检测：捕获 curl -X POST、wget --post、nc、Python/Node 网络外泄。官方给出 7 个真实场景示例：服务器毁灭拦截、反弹 Shell、注入检测、DLP 审计、数据外泄链、凭证窃取、APT 攻击链。

使用方式

浏览器查看与 Web 模式

npx shellward scan --open：扫完直接打开报告；--serve：本地 http://localhost 提供报告，官方称数据全程不出本机。
shellward web：公开仓库 web 扫描器，可在网页贴公开仓库 URL 或用 /scan?repo=URL 链接体检（可部署，见 Dockerfile）。
shellward web --local：本地 web GUI，填本地路径扫描，私有代码不上传、不出本机。

CI 与策略即代码

--json 供 CI；--ci 发现 critical 时让构建失败；--html report.html 导出可打印成 PDF 的报告（备案/审计存档）；也可作为 GitHub Action 接入 PR 门禁。
.shellward.json 声明式门禁：failOn（匹配 secret / pii / overseas / env-perm 类或 critical / high / medium 级别时失败）、maxFindings、allowOverseas；支持按路径规则（path、failOn / maxFindings、allowOverseas；allowOverseas 省略则继承全局，设为空数组可覆盖）。官方称未知字段、拼错的 failOn 值、损坏的 JSON 会在 CI 中打印为 ⚠️ 警告而非被静默忽略。不带该文件时默认「任何 critical 即失败」。

MCP 服务器与 SDK 接入

ShellWard 可作为独立 MCP 服务器通过 stdio 运行，零依赖，无需 @modelcontextprotocol/sdk。在 MCP 配置（claude_desktop_config.json、.cursor/mcp.json、OpenClaw 等）中加入配置即可，无需安装路径，npx 会拉取已发布的 shellward-mcp bin；若已全局安装（npm i -g shellward），直接用 "command": "shellward-mcp"。官方称提供 8 个 MCP 工具：命令检查、注入检测、敏感数据扫描、路径保护、工具策略、响应审计、MCP 工具投毒/rug-pull 扫描、安全状态。也支持作为 SDK（任意 AI agent 平台）与 OpenClaw 插件使用，并支持通过 SDK 自定义规则（字段为增量式，allowedTools 始终优先；无效正则会被跳过而不抛错）。

漏洞库

官方称内置 17 条 CVE / GitHub Security Advisories，/check-updates 检查当前版本是否受影响，例如 CVE-2025-59536（CVSS 8.7，恶意仓库在信任提示前通过 Hooks/MCP 执行命令）、CVE-2026-21852（CVSS 5.3，通过 settings.json 窃取 API 密钥）、GHSA-ff64-7w26-62rf（持久化配置注入、沙箱逃逸），另有 14 条已确认漏洞。远程漏洞库每 24 小时同步，离线时回退本地库。

适用场景

官方描述适用于需要对 AI 智能体做运行时安全的团队：构建自主编码助手、带工具访问的面向客户聊天机器人，或由 LLM 驱动的内部自动化；常见用例包括 MCP 安全强制执行、工具调用拦截与过滤、为任何 LLM 工作流加入 agent 护栏。团队若要对多个 AI 项目做合规自查或接入内部流程，可通过 jnMetaCode@qq.com 联系（需说明团队规模和场景）。

限制与注意事项

官方明确：这是技术自查材料，不是法律意见；备案、定级、PIA 等主体责任不能由工具代替。
scan 是确定性扫描，无法判断个人信息是否真的流向境外，14 个法规控制项中 11 个只能标「需人工确认」。
检测基准方面，官方称 npm run bench 在标注语料上测量各检测器的 precision/recall/F1，CI 对回归失败；扫描器自带 41 个标注用例（24 个真实风险 + 17 个硬负例）的门禁语料。官方称当前 83 个门禁样本，并以设计上保守为原则（enforce 模式下 fail safe，例如 echo "rm -rf /" 也会被标出），并明确列出 5 种不预期被正则/启发式捕获的绕过（leetspeak、base64、非中英语言、shell 变量间接引用），将其排除在门禁之外而非隐藏。官方强调：数字基于当前仓库内语料，是下限而非通用保证。
官方说明 MCP 相关配置、命令与 .shellward.json 字段行为以其文档为准；其他未在资料中出现的信息（如具体收费、平台支持范围等）暂未提供。

工具介绍

用途