haltproof

HaltProof

Slurm、Kubernetes、IPMI クラスター向けの緊急シャットダウンオーケストレーション。実行された内容を正確に記録する、Ed25519 署名付きのハッシュチェーン型証明記録を備えています。

Slurm、Kubernetes、IPMI クラスター向けの署名付きシャットダウンオーケストレーション。デフォルトでドライランを実行し、改ざんを検知できる監査証跡を備えています。

HaltProof は、コンピュートクラスター向けの緊急シャットダウンオーケストレーションおよび暗号学的な監査証明レイヤーです。新しい低レベルのシャットダウン機構を実装するものではありません。信頼できる既存のクラスター操作機能（Slurm、Kubernetes、IPMI/BMC）を調整し、対象となったもの、実行された内容、承認者を正確に記録した、署名付きで改ざんを検知できる記録を生成します。

pip install haltproof-cli

（npm ラッパーを含むインストール方法の全選択肢は、以下のインストールを参照してください。）

目的

オペレーターはすでに、Slurm パーティションをドレインしたり、Kubernetes ノードプールをコーディングしたり、IPMI 経由で物理ホストを電源フェンスしたりするツールを持っています。通常不足しているのは、次のものです。

1. インシデント発生時に、プレッシャーの中で異なる 3 つのコマンドセットを使い分けるのではなく、ツール全体で一貫したインターフェースを提供すること。
2. デフォルトでドライランを実行する安全策を設け、対象グループを打ち間違えても誤ったノードを停止しないようにすること。
3. 実行内容を示す、署名付きで改ざんを検知できる記録を残すこと。誰が実行したか、どのコマンドをどのノードに対して実行したか、各手順が成功したか、記録自体が改変されたり一部が欠落したりしていないかを記録します。

HaltProof はそのレイヤーです。scontrol、kubectl、ipmitool（または mcp から呼び出し可能な同等のコマンド）を呼び出し、各実行を Ed25519 署名付きのハッシュチェーン型証明記録で包みます。

インストール

pip install haltproof-cli

Node.js ベースのツールやエージェントランタイム向けに、npm ラッパーも公開されています。

npm install -g haltproof-cli

警告

npm パッケージを使用するには、Python の haltproof-cli パッケージがすでにインストールされ、PATH 上にある必要があります。これは薄い execFileSync ラッパーであり、再実装ではありません。Python CLI が見つからない場合は、対処方法を示すエラーを出力してゼロ以外のステータスで終了し、黙って別の動作をすることはありません。

目次

• 機能
• クイックスタート
• コマンド
• アーキテクチャ
• セキュリティモデル
• MCP サーバー（AI エージェント向け）
• 比較
• HaltProof とは何か、なぜ存在するのか
• FAQ
• コントリビューション
• ライセンス

機能

• デフォルトでドライランが必須です。 haltproof halt は、実行するコマンドと対象ノードを正確に表示し、--confirm を渡さない限り、その計画の署名付き証明書も書き込みます。このゲートは単一のチョークポイント（haltproof.backends.runner.run_step）にあり、3つすべてのバックエンドがここを経由するため、特定のバックエンドのコードパスからひそかに回避されることはありません。
• 3つの実際のバックエンドで共通のインターフェースを提供します。 kubernetes（kubectl 経由）、slurm（scontrol 経由）、ipmi（ipmitool 経由）は、それぞれ同じ4つの操作からなる ClusterBackend インターフェースを実装しています。操作は drain、isolate_network、power_fence、status です。たとえば、Kubernetes には物理的な電源フェンス機能がないなど、バックエンドがある操作をサポートしない場合は、例外を発生させる代わりに説明付きの SKIPPED 結果を返します。そのため、混在環境全体を停止しても、完全な証明書を1つ作成できます。
• Ed25519 署名付きのハッシュチェーン証明書です。 ドライランでも実行時でも、停止のたびに署名付きレコードを1件、ローカルの追記専用 NDJSON ログに追加します。各レコードには直前のレコードのコンテンツハッシュである prev_hash が埋め込まれているため、haltproof verify --chain では、1件のレコード自体の署名検証だけでは検出できない、エントリーの削除や並べ替えも検出できます。
• すべてのコマンドで構造化出力を利用できます。 halt、verify、status、keygen では --json（または --format json）を利用できるため、スクリプトやエージェントは、人間向けに整形されたテキストを画面から読み取ることなく結果を解析できます。
• エージェント向けに構築された、本格的な MCP サーバーです。 haltproof mcp-server は、公式の mcp Python SDK を基盤とし、stdio 経由で halt、verify、verify_chain、status、keygen を MCP ツールとして公開します。CLI と同じ haltproof.core 関数を呼び出すため、MCP ツールを呼び出すエージェントにも、CLI を使う人間と同じデフォルトのドライラン動作が適用されます。
• テスト済みです。 テスト数は76件、全体の行カバレッジは90％です。この監査で pytest -v --cov=haltproof --cov-report=term-missing を実行し、確認しています。バックエンドのテストでは subprocess 呼び出しをモックしているため、実際のクラスターは必要ありません。

