vaulpann/ghost
GitHub: vaulpann/ghost
基于智能体 LLM 的实时供应链漏洞追踪工具，能在恶意包传播前通过深度代码分析捕获威胁。
Stars: 3 | Forks: 1
Ghost
适用于 npm、PyPI 和 GitHub 的实时供应链威胁情报。
基于 Agentic LLM 的分析，在恶意软件包传播之前将其捕获。
实时仪表板 ·
获取警报 (Slack) ·
@pjvann
## 问题所在
供应链攻击正在快速增长。xz utils 后门、event-stream 事件、ua-parser-js 劫持、Axios 被入侵——这些之所以得逞，是因为没有人以发布速度进行自动化的深度分析。
现有的工具依赖于签名匹配和已知的 CVE 数据库。它们无法捕获**新型攻击**——一个没有先前历史的全新恶意依赖项、版本更新中隐藏的混淆载荷、以及拼写错误的软件包名称。
## Ghost 的工作原理
Ghost 监控着 npm、PyPI 和 GitHub 上 545 多个最关键的开源软件包。当发布新版本或 main 分支有新的提交时，Ghost 会：
1. **检测** 60 秒内的变更
2. **下载** 旧版本和新版本
3. **对比** 源代码
4. **运行 AI 安全代理**，该代理使用真实的工具调查变更
该代理不仅仅是读取差异并猜测。它拥有以下工具：
- **查询软件包** 在 npm/PyPI 上——检查下载量、仓库链接、描述
- **查询 GitHub 仓库**——检查 stars、活跃度、存档状态、最近的提交
- **下载并解压软件包**——实际检查新依赖项的源代码
- **对比依赖项版本**——查看被升级的依赖项内部发生了什么变化
- **扫描可疑模式**——网络调用、进程执行、混淆、凭证访问
- **读取特定文件**——检查安装脚本、入口点以及任何可疑内容
如果一个软件包添加了一个每周下载量仅为 2 且包含 curl 二进制文件的 postinstall 脚本的新依赖项——Ghost 会捕获它。如果子依赖项的版本更新引入了 `eval(atob(...))`——Ghost 会捕获它。
## 架构
```
Cloud Scheduler (every 60s)
|
v
+---------------+
| Ingestion | Polls npm, PyPI, GitHub
| Service | for version changes
+-------+-------+
|
new version detected
|
v
+---------------+
| Diff | Downloads old + new
| Generator | Generates unified diff
+-------+-------+
|
v
+---------------+
| Security | OpenAI Agents SDK
| Agent | GPT-4o with 6 tools
+-------+-------+
|
+-------+-------+
| |
v v
+----------+ +-----------+
| Slack | | Dashboard |
| Alert | | API |
+----------+ +-----------+
```
### 技术栈
| 组件 | 技术 |
|-----------|-----------|
| **Backend** | Python 3.12, FastAPI, SQLAlchemy (async), Alembic |
| **Analysis** | OpenAI Agents SDK, GPT-4o with function tools |
| **Frontend** | Next.js 14, React, TailwindCSS |
| **Database** | PostgreSQL (Neon) |
| **Deployment** | GCP Cloud Run, Vercel, Cloud Scheduler |
| **MCP Server** | Node.js, @modelcontextprotocol/sdk |
### 代理的工具箱
| 工具 | 用途 |
|------|---------|
| `lookup_package_info` | 检查 npm/PyPI 软件包元数据、下载量、仓库 |
| `lookup_github_repo` | 检查 GitHub 仓库 stars、活跃度、发布版本、存档状态 |
| `download_and_list_files` | 下载软件包版本，列出文件，标记安装脚本 |
| `read_file_content` | 从下载的软件包中读取特定文件 |
| `diff_package_versions` | 对比依赖项的两个版本以查看变更内容 |
| `scan_for_suspicious_patterns` | 正则扫描网络调用、eval、进程执行等 |
## MCP 服务器 -- 在您的 AI 编码工具中使用 Ghost
Ghost 附带一个 MCP (Model Context Protocol) 服务器，允许任何 AI 编码助手根据 Ghost 的实时威胁情报检查软件包。
### 添加到 Claude Code
```
cd ghost/mcp && npm install
claude mcp add ghost node -- /path/to/ghost/mcp/index.js
```
然后在任何 Claude Code 会话中：
### 添加到 OpenAI Codex
添加到您的 Codex MCP 配置中：
```
{
"ghost": {
"type": "stdio",
"command": "node",
"args": ["/path/to/ghost/mcp/index.js"]
}
}
```
### MCP 工具
| 工具 | 描述 |
|------|-------------|
| `check_package` | 在将软件包添加为依赖项之前，检查其是否存在供应链威胁 |
| `get_threat_alerts` | 获取所有风险评分较高的软件包 |
| `ghost_status` | 获取监控统计信息——跟踪的软件包、运行的分析、威胁级别 |
MCP 服务器默认连接您的本地 Ghost API。设置 `GHOST_API_URL` 以指向远程实例。
## 自托管
### 前置条件
- Docker & Docker Compose
- Python 3.12+
- Node.js 20+
- OpenAI API key (用于分析代理)
- PostgreSQL 数据库
### 快速开始 (本地开发)
```
# 克隆
git clone https://github.com/vaulpann/versatility-labs.git ghost
cd ghost
# 配置
cp .env.example .env
# 使用你的 OPENAI_API_KEY 和 DATABASE_URL 编辑 .env
# 启动 backend + postgres
docker-compose up --build
# 在另一个终端中，启动 frontend
cd frontend && npm install && npm run dev
# Seed packages
docker exec ghost-backend-1 python -m seed
# 打开 http://localhost:3000
```
### 环境变量
| 变量 | 必填 | 描述 |
|----------|----------|-------------|
| `DATABASE_URL` | 是 | PostgreSQL 连接字符串 (asyncpg 格式) |
| `OPENAI_API_KEY` | 是 | 用于安全代理的 OpenAI API key |
| `GITHUB_TOKEN` | 推荐 | GitHub PAT，用于获得更高的速率限制 (5000 次/小时 vs 60 次) |
| `SLACK_WEBHOOK_URL` | 可选 | 用于警报的 Slack incoming webhook |
| `ADMIN_API_KEY` | 可选 | 保护 webhook/poll 端点 |
| `ALLOWED_ORIGINS` | 可选 | CORS 源 (逗号分隔) |
| `FRONTEND_URL` | 可选 | Slack 警报中链接的前端 URL |
### 生产环境部署
Ghost 专为 GCP Cloud Run + Vercel 设计：
1. **Database**: Neon (托管 Postgres) 或 Cloud SQL
2. **Backend**: `gcloud run deploy ghost-api --source ./backend`
3. **Frontend**: 将仓库连接到 Vercel，将根目录设置为 `frontend`
4. **Auto-polling**: Cloud Scheduler 每分钟调用 `POST /api/v1/webhooks/poll`
5. **Alerts**: 通过数据库配置 Slack webhook
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 中的完整部署指南。
## API
所有读取端点都是公开的。写入端点已被移除或受 `ADMIN_API_KEY` 保护。
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| GET | `/api/v1/packages` | 列出受监控的软件包 (分页) |
| GET | `/api/v1/packages/{id}` | 软件包详情 |
| GET | `/api/v1/packages/{id}/versions` | 版本历史 |
| GET | `/api/v1/versions/{id}/diff` | 原始 diff 内容 |
| GET | `/api/v1/analyses` | 分析流 (分页，可筛选) |
| GET | `/api/v1/analyses/{id}` | 完整分析详情 |
| GET | `/api/v1/analyses/{id}/findings` | 安全发现 |
| GET | `/api/v1/feed` | 仪表板流 (分页) |
| GET | `/api/v1/stats` | 监控统计 |
| POST | `/api/v1/webhooks/poll` | 触发轮询 (需要 `X-API-Key`) |
## 检测原理
### Ghost 捕获的内容 (评分 5.0+)：
- 每周下载量 <1K 且包含下载外部二进制文件的安装脚本的新依赖项
- 新版本引入带有编码载荷的 `eval()` 的依赖项版本更新
- 拼写错误的软件包名称 (例如，用 `plain-crypto-js` 代替 `crypto-js`)
- 数据外泄模式——收集凭证并将其发送到外部 URL 的代码
- 混淆代码替换了先前可读的源代码
### Ghost 正确忽略的内容 (评分 0.0)：
- Dockerfile 变更、CI/CD 配置、构建脚本
- 文档、测试、README、CHANGELOG 更新
- 对知名软件包 (>10K 下载量) 的依赖更新
- 版本元数据、版权年份变更
- Go 模块更新、Rust crate 对标准库的更新
- Linter 配置、类型注解、重构
### Axios 攻击 -- Ghost 如何捕获它
2026 年 3 月 31 日，攻击者劫持了一名 npm 维护者的账户并发布了带有恶意依赖项 `plain-crypto-js@4.2.1` 的 `axios@1.14.1`。
Ghost 的代理将会：
1. 在 60 秒内检测到新的 `axios` 版本
2. 对比 `1.14.0` 与 `1.14.1`——看到新的 `plain-crypto-js` 依赖项
3. 调用 `lookup_package_info("plain-crypto-js", "npm")`——看到 0 下载量，没有仓库
4. 调用 `download_and_list_files("plain-crypto-js", "4.2.1", "npm")`——找到 postinstall 脚本
5. 对 postinstall 调用 `read_file_content()`——看到它下载了一个 RAT 二进制文件
6. 调用 `scan_for_suspicious_patterns()`——确认网络调用 + 进程执行
7. 评分：**9.5/10 严重**——立即向 Slack 触发警报
## 项目结构
```
ghost/
├── backend/
│ ├── app/
│ │ ├── main.py # FastAPI app
│ │ ├── config.py # Settings
│ │ ├── database.py # Async SQLAlchemy
│ │ ├── models/ # ORM models
│ │ ├── schemas/ # Pydantic schemas
│ │ ├── routers/ # API endpoints
│ │ ├── services/
│ │ │ ├── registry/ # npm, PyPI, GitHub clients
│ │ │ ├── diff/ # Diff generation
│ │ │ ├── analysis/
│ │ │ │ ├── agent.py # Security agent (OpenAI Agents SDK)
│ │ │ │ └── pipeline.py # Analysis orchestrator
│ │ │ ├── ingestion.py # Poll orchestrator
│ │ │ └── alerting.py # Slack/webhook dispatch
│ │ └── utils/
│ ├── alembic/ # DB migrations
│ ├── seed.py # Seed 100 packages
│ └── Dockerfile
├── frontend/
│ ├── src/app/ # Next.js pages
│ ├── src/components/ # React components
│ └── src/lib/ # API client, types, utils
├── mcp/
│ └── index.js # MCP server for AI coding tools
├── docker-compose.yml
└── LICENSE
```
## 贡献
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解如何做出贡献的指南。
## 致谢
由 [Validia](https://validia.ai) 的 [Paul Vann](https://x.com/pjvann) 构建。
加入 Slack 上的 [FrontierSec](https://join.slack.com/t/frontiersec/shared_invite/zt-3s0tfehvr-Qjqa1w8ITe7O7zZcd_23ag) 以获取实时警报。
## 许可证
MIT -- 请参阅 [LICENSE](LICENSE)。
标签：DevSecOps, DNS枚举, LLM, MITM代理, npm, PyPI, Unmanaged PE, WSL, 上游代理, 人工智能安全, 代码差异分析, 供应链攻击防护, 依赖管理, 合规性, 威胁情报, 开发者工具, 开源供应链安全, 恶意包检测, 测试用例, 漏洞追踪, 网络安全工具, 自动化分析, 请求拦截, 跨站脚本, 逆向工具, 零日漏洞