aig-skill-scan 0.1.0

AI Native Agent Skill 安全审计工具 —— LLM 驱动的多阶段代码审计与漏洞复审流水线

Skill-Scan

AI Native Agent Skill 安全审计工具 —— LLM 驱动的多阶段代码审计与漏洞复审流水线。

skill-scan 是 Tencent AI-Infra-Guard 的子项目，专门用于对 AI Agent Skill 项目（如 WorkBuddy Skill、Coze 插件、Dify 工具等）进行静态安全审计。它通过三阶段流水线对 Skill 代码进行 LLM 驱动的深度分析：

1. Info Collection —— 项目结构、语言、入口点识别
2. Code Audit —— 多技能并行审计（数据泄露、工具滥用、间接注入、越权等）
3. Vulnerability Review —— 漏洞去重、误报过滤、严重度评分、报告生成

漏洞分类对齐 SkillTrustBench T01–T09 分类法，判定标准：malicious（明确攻击意图）/ suspicious（有漏洞但无明确攻击意图）/ normal（良性）。

---

安装

# 从 PyPI 安装
pip install aig-skill-scan

# 或从源码安装（开发态）
git clone https://github.com/Tencent/AI-Infra-Guard.git
cd AI-Infra-Guard/skill-scan
pip install -e .

要求 Python ≥ 3.12。

---

快速开始

命令行

# 扫描一个本地 Skill 项目目录
skill-scan --repo /path/to/your/skill \
           -m deepseek/deepseek-v3.2-exp \
           -k $OPENROUTER_API_KEY \
           -u https://openrouter.ai/api/v1 \
           --language zh

# 也可以用模块方式调用
python -m skill_scan --repo /path/to/your/skill -k $OPENROUTER_API_KEY

完整参数：

skill-scan --help

参数	说明	默认值
--repo	要扫描的 Skill 项目文件夹路径（必填）	—
-m, --model	LLM 模型名称	deepseek/deepseek-v3.2-exp
-k, --api_key	API Key（不传则从环境变量读取）	—
-u, --base_url	API 基础 URL	https://openrouter.ai/api/v1
-p, --prompt	自定义扫描提示词（可选）	—
--language	输出语言：zh / en	zh
--debug	启用 debug 模式	false

程序化调用

import asyncio
from skill_scan.agent.agent import Agent
from skill_scan.utils.llm import LLM
from skill_scan.utils.llm_manager import LLMManager

async def run():
    llm = LLM(model="deepseek/deepseek-v3.2-exp",
              api_key="sk-...",
              base_url="https://openrouter.ai/api/v1",
              context_window=128_000)
    mgr = LLMManager(api_key="sk-...", base_url="https://openrouter.ai/api/v1")
    specialized = mgr.get_specialized_llms(["thinking", "coding"])

    agent = Agent(llm=llm, specialized_llms=specialized,
                  debug=False, language="zh")
    result = await agent.scan("/path/to/your/skill", "", "zh")
    print(result)

asyncio.run(run())

---

配置

所有配置通过环境变量或 .env 文件注入。skill-scan 会按以下顺序查找 .env：

1. 包根目录（site-packages/skill_scan/.env，安装态一般不用）
2. 当前工作目录（./.env，推荐）

主要环境变量：

变量	说明	默认值
OPENROUTER_API_KEY / LLM_API_KEY / OPENAI_API_KEY	LLM API Key	—
LLM_MODEL / OPENAI_MODEL	默认模型	deepseek/deepseek-v3.2-exp
LLM_BASE_URL / OPENAI_BASE_URL	默认 Base URL	https://openrouter.ai/api/v1
DEFAULT_MODEL_CONTEXT_WINDOW	主模型上下文窗口	128000
THINKING_MODEL / CODING_MODEL / FAST_MODEL	专用模型	gemini-2.5-pro / claude-sonnet-4.5 / gemini-2.0-flash-exp
LOG_LEVEL	日志级别	INFO

---

架构

skill_scan/
├── agent/              # 三阶段 ScanPipeline 编排
│   ├── agent.py        # Agent 主类，调度 Info→Audit→Review
│   └── base_agent.py   # LLM 循环 + 工具调用基类
├── tools/              # XML-schema 工具注册表
│   ├── registry.py     # @register_tool 装饰器
│   ├── dispatcher.py   # ToolDispatcher，工具调用分发
│   ├── file/ ls/ grep/ dir/ base64_decode/ thinking/ finish/
│   └── *_schema.xml    # 工具的 XML schema（给 LLM 看）
├── utils/
│   ├── llm.py          # OpenAI 兼容客户端
│   ├── llm_manager.py  # 多角色 LLM 管理（thinking/coding/fast）
│   ├── prompt_manager.py# prompt 模板加载（从 skill_scan/prompt/）
│   ├── extract_vuln.py # <vuln> XML 提取与解析
│   ├── project_analyzer.py # 语言识别 + calc_skill_score
│   └── pre_scan.py     # 预扫描，生成项目概要
├── prompt/             # 打包的 prompt 模板
│   ├── system_prompt.md
│   ├── compact.md  next_prompt.md  format_report.md
│   └── agents/         # 各阶段专用 prompt
└── main.py             # CLI 入口（cli / main / parse_args）

---

漏洞评分

calc_skill_score 对齐 mcp-scan 的 calc_mcp_score：

严重度	扣分
Critical	-100
High	-40
Medium	-25
Low / Info	-10

最终 skill 分数 = max(0, 100 - Σ扣分)。

---

开发

# 安装开发依赖
pip install -e ".[dev]"

# lint / format
ruff check skill_scan
ruff format skill_scan

# 本地构建
python -m build

# 本地安装测试
pip install dist/skill_scan-0.1.0-py3-none-any.whl
skill-scan --help

---

License

Apache License 2.0。任何再分发或衍生作品必须在文档或界面中明确标注 "Based on Tencent Zhuque Lab AI-Infra-Guard" 并附上原仓库链接 https://github.com/Tencent/AI-Infra-Guard，详见 NOTICE。