ankitranjan-dsai/SGAI
GitHub: ankitranjan-dsai/SGAI
SGAI 是一个基于 Google ADK 与 MCP 构建的多智能体 AI 安全审计工具，通过对比漏洞数据库和静态分析自动检测代码库中的依赖风险与不安全模式，并持续追踪安全态势变化。
Stars: 0 | Forks: 0
# SGAI — SecureGuardAI
**Kaggle AI Agents: Intensive Vibe Coding Capstone — 赛道：Freestyle**
## 问题
AI 编程助手现在编写代码的速度极快、量极大。但在发布前，几乎没有任何代码会进行*安全性*检查：例如带有已知 CVE 的固定依赖项、使用 `subprocess(…, shell=True)`，或对不受信任的输入执行 `yaml.load`。安全审查速度慢、门槛高，而且很容易被忽略——因此漏洞在不知不觉中越积越多，没人能回答“跟上周相比，情况是变好了还是变糟了？”
## 解决方案
SGAI 将一组专家 agent 指向任何代码库——无论是本地路径还是 GitHub URL。它们将 **PyPI、npm、Go 和 crates.io** 的依赖清单与实时的 [OSV.dev](https://osv.dev) 数据库进行对比审计，对 Python 运行 **Bandit** 静态分析（使用 `--deep` 还可进行可选的 **Semgrep** 多语言分析），对检查结果进行去重和风险评级，生成可直接用于修复的报告，并可以提交修复 PR。由于它保存了每一次扫描记录，因此还能准确地告诉你自上次运行以来，**哪些是新出现的、哪些已修复、哪些仍处于未解决状态**。它基于同一套代码支持三种运行方式：**CLI**、**对移动端友好的 Web 应用**，以及任何 agent 都可以调用的可重用 **MCP 服务器**。
## 为什么使用 agent？
安全审计天然具有并行性和专业性。没有任何单一的 prompt 能够同时枚举源代码文件、查询 CVE 数据库、运行静态分析器、评估可利用性并编写补丁。SGAI 将这些任务分别交给专门的 agent 处理，并由一个 orchestrator 进行协调——这使得多 agent 架构成为*必需品*，而不是装饰品。
## 架构
```
┌──────────────────────┐
target repo ──▶ │ OrchestratorAgent │
└──────────┬───────────┘
│ coordinates
┌────────────┬───────────────┼───────────────┬──────────────┐
▼ ▼ ▼ ▼ ▼
ScannerAgent DependencyAudit StaticAnalysis RiskScoring Remediation
(enumerate (OSV.dev CVE (Bandit/Semgrep) (dedupe + (propose
sources) lookup) rank) fixes)
│ │ │ │ │
└────────────┴───────────────┴───────┬───────┴──────────────┘
▼
ReportAgent
(prioritized Markdown report
+ optional GitHub PR)
```
所有的安全工具（CVE 查询、静态分析、沙盒文件读取）都是通过 agent 作为工具调用的 **自定义 MCP 服务器** 来暴露的——实现了完美的解耦、可独立测试，并且可被任何兼容 MCP 的客户端重用。请参阅 [docs/architecture.md](docs/architecture.md)。
## 必修课程概念展示 — 全部 6 项，外加 Sessions & Memory
| 概念 | SGAI 如何展示它 |
|---|---|
| **多 agent 系统 (ADK)** | Orchestrator + 6 个专家 agent，外加一个 triage→report 的叙述流水线，基于 Google 的 Agent Development Kit 构建 |
| **MCP 服务器** | 自定义服务器 (`src/sgai/mcp_server`)，暴露 OSV.dev CVE 查询、Bandit + Semgrep 静态分析以及沙盒文件工具 |
| **安全特性** | 沙盒文件访问（防范 path-traversal + symlink 安全），每个 agent 具备最小权限工具集，无状态请求，输入验证 — 详见 [docs/security.md](docs/security.md) |
| **可部署性** | 无状态的 FastAPI 服务 (`src/sgai/api.py`) + Dockerfile，适配 Cloud Run — 详见 [docs/deploy.md](docs/deploy.md) |
| **Agent 技能 / Agents CLI** | 封装为 `sgai` CLI 和可重用技能 ([SKILL.md](SKILL.md))；支持通过 `uv tool install` 安装 |
| **Antigravity** | 安全 MCP 服务器可插入 Antigravity（以及任何 MCP agent）— 详见 [docs/integrations.md](docs/integrations.md) |
| **Sessions & Memory** *(课程 Day 3)* | 针对每个目标的持久化扫描记忆 (`src/sgai/memory.py`)，报告自上次扫描以来 **新出现 / 已修复 / 仍未解决** 的问题，并记录已接受的风险；同时作为真实的 ADK `MemoryService` 暴露，以便 agent 能够通过 `load_memory` 回溯之前的扫描 |
## 快速开始
**只需双击 — 无需终端：**
| 操作系统 | 双击运行 | 或从终端运行 |
|---|---|---|
| **macOS** | `run.command` | `./run.sh` |
| **Windows** | `run.bat` | `./run.ps1` (PowerShell) |
| **Linux** | — | `./run.sh` |
以上任何一种方式都会自动安装所需的一切（通过 [`uv`](https://docs.astral.sh/uv/)），启动 SGAI，并在服务器准备就绪后打开 **http://localhost:8080**。
## Web 演示
SGAI 的 Web 应用采用移动优先设计：
1. **同一 Wi-Fi：** 在手机上打开 `http://<你的电脑IP>:8080`。
2. **已部署：** 将其托管在 Cloud Run（见下文），即可在任何地方访问公开的 URL。
粘贴一个 `requirements.txt` 和/或一些代码（或点击 **Use sample vulnerable input**），轻触 **Scan**，即可获得一份包含风险摘要、发现的问题及修复方案的评级报告，以及“自上次扫描以来的变化”差异对比 — 手机端无需安装任何软件。
## 演示命令
在 [`examples/kaggle_demo_repo`](examples/kaggle_demo_repo) 中提供了一个独立的、包含刻意安全漏洞的代码库 — 包含 PyPI + npm + Go 依赖项 CVE、供 Bandit 检测的不安全 Python 代码，以及供 Semgrep 检测的不安全 `server.js`。**无需 API key。**
```
uv run sgai scan ./examples/kaggle_demo_repo # 23 findings (deps + Bandit)
uv run sgai scan ./examples/kaggle_demo_repo --deep # 32 findings (+ Semgrep)
uv run sgai scan ./examples/kaggle_demo_repo --sarif out.sarif
uv run sgai history ./examples/kaggle_demo_repo # the scan timeline
```
## CLI 用法
需要 Python 3.10+ 和 [`uv`](https://docs.astral.sh/uv/)。
```
uv sync # create venv + install deps (incl. dev tools)
uv run sgai scan ./examples/vulnerable_app # deterministic scan, NO API key
uv run sgai scan https://github.com/owner/repo # audit any public repo by URL
uv run sgai scan ./examples/multi_lang --deep # + Semgrep multi-language SAST
uv run sgai scan ./path --sarif out.sarif # SARIF 2.1.0 for code scanning
uv run sgai fix ./examples/vulnerable_app # preview dependency upgrades (dry run)
uv run sgai fix . --open-pr # open a remediation PR (repo you own)
uv run sgai scan ./path --explain # multi-agent narrated report (Gemini)
uv run sgai history ./path # scan timeline (new/fixed over time)
uv run sgai accept ./path --reason "tracked in JIRA-123"
uv run python -m sgai.mcp_server.server # run the security MCP server standalone
```
免费的 Gemini key (https://aistudio.google.com/apikey) **仅**在需要执行 `--explain` 时使用；对于轻量级的双 agent 叙述过程，免费层级每分钟 5 次请求的额度已经足够。
## MCP 工具
运行 `python -m sgai.mcp_server.server` 可为任何 MCP 客户端提供以下工具：
| 工具 | 用途 |
|---|---|
| `scan_manifest` | 对照 OSV.dev 审计依赖项清单 (PyPI/npm/Go/crates.io) |
| `scan_dependency` | 检查单个包是否存在 CVE |
| `scan_requirements_file` | 审计整个 `requirements.txt` |
| `run_static_analysis` | Bandit 静态分析 (Python) |
| `run_semgrep` | 多语言静态分析（可选） |
| `list_source_files` / `read_source_file` | 沙盒源码访问 |
关于如何将其接入 Antigravity、Claude Code 或 Gemini CLI：请参阅 [docs/mcp.md](docs/mcp.md) 和 [docs/integrations.md](docs/integrations.md)。
## Memory — “自上次扫描以来发生了什么变化？”
一次性的报告只会告诉你*现在*有什么问题。而 SGAI 还能**记住针对某一目标的每一次扫描**，并回答团队在站会上常问的问题：*发生了什么变化？*
```
uv run sgai scan ./myproject # 1st run: saves a baseline
# …修复一些 deps，引入另一些…
uv run sgai scan ./myproject # 2nd run: "3 new · 1 fixed · 8 still open"
uv run sgai history ./myproject # the full scan timeline
uv run sgai accept ./myproject CVE-... --reason "patch scheduled Q3"
```
每一份报告都会增加一个 **Changes since last scan** 板块；已被接受的风险将不再被标记为新问题。记忆数据存储在 `~/.sgai/` 目录中（可通过 `$SGAI_HOME` 覆盖）；针对 GitHub URL 的目标会根据 URL 进行追踪，因此 Web 应用和已部署的服务也能跨扫描记录代码库状态。
## 安全设计
SGAI 在设计上确保了能够安全地针对不受信任的代码运行：具备沙盒文件访问权限（防范 path-traversal + symlink 安全）、基于最小权限原则分配的 agent MCP 工具集、无状态请求处理（粘贴的代码会在一次性的临时目录中扫描且从不被存储）、代码中不含任何密钥（使用环境变量 + `.env.example`），以及一个仅限本地运行的可选 PR 提交步骤。完整详情请见 [docs/security.md](docs/security.md)。
## 部署
SGAI 以无状态 HTTP 服务和容器镜像的形式发布。
```
# Local:
uv run uvicorn sgai.api:app --host 0.0.0.0 --port 8080
# 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 key 作为 secret 配置）：
[docs/deploy.md](docs/deploy.md)。
## 已知限制
- **静态分析仅支持 Python (Bandit)。** 其他语言可通过依赖清单 CVE 扫描覆盖，而在开启 `--deep` 模式下，可通过可选的 Semgrep 覆盖。
- **Semgrep 会在运行时**通过 `uvx` 获取；如果不可用，将被优雅跳过（扫描的其余部分仍会继续运行）。
- **依赖项的严重程度是基于基准线的。** OSV 批量 API 返回的公告 ID 不包含 CVSS，因此固定依赖中的已知 CVE 默认被视为 **High**。
- **记忆功能通过 `source:id:location` 匹配检查结果。** 编辑静态检查发现的问题上方的代码会导致其行号发生偏移，因此系统可能会将其误读为一个已 *修复* 的问题和一个 *新出现* 的问题。
- **全自动化的工具调用流水线需要更高的 Gemini 配额。** 默认的 `--explain` 路径仅使用两次 LLM 调用，以保持在免费额度内；而确定性的核心流程根本不需要任何 key。
## 未来工作
- 基于 CVSS 的依赖项检查结果严重程度评分。
- 支持更多语言的原生 SAST（超越 Bandit + Semgrep）。
- 接入 CI 的端到端自动修复 PR。
- 基于 MCP 服务器的 IDE 集成 (VS Code / JetBrains)。
## 许可证
MIT © 2026 Ankit Ranjan
标签：AI安全, Chat Copilot, Google ADK, 云安全监控, 多智能体, 安全专业人员, 请求拦截, 逆向工具, 静态分析