Safe Pkgs

🚀 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鉤子集成以進行預提交檢查