SGAI

# SGAI — SecureGuardAI > 一个多代理安全审查工具，用于审计代码库中的漏洞依赖和不安全代码模式，对其进行风险评估，解释并提出修复建议 - 同时记录自上次扫描以来发生的变化。 **Kaggle AI Agents: Intensive Vibe Coding Capstone — Track: Freestyle** [](https://sgai-n2ov.onrender.com) [](https://github.com/ankitranjan-dsai/SGAI/actions/workflows/ci.yml) [](https://github.com/ankitranjan-dsai/SGAI/releases) [](https://github.com/ankitranjan-dsai/SGAI/pkgs/container/sgai) [](pyproject.toml) [](LICENSE) | | | |---|---| | **Live demo** | **[sgai-n2ov.onrender.com](https://sgai-n2ov.onrender.com)** — 粘贴一个公开的 GitHub URL 并扫描它。无需注册，无需 API 密钥。免费层在空闲时休眠，因此第一次加载可能需要 ~50 秒。 | | **Demo video** | [在 YouTube 上观看](https://youtu.be/deRzztaJo9E) | | **Kaggle writeup** | [在 Kaggle 上阅读](https://kaggle.com/competitions/vibecoding-agents-capstone-project/writeups/new-writeup-1782074784033) | | **Judging checklist** | [Kaggle Judging Checklist](#kaggle-judging-checklist) 下方 | --- ## 快速评判运行（5 分钟内，无需 API 密钥） ```bash git clone https://github.com/ankitranjan-dsai/SGAI.git && cd SGAI uv sync # ~10s, 通过 uv 安装所有内容 uv run pytest -q # 完整的测试套件，所有测试均通过 uv run sgai scan ./examples/kaggle_demo_repo # 确定性扫描 — ~20+ 发现，无密钥 uv run sgai scan ./examples/kaggle_demo_repo --deep # + Semgrep 多语言 SAST uv run sgai history ./examples/kaggle_demo_repo # 扫描时间线（会话和内存） uv run sgai check ./examples/kaggle_demo_repo # 代码策略 CI 门控（违反时退出 1） ./run.sh # 网页应用，地址为 http://localhost:8080 ``` 上述每个命令均**无需 Google API 密钥** - 确定性核心（OSV.dev + Bandit/Semgrep）从不调用 LLM。免费的 Gemini 密钥仅解锁 `--explain`（有声报告）和 `--agentic`（完全自主的工具调用）。请参阅 [docs/demo.md](docs/demo.md) 了解完整的演练和 [docs/kaggle_submission.md](docs/kaggle_submission.md) 了解提交清单。 --- ## 问题 AI 编码助手现在编写大量代码，速度很快。其中几乎没有一个在交付前经过**安全**检查：一个固定的依赖项带有已知的 CVE，一个 `subprocess(…, shell=True)`，一个 `yaml.load` 在不受信任的输入上。安全审查很慢，专业化且容易跳过 - 因此漏洞会默默地积累， 没有人能回答“自上次以来是变好还是变坏了？” ## 解决方案 SGAI 将一组专门的代理指向任何存储库 - 本地路径或 GitHub URL。他们审计 **PyPI、npm、Go 和 crates.io** （需求、`pyproject.toml`、`poetry.lock`、`uv.lock`、`Pipfile.lock`、`package-lock.json`、`go.mod`、`Cargo.lock`) 跨依赖清单，针对实时 [OSV.dev](https://osv.dev) 数据库运行 **Bandit** 静态分析（Python）和可选的 **Semgrep** 多语言分析（使用 `--deep`），对发现的结果进行去重和风险排序，编写一个修复就绪的报告，并可以预览依赖项修复 - 并可选地为你拥有的存储库打开一个修复 PR。因为它存储每次扫描，因此它还可以告诉你自上次运行以来**新增了什么，修复了什么，仍然存在什么**。 五个功能使其超越扫描器： - **自我修复补丁** (`sgai heal`) - 将 Bandit/Semgrep 发现的结果映射到 AST 安全重构（`yaml.load`→`yaml.safe_load`，`eval`→`ast.literal_eval`，`shell=True`→`shlex.split`，弱哈希→`sha256`，硬编码密钥→环境变量），应用它们，运行项目的测试套件，通过沙盒 `validate_patch` 工具，并**回滚任何导致测试套件失败的补丁**。 - **依赖项可达性** - 静态导入图决定了易受攻击的包是否实际被导入。可达的 CVE 被**升级**为严重性；未使用的 CVE 被**降级**，因此风险评估针对的是可利用的内容。 - **威胁建模和攻击链** - 将单个发现结果关联成端到端的攻击路径（例如路径遍历 + 硬编码密钥 → 凭证泄露），在报告中渲染为 **Mermaid 图**。 - **容器和密钥扫描** - Dockerfile/compose/Terraform 配置错误（未固定的基础镜像、root/特权容器、开放的 CIDR）+ 基于熵的密钥检测，使用 **LLM 传递来排除虚假凭证**。 - **交互式游乐场** - 一个 Web UI 来观察代码被修复的 side-by-side 差异，并**与修复代理通过 SSE 聊天**以完善修复。 它通过三种方式从一个代码库运行：**CLI**，**移动友好型 Web 应用**，和可重用的 **MCP 服务器** 任何代理都可以调用。 > **诚实的范围：** Python-first 静态分析（Bandit）+ 多生态依赖项清单 CVE 扫描 + 可选的 Semgrep 多语言静态分析在 `--deep` 下。 ### 高级套件（v3） 在上述基础上构建 - **零 LLM 检测**（所有检测都是快速的，确定性的本地分析；LLM 仅叙述，分类和支持聊天机器人）和**确定性扫描差异**（`source:id:location` 指纹记录在 JSON `ScanMemory` 中）- SGAI 添加： - **自我修复 v2** - `validate_patch` 自动检测并运行 `pytest`、`npm test`、`go test` 和 `cargo test`，在严格的 30 秒超时内；补丁**置信度评分**排序重写；**二分搜索回滚**隔离最小的破坏性子集，`O(b·log n)` 测试运行。`POST /commit-patch` 在沙盒内写入验证的差异。 - **可达性 v2** - 生产与测试文件的分类，**传递导入闭包**，和多语言导入图（Python，JS/TS，Go，Rust）。仅测试导入被降级；生产导入被升级。每个发现结果都有一个三态 **可达性** （`production` / `test_only` / `unreached`）。 - **CVSS-accurate 依赖严重性** - 每个建议的完整 OSV 记录被检索，其 CVSS 矢量（v4 > v3 > v2）被评分到标准频段（≥9.0 关键，≥7.0 高，≥4.0 中等，否则低），回落到数据库自己的标签，然后在没有信号时仅使用 HIGH。 CVSS 9.8 RCE 和 CVSS 3.1 ReDoS 不再具有相同的排名。 - **Typosquatting 检测器** - 标志依赖名称为一个编辑，一个相邻的换位，一个同形异义词或一个前缀/后缀远离一个流行的包（`requsts`，`lodahs`，`crypt0graphy`，`requests2`）- 供应链风险在任何 CVE 之前被捕获。纯字符串分析，零网络。 - **上下文感知密钥** - LLM 验证器看到丰富的上下文（文件，变量，周围的行/注释）**每个密钥值都被屏蔽**；测试/夹具密钥自动降级为信息；每个发现结果都有一个**轮换紧急度**分数。 - **威胁建模 v2** - 用户 `custom_chains.json` 模板，**推荐的修复顺序**以破坏每个链（编号 `🔧1 → 🔧2` 直接在 Mermaid 图上），**面向互联网**的入口点权重，和原始 Mermaid 交给评估代理。 - **安全副驾驶 UI** - 可点击的发现卡片启动上下文聊天，**提交补丁**按钮重新验证修复，聊天会话每个目标持续存在，以及一个多文件游乐场显示跨文件补丁。 - **代码策略** - `.sgai/policy.yml` 门控（`no-critical-in-production`，`max-unpatched-cves`，...）；`sgai check` 在违规时退出非零以进行 CI。 - **PR 差异扫描** - `git diff` 增量分析仅报告发现结果**新引入**的更改；`POST /scan/pr` 发布内联 GitHub 审查。 - **SBOM & VEX** - `GET /sbom`（CycloneDX/SPDX）和 `GET /vex`（OpenVEX，将可达性映射到 `affected` / `not_affected` / `under_investigation`）。 - **误报驳回** - `POST /dismiss` + `/undismiss`；驳回的发现结果（按指纹或模式）自动在未来扫描中被抑制。 - **趋势仪表盘** - `GET /trends` 和一个 Chart.js **趋势** 标签，绘制发现结果和风险评分随时间的变化，从 `ScanMemory`。 ## 为什么是代理？ 安全审计自然是并行和专门的。没有单个提示可以同时枚举源文件，查询 CVE 数据库，运行静态分析器，推理可利用性并编写补丁。SGAI 将每个作业交给一个专门的代理，并使用编排器协调它们 - 这就是多代理架构*必要*而非装饰的原因。 ## 架构 ``` ┌──────────────────────┐ 目标存储库 ──▶ │ 编排代理 │ └──────────┬───────────┘ │ 协调 ┌────────────┬───────────────┼───────────────┬──────────────┐ ▼ ▼ ▼ ▼ ▼ 扫描代理 依赖审计 静态分析 风险评分 修复 （枚举 （OSV.dev CVE （Bandit/Semgrep） （去重 + （提出 源代码） 查找） 排名） 修复） │ │ │ │ │ └────────────┴───────────────┴───────┬───────┴──────────────┘ ▼ 报告代理 （优先的 Markdown 报告 + 可选的 GitHub PR） ``` 所有安全工具（CVE 查找，静态分析，沙盒文件读取）都通过**自定义 MCP 服务器** 代理调用的工具 - 清洁解耦，独立测试，并可被任何 MCP 兼容的客户端重用。参见 [docs/architecture.md](docs/architecture.md)。 ## 需求课程概念演示 - 全部 6 项 + 会话和内存 | 概念 | SGAI 如何演示它 | |---|---| | **多代理系统（ADK）| 编排 + 6 个专业代理 + 审查管道构建在 Google 的代理开发工具包上 | | **MCP 服务器** | 自定义服务器 (`src/sgai/mcp_server`) 暴露 OSV.dev CVE 查找，Bandit + Semgrep 静态分析，和沙盒文件工具 | | **安全功能** | 沙盒文件访问（路径遍历 + 符号链接安全），每个代理的权限最低工具过滤器，无状态请求，输入验证 - 参见 [docs/security.md](docs/security.md) | | **可部署性** | 无状态 FastAPI + Dockerfile + 公开的公共容器 - 参见 [docs/deploy.md](docs/deploy.md) | | **代理技能 / 代理 CLI** | 打包为 `sgai` CLI 和可重用技能 ([SKILL.md](SKILL.md))；可使用 `uv tool install` 安装 | | **抗重力** | 安全 MCP 服务器插入抗重力（以及任何 MCP 代理）- 参见 [docs/integrations.md](docs/integrations.md) | | **会话和内存** *(课程第 3 天)* | 持久的目标扫描内存 (`src/sgai/memory.py`) 报告 **新增 / 修复 / 仍然打开** 自上次扫描，并记住已接受的风险；也暴露为真正的 ADK `MemoryService` 代理可以通过 `load_memory` 调用 | ## Kaggle 评审清单 评审区域的直接映射到确切的位置。下面的每个命令都在提交准备过程中重新运行。 | 评审区域 | 分数 | 确切证据 | 命令/文件 | |---|---|---|---| | **推介，问题，解决方案，价值** | 30 | 上方问题/解决方案部分；完整的写入 | [SUBMISSION.md](SUBMISSION.md) | | **多代理系统（ADK）| 技术（50）| 真实的 `LlmAgent`/`SequentialAgent`/`ParallelAgent` 图，不是单个提示 | [src/sgai/agents/orchestrator.py](src/sgai/agents/orchestrator.py)，[narrator.py](src/sgai/agents/narrator.py) | | **MCP 服务器** | 技术（50）| 自定义 FastMCP 服务器，9 个工具，沙盒 | [src/sgai/mcp_server/server.py](src/sgai/mcp_server/server.py) - `uv run python -m sgai.mcp_server.server` | | **安全功能** | 技术（50）| 路径沙盒文件访问，每个代理的工具过滤器限制 | [src/sgai/mcp_server/sandbox.py](src/sgai/mcp_server/sandbox.py)，[docs/security.md](docs/security.md)，`uv run pytest tests/test_sandbox.py -q` | | **部署性** | 技术（50）| 无状态 FastAPI + Dockerfile + 公开的公共容器 | `docker pull ghcr.io/ankitranjan-dsai/sgai:latest`，[docs/deploy.md](docs/deploy.md) | | **代理技能 / 代理 CLI** | 技术（50）| `sgai` 控制台脚本 + [SKILL.md](SKILL.md) | `uv tool install . && sgai scan <target>` | | **会话和内存** | 技术（50）| 跨扫描差异 + ADK `MemoryService` 适配器 | [src/sgai/memory.py](src/sgai/memory.py)，`uv run sgai history ./examples/kaggle_demo_repo` | | **工作代码 / 测试** | 技术（50） ## 快速开始 **只需双击 - 无需终端** | 操作系统 | 双击运行 | 或从终端运行 | |---|---|---| | **macOS** | `run.command` | `./run.sh` | | **Windows** | `run.bat` | `./run.ps1` (PowerShell) | | **Linux** | - | `./run.sh` | 上述任意操作均安装所需内容（通过 [`uv`](https://docs.astral.sh/uv/)），启动 SGAI，并在一旦服务器准备就绪后打开 **http://localhost:8080**。 > 首次 macOS 双击：如果您看到“未识别的开发者”，请右键单击 `run.command` → **打开** → **打开**（仅需一次）。在 Windows 上，`run.bat` 帮助您处理 PowerShell 执行策略。 ## 网页演示 SGAI 的网页应用是移动友好的： 1. **相同 Wi-Fi：** 打开 `http://<您计算机的 IP 地址>:8080` 在您的手机上。 2. **已部署：** 在 Cloud Run 上托管它（下方），并在任何地方打开公共 URL。 粘贴一个 `requirements.txt` 和/或一些代码（或点击 **使用示例漏洞输入**），点击 **扫描**，并获得一个排名报告，包含风险摘要，发现 + 修复，以及“自上次扫描以来更改”的差异 - 无需在手机上安装任何内容。 UI 有四个选项卡： 1. **扫描结果** - 排名报告，具有链式 **Mermaid** 图。 2. **代码游乐场** - 粘贴代码并在 **侧边对比差异** 中观察 SGAI 进行修复。 3. **交互式代理聊天** - 通过 **SSE** 与修复代理聊天以完善修复，然后将其应用回游乐场。 4. **趋势** - 一个 Chart.js 视图，显示 `GET /trends` 提供的发现和风险评分。 ### 截图 | 扫描输入 | 扫描结果 | 趋势 | |---|---|---| |  |  |  | 或者自己运行：`./run.sh` 然后打开 `http://localhost:8080`（一分钟，无需 API 密钥）。 ## 演示命令 一个自包含的故意漏洞仓库位于 [`examples/kaggle_demo_repo`](examples/kaggle_demo_repo) - PyPI + npm + Go 依赖项 CVE，Bandit Python 不安全代码，以及不安全的 `server.js` 用于 Semgrep。**无需 API 密钥**。 ```bash uv run sgai scan ./examples/kaggle_demo_repo # 丰富的报告 - 通常 ~20+ 发现（依赖项 + Bandit） uv run sgai scan ./examples/kaggle_demo_repo --deep # Semgrep 添加更多发现时可用 uv run sgai scan ./example/kaggle_demo_repo --sarif out.sarif uv run sgai history ./examples/kaggle_demo_repo # 扫描时间线 ``` ## CLI 使用方法 需要 Python 3.11+ 和 [`uv`](https://docs.astral.sh/uv/)（如果您没有 3.11+ 版本的 Python，`uv` 将自动获取匹配的 Python 版本）。 ```bash uv sync # 创建虚拟环境并安装依赖（包括开发工具） uv run sgai scan ./examples/vulnerable_app # 确定性扫描，无需 API 密钥 uv run sgai scan https://github.com/owner/repo # 通过 URL 审计任何公共仓库 uv run sgai scan ./examples/multi_lang --deep # + Semgrep 多语言静态代码分析 uv run sgai scan ./path --sarif out.sarif # SARIF 2.1.0，用于代码扫描 uv run sgai fix ./examples/vulnerable_app # 预览依赖升级（干预运行） uv run sgai fix . --open-pr # 打开修复 PR（您拥有的仓库） uv run sgai heal ./path --dry-run # 预览 AST 安全代码补丁（差异） uv run sgai heal ./path # 应用补丁，通过仓库测试验证 uv run sgai check ./path # CI 门控：策略违规时退出非零状态 uv run sgai scan ./path --explain # 多代理叙述报告（Gemini） uv run sgai scan ./path --agentic # 完全自主：编排器 + 6 代理管道执行自己的 MCP 工具调用 # （需要 Gemini 配额余量） uv run sgai history ./path # 扫描时间线（随时间变化的新/修复） uv run sgai accept ./path <finding-id> --reason "tracked in JIRA-123" uv run python -m sgai.mcp_server.server # 独立运行安全 MCP 服务器 ``` ### HTTP API（可部署服务） 除了 `GET /health`、`GET /` 和 `POST /scan[/stream]` 之外，服务还暴露了： `POST /commit-patch`、`POST /heal` + `POST /heal/multi`、`POST /chat`（SSE）+ `WS /chat/ws`（双向）+ `GET/POST/DELETE /chat/session`， `POST /scan/check`、`POST /scan/pr`、`POST /fix/plan`， `GET /sbom`、`GET /vex`、`POST /dismiss` + `POST /undismiss`，以及 `GET /trends`。 免费的 Gemini 密钥（https://aistudio.google.com/apikey）**仅**在 `--explain` 时需要； 免费层级的 5 req/min 足以满足精简的双代理叙述。 ## MCP 工具 运行 `python -m sgai.mcp_server.server` 为任何 MCP 客户端提供这些工具： | 工具 | 用途 | |---|---| | `scan_manifest` | 审计依赖清单（PyPI/npm/Go/crates.io）对抗 OSV.dev | | `scan_dependency` | 检查单个包的 CVE | | `scan_requirements_file` | 审计整个 `requirements.txt` | | `run_static_analysis` | Bandit 静态分析（Python） | | `run_semgrep` | 多语言静态分析（可选） | | `scan_dockerfile` | Dockerfile / compose / Terraform 配置错误检查 | | `scan_secrets` | 高熵 + 已知格式的秘密检测（LLM 虚拟过滤） | | `validate_patch` | 在沙盒中运行目标项目的测试（自愈） | | `list_source_files` / `read_source_file` | 沙盒源访问 | 将其连接到 Antigravity、Claude Code 或 Gemini CLI：请参阅 [docs/mcp.md](docs/mcp.md) 和 [docs/integrations.md](docs/integrations.md)。 ## 内存 — “自上次扫描以来发生了什么？” 一次性报告会告诉您当前存在的问题。SGAI 还**记住对目标的每次扫描** ，并回答团队在站会上的提问：*自上次扫描以来发生了什么？* ```bash uv run sgai scan ./myproject # 第一次运行：保存基线 # …修复一些依赖，引入其他依赖… uv run sgai scan ./myproject # 第二次运行："3 个新 · 1 个已修复 · 8 个仍然开放" uv run sgai history ./myproject # 完整的扫描时间线 uv run sgai accept ./myproject CVE-... --reason "patch scheduled Q3" ``` 每个报告都会增加一个**自上次扫描以来发生变化**的部分；已接受的风险将不再被标记为新增。 内存存储在 `~/.sgai/`（通过 `$SGAI_HOME` 覆盖）； GitHub-URL 目标通过 URL 跟踪，因此 Web 应用程序和部署服务也会记住跨扫描的仓库。 ## 安全设计 SGAI 被设计为可以安全地指向不受信任的代码：沙盒文件访问（防止路径遍历和符号链接）， 每个代理的 MCP 工具集权限最低，请求处理无状态（粘贴的代码在临时目录中扫描并立即丢弃）， 代码中没有秘密（环境变量 + `.env.example`），以及一个可选的本地 PR 步骤。 详细信息请参阅 [docs/security.md](docs/security.md)。 ## 部署 SGAI 以无状态的 HTTP 服务和容器镜像的形式提供。 ```bash # 本地： uv run uvicorn sgai.api:app --host 0.0.0.0 --port 8080 # Docker — 已发布镜像（无需构建）： docker run -p 8080:8080 ghcr.io/ankitranjan-dsai/sgai:latest # Docker — 本地构建： docker build -t sgai . && docker run -p 8080:8080 sgai # Google Cloud Run： gcloud run deploy sgai --source . --region us-central1 --allow-unauthenticated ``` 完整指南（包括将可选的 Gemini 密钥作为秘密进行连接）：[docs/deploy.md](docs/deploy.md)。 ## 已知限制 - **静态分析仅限 Python（Bandit）。** 其他语言通过依赖清单 CVE 扫描和可选的 Semgrep（在 `--deep` 下）覆盖。 - **Semgrep 在运行时通过 `uvx` 获取**；如果不可用，则会跳过但不会影响扫描的其余部分。 - **严重性增强需要额外的 OSV 获取，每个唯一顾问。** 如果记录中没有 CVSS 矢量或数据库标签（罕见；一些 PYSEC 条目），则会回退到 **高**。 - **内存通过 `source:id:location` 匹配发现，具有行偏移容差。** 如果静态发现的代码行移动（代码在其上方编辑），则识别为同一问题；如果同一 ID 的发现移动**文件**，则仍会读取为一个已修复和一个新发现。 - **完全自主的工具调用管道需要更高的 Gemini 配额。** 默认 `--explain` 路径仅使用两个 LLM 调用以保持在免费层级内；确定性核心根本不需要密钥。 ## CI/CD 集成 SGAI 通过 [.github/workflows/](.github/workflows) 中的工作流对其自己的仓库进行防护 — 将它们复制到任何仓库以获得相同的设置： - **`ci.yml`** — 测试、lint 和一个自我审计的 `sgai check .`。 - **`sgai-security.yml`** — 在每个 PR 上：将完整扫描上传为 SARIF 到 GitHub 安全选项卡，然后使用 `sgai check .` 作为合并门控，因此 `.sgai/policy.yml` 策略违规会阻止合并。 - **`sgai-dependency-audit.yml`** — 每周一次定时任务，重新审计每个固定的依赖项以对抗 OSV.dev，并在新的 CVE 出现时打开升级 PR（`sgai fix --open-pr`）。 - **`release.yml`** — 构建并发布 `ghcr.io/ankitranjan-dsai/sgai` 容器镜像到 GitHub Packages 上的每个 `v*` 标签。 此仓库的策略位于 [.sgai/policy.yml](.sgai/policy.yml)；注释副本在 [`examples/policy.yml`](examples/policy.yml) 中，自定义利用链模板在 [`examples/custom_chains.json`](examples/custom_chains.json) 中。 ## 许可证 MIT 2026 Ankit Ranjan