ericrihm/depfence

# depfence — AI 感知型供应链安全工具 **为 LLM、MCP 和 AI/ML 供应链攻击时代构建的依赖扫描器。** [](https://pypi.org/project/depfence/) [](https://github.com/ericrihm/depfence/actions) [](LICENSE) [](https://pypi.org/project/depfence/) ``` pip install depfence depfence scan . ``` ## 为什么选择 depfence？ - **Slopsquatting 防御** — LLM 会产生幻觉编造包名；攻击者则会将其注册。depfence 能在幻觉编造的包名进入你的 lockfile 之前将其检测出来。 - **MCP 服务器审计** — 唯一完全离线、确定性的 MCP 安全扫描器。可检测工具影子攻击、地毯式拉取（rug-pull）攻击、提示词注入（支持多轮编码规范化）、凭证泄露、未固定版本的包以及 23+ 个已知恶意服务器。支持 Claude Desktop、Cursor、VS Code、Windsurf 和 Zed — 无需任何云端 API 调用。 - **集成了 30+ 款扫描器的一体化工具** — 漏洞扩展（EPSS、KEV、OSV、NVD）、行为 AST 分析、供应链攻击检测、IaC 扫描、许可证合规、SBOM 生成以及红队模拟 — 统一集成于单个 CLI 中。 - **超越 CVE** — 一个没有任何安全公告的包，仍然可以在安装时向外部通信、通过 DNS 窃取环境变量，或者嵌入带有任意代码执行功能的 pickle 格式模型权重。depfence 能够捕获所有这些行为。 ## 快速开始 ``` # 安装 pip install depfence # Full scan — 所有 ecosystems，所有 30+ scanners depfence scan . # Fast CI scan — 仅限更改的 packages depfence diff . # Single-package reputation check depfence check requests -e pypi # Auto-fix 有漏洞的 dependencies depfence fix . --apply ```

输出示例

``` $ depfence scan . depfence v0.4.0 scanning 142 packages across 3 lockfiles CRITICAL pytorch-cuda-nightly slopsquat LLM hallucination match for torch (score 0.94) HIGH lodash 4.17.20 npm_advisory CVE-2021-23337 EPSS 0.71 KEV HIGH req-utils 1.0.3 preinstall install script exfiltrates $HOME/.ssh MEDIUM transformers 4.38.0 model_scanner unsafe torch.load() without weights_only=True MEDIUM @angulr/core scope_squat typosquatting @angular/core LOW leftpad 0.0.3 freshness no release in 847 days, 0 maintainers 6 findings (1 critical, 2 high, 2 medium, 1 low) Run `depfence fix .` for remediation suggestions. ```

