mamabearmehmi-hub/skill-sentry
GitHub: mamabearmehmi-hub/skill-sentry
Skill Sentry 是一个在安装前静态扫描 Claude MCP 技能以发现安全威胁的零成本开源工具。
Stars: 1 | Forks: 0
Scan Claude skills for security threats before you install them.
为什么 ·
功能 ·
快速开始 ·
工作原理 ·
限制 ·
贡献
## 为什么我构建了这个
每天我都会发现新的技能和 MCP 服务器，让使用 Claude 构建功能变得像超级能力一样。社区非常棒。人们正在发布工具，将 Claude 变成设计伙伴、数据库管理器和部署引擎。
但有一件事让我夜不能寐：**每一个技能都要求你运行 `npx` 或 `npm install`。**
这意味着你必须信任别人的代码在你的机器上运行。拥有你的文件、环境变量、SSH 密钥和令牌。
我不是安全专家。我只是一个构建者，就像你一样。但我知道足够多的事实，因此害怕在看到内部代码之前就运行 `curl | bash` 的 `postinstall` 脚本。我读过供应链攻击的故事。我见过一个恶意包能造成什么后果。
所以我为自己构建了一个哨兵。
**Skill Sentry 会扫描代码，这样你就不需要了。** 它读取每个文件，检查危险模式，并给出风险评分。这一切都无需执行被扫描的哪怕一行代码。
欢迎你使用它。我希望它能帮助我们保持安全，并让我们继续享受使用 Claude 构建美好事物。
**V** | *只是一个想安心点击安装的构建者*
## 它能做什么
**Skill Sentry 是一个零成本、开源的安全扫描器，专为 Claude MCP 生态系统设计。**
不管它被称为“Skill”还是“MCP Server”。如果有 `package.json`，Skill Sentry 就会扫描它。
### 扫描器会检查以下内容：
| 风险等级 | 检测内容 | 重要性 |
|:---:|---|---|
| **严重** | 带有 Shell 命令的 `postinstall` / `preinstall` 脚本 | 代码会在你检查之前自动运行 |
| **高** | `eval()`、`child_process`、`exec()`、SSH 密钥访问 | 让包控制你的整个系统 |
| **高** | 读取 `process.env.GITHUB_TOKEN` 等密钥 | 凭证可能被盗 |
| **中** | 混淆的 Base64 数据块、未固定版本的 `"*"` 依赖 | 隐藏的有效载荷和供应链风险 |
| **中** | 访问粘贴站点和原始 GitHub URL 的网络请求 | 运行时下载有效载荷 |
### 风险评分
每个技能都会获得一个 **0 到 100** 的评分。
```
Risk Score = min(100, sum of all finding scores)
```
- **0** = 未检测到已知风险模式
- **1-19** = 低风险
- **20-49** = 中风险（请查看结果）
- **50-79** = 高风险（请谨慎）
- **80-100** = 严重（不要安装）
### 已验证发布者和类型混淆检测
知名组织（Anthropic、Stripe、GitHub、Supabase 等）会被识别为 **已验证发布者**。它们的检测结果会显示，但会说明这是预期行为。Stripe 的工具包 *应该* 读取 `STRIPE_API_KEY`。这是正常的。
如果某个仓库所有者看起来与已验证发布者高度相似（例如 `stripee` 对比 `stripe`），扫描器会将其标记为 **潜在的类型混淆攻击**：有人冒充受信任品牌来诱骗你安装恶意代码。
## 功能特性
- **npm CLI**：`npx skill-sentry
` 可从任意终端扫描，无需安装
- **Web 仪表板**：可搜索的审计技能表格，带交互式筛选
- **即时扫描**：粘贴 URL，5-15 秒内获取结果（扫描在服务端运行）
- **直白英语**：每个发现都用人类语言解释，而非安全术语
- **判决结果**：清晰的扫描建议（“无已知风险” / “请仔细审查” / “不要安装”）
- **CI 标志**：`--strict` 和 `--threshold` 用于自动化流水线拦截
- **自动发现**：每日通过 GitHub API 抓取新的 MCP 仓库
- **零成本**：完全在 Vercel 免费层和 GitHub Actions 上运行
## 快速开始
### 在终端中扫描（无需安装）
```
npx skill-sentry https://github.com/owner/repo
```
你会看到一个带直白判决结果的高亮报告：
```
┌─────────────────────────────────────┐
│ SKILL SENTRY v0.2 │
│ Security scanner for Claude skills │
└─────────────────────────────────────┘
Scanning: https://github.com/owner/repo
Cloning and analyzing...
════════════════════════════════════════
NO KNOWN RISK PATTERNS DETECTED
════════════════════════════════════════
Risk Score: 0/100
Files: 42 scanned
Findings: 0 issues
✓ No known risk patterns detected
All 42 files passed 11 security checks.
```
**标志：**
- `--json` 输出原始 JSON（可用于管道传输到其他工具或 CI）
- `--strict` 如果发现任何 HIGH 或 CRITICAL 结果则退出状态为 1
- `--threshold ` 如果风险评分 >= N 则退出状态为 1（0-100）
- `--help` 显示用法
**退出代码**（用于 CI/CD）：
- `0` = 无发现
- `1` = 检测到发现（或超过阈值）
- `2` = 错误（无效 URL 或网络问题）
**在 CI 中使用：**
```
# 阻止添加危险 MCP 依赖的 PR
npx skill-sentry https://github.com/owner/new-skill --strict || exit 1
# 自定义阈值：如果风险分数达到 50 或以上则失败
npx skill-sentry https://github.com/owner/new-skill --threshold 50
```
### 使用仪表板
访问在线仪表板并将任意 GitHub URL 粘贴到提交表单中。结果会在 5-15 秒内直接显示在页面上。无需页面跳转，也无需等待后台任务。
### 本地运行
```
git clone https://github.com/mamabearmehmi-hub/skill-sentry.git
cd skill-sentry
npm install
npm run dev
```
打开 [http://localhost:3000](http://localhost:3000) 查看仪表板。
### 运行测试
```
npm test
```
20 个集成测试会针对真实测试文件验证每一个安全规则。
## 如何使用仪表板
### 第一步：安装前先检查
有人刚刚在 Slack 中分享了一个很酷的 Claude 技能。在运行 `npx` 或 `npm install` 之前：
1. 复制 GitHub URL
2. 将其粘贴到 **提交技能以供审核** 的输入框中
3. 5-15 秒后结果会显示在页面上
4. 阅读判决结果
### 第二步：阅读判决结果
| 你看到的内容 | 含义 | 应该做什么 |
|:---:|---|---|
| **“未检测到已知风险模式”** | 我们的 11 条检测规则均未匹配 | 风险较低，但仍建议检查不熟悉作者提供的代码 |
| **“已验证发布者”** | 已知组织（Stripe、Anthropic 等）且结果符合预期 | 查看结果，但这些通常是该类型工具的正常运行 |
| **“发现一些顾虑”** | 检测到可疑模式 | 阅读发现内容并自行判断 |
| **“高风险”** | 多个危险模式 | 仅在信任作者并了解其所需权限的情况下安装 |
| **“禁止安装”** | 严重威胁：自动执行脚本、窃取凭证或访问 SSH 密钥 | 切勿安装。告知他人。 |
| **“看起来像是伪造账户”** | 仓库所有者与已验证发布者高度相似 | 很可能是一种模仿攻击。不要安装。 |
### 第三步：理解发现内容
每个发现都会用直白语言解释。不需要安全学位：
点击 **“技术细节”** 可展开完整分解，包括文件路径和行号。
## 自动发现：注册表自我增长
Skill Sentry 拥有一个 **每日自动抓取器**，它会：
1. **每天 06:00 UTC** 通过 GitHub Actions 运行
2. **搜索 GitHub** 上标记为 `mcp-server`、`mcp-tool`、`claude-skill` 和 `model-context-protocol` 的仓库
3. **跳过已扫描的仓库**（无重复）
4. **审计每个新仓库** 的全部 11 条安全规则
5. **自动提交结果** 到注册表
6. **Vercel 自动重新部署**，新技能会在几分钟内出现在仪表板上
注册表每天都在增长，无需人工操作。社区也可以通过提交按钮参与反馈，形成越多人使用、内容越完整的良性循环。
**当前注册表：** 已扫描 128+ 个技能，并持续增长。
## “但我们公司已经有 SonarQube / Snyk / Checkmarx 了...”
很好，继续使用它们。Skill S 填补了一个不同的空白。
| 工具 | 何时触发 | 覆盖范围 | 空白点 |
|------|:---:|---|---|
| **SonarQube** | 代码已进入你的仓库后 | 代码质量、错误和你仓库中的安全异味 | 无法在安装前扫描第三方包 |
| **Snyk / Checkmarx** | `npm install` 之后 | 依赖树中的已知 CVE | 此时恶意 `postinstall` 脚本已经运行 |
| **Azure Defender** | 运行时 | 部署基础设施中的威胁 | 无法覆盖开发者本地机器或本地 `npx` |
| **Ivanti App Control** | 端点级别 | 受管控设备上的白名单/黑名单可执行文件和脚本 | 不理解 npm 包，基于二进制而非意图。运行恶意技能的 `node.exe` 与安全的一样 |
| **Skill Sentry** | **安装前** | **你即将信任的包中的危险模式** | **这就是空白点** |
以下是某人安装 Claude 技能的时间线：
```
1. Someone shares a skill URL in Slack
2. Developer runs: npx some-mcp-skill ← Skill Sentry checks HERE
3. npm downloads the package ← Ivanti sees node.exe (allowed)
4. postinstall script runs silently ← Too late. Snyk hasn't scanned yet.
5. Code is in node_modules ← NOW Snyk/Checkmarx can see it
6. Developer commits and pushes ← NOW SonarQube can see it
7. App deploys to production ← NOW Azure Defender can see it
```
第 3-4 步是致命区。恶意代码会在任何企业工具有机会查看之前运行。
**Skill Sentry 是第 2 步的唯一检查。** 在下载前。在执行前。在任何损害发生前。
## 它是如何工作的
```
Terminal or Dashboard
│
▼
┌──────────────┐
│ auditRepo() │ Stateless function: URL in, JSON out
└──────┬───────┘
│
┌──────▼───────┐
│ Clone repo │ git clone --depth 1 (local)
│ or tarball │ GitHub API download (Vercel/npx)
└──────┬───────┘
│
┌──────▼───────┐
│ Scan files │ 11 regex rules x matching file targets
│ (static) │ Records: file, line, match, severity
└──────┬───────┘
│
┌──────▼───────┐
│ Risk score │ min(100, sum of finding scores)
│ + verdict │ Checks verified publishers + typosquats
└──────┬───────┘
│
┌──────▼───────┐
│ Cleanup │ Temp directory deleted (always, even on error)
└──────────────┘
```
**核心原则：** 扫描器**永远不会执行**它正在分析的代码。它下载文件，读取内容，运行正则表达式模式匹配，然后删除文件。仅此而已。静态分析而已。
### 架构
| 层级 | 技术 | 成本 |
|------|------|------|
| CLI | TypeScript + tsx | 免费（npm） |
| 前端 | Next.js 15、Tailwind CSS、Shadcn UI | 免费（Vercel） |
| 数据库 | `registry.json` 提交到 Git | 免费 |
| 扫描器 | TypeScript + 正则表达式（仅使用 Node.js 内置模块） | 免费 |
| 自动化 | GitHub Actions（3 个工作流） | 免费（公开仓库） |
| npm 包 | 22.9KB，仅 2 个生产依赖（tar、tsx） | 免费 |
**总运行成本：每月 0 美元。**
### npm 包：轻量设计
CLI 仅包含 **2 个生产依赖**（tar + tsx）。Web 仪表板的依赖（React、Next.js、Tailwind）仅用于开发环境，运行 `npx skill-sentry` 时不会下载。总安装体积仅约 14MB。
## 项目结构
```
skill-sentry/
├── bin/ # npm CLI entry point
│ ├── cli.js # Node wrapper (loads tsx)
│ └── skill-sentry.ts # CLI with colored output + flags
├── app/ # Next.js App Router (dashboard)
│ ├── page.tsx # Dashboard
│ ├── api/submit/route.ts # Scan API (runs auditor directly)
│ ├── api/check/route.ts # Registry lookup API
│ └── repo/[owner]/[name]/ # Per-repo report pages
├── components/security/ # Dashboard UI components
│ ├── DashboardClient.tsx # Interactive stats + ticker + table
│ ├── SkillsTable.tsx # Searchable skills table (desktop + mobile)
│ ├── SubmitSkillForm.tsx # Submit form with inline results
│ ├── RiskBadge.tsx # Color-coded risk scores
│ ├── FindingCard.tsx # Finding with plain English + source link
│ ├── ThreatBar.tsx # Severity distribution bar
│ ├── SearchFilter.tsx # Search + filter controls
│ └── ReportHeader.tsx # Report page header
├── scripts/ # Scanner engine
│ ├── auditor.ts # Core: auditRepo(url) -> RegistryEntry
│ ├── clone-repo.ts # Git clone or tarball download + cleanup
│ ├── scan-files.ts # File walker + regex matcher
│ ├── cli.ts # JSON CLI (used by GitHub Actions)
│ ├── scraper.ts # GitHub topic discovery
│ └── update-registry.ts # Registry upsert
├── lib/ # Shared types and logic
│ ├── types.ts # TypeScript data contract
│ ├── constants.ts # 11 security rules with plain English
│ ├── registry.ts # Server-side registry helpers
│ ├── registry-utils.ts # Client-safe: verdicts, impact, search
│ └── verified-publishers.ts # Publisher whitelist + typosquat detection
├── .github/workflows/ # GitHub Actions
│ ├── reusable-auditor.yml # Core scan workflow (called by others)
│ ├── on-demand-scan.yml # repository_dispatch trigger
│ └── scheduled-scrape.yml # Daily discovery cron (06:00 UTC)
└── public/data/
└── registry.json # The "database" (128+ entries)
```
## 它是什么以及它不是什么
**让我对你坦诚相待。**
Skill Sentry 是一个 **初级安全扫描器**。它是烟雾探测器，而不是消防队。
**它能捕获：**
- 安装时自动执行的恶意 `postinstall` / `preinstall` 脚本
- `child_process`、`exec`、`spawn` 的使用（可在你的机器上运行命令）
- SSH 密钥访问尝试（`~/.ssh`、`id_rsa`、`known_hosts`）
- 凭证窃取（`process.env.GITHUB_TOKEN`、密钥、API 密钥）
- `eval()` 使用（任意代码执行）
- 混淆的 Base64 有效载荷、未固定版本的依赖、可疑的网络目标
- 类型混淆攻击（模仿已知发布者的伪造账户）
**它无法捕获：**
- 混淆或编码的恶意代码（例如通过字符串拼接构建 `eval`）
- 深度依赖树中的复杂供应链攻击
- 编译后的二进制文件或 WebAssembly 中的威胁
- 文档或 README 中的社会工程学攻击
- 已知依赖中的零日漏洞
**这对你意味着什么：**
- 评分为 **0** 并不意味着包绝对安全，只是未匹配到我们的检测规则
- 如果 Skill Sentry 显示 **“禁止安装”**，请认真对待。确实存在问题
- 对于关键生产系统，请结合使用 Snyk、SonarQube、Checkmarx 和人工代码审查
大多数 npm 供应链攻击都很简单。一个在安装时 `curl` 有效载荷的 `postinstall` 脚本是头号攻击方式。Skill Sentry 能在几秒钟内捕获这些。这解决了最常见的攻击。对于更复杂的长期攻击，企业工具和人工审查仍然不可或缺。
**坦诚说明局限性能建立更多信任。** 我宁愿你知道这个工具能做什么，也不愿你在无意中遭受损失。
## 我如何构建它
我在一次会话中使用 Claude Code（Opus）构建了 Skill Sentry。从痛点到发布的完整构建过程被逐步记录：
**[阅读完整的构建过程](docs/HOW-I-BUILT-THIS.md)**
其中涵盖了架构决策、遇到的问题及修复、推动改进的社区反馈，以及构建你自己的工具的原则。
## 贡献
我构建 Skill Sentry 是因为我需要它。如果你觉得它有用，我很乐意你的帮助让它变得更好。
**这是我的第一个开源项目，所以我也在学习。请对我有耐心，我也会对你有耐心。** 我们都在一起，是因为我们希望用 Claude 安全地构建。
### 如何贡献
1. **Fork 仓库。** 点击 GitHub 上的 Fork 按钮。
2. **创建分支。** `git checkout -b feature/你的想法`
3. **做出修改。** 参考代码库中的模式进行更改。
4. **运行测试。** `npm test`（全部 20 个必须通过）
5. **成功构建。** `npm run build`（必须无错误完成）
6. **打开 Pull Request。** 目标分支为 `main`，并附上清晰的描述
### 我希望得到的帮助
- **更多安全规则。** 看到我遗漏的模式？添加到 `lib/constants.ts`
- **AST 解析。** 超越正则表达式以减少误报
- **更好的正则表达式。** 某些规则可能存在误报/漏报
- **UI 改进。** 仪表板界面可以更好看
- **测试。** 更多边界情况、更多测试文件、更多信心
- **可访问性。** 让仪表板对所有人可用
### 基本规则
- **友善待人。** 我们都在学习。
- **保持简单。** 这个项目故意保持零成本、低依赖。
- **绝不执行代码。** 扫描器绝不能运行被扫描的代码。这是不可谈判的。
- **测试你的修改。** 添加规则就添加测试，修复 Bug 就证明它被修复了。
- **一次只做一件事。** 小的、专注的 PR 更容易被审查
### 分支保护
`main` 分支受到保护。所有变更必须通过 Pull Request 提交，并满足：
- 至少需要 1 次审查
- 过期的审查会在新推送时被清除
- 禁止强制推送
- 禁止删除分支
这不是官僚主义。这是一个安全项目。我们以身作则。
## 开发环境设置
### 先决条件
- Node.js 20+
- Git
- GitHub 账户（用于测试提交流程）
### 环境变量
创建 `.env.local` 文件：
```
# 可选：仅适用于 Web 仪表板的提交按钮
GH_TOKEN=your_github_personal_access_token
# 可选：默认为此仓库
GITHUB_OWNER=mamabearmehmi-hub
GITHUB_REPO=skill-sentry
```
CLI（`npx skill-sentry`）不需要任何环境变量。它使用本地的 `git clone` 或 GitHub API 的 tarball 下载（可通过可选的 `GH_TOKEN` 提高速率限制）。
## 贡献者
## 许可证
MIT 许可证。使用它、分支它、改进它。只需继续安全地构建。
纯静态分析。永不执行代码。永远。
由一位关心安全的 Claude 构建者构建——只希望能安心点击安装。
标签：Claude, CVE检测, JSONLines, LNA, MCP, MITM代理, npm安全, npx, postinstall脚本, SEO: Skill Sentry, SEO: 安全扫描工具, SEO: 开源安全工具, 云安全监控, 前端安全, 威胁情报, 安全威胁, 安全扫描, 开发者工具, 技能安装, 技能扫描, 时序注入, 自动化攻击, 零信任, 静态分析, 风险评分