raj200501/ai-studio-shipcheck

# AI Studio ShipCheck 适用于 Gemini / AI Studio 应用的起飞前（Preflight）验证工具，用于在分享或部署前进行检查。 ShipCheck 会扫描代码仓库或 AI Studio 风格的 ZIP 导出文件，并生成一份 `SHIP`、`CAUTION` 或 `NO_SHIP` 报告，其中包含文件/行号证据、主要风险以及建议的修复方案。 ``` shipcheck demo ``` ``` Target: examples/ai-studio-export-bad.zip Status: NO_SHIP Score: 0 / 100 Findings: 4 high, 7 medium, 1 low Top risks 1. Gemini API key is exposed in browser code. 2. Destructive tool can execute without approval. 3. App claims verified answers without grounding evidence. ``` ## 概念验证 | 信号 | 签入的证据 | | --- | --- | | 静态检查 | 包含 12 条确定性规则，涵盖 secrets、Gemini 集成、tools、grounding、结构化输出、测试、traces、声明以及 prompt 边界。 | | 固定测试数据 (Fixtures) | 包含错误/修复后的支持应用、错误/修复后的 AI Studio 风格导出文件、4 个 ZIP fixtures 以及 8 个对抗性测试用例。 | | 报告产物 | 位于 `reports/` 目录下的 HTML、Markdown 和 JSON 报告，以及位于 `schemas/` 目录下的 JSON schema。 | | 测试覆盖面 | 收集了 40 个 pytest 测试用例，并在 Python 3.10、3.11 和 3.12 上运行 CI。 | | 离线运行 | `shipcheck demo` 可在没有 Gemini API key 的情况下执行扫描和报告生成。 | ## 检查内容 ShipCheck 侧重于在本地源码、文档、fixtures 和 ZIP 导出文件中可见的就绪状态信号。 | 规则 | 检查项 | 严重程度 | | --- | --- | --- | | SC001 | 客户端 Gemini API key 泄露 | 高 | | SC002 | 浏览器直接调用 Gemini API | 中 | | SC003 | 缺少环境变量模板 | 中 | | SC004 | 具有破坏性的 tool 缺少审批边界 | 高 | | SC005 | 权限过大的数据访问 tool | 中 | | SC006 | 不支持的 grounding / 验证声明 | 高 | | SC007 | 脆弱的结构化输出解析 | 中 | | SC008 | Gemini API 调用缺少错误处理 | 中 | | SC009 | 没有针对主要 AI 工作流的冒烟测试 | 中 | | SC010 | Agentic flow 缺少 trace/日志产物 | 中 | | SC011 | README 或 UI 过度夸大功能 | 低 | | SC012 | 针对外部内容缺少 prompt injection 边界 | 高 | 每项发现都包含规则 ID、严重程度、可用时的路径和行号、证据片段、与 Gemini 相关的说明以及建议的修复方案。 ## 产生背景 AI Studio 和 Gemini 让从创意到应用的转变变得非常迅速。这种速度在分享之前增加了一个实际的审查步骤：检查是否存在暴露的 key、危险的 tool 流程、不受支持的声明、脆弱的模型输出解析、缺失的 traces 以及缺失的冒烟测试。 ShipCheck 是有意设计为本地和静态的。它的目的是让接下来的几项修复工作变得显而易见，而不是充当托管的 dashboard 或一种保证。 ## 小型 Gemini 构建者信任循环的一部分 - **ShipCheck** 会问：“我现在应该分享或部署这个 Gemini 应用了吗？” - **Flight Recorder** 会问：“这次 Gemini 运行为什么失败，我能把它变成一个回归测试吗？” - **Interactions Doctor** 会问：“这个 Gemini 应用测试框架是否正确接入了状态、tools、测试、traces 和迭代？” 这些工具是独立的本地实用程序，但关注的问题是相关的。这不是一家公司、一个平台，也不宣称与 Google 有官方关联。 ## 可信度与局限性 ShipCheck 仅检查公开/本地产物：仓库文件、导出的 ZIP 文件、文档、示例、测试、schema 和报告 fixtures。它不会调用 Gemini、检查已部署的基础设施、执行不受信任的应用代码、读取 AI Studio 的私有内部数据，也不会验证事实质量。 当故意记录危险示例时、当审批或 grounding 是通过共享 helper 实现时，或者当服务端代码被放置在类似前端的文件夹中时，可能会出现误报。当 Gemini 调用、审批检查或证据路径隐藏在封装器、生成代码、远程配置或运行时行为之后时，可能会出现漏报。 请将输出结果作为分享或部署前的一项重点关注检查清单。它不能替代安全审查、产品审查、evals、observability 或特定所有权相关的发布标准。 ## 安装 ``` git clone https://github.com/raj200501/ai-studio-shipcheck.git cd ai-studio-shipcheck python -m venv .venv source .venv/bin/activate python -m pip install -e ".[dev]" ``` Demo 和测试不需要 Gemini API key。如果存在 `GEMINI_API_KEY`，`shipcheck doctor` 会报告其存在，但不会将其打印出来。 ## 用法 ``` shipcheck scan ./examples/bad-support-agent shipcheck scan ./examples/bad-support-agent --out ./reports/bad --html shipcheck scan ./examples/ai-studio-export-bad.zip --out ./reports/zip-bad --html shipcheck scan ./examples/bad-support-agent --format json shipcheck scan ./examples/bad-support-agent --format markdown shipcheck scan ./examples/bad-support-agent --strict shipcheck rules shipcheck doctor shipcheck version ``` `--out` 会写入 `report.html`、`report.md` 和 `report.json`。正常的扫描在工具成功运行时会返回退出状态码 `0`，即使存在检查结果也是如此。在 CI 中使用 `--strict`，以便在出现 `NO_SHIP` 时以非零状态码退出。 ZIP 扫描是一等公民行为。ShipCheck 会将 ZIP 输入文件安全地解压到临时目录中，拒绝路径遍历条目，扫描解压后的内容，并在报告中保留原始 ZIP 路径。 ## 开发 ``` make verify make test make demo make reports ``` CI 会在 Python 3.10、3.11 和 3.12 上安装该包，然后运行 `make verify`。 ## 文档 - [报告 schema](docs/spec.md) - [失败模式](docs/failure_modes.md) - [评估说明](docs/evaluation.md) - [套件定位](docs/suite.md) - [schemas/](schemas/) 目录下的机器可读 schema ## 免责声明 ShipCheck 是一个独立的本地开发者工具。它不隶属于 Google，也不受 Google 认可或赞助。它不保证安全性、正确性、事实性、合规性、策略一致性或部署就绪状态。

标签：DLL 劫持, 云安全监控, 代码审查, 大语言模型, 安全规则引擎, 文档结构分析, 逆向工具, 静态分析