クイックスタート

重要

haltproof halt は --confirm を指定しない場合、何も実行しません。計画を表示し、 ドライランの署名付き証明書を書き込みますが、 --confirm を明示的に渡すまでは破壊的な操作は実行されません。

# Generate a signing key for attestations (do this once).
haltproof keygen --output ~/.config/haltproof/ed25519_key

# See what backend HaltProof auto-detected on this host.
haltproof status

# Dry-run a halt against an explicit node list. Nothing runs yet.
haltproof halt gpu-pod-a --nodes node-1,node-2

# Same halt, actually executed.
haltproof halt gpu-pod-a --nodes node-1,node-2 --confirm

# Verify a past attestation's signature and print its timeline.
haltproof verify 1

# Verify the entire attestation log's hash chain instead of a single
# record: this catches a deleted or reordered entry that a
# single-record signature check alone would miss.
haltproof verify --chain --attestation-log ~/.local/share/haltproof/attestations.jsonl

すべてのコマンドで、エージェントが解析可能な出力を得るための --json も利用できます。

haltproof status --json
haltproof halt gpu-pod-a --nodes node-1 --json

設定ファイル（任意）

対象グループ、優先するバックエンド、デフォルトのパスは haltproof.toml ファイルに設定できます（現在のディレクトリ、次に ~/.config/haltproof/config.toml を確認します。または --config / HALTPROOF_CONFIG で指定したパスを使用します）。

backend = "kubernetes"
operator_id = "ops-team"
attestation_log_path = "/var/log/haltproof/attestations.jsonl"

[groups]
gpu-pod-a = ["node-1", "node-2", "node-3"]

[kubernetes]
namespace = "training"

[ipmi]
user = "admin"

すべての設定値には対応する CLI フラグがあり、明示的に指定したフラグは常に設定ファイルより優先されます。

コマンド

以下のリファレンスは、CLI の実際の --help 出力から再生成されています。

haltproof halt TARGET_GROUP

TARGET_GROUP をドレインし、ネットワークから隔離して、電源フェンスを適用します。デフォルトではドライランとなり、--confirm を指定しない限り破壊的な操作は実行されません。

Options:
  --nodes TEXT             Comma-separated explicit node list, overrides
                           config group lookup.
  --backend TEXT           Backend to use: kubernetes, slurm, or ipmi.
  --confirm                Actually execute the halt. Without this, dry-run
                           only.
  --reason TEXT            Reason recorded for drain operations.
  --operator-id TEXT       Operator identity to record. Defaults to OS user.
  --config TEXT            Path to a haltproof.toml config file.
  --attestation-log TEXT   Path to the attestation log file.
  --attestation-key TEXT   Path to the Ed25519 private key used to sign the
                           attestation.
  --no-sign                Skip signing (not recommended); still logs the
                           record unsigned.
  --remote-collector TEXT  Optional URL to POST the signed attestation to.
  --format [human|json]    Output format.
  --json                   Shorthand for --format=json.

haltproof verify [ATTESTATION_REF]

