安全包装
Package safety checks for AI agents before install.
Rust MCP server + CLI with allow/deny decisions, risk scoring, and audit logs.
Documentation · GitHub Action
Without safe-pkgs With safe-pkgs
它是什么
safe-pkgs 在依赖操作之前检查包风险，并返回一个机器可执行的决策。
决策有效载荷包括：
allow:true或falserisk:low | medium | high | criticalreasons：人类可读的发现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 pypiWindows MCP主机（Claude Desktop等）应使用：
safe-pkgs-mcp.exe无需订阅
safe-pkgs 不需要付费计划、托管帐户或API密钥进行内置检查。
- 作为Rust二进制文件（MCP服务器或CLI）在本地运行。
- 默认情况下使用公共包/咨询端点：
- npm注册表+npm下载API+npm流行指数 - crates.io API - PyPI JSON API+pypistats+top-PyPI索引 - API OSV咨询
- 在您的计算机上本地存储缓存和审核日志。
注册和检查支持
支持的注册表：
npm（默认）cargo（crates.io）pypi（Python包）
查看支持图：
- 命令：
safe-pkgs support-map
配置
全局文件：
~/.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": "",
"policy": ""
}
}paths[].ancestors 仅列出祖先（根到直接父级），不包括包本身。 对于直接依赖性， dependency_ancestry 省略。
evidence.id 稳定且面向机器：
- 内置检查：
.（例如：staleness.behind_latest) - 自定义规则：
custom_rule.（例如：custom_rule.low-downloads) - 策略/运行时项：显式ID（例如：
denylist.package,risk.medium_pair_escalation)
信任和安全态势
- 故障关闭行为：出现检查/运行时故障，不允许静默安装。
- 本地审计跟踪：仅附加审计日志以供决策审查。
- 确定性政策背景：应对措施包括
policy_snapshot_version，配置和策略指纹，以及启用的检查集。 - 本地缓存：SQLite缓存由策略指纹+TTL到期的包元组键控。
免责声明
safe-pkgs 作为一个MCP工具，AI代理可以在安装软件包之前调用它。然而， 我们不能保证AI代理总是选择调用此工具 --自主选择工具的代理模型可以继续进行软件包安装，而无需调用 check_package 或 check_lockfile 首先，取决于模型、提示上下文和系统提示配置。
如果你的AI代理跳过了 safe-pkgs 当它应该叫它的时候，请 打开一个问题 通过提示和响应，我们可以改进工具描述和使用指导。
路线图
优先计划工作：
现在
- \[\]内部/私有包名称的依赖性混淆防御
- \[\]政策模拟模式(
what-if)不强制执行 - \[\]延迟、缓存命中率和注册表错误率的度量/日志模式
- \[\]支持远程审计存储后端
- \[\]支持远程配置源（GitHub仓库、HTTP端点等）
- \[\]对私人登记处的支持
下一步
- \[\]保单到期豁免
- \[\]包来源检查（生态系统元数据支持的情况下）
- \[\]发布商信任信号（帐户年龄、维护者流失、所有权变更）
- \[x\] 大型锁文件的性能/规模改进：
- \[x\] 可配置的有界并发（默认：5个并行计算） - \[x\] 阻止API速率限制的批间延迟（默认值：100ms） - \[x\] 缓存命中跟踪以提高可见性
- \[\]其他性能改进（请求合并重复包）
稍后
- \[\]NVD咨询丰富
- \[\]可选Snyk咨询提供商
- \[\]Socket.dev集成
- \[\]用于CI审计的GitHub Actions集成
- \[\]注册表驱动的MCP模式和文档生成（单一事实来源）
- \[\]HTTP流式MCP服务器选项
- \[\]更多经过验证的编辑器配置示例
- \[\]用于预提交检查的Git挂钩集成
发展
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-onlyHTML报告：
cargo llvm-cov --workspace --all-features --html报告路径：
target/llvm-cov/html/index.html
本地文档
pip install zensical
zensical serve注： 此项目现在使用 森西卡尔 而不是MkDocs。 MkDocs 2.0放弃了插件系统，破坏了向后兼容性，没有迁移路径(公告).
确定性评估时钟（可选）
集 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