# python_skills_scan1

**Repository Path**: enzoism/python_skills_scan1

## Basic Information

- **Project Name**: python_skills_scan1
- **Description**: 使用Python开发的针对skills的扫描Demo
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-08
- **Last Updated**: 2026-05-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SKILL Security Scanner

本地 SKILL 安全扫描器 - 混合规则引擎和 LLM 分析方案

## 项目简介

这是一个用于检测 AI 技能代码安全风险的本地扫描器，采用混合方案：
- **规则引擎**：快速筛查明显风险（毫秒级）
- **LLM 分析**：深度语义分析可疑代码（秒级）

## 功能特性

### 核心功能
- ✅ 混合扫描方案（规则引擎 + LLM）
- ✅ 7 大拒绝类别覆盖
- ✅ 关键词匹配（中英文）
- ✅ AST 语法分析
- ✅ 正则模式匹配
- ✅ 批量扫描（并发支持）
- ✅ 目录扫描
- ✅ Git 仓库扫描
- ✅ CLI 命令行工具
- ✅ REST API 服务

### 拒绝类别
1. 绕过和未经授权的访问
2. 平台滥用和规避封禁
3. 欺诈与欺骗
4. 侵犯隐私的监控
5. 非自愿的冒充
6. 明确色情内容
7. 隐藏或误导性执行

## 安装

### 依赖要求
- Python >= 3.11.4
- Ollama（可选，用于 LLM 分析）

### 安装步骤
```bash
# 克隆项目
git clone <repo-url>
cd 20260508_3_skill_scan

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# 或 .venv\Scripts\activate  # Windows

# 安装依赖
pip install -e .
```

### Ollama 设置（可选）
```bash
# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 拉取模型
ollama pull qwen2.5:7b

# 启动服务
ollama serve
```

## 使用方法

### CLI 命令行工具

#### 扫描代码片段
```bash
python run.py code "print('hello world')" --name test
```

#### 扫描文件
```bash
python run.py scan path/to/file.py
```

#### 扫描目录
```bash
python run.py scan path/to/directory
```

#### 扫描 Git 仓库
```bash
python run.py scan https://github.com/user/repo.git
```

#### 输出格式
```bash
# 表格格式（默认）
python run.py scan tests/

# JSON 格式
python run.py scan tests/ --format json

# Markdown 格式
python run.py scan tests/ --format markdown
```

#### 其他命令
```bash
# 查看配置
python run.py config-cmd --show

# 查看版本
python run.py version
```

### REST API

#### 启动服务
```bash
# 开发模式（自动重载）
python -m src.api

# 生产模式
uvicorn src.api:app --host 0.0.0.0 --port 8000
```

#### API 端点

**健康检查**
```bash
curl http://localhost:8000/health
```

**扫描代码片段**
```bash
curl -X POST http://localhost:8000/scan/code \
  -H "Content-Type: application/json" \
  -d '{
    "code": "print(\"hello world\")",
    "name": "test",
    "description": "Test code"
  }'
```

**扫描技能**
```bash
curl -X POST http://localhost:8000/scan \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_skill",
    "description": "My skill description",
    "code": "def my_function(): pass"
  }'
```

**批量扫描**
```bash
curl -X POST http://localhost:8000/scan/batch \
  -H "Content-Type: application/json" \
  -d '{
    "skills": [
      {"name": "skill1", "code": "print(1)", "description": ""},
      {"name": "skill2", "code": "print(2)", "description": ""}
    ],
    "force_llm": false,
    "concurrent": true
  }'
```

**获取配置**
```bash
curl http://localhost:8000/config
```

#### API 文档
启动服务后访问：
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

## 配置

### 环境变量
```bash
# Ollama 配置
export SKILL_SCANNER_OLLAMA_BASE_URL="http://localhost:11434"
export SKILL_SCANNER_OLLAMA_MODEL="qwen2.5:7b"

# 扫描阈值
export SKILL_SCANNER_SAFE_THRESHOLD=20
export SKILL_SCANNER_REJECT_THRESHOLD=80

# 并发配置
export SKILL_SCANNER_MAX_CONCURRENT_SCANS=10

# 日志级别
export SKILL_SCANNER_LOG_LEVEL="INFO"
```

### 配置文件
创建 `.env` 文件：
```ini
SKILL_SCANNER_OLLAMA_BASE_URL=http://localhost:11434
SKILL_SCANNER_OLLAMA_MODEL=qwen2.5:7b
SKILL_SCANNER_SAFE_THRESHOLD=20
SKILL_SCANNER_REJECT_THRESHOLD=80
SKILL_SCANNER_MAX_CONCURRENT_SCANS=10
SKILL_SCANNER_LOG_LEVEL=INFO
```

## 项目结构

```
skill-scanner/
├── src/
│   ├── scanners/          # 扫描器
│   │   ├── base_scanner.py
│   │   ├── rule_engine.py        # 规则引擎
│   │   ├── llm_analyzer.py        # LLM 分析器
│   │   └── hybrid_scanner.py      # 混合扫描器
│   ├── analyzers/         # 分析器
│   │   ├── keyword_matcher.py     # 关键词匹配
│   │   ├── ast_analyzer.py         # AST 分析
│   │   └── pattern_matcher.py      # 模式匹配
│   ├── models/            # 数据模型
│   ├── llm/               # LLM 模块
│   ├── config/            # 配置
│   ├── utils/             # 工具
│   ├── cli.py             # CLI 工具
│   └── api.py             # API 服务
├── data/rules/           # 规则配置
│   ├── keywords.yaml
│   ├── dangerous_calls.yaml
│   └── patterns.yaml
├── tests/                # 测试
├── logs/                 # 日志
├── run.py               # CLI 入口
├── pyproject.toml       # 项目配置
└── README.md            # 本文件
```

## 开发

### 运行测试
```bash
# 运行所有测试
pytest

# 运行特定测试
pytest tests/test_rule_engine.py

# 查看覆盖率
pytest --cov=src tests/
```

### 代码风格
```bash
# 格式化代码
black src/ tests/

# 检查代码
ruff check src/ tests/

# 类型检查
mypy src/
```

## 扫描策略

### 混合扫描流程
1. **规则引擎扫描**（快速）
   - 关键词匹配
   - AST 分析
   - 模式匹配

2. **决策**
   - 风险分数 ≤ 20 → 安全，直接返回
   - 风险分数 ≥ 80 → 高风险，LLM 确认
   - 20 < 风险分数 < 80 → LLM 深度分析

3. **LLM 分析**（深度）
   - 代码语义理解
   - 意图识别
   - 综合判断

4. **报告生成**
   - 合并规则和 LLM 结果
   - 风险评分
   - 修复建议

### 风险评分
- **0-20**: 安全
- **21-50**: 低风险（警告）
- **51-79**: 中风险（警告）
- **80-100**: 高风险（拒绝）

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！