installaudit

installaudit

インストールとはコードの実行です。installaudit は、インストールする前にそのコードの作成者を知らせます。

npm install はファイルをダウンロードするだけではありません。ロックファイルのエントリに hasInstallScript: true があるパッケージは、インストール時にコードを実行します。また、ルートパッケージ自身の preinstall、install、postinstall、prepare スクリプトも実行されます。多くの監査では、依存関係に脆弱性があるかどうかを確認します。installaudit は、その前に「このツリーをインストールした瞬間に何が実行されるのか」という問いに答えます。

package.json と package-lock.json を読み取り、ツリー内のすべてのインストールスクリプトを一覧にし、直接依存と推移的依存を分け、ルートスクリプトを処理内容に基づいて分類して、判定結果を返します。何もインストールせず、スクリプトも実行せず、パッケージも取得しません。

インストール

npx @reneturcios/installaudit audit

または、グローバルにインストールするか、MCP サーバーとして追加します（下記参照）。

CLI

# Audit the current directory
npx @reneturcios/installaudit audit

# Audit another path
npx @reneturcios/installaudit audit ~/src/my-repo

# Machine readable output
npx @reneturcios/installaudit audit ~/src/my-repo --json

# Run as an MCP server on stdio
npx @reneturcios/installaudit mcp

# Print the version
npx @reneturcios/installaudit --version

終了コード：

• 判定結果が CLEAN の場合は 0。
• 判定結果が REVIEW の場合は 1。
• package.json または package-lock.json がない場合を含む、使用方法のエラーの場合は 2。
• 読み取り側が出力パイプを早期に閉じた場合は 141。

MCP

MCP クライアントの設定に追加します：

{
  "mcpServers": {
    "installaudit": {
      "command": "npx",
      "args": ["-y", "@reneturcios/installaudit", "mcp"]
    }
  }
}

ツール：path 引数を受け取る audit_install_scripts。判定結果、件数、検出内容を含む完全なレポートを JSON で返します。

インベントリの仕組み

依存関係は package.json だけでなく、ロックファイルから取得します。実際にインストールされるツリーが解決済みの状態で記録されているのは、ロックファイルだからです。

• ロックファイルの v2 および v3 形式では、packages オブジェクトが node_modules/<name> などのインストールパスをエントリに対応付けます。
• hasInstallScript: true のエントリはインストール時にコードを実行するため、検出内容になります。
• パッケージ名は、パス内の最後の node_modules/ セグメントの後ろから取得します。スコープ付きの名前は 2 つのセグメントで構成されます。node_modules/@scope/name は @scope/name であり、node_modules/a/node_modules/@scope/name も @scope/name です。
• パスに node_modules セグメントが 1 つだけあり、その名前がルートの package.json の dependencies または devDependencies に記載されている場合、そのパッケージは直接依存です。それ以外はすべて推移的依存です。名前が直接依存と一致する入れ子のコピーも、推移的依存に含まれます。
• version と dev フラグはロックファイルのエントリから読み取り、検出内容とともに報告します。

ルートスクリプトは package.json から取得します。インストール前後に npm が実行するスクリプトであるため、読み取るのは preinstall、install、postinstall、prepare のみです。存在するものはそれぞれ、コマンドの内容に基づいて分類され、検出内容になります。

ルール

ルール	重要度	意味
DEP-INSTALL-SCRIPT	medium（直接依存）、low（間接依存）	ロックファイルのエントリーに hasInstallScript: true が設定されている依存関係です。証拠は name@version です。
ROOT-SCRIPT-NETWORK	high	NETWORK に分類されたルートのライフサイクルスクリプトです。
ROOT-SCRIPT-SHELL-OUT	medium	SHELL-OUT に分類されたルートのライフサイクルスクリプトです。
ROOT-SCRIPT-BUILD	low	BUILD に分類されたルートのライフサイクルスクリプトです。
ROOT-SCRIPT-OTHER	info	OTHER に分類されたルートのライフサイクルスクリプトです。

ルートスクリプトの分類には、文書化された単純なパターンを使用し、次の優先順位で確認します。最初に NETWORK、次に SHELL-OUT、続いて BUILD、最後に OTHER です。

分類	パターン
NETWORK	curl または wget、あるいは http:// または https:// の URL と、取得またはダウンロード用のツールを表す単語（fetch、download、curl、wget）の組み合わせです。
SHELL-OUT	シェルインタープリターを表す単語（sh、bash、zsh）、node -e、またはスクリプトインタープリターを表す単語（python、python3、perl、ruby）です。
BUILD	tsc、npm run build（pnpm、yarn、bun も対象）、またはビルドツール名（webpack、vite、rollup、esbuild、parcel、gulp、grunt、babel）です。
OTHER	上記以外すべてです。

すべてのレポートで報告される件数：

• totalDeps：ロックファイルの packages オブジェクトにある依存関係エントリーの総数。ルートエントリーは除外します。
• depsWithScripts：hasInstallScript: true が設定されたエントリー数です。
• directWithScripts：depsWithScripts のうち、直接依存に該当する数です。
• transitiveWithScripts：depsWithScripts のうち、間接依存に該当する数です。
• rootScripts：preinstall、install、postinstall、prepare のうち、存在するルートのライフサイクルスクリプト数です。
• findings：検出事項の総数です。

検出事項は、ルール、次に名前の順で決定的にソートされます。レポートにはタイムスタンプが含まれないため、同じツリーからは常に同じレポートが生成されます。

判定

• CLEAN：ルートに NETWORK または SHELL-OUT スクリプトがなく、依存関係のインストールスクリプトもありません。ルートに BUILD または OTHER スクリプトだけがある場合も判定は CLEAN です。ただし、隠されることなく、low または info の検出事項として報告されます。
• REVIEW：上記以外です。このツリー内で、インストール時に実行されるコードが少なくとも1つあり、人による確認が推奨されます。

制限事項

• ロックファイルのみを対象とします。package-lock.json がない場合は、空のレポートではなくエラー（終了コード 2）になります。ロックファイルがなければ、解決済みのツリーを一覧化できないためです。package.json がない場合も同様にエラーになります。
• 依存関係のスクリプト本体はロックファイルに含まれておらず、取得もされません。依存関係について installaudit が報告するのは、スクリプトの存在、名前、バージョン、dev フラグ、直接または間接の別です。スクリプトの内容は報告せず、意図も判定しません。インストールスクリプトがあるパッケージが完全に正当な場合もあります。ネイティブビルドがよくある例です。
• ルートスクリプトの分類はパターンに基づきます。package.json 内のコマンド文字列をそのまま読み取り、スクリプトが呼び出すファイルを追跡したり、変数を展開したり、ダウンロードしたファイルの動作を追跡したりはしません。
• 対応しているのは、packages オブジェクトを使用するロックファイル v2 と v3 のみです。レガシー形式のロックファイル v1 にある dependencies オブジェクトは読み取らないため、v1 のロックファイルは不完全な一覧ではなくエラーになります。
• 読み取るのは、インストールに関連する4つのルートスクリプトのみです。test や start など、その他のスクリプトは、コマンドにリスクがありそうな場合でも対象外です。
• 直接依存とは、ルートの package.json の dependencies または devDependencies に記載されている依存関係です。このツリーを通じてのみ到達できる依存関係は、誰が管理しているかにかかわらず、ここでは定義上、間接依存です。