1件の証明書レコードの署名、またはログ全体のハッシュチェーンを検証します。ATTESTATION_REF には、レコードファイルへのパス、またはログ内で検索する証明書 ID／シーケンス番号を指定します。ATTESTATION_REF の代わりに --chain を渡すと、--attestation-log 全体を検証します。すべてのレコードの署名が有効で、削除や並べ替えがないことを確認します。

フラグ	説明
--attestation-log TEXT	ATTESTATION_REF が ID／シーケンス番号の場合に検索するログ、または --chain で検証するログです。
--trusted-key TEXT	信頼する Ed25519 公開鍵のパスです。指定した場合、レコードの署名鍵がこの鍵と一致する必要があります。
--chain	単一レコードではなく、--attestation-log のハッシュチェーン全体を検証します。
--format [human|json]	出力形式です。
--json	--format=json の省略形です。

haltproof status

バックエンドの自動検出結果と、任意でターゲットグループの健全性を表示します。

フラグ	説明
--backend TEXT	ステータスを確認するバックエンド。デフォルトは自動検出または設定されたバックエンドです。
--nodes TEXT	健全性を報告するノードのカンマ区切りリストです。
--group TEXT	健全性を報告する名前付きターゲットグループ（設定ファイルから指定）です。
--config TEXT	haltproof.toml 設定ファイルのパスです。
--format [human|json]	出力形式です。
--json	--format=json の省略形です。

haltproof keygen

アテステーション署名用の Ed25519 キーペアを生成します。秘密鍵は 0600 の権限で書き込まれ、表示またはログへの記録は行われません。

Options:
  --output TEXT          Path to write the private key to.
  --force                Overwrite an existing key at the output path.
  --format [human|json]  Output format.
  --json                 Shorthand for --format=json.

haltproof mcp-server

HaltProof MCP サーバーを stdio で起動し、halt、verify、verify_chain、status、keygen を MCP ツールとして公開します。--help 以外のフラグはありません。

すべてのサブコマンドで、上記と同じリファレンスを直接表示する --help も使用できます。

アーキテクチャ

HaltProof は3つのレイヤーで構成されています。

1. トランスポートレイヤー：Click ベースの CLI（haltproof.cli）と MCP サーバー（haltproof.mcp_server）です。どちらも haltproof.core の同じコア関数を呼び出す薄いラッパーであるため、CLI を実行する人間と MCP ツールを呼び出すエージェントは、halt のデフォルトで有効なドライランゲートも含め、同一の動作を得られます。

2. バックエンドレイヤー：4つの操作を備えた ClusterBackend 抽象インターフェース（haltproof.backends.base）です。

   ClusterBackend
   ├── drain(nodes, dry_run, reason)         -> stop new work being scheduled
   ├── isolate_network(nodes, dry_run)       -> cut nodes off from the workload network
   ├── power_fence(nodes, dry_run)           -> hard power off
   └── status(nodes)                         -> current reachability/state
   

   現在、3つのバックエンドがこれを実装しています。

   バックエンド	drain	isolate_network	power_fence	基盤となるツール
   kubernetes	cordon + drain	全拒否 NetworkPolicy	非対応（ipmi を使用）	kubectl
   slurm	scontrol update state=drain	state=power_down（SuspendProgram フック）	非対応（ipmi を使用）	scontrol
   ipmi	非対応（slurm／kubernetes を使用）	非対応	ipmitool chassis power off	ipmitool

   特定の操作に対応していないバックエンドは例外を発生させず、説明付きの SKIPPED 結果を返します。そのため、異種環境に対する停止シーケンスでも、完全で正確なアテステーション記録が1件生成されます。新しいスケジューラーやフェンシングツールに対応するには、バックエンドモジュールを1つ追加して haltproof.backends.detect に登録するだけでよく、オーケストレーションレイヤーやアテステーションレイヤーを変更する必要はありません。

   バックエンドの選択順序は、明示的な --backend フラグ、設定ファイルの backend キー、PATH 上で見つかった kubectl／scontrol／ipmitool に基づく自動検出の順です。

