npx-vibe

npx-vibe

コード実行前に、証拠を重視して npm パッケージをレビューします。開発者、コーディングエージェント、MCP クライアント、CI 向けです。

npx-vibe はレジストリのパッケージを解決し、パッケージコードを実行せずに tarball をダウンロードして検証します。インストール時に実行されるコードと実行可能なソースコードを範囲を限定して読み取り、証拠とともに Proceed、Caution、Block を報告します。

3.0.0 は、最終リリースとして予定されています。積極的なメンテナンスは終了しており、今後の互換性更新やセキュリティパッチの提供予定はありません。 パッケージは MIT ライセンスで引き続き利用できます。導入前にメンテナンスポリシーと3.0 移行ガイドをお読みください。

ウェブサイトとデモ · npm パッケージ · 変更履歴 · npm 12 ガイド

クイックスタート

Node.js 20 以降と npm レジストリへのアクセスが必要です。デフォルトのスキャンにアカウント、AI モデル、API キーは必要ありません。

# Review only — does not execute the target package
npx --yes [email protected] [email protected]

# Inspect install-time behavior
npx --yes [email protected] esbuild

# Review a project's locked production dependency tree
npx --yes [email protected] project

# Include development dependencies
npx --yes [email protected] project --include-dev

外側の npx は npx-vibe 自体をインストールして実行します。レビュー対象のパッケージは実行されません。CLI をグローバルにインストールすることもできます。

npm install --global [email protected]
npx-vibe [email protected]

デフォルトではスキャンが実行されます。パッケージの実行には、別途 run コマンドが必要です。

npx --yes [email protected] run cowsay -- hello
npx --yes [email protected] run --bin tsc typescript -- --version

Proceed の結果は、要求された実行を許可します。Caution の場合、対話型ターミナルでは確認を求め、それ以外では実行せずに終了します。Block の場合、--force で明示的に上書きしない限り、実行を阻止します。デフォルトではインストールスクリプトを無視します。実行はサンドボックス化されておらず、レビューされていない推移的依存関係をインストールする可能性があります。対象範囲を広げる必要がある場合は、プロジェクトを別途スキャンしてください。

レビュー対象

• パッケージの正確なバージョン、レジストリのメタデータ、tarball の整合性。
• レビュー範囲内のインストールフック、bin エントリーポイント、到達可能な相対ソースインポート。
• 認証情報の読み取りとネットワーク呼び出しの組み合わせ、ダウンロードしたペイロードの実行、不審な書き込み、難読化などの兆候。
• 利用可能な場合は、OSV の既知の脆弱性アドバイザリ。
• リポジトリの活動状況、メンテナー、パッケージ履歴、ダウンロード数。これらは状況を把握するための情報であり、信頼性の証明でも、スコアを下げる要因でもありません。
• AI の検出結果とソースを照合する、オプションのモデルによる解釈。
• 新たな検証を省略せずに保持する、ローカルの整合性キー付きレビュー履歴。

アーカイブは展開や実行をせず、メモリ上で解析します。ファイルの選択とソース解析には上限があり、ツールがすべてのソースファイルをレビューしたり、単一のパッケージのすべての依存関係を再帰的に調査したりすることはありません。

判定と自動化

終了コード	意味	エージェントのアクション
0	Proceed：レビュー範囲内にブロック要因となる兆候はありません	continue
2	Caution：証拠の確認が必要です	review
3	Block：高リスクの検出結果があります	stop
1	エラー、または要求されたレビューが未完了です	retry

スキャンが完了して Proceed となっても、安全が保証されるわけではありません。OSV への照会が利用できない場合は、「該当なし」ではなく「利用不可」と表示されます。OSV は補足情報であり、障害が発生しても、それ自体がパッケージスキャンの失敗にはなりません。--no-advisories を指定すると、OSV の照会が明示的に無効になります。

プロジェクトの対象範囲：暗黙のフォールバックなし

空でないプロジェクトをデフォルト設定でスキャンするには、packages マップを含む package-lock.json（npm ロックファイル v2/v3）が必要です。インストールスクリプトを実行せずに生成してください：

npm install --package-lock-only --ignore-scripts
npx --yes [email protected] project

ロックファイルがありませんか？対象を明示的に絞ってレビューしてください：

npx --yes [email protected] project --direct-only

