Safe Pkgs

🚀 safe-pkgs

safe-pkgs は、AIエージェントがパッケージをインストールする前に、パッケージの安全性をチェックするツールです。Rustで構築されたMCPサーバーとCLIを備え、許可/拒否の判断、リスクスコアリング、および監査ログを提供します。

ドキュメント · GitHub Action

</td>
<td align="center" valign="top">
  
</td>

🚀 クイックスタート

safe-pkgs は、依存関係のアクションを実行する前にパッケージのリスクをチェックし、機械的に実行可能な1つの判断を返します。

判断のペイロードには以下が含まれます:

• allow: true または false
• risk: low | medium | high | critical
• reasons: 人が読める調査結果
• evidence: 構造化された調査結果 (kind, 安定した id, severity, message, facts)
• metadata: パッケージのコンテキスト (最新バージョン、公開日、ダウンロード数、アドバイザリー)
• fingerprints: 決定論的なハッシュ (config, policy)

📦 インストール

一度だけインストールします:

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サーバーまたはCLI)。
• デフォルトで公開パッケージ/アドバイザリーエンドポイントを使用します:
  • 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

💻 使用例

基本的な使用法

設定例

グローバルファイル:

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

🔧 技術詳細

信頼性とセキュリティ

• フェイルセーフ動作: チェック/ランタイムの失敗は表示され、インストールを黙って許可することはありません。
• ローカル監査トレイル: 決定のレビュー用の追記専用の監査ログ。
• 決定論的なポリシーコンテキスト: レスポンスには policy_snapshot_version、設定とポリシーのフィンガープリント、および有効なチェックセットが含まれます。
• ローカルキャッシュ: ポリシーのフィンガープリント + パッケージのタプルでキー付けされたSQLiteキャッシュで、TTLによる期限切れがあります。

注意事項

safe-pkgs は、AIエージェントがパッケージをインストールする前に呼び出すことができるMCPツールとして機能します。ただし、AIエージェントが常にこのツールを呼び出すことを保証することはできません。ツールを自律的に選択するエージェントモデルは、モデル、プロンプトコンテキスト、およびシステムプロンプトの設定に応じて、check_package または check_lockfile を最初に呼び出さずにパッケージのインストールを続行する場合があります。

AIエージェントが safe-pkgs を呼び出すべきときにスキップした場合は、問題を報告 して、プロンプトとレスポンスを提供してください。これにより、ツールの説明と使用ガイダンスを改善することができます。

📚 ドキュメント

ロードマップ

優先度の高い予定作業:

現在

• [ ] 内部/プライベートパッケージ名の依存関係混同防御
• [ ] 強制なしのポリシーシミュレーションモード (what-if)
• [ ] レイテンシ、キャッシュヒット率、およびレジストリエラー率のメトリクス/ログスキーマ
• [ ] リモート監査ストレージバックエンドのサポート
• [ ] リモート設定ソース (GitHubリポジトリ、HTTPエンドポイントなど) のサポート
• [ ] プライベートレジストリのサポート

次のステップ

• [ ] 期限付きのポリシー免除
• [ ] パッケージの出所チェック (エコシステムメタデータがサポートする場合)
• [ ] パブリッシャーの信頼信号 (アカウントの年齢、メンテナの交代、所有権の変更)
• [ ] パフォーマンス/スケールの改善 (大規模なロックファイルのリクエスト結合 + 制限付きの並行性)

将来的な計画

• [ ] 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の代わりに Zensical を使用しています。 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