AI Agent 接入 MCP 前怎么做安全体检：用 AgentShield 离线扫描工具、配置与风险链路
AI Agent 的风险并不只在模型回答。一个能调用 shell、文件系统、HTTP 服务或浏览器的 Agent，实际继承了工具实现、MCP 配置、依赖版本和提示词里的执行边界。很多团队会在上线后才加密钥扫描或审计日志，但这时危险的工具描述、可控 URL、未固定依赖可能已经进入了 Agent 的可调用面。
AgentShield 是一个面向 Agent 工具和 MCP 生态的本地 Rust 安全扫描器。它的定位不是取代通用 SAST、密钥扫描或依赖分析，而是在这些通用检查之外，理解「提示词—工具定义—参数—执行点」这条 Agent 特有路径。项目当前 README 标示为 1.0.1 GA，并声明采用 MIT OR Apache-2.0 双许可证。
这篇文章聚焦一个实用场景：在把一个 MCP server 或自定义 Agent 工具加入 Claude Code、Cursor 或内部工作流之前，如何先在本地完成一轮可复现的安全体检，并把结果接进 CI。
为什么普通扫描还不够
传统扫描擅长发现代码中的已知漏洞、硬编码密钥或过期依赖；但 Agent 工具还会把自然语言约束、JSON Schema、工具返回内容和执行权限拼在一起。比如一个“下载文档”的工具如果将用户传入的 URL 直接交给 HTTP 客户端，就不仅是普通的请求逻辑，也可能成为 SSRF 入口；一个“运行诊断”的工具如果把参数拼接进 shell 命令，就会把提示注入的结果带到命令执行点。
AgentShield 的 README 列出的关注面包括命令注入、凭据外泄、SSRF、不安全文件访问、运行时安装包、提示注入表面和依赖卫生。它会把 MCP、OpenClaw、Hermes Agent、CrewAI、LangChain/LangGraph、GPT Actions 与 Cursor Rules 等七类框架或客户端配置归一到同一中间表示再分析。这里的价值在于：审查对象不只是 .py 或 .ts 源码，也包括 Agent 能够发现并调用的工具边界。
不过要保持边界感。项目文档明确把 AgentShield 视为 CodeQL、Gitleaks、Semgrep 等工具的补充：前者更侧重 Agent/MCP 工具面、提示词与出站访问，而不是替代全面的漏洞、密钥和供应链治理。
从本地扫描开始，而不是先授予权限
官方 README 提供安装脚本、Homebrew、Cargo 与预构建二进制等方式。团队若希望锁定 README 标示的发布线，可用带 tag 的 Cargo 安装；下面的命令会安装完整 feature 集并执行首次配置与扫描：
cargo install --git https://github.com/aiconnai/agentshield \ --tag v1.0.1 --features full --force agentshield quickstart agentshield scan . --ignore-tests --fail-on high --explain
quickstart 用于创建配置并解释首轮扫描；第二条命令扫描当前仓库，将高危及以上发现作为失败条件。这里有两个容易被忽略的取舍。
第一，--ignore-tests 适合避免测试夹具干扰首轮结果，但不能把它当作永久豁免：如果测试目录里保存了真实工具配置或示例密钥，仍应单独检查。第二，--fail-on high 是发布门槛，不是风险归零承诺。中低危问题可以先记录、解释和排期，但针对能执行命令、读取凭据或访问内网的工具，应该先弄清参数是否可控、实际权限是什么、是否有替代实现。
扫描结果可输出到控制台、JSON、SARIF 或独立 HTML 报告。对 CI 和代码审查而言，SARIF 很实用，因为 GitHub Code Scanning 可以把发现定位到提交或拉取请求：
agentshield scan ./mcp-server \ --format sarif --output agentshield.sarif \ --fail-on high
不要把生成的报告本身当成“已修复”的证据。更可靠的闭环是：针对每条高危发现，定位工具调用的输入来源、确认执行 sink 是否真可达、修复后重新运行同一命令，并保留报告作为这次变更的审计附件。
用规则与修复把检查变成可维护的流程
Agent 工具往往有组织特有的危险模式，例如不允许工具读取某个密钥目录，或不允许访问未批准的域名。AgentShield 支持从 .agentshield/rules 目录加载 YAML 声明式自定义规则：
agentshield scan . --rules-dir .agentshield/rules agentshield list-rules
先用 list-rules 查看实际启用的内置和自定义规则，再写团队规则，能避免“以为规则被加载、实际路径写错”的误判。项目 README 写明内置有 25 条上下文规则；自定义规则不该无差别复制现有规范，而应只覆盖团队确实需要阻断的能力组合，例如生产环境的 shell 执行或未经代理的出站请求。
对于可自动处理的问题，先预览再落盘是更稳妥的方式：
agentshield fix . --dry-run agentshield fix .
--dry-run 的意义是把自动修复从黑盒动作变成可审阅 diff。尤其是安全工具修改依赖固定方式或反序列化调用时，开发者仍要运行测试，确认修复没有改变工具的协议、认证或错误处理语义。
CI 不该从“全绿”开始
已有项目可能存在历史问题，直接启用阻断式扫描会让团队在第一天面对大量旧债。官方文档提供 baseline 工作流：先写出当前发现快照，再让 CI 对新增问题保持敏感。
agentshield scan --write-baseline .agentshield-baseline.json agentshield ci install --baseline .agentshield-baseline.json
这不是接受旧风险，而是把迁移拆成两条线：一条逐步消化 baseline，另一条不让新的工具代码、MCP 配置或依赖回退进入主分支。若项目希望同时引入更广泛的检查套件，README 还提供 agentshield ci install --suite，用于生成包含 CodeQL、Gitleaks、Semgrep CE 与 AgentShield 的起始工作流。生成后仍要审阅工作流权限和触发分支，特别是 SARIF 上传所需的 security-events: write 权限不应被随意扩大。
静态扫描之后：别把运行时守护当成默认安全网
AgentShield 还描述了实验性的 runtime guard，可作为 MCP stdio 与 HTTP/SSE 流的反向代理来检查工具调用、遮盖泄露的秘密。README 中给出的形式如下：
agentshield guard \ --listen 127.0.0.1:8080 \ --target http://127.0.0.1:3000
这类守护层适合在高权限工具前增加一层观察和策略执行，但它不是静态扫描的替代品，也不应在未验证协议兼容性时直接代理生产流量。项目 README 将 runtime guard 的范围与路线图另列在文档中，说明它仍需要按当前版本能力评估。实践上可以先在隔离环境验证：工具发现是否正常、流式响应是否被保持、错误码是否可观测、密钥脱敏是否影响下游调试；通过后再决定是否接入生产。
扫描范围需要和权限模型一起读
扫描命令只能告诉你某段配置或实现触发了哪些规则，不能替你决定这个工具是否应被授予权限。因此在处理每一项结果时，建议同时记录三件事：该工具实际可访问的目录或网络范围、调用者能否影响参数、以及失败时是否会把响应内容回填给模型。相同的 curl、文件读取或子进程调用，在只读临时目录和可访问生产凭据的宿主机上，风险级别完全不同。
这也是把扫描放在接入前而非事故后执行的原因。先在最小权限环境中验证工具配置，再逐步增加所需能力，能让规则命中的解释与真实部署边界对齐。若某个例外确有业务必要，应把理由、限制条件和复查日期写进变更记录；不要只靠一条忽略规则让发现从报告中消失。
一个可执行的接入清单
把新的 MCP 工具加入编码 Agent 前，可以按下面的顺序执行：
- 在隔离仓库或工作目录运行
agentshield scan，不要一开始就给工具生产密钥和广泛文件权限。 - 对高危发现逐条追踪输入、权限和执行点；修复后使用相同参数复扫，而不是只看一次控制台输出。
- 用 SARIF 或 HTML 报告把结果带进审查流程；需要自动修复时，先执行
fix --dry-run并审阅 diff。 - 将组织特有的限制写成版本控制下的 YAML 规则，并用
list-rules确认它们确实生效。 - 对存量仓库先建立 baseline，同时让 CI 阻断新增风险；再分批清理基线中的历史问题。
- 只有在协议和运维行为经过测试后，才评估 runtime guard；它是纵深防御的一层，不是授权过宽的补救措施。
Agent 的工具能力越接近真实系统，安全检查越应该靠近代码、配置和合并请求。离线扫描不能证明工具绝对安全，却能把“上线后才发现 Agent 能做什么”的问题，前移成开发者可以复现、审阅和持续执行的工程流程。