## 功能特性 ### 漏洞检测 | 扫描器 | 可检测内容 | |---|---| | `osv` | OSV 数据库 — 涵盖 npm、PyPI、Cargo、Go、Maven、NuGet、Ruby、PHP、Swift | | `npm_advisory` | OSV + 针对 npm 的 GitHub Advisory DB | | `pypi_advisory` | OSV + 针对 PyPI 的 GitHub Advisory DB | | `epss` | EPSS 利用概率评分，用于优先级排序 | | `kev` | CISA 已知被利用漏洞列表 | ### AI/ML 供应链 | 扫描器 | 可检测内容 | |---|---| | `slopsquat` | 被攻击者注册的、由 LLM 幻觉产生的包名 | | `model_scanner` | 不安全的 `torch.load`、pickle 模型文件、未经验证的 HuggingFace 拉取 | | `model_integrity` | 模型权重文件的哈希和来源验证 | | `ai_vulns` | 特定于 AI/ML 框架的漏洞模式 | | `mcp_scanner` | MCP 服务器配置错误、工具影子攻击、凭证泄露、已知恶意包、TLS 强制执行、版本固定、带有编码规范化的提示词注入 | | `mcp_fingerprint` | 通过 schema 变更指纹识别 MCP 地毯式拉取（rug-pull）攻击 + 参数级注入扫描 | ### 供应链攻击 | 扫描器 | 可检测内容 | |---|---| | `scope_squatting` | npm 作用域拼写劫持（`@angulr` vs `@angular`） | | `dep_confusion` | 导致命名空间劫持的私有仓库配置错误 | | `ownership` | 维护者接管和版本顺序异常 | | `preinstall` | 恶意安装脚本：管道至 shell（pipe-to-shell）、凭证窃取、环境变量窃取 | | `provenance` / `provenance_checker` | 缺失或无效的 SLSA 证明 | | `behavioral` | 可疑的 API 模式：eval、exec、child_process | | `obfuscation` | Base64 执行、十六进制字符串、字符编码（charcode）、高熵 payload | | `network` | 挖矿池、Webhook 数据窃取、DNS 隧道、硬编码 IP | | `reputation` | 低信任度包：新建包、无代码仓库、单一维护者 | ### 合规性 | 扫描器 | 可检测内容 | |---|---| | `license_scanner` | AGPL/GPL/copyleft 合规风险 | | `license_compat` | 许可证冲突检测（MIT 项目中的 GPL，专有项目中的 AGPL） | | `reachability` | 哪些存在漏洞的 import 实际上在你的代码中被调用 | | `phantom_deps` | 已声明但从未被 import 的包 | | `freshness` | 已弃用的包、无人维护的依赖（2 年以上未发布新版本） | | `pinning` | 未固定版本的依赖、通配符版本、缺失 lockfile | | `sbom` | CycloneDX 1.5 和 SPDX 2.3 生成 | ### 安全运营 | 扫描器 | 可检测内容 | |---|---| | `secrets` | AWS 密钥、GitHub PAT、私钥、Stripe token、数据库连接字符串 | | `ci_secrets` | 与可疑包行为相关联的 CI 密钥暴露风险 | | `dockerfile` | 未固定版本的基础镜像、root 用户、ENV/ARG 中的密钥、已停止维护（EOL）的镜像 | | `terraform` | 未固定版本的模块/提供者、HTTP 源、未经验证的命名空间 | | `gha_scanner` | 未固定版本和受损的 GitHub Actions | | `gha_workflow` | 脚本注入、过于宽松的权限、`pull_request_target` 攻击 | | `risk-score` | 集成 OpenSSF Scorecard 的复合 A-F 风险评分 | ## 支持的生态系统 | 生态系统 | Lockfile / 清单文件 | |---|---| | npm / Node.js | `package-lock.json`、`yarn.lock`、`pnpm-lock.yaml` | | PyPI / Python | `requirements.txt`、`poetry.lock`、`Pipfile.lock`、`uv.lock` | | Cargo / Rust | `Cargo.lock` | | Go | `go.sum`、`go.mod` | | Maven / Java | `pom.xml` | | NuGet / .NET | `packages.lock.json`、`*.csproj` | | RubyGems | `Gemfile.lock` | | Composer / PHP | `composer.lock` | | Swift / SPM | `Package.resolved` | ## 输出格式 所有命令都接受 `--format` 和 `-o` 参数： | 格式 | 标志 | 用例 | |---|---|---| | Rich 终端表格 | `--format table`（默认） | 本地开发 | | JSON | `--format json` | 流水线集成、`jq` 过滤 | | HTML | `--format html` | 可共享的安全报告 | | SARIF | `--format sarif` | GitHub Code Scanning、Azure DevOps | | CycloneDX 1.5 | `depfence sbom --format cyclonedx` | SBOM 交付 | | SPDX 2.3 | `depfence sbom --format spdx` | SBOM 交付 | ``` depfence scan . --format json | jq '.findings[] | select(.severity == "CRITICAL")' depfence scan . --format sarif -o results.sarif depfence sbom . --format cyclonedx -o sbom.json ``` ## CI/CD 集成 ### GitHub Actions — 单行复合操作 ``` - uses: ericrihm/depfence@v1 with: fail-on: high # critical | high | medium | low | any | none format: sarif upload-sarif: true # uploads to GitHub Code Scanning automatically ```

带有 SARIF 上传的完整工作流