ワークスペース／ローカルリンク、Git ソース、エイリアス、外部レジストリのアーティファクトは、このレジストリ限定のレビュー範囲外です。これらはスキップ対象として報告され、同じような名前の公開パッケージに置き換えられることはありません。パッケージのスキップ、パッケージ数の上限、またはスキャン失敗がある場合、結果は**不完全（終了コード 1）**になります。デフォルトの上限は 500 パッケージです。--max-packages で 5,000 まで引き上げられます。

レジストリのインテグリティと、ロックファイルに記録されたインテグリティがある場合はその両方が、ダウンロードしたアーティファクトと一致している必要があります。--include-dev を指定しない限り、開発依存関係は除外されます。

npm インストールスクリプトの権限

npx-vibe は、ロックファイルでインストールスクリプトがあると示された依存関係をレビューし、approve、review、または deny を推奨できます：

npx --yes [email protected] approve-scripts
npx --yes [email protected] approve-scripts --all

認識されたローカルビルドコマンドは承認できます。ネットワーク／シェルの動作、暗黙的なネイティブビルド、ソースの一部だけを読み取る場合はレビューが必要です。高リスクの検出結果は拒否されます。推奨は、ビルドツールや、それが使用するすべてのファイルが安全であることを保証するものではありません。

曖昧さのない判断のみを記録するには：

npx --yes [email protected] approve-scripts --write

新しい allowScripts エントリは、必ずレビュー済みのバージョンに固定されます。人によるレビューが必要なエントリが、暗黙のうちに承認されることはありません。また、不完全なレビューでは権限を書き込めません。既存の広範な権限は保持されます。--all を使い、権限は自分で削除するか、範囲を狭めてください。--pin は引き続き互換性エイリアスとして利用できます。

読み取りとレビューは npm 10/11 および npm 12 で動作します。allowScripts の適用には、対応する npm バージョンが必要です。npm 12 ガイドを参照してください。

コーディングエージェント

--agent は schema 3 の判定エンベロープを出力し、ローカル履歴への書き込みを無効にして、実行および権限書き込みのフラグを拒否します：

npx --yes [email protected] --agent [email protected]
npx --yes [email protected] project --agent --include-dev
npx --yes [email protected] approve-scripts --agent

簡略化した例（完全な結果にはレポートも含まれます）：

{
  "schemaVersion": 3,
  "kind": "package-scan",
  "status": "complete",
  "decision": {
    "verdict": "proceed",
    "riskScore": 0,
    "action": "continue",
    "exitCode": 0,
    "mayContinue": true
  },
  "coverage": {
    "scope": "package",
    "complete": true,
    "requested": 1,
    "scanned": 1,
    "skipped": 0,
    "failed": 0,
    "reasons": []
  }
}

すでに承認済みのワークフローを続行する前に、schema 3、status === "complete"、coverage.complete === true、および decision.action === "continue" を必須としてください。review の場合は人に確認し、stop の場合は実行せず、retry の場合はまずカバレッジ不足またはエラーを解消してください。対象のカバレッジ数は、ソースファイルを網羅的に調査したことを意味しません。

削除された decision.safeToExecute フィールドは、意図的に別の安全性を保証するフィールドで置き換えられていません。

ポータブルな Agent Skill をインストールします：

npx skills add Devrajsinh-Jhala/NPM-Vibe-check --skill npx-vibe -g

Agent Skill · エージェント向けドキュメント

MCP サポート

ローカルで動作する、依存関係不要の stdio MCP サーバーを起動します。

npx --yes [email protected] npx-vibe-mcp

クライアント設定の例（設定形式はクライアントによって異なる場合があります）：

{
  "mcpServers": {
    "npx-vibe": {
      "command": "npx",
      "args": ["--yes", "[email protected]", "npx-vibe-mcp"]
    }
  }
}

ツール：

ツール	用途
scan_package	公開 npm パッケージの仕様を 1 件レビューします
scan_project	ロックされた依存関係ツリーをレビューします。directOnly を指定すると対象を明示的に絞り込みます
approve_scripts	インストールスクリプトの許可に関する推奨事項を読み取り専用で提示します
list_providers	対応プロバイダーと設定を一覧表示します。リアルタイムのモデル検出は行いません

ツールは読み取り専用で、スキーマに基づいており、JSON テキストと構造化コンテンツの両方を返します。不完全な結果やエラー結果では、MCP の isError: true が設定されます。プロトコルは 2025-11-25 に対応し、ツールの結果ではスキーマ 3 を使用します。認証情報はサーバー環境から提供し、ツールの引数には渡しません。

