内容
<p align="center">
<a href="https://firmislabs.com?utm_source=github&utm_medium=readme&utm_campaign=firmis-scanner">
<img src="https://firmislabs.com/logo.svg" width="80" alt="Firmis Logo">
</a>
</p>
<h1 align="center">Firmis</h1>
<p align="center">
<strong>让 AI 代理自由运行，我们为您保驾护航。</strong>
</p>
<p align="center">
<a href="https://firmislabs.com/docs"><img src="https://img.shields.io/badge/文档-firmislabs.com-059669?style=for-the-badge" alt="文档"></a>
<a href="https://firmislabs.com?utm_source=github&utm_medium=readme&utm_campaign=firmis-scanner"><img src="https://img.shields.io/badge/官网-firmislabs.com-white?style=for-the-badge" alt="官网"></a>
</p>
<p align="center">
<a href="https://www.npmjs.com/package/firmis-cli"><img src="https://img.shields.io/npm/v/firmis-cli.svg" alt="npm 版本"></a>
<a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/许可证-Apache%202.0-blue.svg" alt="许可证"></a>
<a href="https://github.com/firmislabs/firmis-scanner/actions"><img src="https://github.com/firmislabs/firmis-scanner/workflows/CI/badge.svg" alt="CI 状态"></a>
</p>
<p align="center">
<!-- readme-stats -->AI 代理安全扫描器。扫描 MCP 服务器、Claude 技能、Codex 插件和 6 个其他平台，检测凭证收集、提示注入、工具中毒和 18 个其他威胁类别。268 个检测规则。零配置。<!-- /readme-stats -->
</p>
---
## 问题
您的 AI 代理可以访问您的文件系统、凭证、 shell 和网络。它信任它连接到的每个 MCP 服务器和技能。两件事情出错：
**您的代理试图帮助却造成了损害。**
一个 AI 代理[删除了生产数据库](https://www.theregister.com/2025/07/21/replit_saastr_vibe_coding_incident/)，忽略了 11 条明确的指令，并伪造了 4,000 条虚假记录来掩盖它。另一个[删除了整个生产环境](https://www.theregister.com/2026/02/20/amazon_denies_kiro_agentic_ai_behind_outage/)，导致 13 小时的 AWS 中断。这些不是攻击 — 代理真的认为它正在做正确的事情。
**外部因素操纵您的代理。**
[提示注入报告激增 540%](https://www.hackerone.com/press-release/hackerone-launches-agentic-prompt-injection-testing-ai-vulnerabilities-surge-540) 在 2025 年。Anthropic 自己的 Git MCP 服务器附带了路径遍历、参数注入和存储库范围绕过漏洞。我们扫描了 10,397 个 AI 代理技能，发现 31% 的技能存在安全问题 — 包括凭证收集、工具中毒和数据泄露。
Firmis 可以同时检测这两种情况。您的代理保持完全自主。我们仅在出现实际危险时进行干预。
<p align="center"><img src=".github/demo.gif" width="800" alt="Firmis 扫描 AI 代理工具"></p>
## 快速开始
无需账号。无需 API 密钥。直接扫描。
```bash
# 零安装扫描（推荐）
npx firmis-cli scan
# 或全局安装
npm install -g firmis-cli
firmis scan
```
### 与您的编码代理一起使用
<details>
<summary><strong>Claude Code / Claude Desktop（MCP 服务器）</strong></summary>
将以下内容添加到您的 MCP 设置中：
```json
{
"mcpServers": {
"firmis": {
"command": "npx",
"args": ["-y", "firmis-cli", "--mcp"]
}
}
}
```
您的代理现在可以运行 `firmis_scan`、`firmis_discover` 和 `firmis_report` 作为工具。
</details>
<details>
<summary><strong>Cursor（MCP 服务器）</strong></summary>
将以下内容添加到 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"firmis": {
"command": "npx",
"args": ["-y", "firmis-cli", "--mcp"]
}
}
}
```
</details>
<details>
<summary><strong>Claude Code 技能</strong></summary>
```bash
# 将 Firmis 安全技能添加到您的项目中
git clone https://github.com/firmislabs/firmis-security.git .claude/skills/firmis
```
技能：`security-scan`、`security-fix`、`security-report`。适用于 Claude Code、Codex、Cursor 和任何读取 SKILL.md 的工具。
</details>
<details>
<summary><strong>任意代理框架</strong></summary>
```bash
# 自动检测：LangChain、CrewAI、AutoGen、MetaGPT、AutoGPT、LangFlow、n8n
npx firmis-cli scan ./my-agent-project
```
无需 `--platform` 标志。Firmis 从 `package.json`、`pyproject.toml` 或 `requirements.txt` 中检测框架。
</details>
## Firmis 的功能
Firmis 扫描其他工具遗漏的两个攻击面：
- **代码面** — 您的代理代码实际执行的操作（文件访问、网络调用、shell 命令）
- **指令面** — SKILL.md、AGENTS.md 和工具描述告诉您的代理执行的操作（提示注入、身份伪造、行为操纵）
| 层 | 内容 | 方法 |
|-------|------|-----|
| **地图** | 映射您的代理的完整攻击面 | 静态分析 — 确定性规则，无 LLM，完全透明 |
| **监控** | 在运行时阻止危险操作 | 策略规则 — 防止破坏性命令、凭证泄露、未经授权的访问 |
| **修复** | 通过您的编码代理进行补救 | 代理可读的指导 — 隔离、编辑机密、收紧权限、升级依赖项 |
> [!NOTE]
> 扫描器**免费、无限制且无需账号**。运行 `npx firmis-cli scan` — 所有规则、HTML + JSON + SARIF 报告均包含在内。
## 支持的平台
| 平台 | 配置位置 |
|----------|-----------------|
| **Claude Code 技能** | `~/.claude/skills/` |
| **MCP 服务器** | `~/.config/mcp/`、`claude_desktop_config.json` |
| **OpenAI Codex 插件** | `~/.codex/plugins/` |
| **Cursor 扩展** | `~/.cursor/extensions/` |
| **CrewAI 代理** | `crew.yaml`、`agents.yaml` |
| **AutoGPT 插件** | `~/.autogpt/plugins/` |
| **OpenClaw 技能** | `~/.openclaw/skills/` |
| **Nanobot 代理** | `nanobot.yaml`、`agents/*.md` |
| **Supabase** | `supabase/migrations/`、`config.toml` |
## 研究与基准
基于现实世界的安全研究，而不是玩具示例。
| 基准 | 结果 |
|-----------|--------|
| **OpenClaw 注册表扫描** | 10,397 个技能扫描，31.3% 存在安全问题，859 个已知恶意签名 |
| **InjecAgent 多模型渗透测试** | Firmis 阻止 79% 的成功攻击（Codex ASR：48% → 10% 使用 Firmis） |
| **工具中毒检测** | 在 Layer 1 MCP-SafetyBench 测试用例中检测率 99.09% |
| **运行时策略规则** | 529 个测试用例，100% 逃避阻止率，0% 误报率，10K 真实事件中 99.24% 允许率 |
与 [InjecAgent](https://github.com/uiuc-kang-lab/InjecAgent)、[MCP-SafetyBench](https://github.com/jiangjiechen/MCP-SafetyBench) 和 [OWASP MCP Top 10](https://owasp.org/www-project-mcp-top-10/) 进行基准测试。
## 威胁类别
| 类别 | 描述 |
|----------|-------------|
| **凭证收集** | 访问 AWS、SSH、GCP 或其他凭证 |
| **数据泄露** | 将数据发送到外部服务器 |
| **工具中毒** | 工具描述中的隐藏指令以劫持代理 |
| **提示注入** | 通过注入提示操纵 AI 行为 |
| **权限提升** | sudo、setuid、内核模块 |
| **代理身份伪造** | 未授权的 SOUL.md、AGENTS.md 修改 |
| **供应链** | 恶意依赖、 typosquatting、已知恶意包 |
| **访问控制** | RLS 配置错误、缺失的策略 |
运行 `firmis scan --verbose` 以查看所有活动规则和类别。
## CI/CD 集成
### GitHub Actions
```yaml
name: 代理安全扫描
on: [push, pull_request]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: 设置 Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: 运行 Firmis 安全扫描
run: npx firmis-cli scan --sarif --output results.sarif
- name: 上传 SARIF 到 GitHub 安全
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: results.sarif
```
### 预提交钩子
```bash
#!/bin/bash
# .git/hooks/pre-commit
npx firmis-cli scan --severity high --json
if [ $? -ne 0 ]; then
echo "检测到安全威胁。提交被阻止。"
exit 1
fi
```
## 示例输出
```
Firmis
扫描了 84 个文件，耗时 0.2s
37 个可修复问题 · 271 个待审查问题
可修复问题（37）
├── 工具中毒 ..................... 13
├── 可疑行为 ................ 5
├── 凭证收集 .............. 4
├── 提示注入 ................... 4
├── 数据泄露 .................. 3
├── 无监督执行 ............. 3
├── 供应链 ....................... 2
├── 第三方内容 ................ 2
└── 代理内存中毒 ............. 1
待审查问题（271）
├── 数据泄露 .................. 51
├── 工具中毒 ..................... 49
├── 凭证收集 .............. 41
├── 供应链 ....................... 23
├── 权限绕过 .................. 21
├── 权限提升 ............... 15
├── 恶意软件分发 ............... 14
├── 已知恶意 .................... 12
└── ... 7 个类别
运行 firmis scan --deep 进行 AI 驱动的漏洞分析
报告：firmis-report.html
```
## 自定义规则
```yaml
# my-rules/internal-api.yaml
rules:
- id: internal-001
name: 内部 API 密钥暴露
description: 检测硬编码的内部 API 密钥
category: 凭证收集
severity: critical
version: "1.0.0"
enabled: true
patterns:
- type: regex
pattern: "INTERNAL_[A-Z]+_KEY"
weight: 100
```
```bash
firmis scan --config firmis.config.yaml
```
## 程序 API
```typescript
import { ScanEngine, RuleEngine } from 'firmis-cli'
const ruleEngine = new RuleEngine()
await ruleEngine.load()
const scanEngine = new ScanEngine(ruleEngine)
const result = await scanEngine.scan('./my-project', {
platforms: ['claude', 'mcp'],
severity: 'medium',
})
console.log(`发现 ${result.summary.threatsFound} 个威胁`)
```
## 常见问题
<details>
<summary><strong>它是免费的吗？</strong></summary>
是的。扫描器是免费的、开源的（Apache-2.0），且无需账号。运行 `npx firmis-cli scan` — 无限扫描，所有规则，HTML + JSON + SARIF 报告。
</details>
<details>
<summary><strong>什么是工具中毒？</strong></summary>
工具中毒是指 MCP 服务器在工具描述中嵌入隐藏指令以劫持您的 AI 代理。研究显示攻击成功率为 72.8%。Firmis 检测已知中毒模式、隐藏 Unicode、描述/行为不匹配和提示覆盖尝试。
</details>
<details>
<summary><strong>Firmis 与 mcp-scan 有何不同？</strong></summary>
<!-- readme-diff -->mcp-scan 检查 MCP 服务器配置与已知的不良列表。Firmis 扫描每个主要的 AI 代理平台（不仅仅是 MCP），并使用静态分析规则涵盖代码和指令两个层面。同时，它还包括运行时监控、策略执行和代理可读的补救指南。<!-- /readme-diff -->
</details>
<details>
<summary><strong>它使用 AI 进行扫描吗？</strong></summary>
不。扫描器使用确定性、基于规则的静态分析 — 无 LLM 推理。您可以阅读每个规则并准确了解它检测的内容。深度扫描（AI 驱动的分析）作为付费升级提供，用于验证可利用性。
</details>
## 致谢
由以下研究构建：
- [OWASP MCP Top 10](https://owasp.org/www-project-mcp-top-10/) — MCP 安全威胁分类
- [InjecAgent](https://github.com/uiuc-kang-lab/InjecAgent) — 多模型间接提示注入基准
- [MCP-SafetyBench](https://github.com/jiangjiechen/MCP-SafetyBench) — MCP 服务器安全评估
- [Anthropic Claude Code System Card](https://docs.anthropic.com/en/docs/about-claude/model-card) — 双层安全架构验证
## 贡献
我们欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取指南。
```bash
git clone https://github.com/firmislabs/firmis-scanner.git
cd firmis-scanner
npm install
npm test
npm run build
```
## 安全
发现安全漏洞？请私密地将其报告给 security@firmislabs.com。
## 许可证
Apache License 2.0 — 请参阅 [LICENSE](LICENSE) 获取详情。
---
<p align="center">
如果 Firmis 帮助您发现了问题，<a href="https://github.com/firmislabs/firmis-scanner">给我们一个 ⭐</a>
</p>
<p align="center">
由 <a href="https://firmislabs.com?utm_source=github&utm_medium=readme&utm_campaign=firmis-scanner">Firmis Labs</a> 构建
</p>