``` name: Dependency Security on: push: branches: [main] paths: - '**/package-lock.json' - '**/yarn.lock' - '**/requirements.txt' - '**/poetry.lock' - '**/Cargo.lock' - '**/go.sum' pull_request: paths: - '**/package-lock.json' - '**/yarn.lock' - '**/requirements.txt' - '**/poetry.lock' schedule: - cron: '0 6 * * 1' jobs: depfence: runs-on: ubuntu-latest permissions: security-events: write steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: '3.12' - run: pip install depfence - run: depfence scan . --format sarif -o depfence.sarif --fail-on high - uses: github/codeql-action/upload-sarif@v3 if: always() with: sarif_file: depfence.sarif category: depfence ```

检测结果将显示在仓库“Security（安全）”选项卡下的“Code Scanning”中，并在相关文件和代码行处提供针对每条结果的注解。 ## 配置 将 `depfence.yml` 放置在项目根目录下，以实现策略即代码和扫描器调优。

depfence.yml 示例

``` # depfence.yml scanners: exclude: [phantom_deps] # disable specific scanners fail_on: high # default --fail-on threshold rules: - name: no-gpl-in-production description: Block copyleft-licensed packages match: license_category: copyleft action: block - name: require-provenance-for-popular description: Require SLSA provenance for high-download packages match: weekly_downloads_min: 100000 has_provenance: false action: block - name: warn-on-ownership-change description: Flag packages whose maintainers changed recently match: ownership_changed_days: 30 action: warn - name: no-install-scripts-npm description: Block npm packages that run code at install time match: has_install_scripts: true action: block ecosystems: [npm] ignore: - id: CVE-2021-23337 package: lodash reason: "not reachable via our import path" expires: 2026-12-31 ```

**环境变量** | 变量 | 描述 | 默认值 | |---|---|---| | `DEPFENCE_PLUGIN_PATH` | 以冒号分隔的插件目录 | — | | `DEPFENCE_CACHE_DIR` | 用于差异扫描和 MCP 指纹的缓存 | `~/.depfence/cache` | | `DEPFENCE_TIMEOUT` | 注册表请求的 HTTP 超时时间（秒） | `30` | **退出码** | 代码 | 含义 | |---|---| | `0` | 未发现达到阈值的问题，或指定了 `--fail-on none` | | `1` | 发现达到或超过 `--fail-on` 阈值的问题，或触发了策略阻止 | | `2` | 扫描错误（解析失败、网络错误） | ## 插件系统 depfence 通过 pip 入口点、`DEPFENCE_PLUGIN_PATH` 或 `~/.depfence/plugins/` 发现插件。 ``` # pyproject.toml: # [project.entry-points."depfence.scanners"] # my_scanner = "mypackage.scanner:MyScanner" from depfence.core.models import Finding, PackageMeta, Severity class MyScanner: name = "my_scanner" ecosystems = ["npm", "pypi"] async def scan(self, packages: list[PackageMeta]) -> list[Finding]: findings = [] for pkg in packages: # detection logic pass return findings ``` ``` depfence plugins # list all loaded scanners, analyzers, reporters ``` ## 安装 ``` pip install depfence # stable pip install "depfence[ml]" # with scikit-learn behavioral scoring pipx run depfence scan . # no install required ``` 需要 Python 3.10+。已在 3.10、3.11、3.12、3.13 版本上测试。 ## 许可证 MIT。详见 [LICENSE](LICENSE)。 *depfence 正处于积极开发中。在 0.x 版本系列期间，扫描器接口和策略 schema 可能会在次要版本之间发生变化。*

标签：AI安全, Chat Copilot, CI/CD安全, CISA项目, Claude, CVE检测, DevSecOps, DLL 劫持, DNS数据外泄, EPSS, IaC扫描, Linux系统监控, Llama, LLM防护, LNA, MCP Server, MCP安全审计, NVD, OSV, pip, Prompt注入, PyPI, Python安全工具, Python库, Rug-pull攻击, SBOM生成, Slopsquatting检测, StruQ, Vercel, 上游代理, 依赖安全扫描, 包名幻觉防护, 包管理器安全, 大语言模型, 威胁情报, 安全合规, 开发者工具, 文档安全, 模块化设计, 模型安全, 环境变量泄露, 红队模拟, 网络代理, 自动化修复, 许可证合规, 逆向工具