trustlock

Gitネイティブな依存関係アドミッションコントローラ。依存関係の変更ごとに信頼シグナルを評価します。

仕組み

trustlockはGit pre-commitフック（アドバイザリモード）とCIチェック（強制モード）として動作します：

• アドバイザリ（pre-commit）： 違反を警告し、コード0で終了。すべてのパッケージが許可された場合に信頼ベースラインを更新します。
• 強制（--enforce）： 違反をブロックし、コード1で終了。ベースラインは更新されません。

パッケージごとに評価される信頼シグナル：

• クールダウン — バージョンがレジストリに公開されてからの経過時間
• プロビナンス — パッケージにSLSA証明書があるかどうか
• ピニング — ロックファイルが正確なバージョンを使用しているかどうか
• インストールスクリプト — パッケージがインストール時にスクリプトを実行するかどうか
• ソース — パッケージがレジストリ、Git URL、ローカルパス、URLのいずれから来ているか
• 新しい依存関係 — プロジェクトに初めて追加されるパッケージ
• 推移的サプライズ — 推移的依存関係の数が予想外に増加したかどうか
• パブリッシャー変更 — パッケージのパブリッシャーIDがバージョン間で変わったかどうか

インストール

npm install -g trustlock

Node.js >= 18.3が必要です。

対応ロックファイル

クイックスタート

ワークフロー1 — プロジェクトへの導入

# 1. プロジェクトでtrustlockを初期化
trustlock init

# 2. Git pre-commitフックをインストール
trustlock install-hook

# 3. 必要に応じて現在の依存関係の状態を確認
trustlock audit

init実行後、trustlockは以下を作成します：

• .trustlockrc.json — ポリシー設定
• .trustlock/baseline.json — 信頼済み依存関係のスナップショット
• .trustlock/approvals.json — 承認記録
• .trustlock/.cache/ — レジストリキャッシュ（gitignore対象）

.trustlockrc.jsonと.trustlock/baseline.jsonをリポジトリにコミットします。

ワークフロー2 — 依存関係の更新をチェックして許可

# 通常通り依存関係をインストール
npm install [email protected]

# pre-commitフックによりtrustlock checkが自動実行されます。
# 手動で実行する場合：
trustlock check

# すべてのパッケージが許可された場合の出力：
# ✔ [email protected] — admitted

すべてのパッケージが合格すると、trustlock checkは自動的にベースラインを更新し（アドバイザリモードのみ）、コード0で終了します。

ワークフロー3 — ブロックされた依存関係への対処

# 新しいパッケージがクールダウンのルールに違反：
trustlock check
# ✖ [email protected] — blocked
#   exposure:cooldown  公開から2時間（ポリシーでは72時間必要）
#   承認するには：trustlock approve [email protected] --override cooldown --reason "..." --expires 7d

# オーバーライドを承認して再チェック：
trustlock approve [email protected] \
  --override cooldown \
  --reason "機能Xに必要。チームレビューで安全性確認済み" \
  --expires 7d

trustlock check
# ✔ [email protected] — admitted with approval

ワークフロー4 — プロジェクト間の依存関係状況の比較

# モノレポパッケージ間でのバージョンドリフトやプロビナンスの不一致を検出
trustlock audit --compare packages/frontend packages/backend packages/shared

コマンド

ポリシープロファイル

trustlockには--profileで選択可能な2つの組み込みプロファイルが付属しています：

# CIでstrictプロファイルを使用
trustlock check --enforce --profile strict

組織ポリシーの継承

チームは共有URLにポリシーを集中管理し、リポジトリごとに拡張できます：

{
  "extends": "https://policy.example.com/trustlockrc.json",
  "cooldown_hours": 96
}

リポジトリの設定は組織ポリシーを厳しくすることしかできません。下限強制により、リポジトリが組織で設定された閾値を緩和することを防ぎます。

ドキュメント

• USAGE.md — 全コマンドリファレンス、全フラグ、終了コード、エラーメッセージ
• POLICY-REFERENCE.md — すべての.trustlockrc.jsonオプション
• ARCHITECTURE.md — 設計判断とモジュールマップ
• examples/ — 設定およびCIワークフローの例

CI統合

trustlockをCIパイプラインに追加：

# GitHub Actions — 詳細は examples/ci/github-actions.yml
- run: npx trustlock check --enforce

examples/ にGitHub Actions、Lefthook、Huskyの設定があります。

trustlockがタイムライン上のどこに位置するか

trustlockはコミット時にロックファイルの変更を評価します。npm installをインターセプトしたりサンドボックス化したりはしません。悪意のあるパッケージがpostinstallスクリプトを実行する場合、trustlockがそれを検知する前に実行されます。trustlockは危険なロックファイルがコミットされマージされるのを防ぎ、影響範囲をチーム全体や本番環境ではなく、単一の開発者マシンに限定します。インストール時のスクリプトブロックには、--ignore-scripts またはpnpmのデフォルトのライフサイクルスクリプト制御を使用してください。

trustlockが行わないこと

• マルウェアスキャナーではない — trustlockはパッケージのソースコードを検査したり、既知の悪意のあるシグネチャを検出したりしません。そのためには専用のスキャナーを使用してください。
• インストール時サンドボックスではない — trustlockはnpm installをインターセプトしません。そのためには--ignore-scriptsを使用してください。
• CVEトラッカーではない — 脆弱性データベースにはnpm auditやSnykを使用してください。
• ライセンスチェッカーではない — license-checkerなどを使用してください。
• pnpm trustPolicyやnpmのmin-release-ageの代替ではない — これらはレジストリによって強制されるサーバーサイドの制御です。trustlockはリポジトリ境界でのクライアントサイドのアドミッションゲートです。

背景

trustlockは、標準的なNode.jsツールチェーンがプロジェクトに実際に何が取り込まれるかについて受動的すぎるというフラストレーションから生まれました。npm installは何でも取得します——2分前に公開されたパッケージ、インストール時に任意のスクリプトを実行するもの、レジストリのtarballから一晩でGit URLに変わったもの——そして得られるフィードバックはロックファイルの差分だけです。

trustlockが対処する脅威モデルは狭いですが現実的です：悪意のあるバージョンが公開されてから削除またはフラグが立てられるまでのウィンドウです。脆弱性スキャナーは事後に動作します。trustlockはアドミッション時点で、何かがリポジトリやCIに着地する前に動作します。

設計は意図的に最小限です。trustlockにはランタイムの依存関係がありません——それ自体がサプライチェーンリスクゼロのツールです。脆弱性スキャナーや依存関係監査の代替ではなく、信頼の継続性を強制します。一度ベースラインに含まれたバージョンは信頼されます。新しいものは、宣言されたポリシーに対して許可を得なければなりません。

承認ワークフローは、監査可能性を失わずに逃げ道を必要とするチームのために存在します。すべてのオーバーライドはタイムスタンプ付きで、特定のルールにスコープされ、期限があります。clean-approvalsは後付けではなく、第一級のコマンドです。