全仓库一键安全体检:gemini-cli-security的/security:analyze-full命令实战指南
全仓库一键安全体检:gemini-cli-security的/security:analyze-full命令实战指南
gemini-cli-security 是 Google 官方开源的 Gemini CLI 安全扩展,安装后只需输入一条 /security:analyze-full 命令,就能对整个代码仓库做一次自动化安全体检:从硬编码密钥、SQL 注入、XSS 到隐私数据泄露,自动扫描、自动定级、自动生成带行号定位的专业安全报告。对于不想部署重型 SAST 工具、又希望快速摸清仓库安全底数的新手和中小团队来说,它几乎是最低门槛的选择。🩺
它和 /security:analyze 有什么区别?
这个扩展提供了一组 /security: 开头的命令,其中最常用的三个如下:
| 命令 | 扫描范围 | 适用场景 |
|---|---|---|
/security:analyze |
当前分支相对主干的代码改动(基于 git diff) | 提交 PR 前的增量检查 |
/security:analyze-full |
整个仓库的全部文件 | 接手新项目、定期安全体检 |
/security:scan-deps |
第三方依赖 | 排查依赖库已知漏洞(集成 OSV-Scanner) |
/security:analyze-full 的价值在于:很多老项目里"祖传代码"的漏洞永远不会出现在新的 diff 里,只有全仓库扫描才能把它们翻出来。
快速上手:三步完成安装与首次全仓扫描
前置条件:已安装 Node.js 与 Gemini CLI(v0.4.0 或更新版本)。
第 1 步:安装扩展
gemini extensions install <本仓库地址>
第 2 步:进入你的项目目录,启动 Gemini CLI
cd /path/to/your-project
gemini
第 3 步:输入命令,开始体检
/security:analyze-full
命令提交后无需任何额外操作,扩展会自动规划任务、逐文件分析,并在终端输出一份结构化的安全报告。
执行后发生了什么:四阶段全自动审计流程
/security:analyze-full 背后是一套完整的"侦察 → 深挖"流水线,其提示词定义在 commands/security/analyze-full.toml 中,大致分为四个阶段:
Phase 0|初始化
在工作区创建 .gemini_security/ 目录,生成任务清单 SECURITY_ANALYSIS_TODO.md 和草稿报告 DRAFT_SECURITY_REPORT.md,作为整个扫描过程的"工作底稿"。
Phase 1|确定扫描范围
扩展会调用 MCP 工具 get_files_to_audit 获取仓库中所有值得审计的文件(自动过滤文档、测试等无关文件,实现见 mcp-server/src/filesystem.ts),并用 get_line_count 统计总代码行数,然后向你汇报将要分析哪些文件。
Phase 2|两遍扫描循环(核心)
- 侦察遍(Recon):快速通读每个文件,只负责"插旗"——发现可疑的用户输入来源(Source)时,立即在任务清单里追加一条
Investigate data flow from [变量名] on line [行号]子任务; - 调查遍(Investigate):逐个追踪这些变量在代码中的流向,直到找到它被执行、渲染或存储的位置(Sink)。如果中间没有消毒、校验或转义,就确认一个漏洞,并写入草稿报告。
这种"先广后深"的两遍模型保证了不漏扫、不浅尝辄止。
Phase 3|终审
扩展会调用 find_line_numbers 工具为每条发现精确定位行号,并对照内置的"五问检查清单"逐条复核,过滤掉推测性、无实际影响的误报,保证"报出来的每一条都值当修"。
Phase 4|报告与清理 输出最终报告,然后删除临时任务文件(保留你请求的 JSON 报告),工作区干干净净。
它能查出哪些"问题"?
扩展内置了一份相当全面的漏洞知识库(GEMINI.md),覆盖以下六大类:
| 类别 | 典型问题 |
|---|---|
| 🔑 密钥管理 | 硬编码 API Key、密码、私钥、数据库连接串 |
| 💉 注入类 | SQL 注入、XSS、命令注入、SSRF、服务端模板注入(SSTI) |
| 🗄️ 不安全数据处理 | 弱加密算法(DES/RC4/MD5)、日志打印敏感信息、不安全反序列化 |
| 🔐 认证 | 会话 Token 可预测、密码重置流程不安全、认证绕过 |
| 🕵️ 隐私违规 | PII(邮箱、手机号等)未脱敏写入日志、直发第三方 API |
| 🤖 LLM 安全 | 提示词注入、LLM 输出被 eval() 直接执行等 |
每条发现都会标注严重程度(Critical / High / Medium / Low,评级标准见 GEMINI.md)、文件路径、行号、漏洞代码行、影响说明和修复建议——拿来就能修。
实战技巧:自定义范围与 JSON 报告
用自然语言缩小范围:全仓扫描前,你可以直接在命令后追加说明。比如只想扫 scripts 目录:
/security:analyze-full Analyze all the source code under the scripts folder. Skip docs and config files.
导出 JSON 报告:加上 --json 标志(或用自然语言说"以 JSON 格式返回报告"),扩展会把报告转换保存为 .gemini_security/security_report.json(实现见 mcp-server/src/index.ts),方便接入 CI 或安全平台做二次分析。
建立误报白名单:如果你认为某条发现是误报并说明理由,扩展会把它记录到 .gemini_security/vuln_allowlist.txt,之后每次扫描都会自动跳过,避免反复提醒同一个"没问题"的点。
大仓库注意:超过 2 万行会触发二次确认
出于成本与效率考虑,当待分析文件总行数超过 20000 行时,扩展会暂停并询问你是否继续(见 commands/security/analyze-full.toml)。如果项目确实很大,建议两种做法:
- 用自然语言参数把范围限定在核心业务代码目录;
- 日常开发用
/security:analyze只扫增量,定期(比如每月)再跑一次/security:analyze-full做全面体检。
报告有多靠谱?
官方用 OpenSSF CVE 基准数据集(真实历史漏洞仓库)做了评测:精确率 90%、召回率 93%(README.md),在同类 AI 扫描工具中属于第一梯队。
当然也要理性看待:扩展自己也强调,这是"第一遍分析"而非完整安全审计,建议与其他工具(如 /security:scan-deps 依赖扫描)和人工 Review 配合使用。
延伸阅读
- 完整功能与基准测试:README.md
- 命令定义:commands/security/analyze-full.toml
- MCP 服务器工具实现:mcp-server/src/index.ts
- 漏洞修复技能(扫描后的下一步):skills/security-patcher/SKILL.md
- 版本更新记录:CHANGELOG.md(当前版本 0.5.0,已支持 JSON 报告输出与 PoC 验证)
一条命令、零配置,把整个仓库交给 /security:analyze-full 扫一遍——这就是 AI 时代做安全基线检查的最快姿势。✅

