Metadata-Version: 2.4
Name: aig-skill-scan
Version: 0.1.0
Summary: AI Native Agent Skill 安全审计工具 —— LLM 驱动的多阶段代码审计与漏洞复审流水线
Author-email: Tencent Zhuque Lab <ai-infra-guard@tencent.com>
Maintainer: Tencent Zhuque Lab
License: Apache-2.0
Project-URL: Homepage, https://github.com/Tencent/AI-Infra-Guard
Project-URL: Repository, https://github.com/Tencent/AI-Infra-Guard
Project-URL: Documentation, https://github.com/Tencent/AI-Infra-Guard/tree/main/skill-scan
Project-URL: Bug Tracker, https://github.com/Tencent/AI-Infra-Guard/issues
Project-URL: Source Code, https://github.com/Tencent/AI-Infra-Guard/tree/main/skill-scan
Keywords: ai-security,agent-security,skill-scan,red-team,llm,audit,vulnerability,ai-infra-guard
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: loguru==0.7.3
Requires-Dist: openai==2.8.1
Requires-Dist: pydantic==2.12.4
Requires-Dist: python-dotenv==1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: ruff>=0.11.5; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# Skill-Scan

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

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

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

漏洞分类对齐 [SkillTrustBench](https://github.com/Tencent/AI-Infra-Guard) T01–T09 分类法，判定标准：`malicious`（明确攻击意图）/ `suspicious`（有漏洞但无明确攻击意图）/ `normal`（良性）。

---

## 安装

```bash
# 从 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。

---

## 快速开始

### 命令行

```bash
# 扫描一个本地 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` |

### 程序化调用

```python
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 - Σ扣分)`。

---

## 开发

```bash
# 安装开发依赖
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](./NOTICE)。
