JinDaGe - safe-pkgs MCP Details

article

README

🚀 safe-pkgs

safe-pkgs 是一款用于在AI代理安装软件包前进行安全检查的工具。它基于Rust构建，拥有MCP服务器和命令行界面，能够做出允许或拒绝的决策，对软件包进行风险评分，并生成审计日志。

🚀 快速开始

safe-pkgs 可在依赖操作前检查软件包风险，并返回一个可由机器执行的决策。决策负载包含以下内容：

allow：true 或 false
risk：low | medium | high | critical
reasons：可读的检查结果
evidence：结构化的检查结果（kind、稳定的 id、severity、message、facts）
metadata：软件包上下文信息（最新版本、发布日期、下载量、安全公告）
fingerprints：确定性哈希（config、policy）

60秒完成安装与运行

一次性安装

cargo install --path . --locked

运行MCP服务器

safe-pkgs serve

进行一次性审计

safe-pkgs audit /path/to/project-or-lockfile
safe-pkgs audit /path/to/requirements.txt --registry pypi

Windows MCP主机（如Claude Desktop等）请使用

safe-pkgs-mcp.exe

✨ 主要特性

无需订阅

safe-pkgs 进行内置检查时无需付费计划、托管账户或API密钥。

以Rust二进制文件形式在本地运行（MCP服务器或命令行界面）。
默认使用公共软件包/安全公告端点：
- npm注册表 + npm下载API + npms流行度指数
- crates.io API
- PyPI JSON API + pypistats + top-pypi指数
- OSV安全公告API
缓存和审计日志本地存储在您的机器上。

支持的注册表和检查

支持的注册表

npm（默认）
cargo（crates.io）
pypi（Python软件包）

查看支持映射

safe-pkgs support-map

信任与安全态势

故障关闭行为：检查/运行时失败会显示错误信息，不会默默允许安装。
本地审计跟踪：追加式审计日志，用于决策审查。
确定性策略上下文：响应中包含 policy_snapshot_version、配置和策略指纹，以及启用的检查集。
本地缓存：SQLite缓存，以策略指纹 + 软件包元组为键，设置了TTL过期时间。

📦 安装指南

安装命令

cargo install --path . --locked

💻 使用示例

基础用法

运行MCP服务器：

safe-pkgs serve

进行一次性审计：

safe-pkgs audit /path/to/project-or-lockfile
safe-pkgs audit /path/to/requirements.txt --registry pypi

Windows MCP主机使用：

safe-pkgs-mcp.exe

高级用法

强制固定策略评估时间

设置 SAFE_PKGS_EVALUATION_TIME 为RFC3339时间戳，以强制固定策略评估时间（用于重放/调试运行）：

SAFE_PKGS_EVALUATION_TIME=2026-01-01T00:00:00Z safe-pkgs audit /path/to/project

$env:SAFE_PKGS_EVALUATION_TIME = "2026-01-01T00:00:00Z"
safe-pkgs audit C:\path\to\project

📚 详细文档

配置

全局文件

~/.config/safe-pkgs/config.toml

项目覆盖

.safe-pkgs.toml

最小配置示例

min_version_age_days = 7
min_weekly_downloads = 50
max_risk = "medium"

[cache]
ttl_minutes = 30

[allowlist]
packages = ["my-internal-pkg"]

[denylist]
packages = ["event-stream@3.3.6"]

完整配置架构

docs/configuration-spec.md

MCP配置示例

macOS/Linux

{
  "servers": {
    "safe-pkgs": {
      "type": "stdio",
      "command": "/path/to/safe-pkgs",
      "args": ["serve"]
    }
  },
  "inputs": []
}

Windows（无控制台窗口

{
  "servers": {
    "safe-pkgs": {
      "type": "stdio",
      "command": "safe-pkgs-mcp.exe"
    }
  },
  "inputs": []
}

决策输出示例

