# cmic-skill-scanner

**Repository Path**: random_player/cmic-skill-scanner

## Basic Information

- **Project Name**: cmic-skill-scanner
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-08
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# cmic-skill-scanner

Skill 安全扫描器，支持对单个 skill 或批量 skill 目录进行安全审计。

## 引擎模式

默认使用 `auto` 模式：
- 优先使用本地可用的兼容扫描器
- 扫描器不可用、超时或执行失败时自动回退到内置 native 引擎
- 如需保证只运行内置规则，请显式使用 `--engine native`

```bash
skillscan scan /path/to/target                  # 默认 auto：优先兼容扫描器，失败回退 native
skillscan scan /path/to/target --engine native   # 显式使用 native
skillscan scan /path/to/target --engine external # 强制使用兼容扫描器
```

## 常用命令

```bash
skillscan inspect /path/to/target
skillscan scan /path/to/target
skillscan review /path/to/target
skillscan review /path/to/skills --output-dir /tmp/skillscan-out
skillscan benchmark --engine native
skillscan package-skill --binary ./target/release/skillscan --version v0.11.0
```

## 输出说明

- `scan`: 输出扫描结果的原始 JSON。
- `review`: 支持单 skill 和批量目录模式，输出风险评级与发现项摘要。
- `benchmark`: 默认按 `auto` 模式评测；传 `--engine native` 时只评测内置引擎，按 `benign / suspicious / malicious / incomplete` 统计匹配情况。

## 可选兼容扫描器

如需使用兼容的 `skill-scanner`，克隆仓库时一并获取 submodule：

```bash
# 克隆仓库时一并获取 submodule
git clone --recursive ssh://softserve/cmic/cmic-skill-scanner

# 或在已有仓库中初始化
git submodule update --init --recursive
```

`--engine external` 强制使用兼容扫描器，失败时直接报错。

## 兼容扫描器参数

默认启用 behavioral 分析器。可通过 `--scanner-arg` 追加参数：

```bash
skillscan scan /path/to/target --engine external \
  --scanner-arg "--enable-meta"
```

`--scanner-arg` 会原样传给兼容扫描器。不要用它传递本工具的 `--use-llm`：该开关会由
CMIC 统一处理并传给所选引擎。

## LLM 语义分析（可选）

`--use-llm` 支持全部引擎模式：

- `native` 使用内置 OpenAI-compatible 语义分析；
- `external` 和 `auto` 会向兼容的 `skill-scanner` 传递 `--use-llm` 及子进程环境变量
  `SKILL_SCANNER_LLM_BASE_URL`、`SKILL_SCANNER_LLM_MODEL`、`SKILL_SCANNER_LLM_API_KEY`；
- `auto` 在兼容扫描器不可用或执行失败时，以相同配置回退 native LLM。

未配置 `--use-llm` 时，native 输出协议和原有静态扫描保持一致。对于“描述与代码矛盾”、身份伪装、
虚假执行结果等需要语义判断的风险，可以显式启用 OpenAI-compatible 端点：

```bash
skillscan scan /path/to/target --engine native --use-llm \
  --llm-endpoint http://localhost:11434/v1 \
  --llm-model your-model

# 对兼容的 skill-scanner 启用其 LLM analyzer
skillscan scan /path/to/target --engine external --use-llm \
  --llm-endpoint http://localhost:11434/v1 \
  --llm-model your-model
```

也可以用环境变量保存连接信息：`SKILLSCAN_LLM_ENDPOINT`（或
`SKILLSCAN_LLM_BASE_URL`）、`SKILLSCAN_LLM_MODEL`、`SKILLSCAN_LLM_API_KEY`。远端端点会收到
native 的静态 finding 摘要和最多 24 个文本文件的内容（单文件最多 8 KiB、合计最多 64 KiB）；对
`api_key`、`token`、`password`、`secret`、`authorization` 等名称的行会做基础值脱敏。该脱敏不是
完整的敏感信息保证，启用前应确认 endpoint 的信任与数据出境策略。兼容扫描器的发送内容、脱敏、
重试和失败处理由该扫描器定义；CMIC 不会将 API key 写入扫描命令或报告。

- LLM finding 复用原有 `findings` / `EngineReport` JSON 字段，`analyzers_used` 会记录执行的分析器；
- 确定性 HIGH/CRITICAL finding 永不被 LLM 降级；LLM 自身 finding 最高为 MEDIUM。只有有
  直接证据的实质性外部结果伪造、无确认高影响自主行为、虚假安全控制声明或受保护边界规避
  可保留 MEDIUM，其余和未知类别自动降为 LOW；这套归一化规则适用于 native。
- native LLM 端点不可用时，native 静态扫描仍正常返回，原因写入 `engine.fallback_reason`；`auto`
  在兼容扫描器进程失败时回退 native。

## 企业集成

支持批量扫描目录并将结果上报到指定接口：

```bash
skillscan review /srv/skills \
  --output-dir /var/reports/skillscan \
  --upload-url https://scanner.example.com/api/report \
  --instance-id sk-xxxxxxxxxxxxxx
```

环境变量支持：`SKILLSCAN_UPLOAD_URL`、`SKILLSCAN_INSTANCE_ID`、`SKILLSCAN_INSTALL_KEY`。

> 注意：上报到网关时需要鉴权。优先使用 `--install-key`（即安装时颁发的 `sk-` 凭证）作为 `Authorization: Bearer` 的密钥。
> 如果未传 `--install-key`，会 fallback 到 `--instance-id` 作为密钥（兼容旧版）。
> 上报请求会自动带上 `Authorization`、`X-Timestamp`、`X-Nonce` 三个 Header。

详细示例见 `examples/enterprise/`。