3. アテステーションレイヤー（haltproof.attestation）：ドライランでも実際の操作でも、すべての停止操作によって署名付きのハッシュチェーンレコードが1件生成され、ローカルの追記専用 NDJSON ログに追加されます。

セキュリティモデル

• 署名。 アテステーションレコードは Ed25519（cryptography ライブラリ）で署名されます。署名用の公開鍵はレコード自体に埋め込まれているため、haltproof verify は内部の署名の有効性を単独で検証できます。特定の既知のオペレーターキーによる署名も必須にするには、--trusted-key を指定します。
• レコード単位の改ざん検知。 署名の対象は、署名フィールドを除くレコード全体、オペレーター、対象ノード、各ステップのコマンドとステータス、タイムスタンプ、および以下のチェーンリンクです。失敗したステップを隠すなど、フィールドを変更すると署名が無効になります。
• ログ全体にわたる改ざん検知。 レコード自体の署名で証明できるのは、そのレコードの内容が変更されていないことだけです。レコード全体が削除または並べ替えられていないことは証明できません。各レコードには、その直前のレコードのコンテンツハッシュである prev_hash が埋め込まれているため、haltproof verify --chain でシーケンス番号に欠落がなく、チェーン内のすべてのリンクが一致することを確認できます。
• 鍵の取り扱い。 haltproof keygen は秘密鍵をパーミッション 0600 で書き込み、CLI 出力、JSON 出力、MCP ツールの結果のいずれにも鍵の情報を表示または記録しません。この鍵を持つ人は、あなたが作成したものとして検証されるレコードに署名できるため、SSH 秘密鍵と同様に取り扱ってください。
• BMC 認証情報。 IPMI バックエンドは IPMI_PASSWORD 環境変数から BMC パスワードを読み込み、ipmitool -E に渡すため、コマンドライン引数、プロセス一覧、アテステーションレコードに記録されるコマンドのいずれにも表示されません。
• デフォルトでドライラン。 haltproof halt で破壊的な操作を実行するには、明示的に --confirm を指定する必要があります。これは、すべてのバックエンドが処理を経由する単一の制御点（haltproof.backends.runner.run_step）で強制されます。
• オペレーターの識別情報。 明示的に指定した --operator-id、環境から取得できる場合は SSH 証明書の識別情報、コマンドを実行している OS ユーザーの順に記録されます。

MCP サーバー（AI エージェント向け）

haltproof mcp-server

公式の mcp Python SDK を使用して、stdio 上で MCP サーバーを起動し、halt、verify、verify_chain、status、keygen をツールとして公開します。MCP 経由で接続したエージェントは、CLI の --json モードと同じ JSON 形式の結果を受け取り、halt もデフォルトでドライランとして動作します。CLI と MCP サーバーが haltproof.core 内の同じ基盤関数を呼び出すためです。

比較

HaltProof は Slurm、Kubernetes、IPMI と競合するものではありません。オペレーターがこの作業にすでに使用しているツールの上に位置し、それら単独では提供できないもの、つまり単一のインターフェース、単一の安全ゲート、署名付き記録を追加します。

機能	HaltProof	kubectl（標準）	scontrol（標準）	ipmitool（標準）
Slurm、Kubernetes、IPMI を横断する単一コマンド	はい	いいえ、Kubernetes のみ	いいえ、Slurm のみ	いいえ、IPMI のみ
どのバックエンドも実行する前に適用される、一貫したドライランゲート	はい、3 つすべてのバックエンドで 1 つの --confirm フラグを使用	部分的：--dry-run=client は構文のみを検証し、実際のクラスター変更は検証しません	組み込みのシミュレーションモードはありません。state=drain は即座に適用されます	電源コマンドにドライランの概念はありません
実行内容を記録した暗号署名付き記録	はい、Ed25519	いいえ	いいえ	いいえ
監査証跡から削除または順序変更された記録を検出	はい、ハッシュチェーンログ	いいえ	いいえ	いいえ
すべてのアクションで構造化 JSON 出力	はい、すべてのコマンド	部分的：-o json は読み取り／取得コマンドに対応しますが、drain／cordon アクションの結果には対応しません	いいえ、プレーンテキストのみ	いいえ、プレーンテキストのみ
AI エージェントから直接呼び出せる MCP サーバー	はい	いいえ	いいえ	いいえ

