pezhik/skilltotal

# SkillTotal [](https://pypi.org/project/skilltotal/) [](https://pypi.org/project/skilltotal/) [](LICENSE) [](https://github.com/pezhik/skilltotal/actions/workflows/ci.yml) **AI 组件安全平台 — 开源 CLI 引擎。** SkillTotal 静态分析 AI 相关组件 — agent 技能/插件、MCP 服务器、npm / Python 包、代码库，以及**你作为归档或文件上传的 AI 生成的项目** — 以便在 安装或信任组件**之前**暴露供应链风险、危险能力、prompt 注入面和数据泄露 路径。将其指向一个路径、git URL、 `npm:` / `pypi:` 包，或项目归档 (`.zip` / `.tar.gz`) / 单个文件。 **在线试用（无需安装，无需账户）：** [www.skilltotal.ai](https://www.skilltotal.ai) — 该网站运行的是相同的引擎。 Prefer the CLI? `pipx install skilltotal` (below). 它**仅分析组件本身** — 绝不分析你的用户、公司、环境、 部署或运行时上下文。每个分数和发现都完全源自 组件内部的文件。 ## 为什么选择 SkillTotal - **100% 本地且离线** — 组件的代码**绝不离开你的机器**。无需账户， 无需 API token，无需云上传（不同于将你的组件发送到后端的云扫描器）。 - **零运行时依赖**，纯 Python 标准库 — 可审计且易于 vendor/air-gap。 - **确定性** — regex + AST，静态引擎中无 LLM；相同的输入总是产生 相同的报告。 - **证据锚定且低误报** — 每个发现都指向确切的 file:line。 - **免费且开源** (Apache-2.0) — 完整的静态报告永久免费。 ## 安装 要求 **Python 3.10+**。零运行时依赖。仅在扫描 远程 URL 时才需要 `git`。 推荐用于 CLI — [pipx](https://pipx.pypa.io)（隔离安装；同样适用于 Debian/Ubuntu，因为裸 `pip install` 会被 PEP 668 阻止）： ``` pipx install skilltotal ``` 或安装到虚拟环境中 / 作为库使用： ``` pip install skilltotal ``` 从源码安装（开发）： ``` pip install -e ".[dev]" ``` ## 用法 ``` # 人类可读报告 skilltotal scan ./path/to/component # 扫描远程仓库（shallow git clone） skilltotal scan https://github.com/owner/repo # 扫描项目归档或单个文件（例如作为 ZIP 下载的 AI 生成项目） skilltotal scan ./my-project.zip skilltotal scan ./app.tar.gz skilltotal scan ./suspicious.py # 扫描来自 registry 的 package（最新或固定版本） skilltotal scan npm:left-pad skilltotal scan npm:left-pad@1.3.0 skilltotal scan pypi:requests skilltotal scan pypi:requests==2.31.0 # 输出 JSON 到 stdout skilltotal scan ./component --json # SARIF 2.1.0（GitHub Code Scanning / IDE） skilltotal scan ./component --sarif --output report.sarif # 将报告写入文件（如果指定 --sarif 则为 SARIF，否则为 JSON） skilltotal scan ./component --output report.json # CI gate：如果任何发现为 high 或 critical，则 exit code 为 2 skilltotal scan ./component --fail-on-high # Baseline：快照当前发现，然后在后续扫描中抑制它们 skilltotal scan ./component --write-baseline .skilltotal-baseline.json skilltotal scan ./component --baseline .skilltotal-baseline.json --fail-on-high # Inventory：发现此机器上已安装的 AI 组件并扫描它们 # （读取 Claude Desktop/Code、Cursor、Windsurf、VS Code、Gemini 的 agent config 和 # local skills；为每个 MCP server 派生 npm:/pypi:/local source 并运行 engine） skilltotal inventory skilltotal inventory --json skilltotal inventory --no-scan # list only, do not scan skilltotal inventory --project . # also include this project's agent configs # 列出所有检测规则 skilltotal rules list skilltotal rules list --json ``` **Baseline** 通过 `(rule id, file, code snippet)` 的稳定指纹抑制发现 — 与行号无关，因此能在编辑后保留。 被抑制的发现会在评分前移除，并且不会影响风险评分。 `python -m skilltotal ...` 与 `skilltotal` 控制台脚本的工作方式完全相同。 ### 退出代码 | Code | Meaning | |------|---------| | 0 | 成功 | | 1 | 用法 / 收集错误（例如：缺少路径，clone 失败） | | 2 | 设置了 `--fail-on-high` 并且产生了严重程度 ≥ high 的发现 | ## 方法论 SkillTotal 对 AI 组件 — MCP 服务器、agent 技能/插件、npm 和 PyPI 包，以及 AI 生成的项目/代码库 — 执行**静态**安全分析。该引擎 结合了能力分析、危险模式检测、权限分析、供应链 （安装时）分析、prompt 面分析和数据流关联（例如，secret 访问结合网络出口）。发现被映射到风险类别，并促成 **0–100 的风险评分**；能力会被报告，但绝不会推高分数 — capability ≠ risk。 不会执行任何内容，也不会调用 LLM，因此结果是确定且可重现的。 ## 检测内容 | Category | Examples | |----------|----------| | Shell 执行 | `subprocess.*`, `os.system`, `child_process.exec` | | 文件系统访问 | `open`, `read_text`/`write_text`, `fs.readFile`/`writeFile` | | 敏感路径 | `~/.ssh`, `~/.aws`, `.env`, `id_rsa`, `credentials`, `secrets` | | 网络出口 | `requests`, `urllib`, `aiohttp`, `fetch`, `axios` | | 安装时执行 | npm `preinstall`/`postinstall`/`prepare`, `setup.py` hooks | | 动态代码执行 | `eval`, `exec`, `compile`, `new Function`, `vm.runInNewContext` | | 混淆 | 解码并执行链，base64 blobs, hex escaping, minification | | MCP 风险 | 清单，危险工具 (shell/fs/network/credential)，服务器命令 | | Prompt 面 | "ignore previous instructions", "reveal system prompt", 数据泄露措辞 | ### 按组件类型的覆盖范围 图例：**✅** 默认针对此组件类型进行分析 · **⚠️** 引擎检测此项，但 该面对于此类型并不常见 — 因此仅当组件实际包含 它时才会被标记（例如：npm/PyPI 包内的 prompt 注入文本） · **❌** 不适用于此类型 · **🚧** 已计划 (SkillTotal Cloud)。 列是 SkillTotal 扫描的组件类型。**AI 项目** = 已扫描的代码库或文件夹 — agent 技能/插件、AI 生成的代码库，或一组 prompts/configs — 且不是已发布的 npm/PyPI 包。 | Category | MCP | npm | PyPI | AI project | |---|---|---|---|---| | Prompt 注入 / 指令覆盖 | ✅ | ⚠️ | ⚠️ | ✅ | | 工具投毒 (MCP 工具元数据) | ✅ | ❌ | ❌ | ⚠️ | | 危险能力 (shell / fs / network) | ✅ | ✅ | ✅ | ⚠️ | | 数据泄露 (secret 访问 + 出口) | ✅ | ✅ | ✅ | ⚠️ | | Secret 窃取 / 敏感路径访问 | ✅ | ✅ | ✅ | ⚠️ | | 动态代码执行 | ✅ | ✅ | ✅ | ⚠️ | | 混淆 (解码并执行) | ✅ | ✅ | ✅ | ✅ | | 隐藏 Unicode 走私 | ✅ | ✅ | ✅ | ✅ | | 嵌入式 secrets (硬编码的 keys/tokens) | ✅ | ✅ | ✅ | ✅ | | 安装时 / 供应链 hooks | ⚠️ | ✅ | ✅ | ❌ | | 过度授权 / 自动批准的工具 | ✅ | ❌ | ❌ | ⚠️ | | 运行时行为分析 | 🚧 | 🚧 | 🚧 | 🚧 | | 沙箱分析 | 🚧 | 🚧 | 🚧 | 🚧 | ### 典型发现 - MCP 工具可以执行任意 shell 命令 - 包从外部 URL 下载并运行代码 - 检测到对凭据位置的访问 (`~/.aws`, `~/.ssh`, `.env`) - 检测到动态代码执行 (`eval` / `exec`) - 工具描述或技能中的 prompt 注入 / 指令覆盖措辞 - 敏感数据访问结合了出站网络出口 - 硬编码的 API keys 或 tokens - 具有自动批准或过度授权工具的 MCP 服务器 ## 不在范围内 SkillTotal 静态分析**单个组件自身的文件**。它不执行代码， 观察运行时行为，或评估你的环境、部署或基础设施。它**不能** 代替： - 渗透测试 - 应用程序安全 评估 - 架构 / 设计审查 - 云安全或基础设施评估 - Kubernetes / container 运行时审计 - 业务逻辑审查 - 手动代码审查 运行时行为和沙箱分析已计划用于 **SkillTotal Cloud**（付费）。 ## 输出 一份标准化报告，包含组件标识、**风险评分 (0–100)** 和 **风险级别** (low / medium / high / critical)、检测到的 **capabilities**（每个都有证据支持）、**findings**、**needs_review** 和 **metadata**。参见 [docs/report-schema.md](docs/report-schema.md) 和 [docs/scoring.md](docs/scoring.md)。 ## 架构 `skilltotal/` 下的包（除 `cli.py` 外）是一个纯的、无副作用的库，因此 相同的引擎可以为未来的 Web 应用和企业 SaaS 提供支持。参见 [docs/architecture.md](docs/architecture.md)。 ## 开发 ``` pip install -e ".[dev]" pytest ``` ## 准确性说明 - Python 通过 **AST** 进行分析（解析 import 别名，区分 `open(p,'w')` 与 读取，忽略仅出现在字符串/注释中的 API 名称）。Node.js/config 使用 regex。 - **测试代码** (`__tests__/`, `*.test.*`, `tests/`, `conftest.py`, …) 被降级为 `needs_review` — 它不会被使用者执行，因此不会影响分数。 - 模糊信号（裸 `secrets`/`credentials` 词，孤立的 base64 blobs，“before answering” 措辞，minified 文件）会进入 `needs_review`，而不会进入 `findings`。 - **隐藏 Unicode**（ASCII-smuggling 标签字符，Trojan-Source bidi 覆盖， zero-width 字符）会被检测和解码 — 这是用来将指令 逃避人工审查的真实手段。有关针对真实世界攻击的校准，请参见 `tests/manual_eval/`。 - Shell 执行涵盖 `subprocess`/`os.system`, `asyncio.create_subprocess_*`, Node `child_process`，以及常见的进程生成库（Python `sh`/`plumbum`/`pexpect`/ `invoke`/`fabric`；Node `zx`/`execa`/`cross-spawn`/`shelljs`/`tinyexec`/`node-pty`）。 - MCP 危险工具通过名称/描述进行分类，无论是在 JSON 清单中**还是 在代码中定义时** (`server.tool("run_command", …)`, `@mcp.tool` 修饰 `def read_file`)。 - **局限性：** 检测处于 call/import 级别。通过*无法识别的* 更高级别库（例如：内部写入文件的 git 库，浏览器库）实现的能力 可能不会被标记为原始的 filesystem/shell 调用。能力表示*存在*，而未证明 被滥用。 ## 开源版对比 SkillTotal Cloud SkillTotal 是 **open core**。此引擎（分析 + 所有检测规则 + CLI）是开源的 且**能够独立完整运行** — 在本地或 CI 中运行，免费，离线，具有零运行时 依赖。它告诉你一个组件做了**什么**，并附带证据。 付费功能仅通过 **SkillTotal Cloud**（网站）提供，并解释了**为什么 重要**：对发现的 LLM 解释和优先级排序、动态沙箱执行、 托管、扫描历史记录和监控。它们是建立在此引擎之上的服务器端服务 — 其代码不属于本仓库。参见 [docs/open-core.md](docs/open-core.md)。 ## License [Apache-2.0](LICENSE)。另见 [NOTICE](NOTICE)。

标签：AI组件安全, Blue Team, DNS 反向解析, IP 地址批量处理, Python, 文档结构分析, 无后门, 网络安全审计, 自动化payload嵌入, 逆向工具, 错误基检测, 静态代码分析