AI导哈

AI代理包安全检查工具

safe-pkgs是一款为AI代理设计的包安全检查工具，提供安装前的风险评估、允许/拒绝决策及审计日志功能。

  • by math280h
  • Rust
  • 本地部署
  • 7 星标
  • 更新于
在 GitHub 查看 math280h/safe-pkgs

使用说明

安全包装

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 或 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

预览决定而不强制执行（如果）：

safe-pkgs simulate /path/to/project-or-lockfile

Windows 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

私人/认证注册机构

将注册表客户端指向私有镜像，并通过环境变量使用承载令牌进行身份验证。

基本URL重写（未设置时，每个重写默认为公共端点）：

  • npm：
    • SAFE_PKGS_NPM_REGISTRY_API_BASE_URL （包元数据；默认值 https://registry.npmjs.org)
    • SAFE_PKGS_NPM_DOWNLOADS_API_BASE_URL （下载；默认值 https://api.npmjs.org)
    • SAFE_PKGS_NPM_POPULAR_INDEX_API_BASE_URL （人气指数；默认值 https://api.npms.io)
  • pypi：
    • SAFE_PKGS_PYPI_PACKAGE_API_BASE_URL （包元数据；默认值 https://pypi.org/pypi)
    • SAFE_PKGS_PYPI_DOWNLOADS_API_BASE_URL （下载；默认值 https://pypistats.org/api/packages)
    • SAFE_PKGS_PYPI_POPULAR_INDEX_URL （流行度指数；默认顶级pypi包JSON）
  • cargo：还没有基URL覆盖env-var；所有调用都使用crates.io API库(https://crates.io/api/v1).

承载令牌认证——设置后，请求发送 Authorization: Bearer <token>:

  • SAFE_PKGS_NPM_REGISTRY_TOKEN
  • SAFE_PKGS_PYPI_REGISTRY_TOKEN
  • SAFE_PKGS_CARGO_REGISTRY_TOKEN

令牌仅发送到注册表元数据/API主机，以避免将其泄漏到非注册表主机：

  • npm和pypi：令牌仅发送到包元数据主机。下载量和受欢迎程度主机（例如。 api.npmjs.org, api.npms.io, pypistats.org)不接收令牌，因为它们是独立的第三方服务。
  • cargo：每个请求都针对相同的crates.io API库，因此所有请求（元数据、下载、流行的crates-ling）都携带令牌。

空或仅空白的令牌值被视为未设置（不发送身份验证标头）。

配置

全局文件：

  • ~/.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)

信任和安全态势

  • 故障关闭行为：出现检查/运行时故障，不允许静默安装。
  • 本地审计跟踪：仅附加审计日志以供决策审查，并可选择远程HTTP后端（请参阅 [audit] 在配置规范中）。
  • 确定性政策背景：应对措施包括 policy_snapshot_version，配置和策略指纹，以及启用的检查集。
  • 本地缓存：SQLite缓存由策略指纹+TTL到期的包元组键控。

免责声明

safe-pkgs 作为一个MCP工具，AI代理可以在安装软件包之前调用它。然而， 我们不能保证AI代理总是选择调用此工具 --自主选择工具的代理模型可以继续进行软件包安装，而无需调用 check_package 或 check_lockfile 首先，取决于模型、提示上下文和系统提示配置。

如果你的AI代理跳过了 safe-pkgs 当它应该叫它的时候，请 打开一个问题 通过提示和响应，我们可以改进工具描述和使用指导。

路线图

优先计划工作：

现在

  • [x] 内部/私有包名称的依赖性混淆防御
  • [x] 政策模拟模式(what-if)不强制执行
  • [x] 延迟、缓存命中率和注册表错误率的度量/日志模式
  • [x] 支持远程审计存储后端
  • [x] 支持远程配置源（GitHub仓库、HTTP端点等）
  • [x] 对私人注册中心的支持

下一步

  • []保单到期豁免
  • []包来源检查（生态系统元数据支持的情况下）
  • []发布商信任信号（帐户年龄、维护者流失、所有权变更）
  • [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-only

HTML报告：

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

相关 MCP