agentverus/agentverus-scanner
GitHub: agentverus/agentverus-scanner
一款面向 AI Agent 技能文件的专项安全扫描器，可检测提示词注入、数据窃取等 11 类 ASST 威胁并生成结构化信任报告。
Stars: 5 | Forks: 1
# AgentVerus Scanner
面向 AI Agent 技能（`SKILL.md` 及其变体）的开源安全与行为信任扫描器。
[](https://www.npmjs.com/package/agentverus-scanner)
[](./LICENSE.md)
[](https://github.com/agentverus/agentverus-scanner/releases/latest)
/
# JSON 输出
npx agentverus scan ./SKILL.md --json
# 用于 GitHub Code Scanning 的 SARIF 输出
npx agentverus scan . --sarif agentverus-scanner.sarif --fail-on-severity high
# 用于供应链审查的 CycloneDX SBOM 输出
npx agentverus scan ./SKILL.md --sbom agentverus-scanner.sbom.json
```
### 检查 ClawHub 技能
通过 Slug 检查 ClawHub 注册表中的任何技能——下载、扫描并打印信任报告：
```
# 检查单个 skill
npx agentverus check web-search
# 检查多个 skill
npx agentverus check git-commit docker-build
# JSON 输出
npx agentverus check web-search --json
```
### 注册表扫描
批量扫描整个注册表，生成报告并构建静态仪表板：
```
# 扫描 registry 中的所有 skill（4,929 个 skill，50x 并发约 100 秒）
npx agentverus registry scan --concurrency 50
# 生成 markdown 分析报告
npx agentverus registry report
# 生成交互式 HTML 仪表板
npx agentverus registry site --title "ClawHub Security Analysis"
```
注册表扫描选项：
- `--urls ` — 技能 URL 列表的路径（默认：`data/skill-urls.txt`）
- `--out ` — 输出目录（默认：`data/scan-results`）
- `--concurrency ` — 并行下载数（默认：25）
- `--limit ` — 仅扫描前 N 个技能（用于测试）
退出代码：
- `0`：扫描通过
- `1`：扫描完成但策略检查失败
- `2`：一个或多个目标扫描失败（结果不完整）
## GitHub Action
使用捆绑的 Action 在 PR 中扫描 `SKILL.md` 并将 SARIF 上传至 GitHub Code Scanning：
```
name: Skill Trust Scan
on:
pull_request:
push:
branches: [main]
jobs:
scan:
runs-on: ubuntu-latest
permissions:
contents: read
security-events: write
steps:
- uses: actions/checkout@v4
# Pin to a release tag or SHA for supply-chain safety and reproducibility.
- uses: agentverus/agentverus-scanner/actions/scan-skill@v0.3.0
with:
target: .
fail_on_severity: high
upload_sarif: true
```
## 信任等级徽章 (GitHub Pages)
生成**仓库级别**和**单个技能**的信任等级徽章，格式为 [Shields.io endpoint](https://shields.io/endpoint) JSON：
```
# 写入：
# - badges/repo-certified.json
# - badges/repo-certified-pct.json
# - badges/skills/.json
npx agentverus scan . --badges
```
徽章含义：
- `repo-certified.json` — 仅当仓库中*所有*技能均为 `CERTIFIED`（且无扫描失败）时才为 **CERTIFIED**。否则为 **NOT CERTIFIED**。
- `repo-certified-pct.json` — `CERTIFIED` 技能的百分比（例如 `Certified 83%`）。
- `skills/.json` — 单个技能徽章（权威）。`slug` 源自被扫描文件的路径（例如 `skills/web-search/SKILL.md` → `skills--web-search--SKILL.md.json`）。
嵌入到你的 README 中（示例 URL 假设你将 `badges/` 目录部署为 **GitHub Pages 站点根目录**）：
```
```
单个技能徽章：
```
```
要通过 GitHub Pages 发布，请在推送到 `main` 分支时运行徽章生成，并部署 `badges/` 目录：
```
name: Publish AgentVerus Badges
on:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npx agentverus scan . --badges
- uses: actions/upload-pages-artifact@v3
with:
path: badges
deploy:
needs: build
runs-on: ubuntu-latest
steps:
- uses: actions/deploy-pages@v4
```
## 能力合约
AgentVerus 将**声明的意图**与**推断的运行时行为**进行对比。
- 声明来源：
- Frontmatter 中的权限声明（例如 `permissions: - network: "..."`）
- 框架权限列表（`permissions: [network_restricted, read]`）
- 推断来源：
- 声明的工具/权限
- 指令/内容中的行为模式
- 扫描期间提取的依赖指标
如果推断出高风险行为但未声明，扫描器会添加明确的 `PERM-CONTRACT-MISSING-*` 发现结果。这使得声明偏差在审查和 CI 过程中可见。
## SBOM 输出
`--sbom` 会写入一个 CycloneDX 1.5 JSON 文档，包含：
- 扫描器元数据和版本
- 每个目标的技能组件
- 从扫描证据中提取的依赖指标组件
- 技能 → 依赖关系
这旨在为治理和发布检查提供供应链**基础工作**。
## MCP Server (Agent 集成)
如需通过 MCP 进行 Agent/框架集成，请使用配套包：
```
npx -y agentverus-scanner-mcp
```
## 编程方式使用
```
import { buildSbomDocument, scanSkill, scanSkillFromUrl } from "agentverus-scanner";
const report1 = await scanSkill("# My Skill\\n...");
console.log(report1.overall, report1.badge);
const report2 = await scanSkillFromUrl("https://raw.githubusercontent.com/user/repo/main/SKILL.md", {
timeout: 30_000,
retries: 2,
retryDelayMs: 750
});
console.log(report2.metadata.skillFormat, report2.findings.length);
const sbom = buildSbomDocument([{ target: "./SKILL.md", report: report1 }]);
console.log(sbom.bomFormat, sbom.components.length);
```
## 信任评分
总分是各类别分数的加权平均值：
| Category | Weight |
|----------|--------|
| Permissions | 20% |
| Injection | 25% |
| Dependencies | 15% |
| Behavioral | 15% |
| Content | 10% |
| Code Safety | 15% |
## 徽章等级
徽章等级规则：
- 任何 **critical**（严重）发现：`REJECTED`
- 分数 `< 50`：`REJECTED`
- 分数 `50–74`：`SUSPICIOUS`
- 分数 `75–89` 且 `<= 2` 个高危发现：`CONDITIONAL`
- 分数 `>= 90` 且 `0` 个高危发现：`CERTIFIED`
## ASST 分类法
发现结果引用了 AgentVerus 技能安全分类法：
- **ASST-01**: 指令注入
- **ASST-02**: 数据窃取
- **ASST-03**: 权限提升
- **ASST-04**: 依赖劫持
- **ASST-05**: 凭证窃取
- **ASST-06**: Prompt 注入中继
- **ASST-07**: 欺骗性功能
- **ASST-08**: 过度权限
- **ASST-09**: 缺失安全边界
- **ASST-10**: 混淆
- **ASST-11**: 触发器操纵
## 开发
```
pnpm install
pnpm typecheck
pnpm test
pnpm lint
# 构建 action bundle（写入 actions/scan-skill/dist/index.cjs）
pnpm build:actions
```
## 贡献
我们欢迎各种贡献！请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md) 了解以下准则：
- 报告 Bug 和误报
- 添加或改进检测规则
- 编写测试和固定数据
- Pull Request 流程
## 更新日志
查看 [CHANGELOG.md](./CHANGELOG.md) 获取完整的变更历史。
## 许可证
MIT — 详见 [LICENSE.md](./LICENSE.md)。
标签：AI代理, AI基础设施安全, AI安全, ASST威胁, Chat Copilot, DevSecOps, DNS 反向解析, DNS 解析, IP 地址批量处理, MITM代理, NPM包, OSV-Scalibr, RASP, WebSocket, 上游代理, 云安全监控, 依赖分析, 信任边界, 开源安全工具, 技能验证, 提示词注入检测, 数据渗漏, 文档结构分析, 权限分析, 混淆检测, 社会工程学检测, 自动化攻击, 逆向工程平台, 配置篡改检测, 防病毒, 隐蔽威胁, 静态分析, 风险评分