gauravn17/periscope

# Periscope **基于知识图谱的代理式供应链威胁情报。** Dependabot 告诉你该升级什么。而 Periscope 会告诉你实际上什么是真正有风险的、原因是什么， 并用通俗易懂的英文回答你的问题 —— 支持任何 MCP 客户端，包括 Claude。 ## 问题所在 当严重的漏洞爆发时（如 log4j、xz-utils），每个团队都会问同样的三个 问题：*我们受影响吗？具体在哪里？我们需要更改什么？* 手动回答这些 问题需要几天时间，因为易受攻击的包通常深埋在传递依赖树中 —— 而且没有免费工具能回答这样的跨仓库问题： - “我的哪些仓库受到了 CVE-2026-XXXX 的影响，以及是通过什么链条？” - “哪一次单一升级能清除最多的严重漏洞？” - “我的依赖树中，哪些包只有一个维护者且 2 年内没有发布过新版本？” ## 工作原理 ``` ┌─────────────────────────────┐ │ Agent (LLM) │ │ Ollama / Groq / Gemini │ │ tool-use loop + reports │ └──────┬──────┬──────┬────────┘ │ MCP │ MCP │ MCP ┌──────────┴─┐ ┌──┴───┐ ┌┴─────────┐ │ Neo4j MCP │ │ OSV │ │ GitHub │ │ (graph │ │ MCP │ │ MCP │ │ queries) │ │ │ │ (PRs) │ └──────┬─────┘ └──┬───┘ └──────────┘ │ │ ┌──────┴──────────┴───────┐ │ Neo4j knowledge graph │ │ Projects → Packages → │ │ Versions ← Vulns │ └─────────────────────────┘ ``` 1. **摄入 (Ingest)** — 将你仓库中的 lockfile/manifest 解析到 Neo4j 图谱中： 项目、包、版本、传递依赖边。 2. **链接 (Link)** — 查询 OSV.dev 以获取影响图中每个版本的已知漏洞， 并将它们作为 `(:Vulnerability)-[:AFFECTS]->(:PackageVersion)` 附加进去。 3. **监视 (Watch)** — agent 轮询 OSV 订阅源；新的安全公告会将其唤醒。 4. **推理 (Reason)** — 确定性的 Cypher 查找受影响的项目和依赖链； LLM 判断真实世界的严重程度（生产依赖对比开发依赖，以及树中的实际版本 范围），并编写通俗易懂的英文影响报告。 5. **行动 (Act)** — agent 发起一个 PR 来升级依赖，并在描述中附带完整的链条和 理由。由人类进行批准。始终如此。 **设计原则：** 确定性检索，LLM 在此基础上进行推理。查找受影响的 项目是一个精确的图查询 —— 不可能产生幻觉。LLM 只负责选择 工具、判断上下文，并为人类编写内容。这就是为什么免费的本地 8B 模型就足够了。 ## 技术栈（全部免费） | 组件 | 技术 | 成本 | |---|---|---| | 知识图谱 | Neo4j 社区版 (Docker) 或 Aura 免费层 | $0 | | 漏洞数据 | OSV.dev + deps.dev 公共 API（无需密钥） | $0 | | LLM | Ollama（本地）或 Groq / Gemini 免费层 | $0 | | MCP server | Python/Go, MCP SDK | $0 | | PR 自动化 | GitHub API | $0 | | 托管（后期） | Cloudflare Workers 免费计划 | $0 | ## 快速开始（阶段 1） ``` # 1. 启动 Neo4j docker compose up -d # browser at http://localhost:7474 (neo4j / periscope1) # 2. 安装 python -m venv .venv && source .venv/bin/activate pip install -e ".[dev]" # 3. 将 repo 的依赖项导入图中 periscope ingest ~/some-repo --name my-project # 4. 从 OSV.dev 链接已知漏洞 periscope link-vulns # 5. 提出关键问题 periscope affected GHSA-xxxx-xxxx-xxxx periscope report # summary of all vulns across all ingested projects ``` ## 路线图 - [x] **阶段 1 — 全景图。** Lockfile 解析器 (npm, PyPI) → Neo4j。OSV 链接。 CLI 通过完整的依赖链查询受影响的项目。 - [ ] **阶段 2 — 组织级情报。** 摄入 GitHub 用户/组织的所有仓库。 通过 deps.dev 提供维护者风险信号（单一维护者、停滞的发布）。 - [ ] **阶段 3 — agent。** MCP server（Neo4j, OSV, GitHub）+ 具有可插拔 模型后端（Ollama/Groq/Gemini）的 agent 循环。通俗易懂的英文影响报告。 - [ ] **阶段 4 — 双手。** OSV 订阅源监视器；带有 人工介入审批的自动化修复 PR；对写入操作采用 OPA 风格的防护机制。 - [ ] **阶段 5 — 验证。** 评估工具：使用历史 CVE 为图谱提供种子，衡量 检测的准确率/召回率。仪表盘。可达性分析（探索性目标）。 ## 仓库结构 ``` periscope/ Python package cli.py typer CLI (ingest, link-vulns, affected, report) config.py env-based settings graph/ Neo4j client + schema (constraints, indexes) ingest/ lockfile parsers + ingestion pipeline vuln/ OSV.dev client mcp-servers/ Phase 3: MCP servers (Neo4j, OSV, GitHub) agent/ Phase 3: agent loop + model adapters tests/ pytest ```

标签：AI智能体, AI风险缓解, GPT, MCP, 威胁情报, 安全规则引擎, 开发者工具, 漏洞管理, 请求拦截, 逆向工具