{
  "allow": true,
  "risk": "low",
  "reasons": [
    "lodash@3.10.1 is 1 major version behind latest (4.17.21)"
  ],
  "evidence": [
    {
      "kind": "check",
      "id": "staleness.behind_latest",
      "severity": "low",
      "message": "lodash@3.10.1 is 1 major version behind latest (4.17.21)",
      "facts": {
        "package_name": "lodash",
        "resolved_version": "3.10.1",
        "latest_version": "4.17.21",
        "major_gap": 1
      }
    }
  ],
  "fingerprints": {
    "config": "c7d9f5b8b9a8f2a9f6b1f42f0e8e8c8a63f2b2ef8fdde1f3cd9ea4f5a2c08a0b",
    "policy": "fca103ee4fd5b86595a6a6e933f8a5f87db0ce087f80744dc1ea9cdbf58f7a6f"
  },
  "metadata": {
    "latest": "4.17.21",
    "requested": "3.10.1",
    "published": "2015-08-31T00:00:00Z",
    "weekly_downloads": 45000000
  }
}

锁定文件审计输出示例 (`dependency_ancestry`)

输入锁定文件 (`package-lock.json`)

{
  "name": "demo",
  "lockfileVersion": 2,
  "dependencies": {
    "react": {
      "version": "18.2.0",
      "dependencies": {
        "loose-envify": {
          "version": "1.4.0"
        }
      }
    }
  }
}

审计输出

{
  "allow": true,
  "risk": "low",
  "total": 2,
  "denied": 0,
  "packages": [
    {
      "name": "react",
      "requested": "18.2.0",
      "allow": true,
      "risk": "low",
      "reasons": [],
      "evidence": []
    },
    {
      "name": "loose-envify",
      "requested": "1.4.0",
      "allow": true,
      "risk": "low",
      "reasons": [],
      "evidence": [],
      "dependency_ancestry": {
        "paths": [
          { "ancestors": ["react"] }
        ]
      }
    }
  ],
  "fingerprints": {
    "config": "<sha256>",
    "policy": "<sha256>"
  }
}

paths[].ancestors 仅列出祖先（从根到直接父级），不包括软件包本身。对于直接依赖项，dependency_ancestry 会被省略。

evidence.id 是稳定的且面向机器的：

内置检查：<check_id>.<reason_code>（例如：staleness.behind_latest）
自定义规则：custom_rule.<rule_id>（例如：custom_rule.low-downloads）
策略/运行时项：显式ID（例如：denylist.package、risk.medium_pair_escalation）

🔧 技术细节

开发

cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test

覆盖率

安装

rustup component add llvm-tools-preview
cargo install cargo-llvm-cov

摘要

cargo llvm-cov --workspace --all-features --summary-only

HTML报告

cargo llvm-cov --workspace --all-features --html

报告路径

target/llvm-cov/html/index.html

本地文档

pip install zensical
zensical serve

注意：此项目现在使用 Zensical 代替MkDocs。MkDocs 2.0 移除了插件系统，且没有迁移路径导致向后不兼容（公告）。

📄 许可证

文档中未提及许可证相关信息，故跳过此章节。

免责声明

safe-pkgs 作为一个MCP工具，可供AI代理在安装软件包前调用。然而，我们无法保证AI代理会始终选择调用此工具 — 自主选择工具的代理模型可能会在未先调用 check_package 或 check_lockfile 的情况下进行软件包安装，这取决于模型、提示上下文和系统提示配置。

如果您的AI代理在应该调用 safe-pkgs 时跳过了它，请提交一个问题，提供提示和响应信息，以便我们改进工具描述和使用指南。

路线图

当前计划

[ ] 针对内部/私有软件包名称的依赖混淆防御
[ ] 无强制执行的策略模拟模式 (what-if)
[ ] 延迟、缓存命中率和注册表错误率的指标/日志架构
[ ] 支持远程审计存储后端
[ ] 支持远程配置源（GitHub仓库、HTTP端点等）
[ ] 支持私有注册表

下一步计划

[ ] 带有过期时间的策略豁免
[ ] 软件包来源检查（在生态系统元数据支持的情况下）
[ ] 发布者信任信号（账户年龄、维护者变动、所有权变更）
[ ] 性能/扩展性改进（请求合并 + 大锁定文件的有界并发）

未来计划

[ ] NVD安全公告增强
[ ] 可选的Snyk安全公告提供程序
[ ] Socket.dev集成
[ ] GitHub Actions集成以进行CI审计
[ ] 由注册表驱动的MCP架构和文档生成（单一事实来源）
[ ] HTTP可流式传输的MCP服务器选项
[ ] 更多经过验证的编辑器配置示例
[ ] Git钩子集成以进行预提交检查