この監査のために実施した GitHub 検索（2026 年 8 月）では、複数のバックエンドにまたがる統合クラスターオーケストレーション、デフォルトで有効なドライランゲート、暗号署名付きのハッシュチェーン監査証跡を組み合わせた既存のオープンソースプロジェクトは見つかりませんでした。AI エージェントのツール呼び出しポリシープロキシなど、近接するプロジェクトは 1 つ上のレイヤーで動作します。つまり、AI エージェントのツール呼び出しで許可される操作をインターセプトして監査するものであり、基盤となるコンピューティング自体のインフラレベルのシャットダウンを行うものではありません。HaltProof がこのカテゴリとどのように関係するかについては、以下の FAQ をご覧ください。

HaltProof とは何か、なぜ存在するのか

HaltProof は、オペレーターがすでに信頼しているクラスターシャットダウンのプリミティブ、すなわち Slurm 用の scontrol、Kubernetes 用の kubectl、IPMI/BMC 用の ipmitool の上に構築された、オーケストレーションおよび監査証跡のレイヤーです。ノードのドレイン、分離、電源フェンシングを再実装するものではありません。実際のツールを呼び出し、その呼び出しをデフォルトで有効なドライランによる安全確認の背後に置き、対象となったもの、実行された内容、承認者を正確に記録した改ざん検知可能な記録に署名します。

実際のインシデントでは、次の 3 つの問題が同時に発生しがちなため、HaltProof は必要です。

1. 緊急時に異なる 3 種類のコマンドセットが必要です。 オペレーターは Slurm パーティションのドレイン、Kubernetes ノードプールのコルドン、IPMI 経由での物理ホストの電源フェンシングの方法をすでに知っています。しかし、インシデント中にこの 3 つすべてを一貫して実施するには、最悪のタイミングで、異なるツール、異なるフラグの規則、異なる障害モードをそれぞれ覚えておく必要があります。
2. 共通の安全策がありません。 kubectl drain --dry-run=client は構文のみを検証し、実際のクラスター変更をシミュレートしません。scontrol update state=drain は実行した瞬間に適用されます。対象グループを誤って入力しても、実際の処理が行われる前にそれを検知するための、一貫したツール非依存の方法がありません。
3. 事後に証明するものがありません。 3 つの標準ツールのいずれも、対象となったもの、実際に実行された内容、成功したかどうか、承認者を記録した、署名付きの改ざん検知可能な記録を生成しません。変更管理の証跡や EU AI Act の人間による監督に関する規定などのコンプライアンスフレームワーク向けに、こうしたログ記録と署名のレイヤーを自分で構築するには、ゼロから実装する必要があります。

HaltProof は、これら 3 つすべてに同時に対応するレイヤーです。単一の CLI と単一の MCP インターフェース、すべてのバックエンドが経由する単一の --confirm ゲート、そして Ed25519 署名付きのハッシュチェーン認証ログを提供します。

FAQ

HaltProof は実際には何をするもので、kubectl／scontrol／ipmitool を直接スクリプトから実行するのと比べて、最も大きな違いは何ですか？ HaltProof は、scontrol、kubectl、ipmitool など、直接実行するのと同じツールを呼び出しますが、すべての呼び出しにデフォルトでドライランとなるゲートを設け、Ed25519 署名付きのハッシュチェーン形式の証跡レコードを生成します。手書きのスクリプトでも同じ基盤コマンドを呼び出せますが、--confirm なしでは実行を拒否せず、後からログが改変または削除されていないことを証明するレコードも生成しません。

HaltProof 自体が電源やネットワークアクセスを遮断しますか？ いいえ。すでに実行して信頼している scontrol、kubectl、ipmitool を呼び出し、各呼び出しをドライランゲートと署名付きレコードで保護します。HaltProof が提供するのはオーケストレーションと証明であり、新たな低レベルのシャットダウン機構ではありません。