正規の MCP Registry ID は io.github.Devrajsinh-Jhala/npx-vibe です。npm への公開と MCP Registry への公開は別々です。利用可能なバージョンはレジストリエントリーで確認してください。

このアニメーションは、Caution レビューのフローを示しています。表示されているのは簡略化された結果であり、プロバイダーへのリアルタイムの呼び出しではありません。

任意の AI レビュー

環境にプロバイダー固有のキーがあっても、AI はデフォルトで無効です。明示的にオプトインすると、ヒューリスティックな検出結果を根拠としてレビューが行われます。

オンラインプロバイダーには、Gemini、OpenAI、Anthropic、OpenRouter、Groq、Together、およびカスタムの OpenAI 互換エンドポイントが含まれます。「最新モデル」の固定リストはありません。アカウントで利用できる正確なモデル ID を選択してください。

npx --yes [email protected] --models
npx --yes [email protected] --ai online --provider gemini --model <model-id> esbuild
npx --yes [email protected] --ai ollama --model <installed-model> esbuild

山括弧で囲まれたプレースホルダーを置き換えてください。これらはシェル引数としてそのまま指定する値ではありません。GEMINI_API_KEY、OPENAI_API_KEY、ANTHROPIC_API_KEY などのプロバイダー固有のキーを環境に設定してください。明示的な --ai off は、キーによる有効化より優先されます。専用の NPX_VIBE_API_KEY と --api-key は、意図的にオプトインするためのものです。シークレットがシェル履歴に残らないよう、環境変数の使用を推奨します。

どのプロバイダーのものか曖昧な直接キーを使うには、--provider が必要です。キーが別のプロバイダーに暗黙的に転送されることはありません。カスタムエンドポイントを使う場合は、--api-url（チャット補完エンドポイントの完全な URL）と正確な --model も必要です。プロバイダーのエラーは内容を秘匿して報告され、決定論的なレビューに置き換わることはありません。

オンラインレビューでは、選択したパッケージのソースと、範囲を限定したメタデータが選択したプロバイダーに送信されます。環境やローカルのプロジェクトファイルがアップロードされることはありません。ローカルの Ollama レビューでは、これらの情報は設定済みのローカルエンドポイント内に保持されます。AI の結果はあくまで参考情報であり、信頼性を判断する権限を持つものではありません。

GitHub Actions

Action とスキャナーのリリースの両方を固定します。

- uses: actions/checkout@v6
- uses: actions/setup-node@v6
  with:
    node-version: 24
- uses: Devrajsinh-Jhala/[email protected]
  with:
    version: '3.0.0'
    command: project
    include-dev: 'true'
    fail-on: caution

この Action は一時的な隔離環境にインストールし、アノテーションとジョブのサマリーを出力して、verdict と exit-code を公開します。fail-on では block（デフォルト）、caution、または never を指定できます。エラーと網羅性が不完全な場合は、常に失敗します。 Action では AI とローカルの履歴への書き込みは無効です。変更される可能性のあるタグより、コミット SHA のほうが強固に固定できます。

Marketplace の掲載ページ · Action の入力

制限事項とサポート

npx-vibe は、サンドボックス、ウイルス対策エンジン、網羅的な監査、または依存関係の制御に代わるものではありません。条件付き、実行時のみ、遅延、難読化された動作や、推移的な動作を見落とすことがあり、誤検知が発生する可能性もあります。アーカイブの検査には、サイズ、ファイル数、ソース選択の上限があります。ネットワークのメタデータやアドバイザリーサービスを利用できない場合や、情報が古い場合があります。

スキャン後にパッケージを実行する場合、npm は別途インストールを実行します。レビューはアトミックなインストールではなく、実行されたすべての内容を証明するものでもありません。このリリースは更新されないため、その後にプロバイダー API、モデルの利用可否、npm の動作、MCP エコシステムが変更される場合があります。

セキュリティ境界 · メンテナンスとフォーク · 移行

開発

npm install --ignore-scripts
npm run verify
npm run smoke:pack
npm run site:preview

テストスイートでは、判定、アーカイブの上限、プロバイダーのルーティングと秘匿化、ロックされた依存関係のスキャン、スクリプトの権限、エージェントのスキーマ、MCP トランスポートを対象にしています。パッケージ化されたアーティファクトのチェックでは、CLI と MCP の両方のエントリーポイントを検証します。

ライセンス

MIT · Devrajsinh Jhala が開発しました。