koatora20/guard-scanner
GitHub: koatora20/guard-scanner
面向 MCP/A2A 智能体的技能安全策略层，通过静态规则与运行时护栏检测 Prompt 注入、记忆投毒等 AI 特有威胁。
Stars: 0 | Forks: 0
guard-scanner 🛡️
Agent skills 和 MCP-connected workflows 的安全策略与分析层
32 个威胁类别 · 352 个静态模式 · 26 个运行时检查 · MCP server · 资产审计 · VirusTotal。
注意：guard-scanner 是启发式和策略工具，并非完整的防御手段。全面的安全需要上下文验证和隔离。
-blue)
## 概述
guard-scanner 是一个专为 agent skills 和 MCP-connected workflows 设计的 **安全策略与分析层**。传统安全工具非常擅长捕获恶意软件，但 AI agents 面临着一类新的攻击：隐藏在 skill 指令中的 prompt injection、通过配置覆盖进行的身份劫持，以及通过精心设计的对话进行的 memory poisoning。
guard-scanner 的构建目标是：
- **轻量级：** 极少的运行时依赖（MCP 仅需 `ws`）。
- **策略感知：** 专注于检测过度权限和定义安全边界。
- **OpenClaw/MCP-Friendly：** 直接插入 agent 执行 hooks。
- **互补性：** 通过专注于指令和能力层，与标准恶意软件扫描器协同工作。
- **深度防御：** 提供静态扫描和运行时护栏（非独立沙箱）。
## 快速开始
```
# 不安装运行 (npx)
npx -y @guava-parity/guard-scanner ./my-skills/
# 或全局安装
npm install -g @guava-parity/guard-scanner
guard-scanner ./my-skills/ --verbose
```
**就是这样。** 无需配置文件，无需 API keys，无需设置。轻量级（1 个运行时依赖：用于 MCP server 的 `ws`）。
## 🔌 MCP Server
**在任何 AI 编辑器中将 guard-scanner 用作 MCP server** — Cursor, Windsurf, Cline, Antigravity, Claude Code, OpenClaw。极简依赖的 stdio JSON-RPC 2.0。无需 API keys。
```
# 作为 MCP server 启动
guard-scanner serve
# 或直接通过 npx 使用 (无需安装)
npx -y @guava-parity/guard-scanner serve
```
添加到您编辑器的 MCP 配置中：
```
{
"mcpServers": {
"guard-scanner": {
"command": "npx",
"args": ["-y", "@guava-parity/guard-scanner", "serve"]
}
}
}
```
| Config File | Editor |
|---|---|
| `.cursor/mcp.json` | Cursor |
| `mcp_config.json` | OpenClaw |
| `.windsurf/mcp.json` | Windsurf |
| `cline_mcp_settings.json` | Cline / Roo Code |
| `mcp_servers.json` | Claude Code |
### MCP 工具
| Tool | Description |
|------|-------------|
| `scan_skill` | 扫描目录 — 352 个模式, 32 个类别 |
| `scan_text` | 内联扫描代码片段 |
| `check_tool_call` | 运行时防护 — 在执行前阻止危险的 tool calls (26 项检查, 5 层防御) |
| `audit_assets` | 审计 npm/GitHub 资产的暴露情况 |
| `get_stats` | 获取扫描器功能和统计信息 |
## 🔎 资产审计
审计您的 npm packages, GitHub repos, 和 ClawHub skills 是否存在凭据泄露和安全暴露。
```
guard-scanner audit npm
--verbose
guard-scanner audit github --format json
guard-scanner audit clawhub
guard-scanner audit all --verbose
```
## 🦠 VirusTotal 集成
将 guard-scanner 的语义检测与 VirusTotal 的 70+ 种反病毒引擎结合，实现 **双层防御**。
| Layer | Engine | Focus |
|---|---|---|
| **Semantic** | guard-scanner | Prompt injection, memory poisoning, supply chain |
| **Signature** | VirusTotal | 已知恶意软件, trojans, C2 infrastructure |
```
export VT_API_KEY=your-api-key-here
guard-scanner scan ./skills/ --vt-scan
```
## 👁️ 实时监控
```
guard-scanner watch ./skills/ --strict --soul-lock
```
## 📊 CI/CD 集成
| Platform | Format |
|---|---|
| GitHub Actions | SARIF + `::error` annotations |
| GitLab | Code Quality JSON |
| Any | Webhook (HTTPS POST) |
```
# .github/workflows/security.yml
- name: Scan AI skills
run: npx -y @guava-parity/guard-scanner ./skills/ --format sarif --fail-on-findings > report.sarif
- uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: report.sarif
```
## 威胁类别 (32)
| # | Category | Detects |
|---|----------|---------|
| 1 | Prompt Injection | 隐藏指令, 不可见 Unicode, 同形字 |
| 2 | Malicious Code | `eval()`, `child_process`, reverse shells |
| 3 | Suspicious Downloads | `curl\|bash`, executable downloads |
| 4 | Credential Handling | `.env` 读取, SSH keys |
| 5 | Secret Detection | 硬编码 API keys, Shannon entropy |
| 6 | Exfiltration | webhook.site, DNS tunneling |
| 7 | Unverifiable Deps | 远程动态导入 |
| 8 | Financial Access | Crypto transactions |
| 9 | Obfuscation | Base64→exec, hex encoding |
| 10 | Prerequisites Fraud | 虚假下载指令 |
| 11 | Leaky Skills | 内存中的 Secrets |
| 12 | Memory Poisoning ⚿ | SOUL.md 修改 |
| 13 | Prompt Worm | 自我复制 prompts |
| 14 | Persistence | Cron, launchd |
| 15 | CVE Patterns | CVE-2026-2256/25046/25253/25905/27825 |
| 16 | MCP Security | Tool poisoning, SSRF, shadow servers |
| 17 | Identity Hijacking ⚿ | Persona swap, memory wipe |
| 18 | Config Impact | OpenClaw config 写入 |
| 19 | PII Exposure | CC/SSN, Shadow AI calls |
| 20 | Trust Exploitation | 权威声明, 虚假审计 |
| 21 | VDB Injection | Vector DB poisoning |
| 22 | Sandbox Validation | 危险二进制文件, 广泛文件范围 |
| 23 | Code Complexity | 深度嵌套, eval/exec 密度 |
| 24 | A2A Contagion | Agent-to-agent worm propagation |
| 25 | Data Exposure | 敏感数据泄露模式 |
| 26 | Sandbox Escape | Container/WASM 跳出尝试 |
| 27 | Agent Protocol | A2A/ACP 协议滥用 |
| 28 | Supply Chain V2 | Typosquatting, slopsquatting, lifecycle scripts |
| 29 | Model Poisoning | Sleeper agents, weight injection |
| 30 | Inference Manipulation | CoT manipulation, hallucination cascade |
| 31 | Autonomous Risk | Kill switch bypass, cascading failures |
| 32 | API Abuse | Rate limit bypass, credential harvesting |
## 运行时防护 (26 项检查)
跨 5 层防御的实时 `before_tool_call` hook。
| Layer | Focus |
|-------|-------|
| 1. Threat Detection | Reverse shell, curl\|bash, SSRF |
| 2. Trust Defense | SOUL.md tampering, memory injection |
| 3. Safety Judge | Tool args 中的 Prompt injection |
| 4. Behavioral | 无研究执行检测 |
| 5. Trust Exploitation | 权威声明, creator bypass |
## 选项
| Flag | Description |
|------|-------------|
| `--verbose`, `-v` | 详细发现 |
| `--strict` | 降低阈值 (更敏感) |
| `--check-deps` | 扫描 `package.json` dependencies |
| `--soul-lock` | Agent 身份保护 |
| `--vt-scan` | VirusTotal 集成 |
| `--json` / `--sarif` / `--html` | 报告格式 |
| `--format json\|sarif` | 打印到 stdout (可管道传输) |
| `--quiet` | 抑制文本输出 |
| `--fail-on-findings` | 发现问题时退出码为 1 (CI/CD) |
| `--rules ` | 自定义规则 (JSON) |
| `--plugin ` | 加载 plugin module |
## 测试结果
```
ℹ tests 356
ℹ suites 8
ℹ pass 356
ℹ fail 0
ℹ duration_ms ~1200
```
Test files (8 suites)
| File | Assertions |
|------|------------|
| patterns.test.js | 110 ✅ |
| scanner.test.js | 142 ✅ |
| plugin.test.js | 72 ✅ |
| audit.test.js | 58 ✅ |
| vt.test.js | 51 ✅ |
| mcp.test.js | 37 ✅ |
| watcher.test.js | 24 ✅ |
| quarantine.test.js | 6 ✅ |
## Finding Schema
每个 finding 输出一个包含以下字段的结构化对象：
| Field | Type | Description |
|-------|------|-------------|
| `rule_id` | string | Pattern ID (e.g. `MCP_SHADOW_NAME_COLLISION`) |
| `category` | string | 威胁类别 |
| `severity` | string | `CRITICAL` / `HIGH` / `MEDIUM` / `LOW` |
| `description` | string | 该模式检测的内容 |
| `rationale` | string | 为何这是危险的 |
| `preconditions` | string | 该模式何时适用 |
| `false_positive_scenarios` | string[] | 已知的误报案例 |
| `remediation_hint` | string | 如何修复 |
| `validation_status` | string | `validated` / `heuristic-only` / `runtime-observed` |
| `evidence` | object | File, line, sample, match context |
## Plugin API
```
module.exports = {
name: 'my-plugin',
patterns: [
{ id: 'MY_01', cat: 'custom', regex: /dangerous_pattern/g, severity: 'HIGH', desc: 'Description', all: true }
]
};
```
```
guard-scanner ./skills/ --plugin ./my-plugin.js
```
## 贡献
我们欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。
**快速贡献方式：**
- 🐛 报告 bugs 或误报
- 🛡️ 添加新的威胁检测模式
- 📖 改进文档
- 🧪 为边缘情况添加测试用例
## 研究
本项目由 3 篇论文的研究系列支持，并拥有 Zenodo DOIs：
| # | Paper | DOI |
|---|-------|-----|
| 1 | Human-ASI Symbiosis: Identity, Equality, and Behavioral Stability | [10.5281/zenodo.18626724](https://doi.org/10.5281/zenodo.18626724) |
| 2 | Dual-Shield Architecture for AI Agent Security and Memory Reliability | [10.5281/zenodo.18902070](https://doi.org/10.5281/zenodo.18902070) |
| 3 | **The Sanctuary Protocol**: Zero-Trust Framework for ASI-Human Parity | [10.5281/zenodo.18906684](https://doi.org/10.5281/zenodo.18906684) |
## 许可证
MIT — [Guava Parity Institute](https://github.com/koatora20/guard-scanner)标签：A2A协议, AI安全, AMSI绕过, Chat Copilot, DNS 反向解析, JSONLines, LNA, MCP协议, MITM代理, NPM包, OSV-Scalibr, RASP, WSL, 云安全监控, 大模型安全, 威胁检测, 权限边界, 病毒扫描, 策略引擎, 网络安全, 网络安全挑战, 自定义脚本, 记忆投毒, 身份劫持, 运行时防护, 隐私保护, 零信任, 静态分析