HaltProof がサポートするオペレーティングシステムと Python のバージョンを教えてください。 公開されている PyPI パッケージは、Linux と macOS で Python 3.10 以降を対象としています（Operating System :: POSIX :: Linux と Operating System :: MacOS の分類を参照してください）。現時点では Windows の分類はなく、特に IPMI バックエンドは ipmitool のシェル実行に依存しているため、Windows は主な対象ではありません。Windows での利用が必要な場合は、イシューを作成してください。

同じツールを呼び出すランブックや Ansible プレイブックを書く場合と何が違いますか？ ランブックや Ansible プレイブックでも同じ基盤コマンドを呼び出せますが、実際に実行された内容について、暗号署名付きで改ざんを検知できるレコードを単独では生成しません。そのためには、ログ記録と署名のレイヤーを自分で構築する必要があります。HaltProof ではこれがデフォルトの動作として提供されます。また、3 つのバックエンドそれぞれに別々の安全規約を設けたプレイブックを用意する代わりに、すべてのバックエンドで共通の、デフォルトでドライランとなる単一のゲートを利用できます。

これは「AI セーフティのキルスイッチ」ですか？ いいえ。HaltProof は、クラスター運用者向けのインフラストラクチャーのインシデント対応およびコンプライアンス監査ツールです。AI モデルの動作に関する見解は持たず、AI セーフティやアラインメントに関する主張もしません。AI エージェントの個々のツール呼び出しをインターセプトして監査するツールは、まったく別のレイヤーで動作します。HaltProof は、AI を使わないワークロードの場合と同じように、基盤となるコンピューティングのシャットダウン自体をオーケストレーションします。

ノードに必要なツールがインストールされていない場合はどうなりますか？ 該当するバックエンドは、そのステップを実際のエラー（たとえば executable not found）とともに failed として報告します。証跡レコードは引き続き書き込まれて署名されるため、失敗そのものが監査可能な履歴に残ります。

証跡に署名せずに HaltProof を使えますか？ はい。--no-sign を指定すると署名を省略しつつ、レコードはログに書き込まれます。これはローカルテストを目的としたもので、署名されていないレコードは真正性を検証できないため、本番環境のインシデント対応には適していません。

証跡ログに中央サーバーは必要ですか？ いいえ。デフォルトでは、ローカルの追記専用 NDJSON ファイルです。--remote-collector を使うと、中央コピーを保存したいチーム向けに、署名済みの各レコードを設定した URL に POST できます。ただし、検証にそのサーバーへの接続は必要ありません。

2 人の運用者が同じ証跡ログに対して同時に halt を実行するとどうなりますか？ 追記にはファイルロック（POSIX では fcntl.flock）が使われるため、書き込みが混在することはありません。ただし、シーケンス番号は各コマンドの開始時にログを読み取って割り当てられます。操作ごとの厳密な直列化が必要な場合は、バックエンドごと、またはインシデントごとのログファイルを各運用者に指定してください。

HaltProof のライセンスは何ですか？商用利用できますか？ MIT です。著作権表示とライセンステキストを添付したままであれば、商用利用を含め、使用、変更、再配布ができます。LICENSE を参照してください。

コントリビューション

コントリビューションを歓迎します。まず CONTRIBUTING.md をお読みください。開発環境のセットアップ、テストスイートの実行（pytest -v --cov=haltproof --cov-report=term-missing）、および ClusterBackend インターフェースを実装して新しいバックエンドを追加する手順について説明しています。アテステーションの署名／検証、またはドライラン／--confirm のゲートに関わる変更は、CODEOWNERS に従って追加レビューを受けます。公開の課題を作成するのではなく、脆弱性を非公開で報告する方法については SECURITY.md をご覧ください。

git clone https://github.com/RudrenduPaul/HaltProof.git
cd HaltProof
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -v --cov=haltproof --cov-report=term-missing

ライセンス

MIT © Rudrendu Paul and Sourav Nandy