ProofRun – AIコーディングエージェントのためのローカル検証レシート
ProofRun – a local verification receipt for AI coding agents (github.com)
要約
ProofRunは、AIコーディングエージェントが実行したテストやチェックの結果を、コードの正確な状態と暗号学的に紐付けるローカル検証レシートシステムです。AIが「テストはすべてパスした」と主張しても、それが過去のコード状態に対するものか、現在のコードに対するものか区別がつかない問題を解決します。コードが変更されると結果は自動的に「STALE」(期限切れ)とマークされ、常に最新のコードに対する検証結果であることを保証します。
全文翻訳
AIコーディングエージェントのためのローカル検証レシート。
ライセンス: MIT Go 1.22+ CI codecov Release
ProofRun: チェックを実行するとPASSし、コードを編集するとSTALEに自動的に切り替わる様子
ProofRunはコードが正しいかどうかを判断しません。それは、あなたの現在のコードに対して実際にどのチェックが実行されたかを、お願いするのではなく、暗号学的に証明します。
問題点
AIコーディングエージェントが「すべてのテストに合格した」と言ったとします。それは本当でしょうか?
そうかもしれません。それはエージェントが最後にテストを実行した時には真実だったかもしれません。しかし、それは3回の編集前だったかもしれません。エージェントはそれを実行したことすら覚えていないかもしれません――単に「変更は正しそうだ、テストはおそらくまだパスするだろう」と推測しているだけかもしれません。言葉だけでは、「実行してパスした」と「パスするだろうと確信している」を区別する方法はありません。
ProofRunはそのギャップを埋めます。エージェントをより正直にすることによってではなく、主張自体を検証可能にすることによってです。
仕組み
$ proofrun run test -- pytest
...
test: pass (exit 0, 1841ms)
$ proofrun status
test PASS (exit 0, 1841ms)
# この時点以降のコード変更 — エージェントでも人間でも、関係ない
$ proofrun status
test STALE (last run: pass, exit 0 — code changed since)
すべてのチェック結果は、あなたの正確なコード状態のフィンガープリントにバインドされます。gitコミットに加えて、コミットされていないすべてのもの(ステージング済みか否か、追跡されているか否か)のハッシュが含まれます。1バイトでも変更すると、結果は自動的に STALE に切り替わります。「このPASSはまだ有効か?」と尋ねるのを誰も覚えている必要はありません。
インストール
curl -L https://github.com/yebiguo/proofrun/releases/download/v0.3.0/proofrun_linux_amd64.tar.gz | tar xz
# 他のプラットフォーム: https://github.com/yebiguo/proofrun/releases
またはソースからビルドします:
go install github.com/yebiguo/proofrun/cmd/proofrun@latest
クイックスタート
proofrun init # .proofrun.yml を書き出す
proofrun run test -- pytest # pytest を実際に実行し、結果をバインドする
proofrun status --strict # 何か PASS でないものがあれば非ゼロで終了する
なぜこれなのか、単にエージェントを信頼するのではなく
- LLM呼び出しは一切なし。 ProofRunはAIを検証するためにAIを使用しません。実際のサブプロセスを開始し、その実際の終了コードを読み取ります――それがメカニズム全体です。
- 4つのステータス、決して推測ではない。
PASS,FAIL,STALE,NOT RUN— それぞれが観測された実行、またはその不在の文書化された記録から来ています。「おそらく大丈夫」という5番目の状態はありません。 - 完全にオフライン。 ネットワーク呼び出しゼロ、テレメトリゼロ、アカウントゼロ。
- argvレベルで正確、文字列マッチングではない。
pytest -k "foo bar"として宣言されたチェックは、単にテキストに平坦化されたときに似ているように見えるコマンドでは満足できません――ProofRunは文字列ではなく、実際の引数配列を比較します。
ProofRunが意図的に行わないこと
テスト出力を解析しません、コード品質を判断しません、何も自動修正しません。完全な境界についてはAGENTS.mdを参照してください。
2つのAIエージェントによって構築された、どちらか一方だけでは信頼されない
ProofRunは、人間の指示の下でAIコーディングエージェント(Claude Code)によって書かれています。すべての変更――最初のリリースだけでなく――は、マージされる前に、2番目のAIエージェント(Codex)による独立した読み取り専用の敵対的レビューを経ます。人間が作業を指示し、実際のマージ決定を行いますが、どちらのエージェントも自身の「これは動作する」という主張は単独では十分とは見なされません。
そのレビュープロセスは形式的なものではありません。最初のリリース前に、ProofRun自身のコマンド比較が騙される可能性があることを発見しました。誤って引用されたシェル引数により、チェックがサイレントにゼロテストを実行しても PASS と報告される可能性がありました。完全な再現手順、正確な修正、そして単純なパッチでは不十分だった理由については、docs/case-study.md を参照してください。同じプロセスは、プロジェクトが成長するにつれて、依然として実際の、重大なバグを発見しています――最近ではv0.3で、攻撃者が仕込んだ署名キーがサイレントに信頼されることを許すシンボリックリンクされた .proofrun/ ディレクトリを発見しました。これは、そのコードが出荷される前でした。
すべての修正は、受け入れられる前に実際の再現手順に対して検証されます――単に妥当性のレビューや、ローンチ時だけでなく。AIエージェントに責任を持たせるためのツールが、それ自体に継続的に、一度限りのゲートではなく、同じ精査に耐えられないのであれば、存在する意味がありません。
コマンド
proofrun init # .proofrun.yml を生成する
proofrun run <check-name> -- <cmd> # <cmd> を実際に実行し、終了コード + 期間を現在のgit状態にバインドする
proofrun run-all [--only <name>] # 宣言されたすべてのチェックを実行し、各実行後に結果を保存する
proofrun status [--strict] # チェックごとの PASS / FAIL / STALE / NOT RUN; --strict は必要なチェックが PASS でない場合に非ゼロで終了する
proofrun report [--json] # 完全なレポート、人間可読または機械可読
設定: .proofrun.yml
checks:
test:
command: [pytest]
required: true
build:
command: [npm, run, build]
required: true
lint:
command: [ruff, check, .]
required: false
command はシェル文字列ではなく、argvリストです――ProofRunはシェルを経由せず、実際に実行されたものと宣言されたものを比較するには、要素ごとに正確である必要があります。required: true は、チェックが status --strict をブロックするものであり、pre-commitフックやCIゲートに配線するものです。
フィンガープリントの仕組み
すべての結果は、現在のgit HEAD と git diff HEAD のSHA-256ハッシュ(追跡されていない、無視されていないファイルの内容と組み合わせたもの)にバインドされます。proofrun status は毎回そのフィンガープリントを再計算し、ローカルに保存されているものと比較します――1バイトの変更や1つの新しいファイルであっても、不一致があれば STALE と報告されます。
改ざん防止レシート
保存されたすべての結果は、初回使用時に生成され、.proofrun/secret に保持されるランダムキーで署名(HMAC-SHA256)されます――自動的に作成され、リポジトリローカルの .git/info/exclude を介して(gitにコミットされないように最善を尽くします)(たとえあなたの .gitignore が .proofrun/ に言及していなくても。キーがそれでもgit追跡される場合、ProofRunは、リポジトリをクローンした誰もがすでに知っているキーで署名するのではなく、信頼しないことを拒否します)。ProofRun自体は決してキーをどこにも送信しません。手編集された receipt.json――たとえ完璧に一致するフィンガープリントを持っていても――はもはや検証されません。.proofrun.yml で宣言されたチェックの場合、それは NOT RUN として表示されます。宣言されずに proofrun run された一度きりのチェックの場合、信頼できないエントリは完全に破棄され、チェックは status 出力から消えます――偽のPASSは表示されず、カウントされません。
これが保証すること、しないこと:
- 改ざん防止、改ざん不可能ではない。 これは、単純な手編集(または署名の存在を知らないAIエージェントが結果を偽装しようとする)を検出しますが、
.proofrun/secretを読み取って一致する署名を偽造できる洗練された攻撃者は検出できません。それは、ローカル専用の整合性スキームの固有の限界です。 - マシンローカルであり、ポータブルな証拠ではない。
.proofrun/secretなしでreceipt.jsonを別のマシンにコピーしても検証できません。これは誰かに証拠として手渡すことを意図したものではありません――GitHub Actionの独立した再実行が、第三者が信頼すべき証拠を生成するものです。 - ロールバック/リプレイに対する防御にはならない。 同じフィンガープリントを持つ作業ツリーに対して(例えばコードがロールバックされた場合)後で復元された、以前の実際の実行からの正当に署名されたレシートは正しく検証されます――署名は「このマシンが過去のある時点でこれを生成した」ことを証明するのであり、「これが最新の実行である」ことを証明するものではありません。
- v0.3より前のレシートの移行なし — それらは単に
NOT RUNとして読み取られます;チェックを再実行してください。 - GitHub Actionはこれらに依存しない — それはチェックアウトされた
receipt.jsonを決して信頼しません(再実行前に.proofrun/をクリアします)、したがってローカル署名は、Actionの出力が信頼できる理由とは無関係です。
receipt.json
.proofrun/receipt.json はプレーンで読みやすいJSONファイルであり、外部ツールが直接解析することを歓迎しますが、ディスク上の生ファイルは信頼されていないストレージであり、信頼されたビューではありません。自分で読むということは、独自の署名検証を行う(またはフィンガープリント/終了コードだけを信頼する、これはこのプロジェクト全体が存在する理由である偽PASSのリスクと全く同じです)ことを意味します。ProofRunの実際の信頼決定――署名チェック済み、無効なエントリは破棄――をしたい場合は、proofrun status/proofrun report --json を呼び出すか、Receipt.Load が行うこと(下記参照)を再現してください。ファイル自体をそのまま読むのではなく。実際の例を以下に示します。このリポジトリに対して proofrun run build -- go build ./... を実行して生成されたものです。
{
"schema": "proofrun/v2",
"checks": {
"build": {
"status": "pass",
"command": ["go", "build", "./..."],
"exit_code": 0,
"duration_ms": 1543,
"started_at": "2026-08-16T12:32:23.2985133Z",
"verified_against": {
"head": "13ee2ba83dd2d0b992101a1e7462397758704663",
"diff_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
},
"signature": "02d78d28bf62cad8226b48ce93fc6e21a29d3d4037b7bebed0b0a6628ede2a2f"
}
}
}
| フィールド | 意味 |
|---|---|
schema | フォーマットマーカー(v0.3時点では proofrun/v2)。人間向けのラベルであり、検証が分岐するものではありません――署名の有効性が実際のゲートであり、この文字列ではありません。 |
checks.<name>.status | 最後の実際の実行の文字通りの結果:「pass」または「fail」、プロセスの終了コードのみから派生します。STALE と NOT RUN はここに書き込まれません――これらは読み取り時に計算され、保存されません。 |
checks.<name>.command | 実行された正確なargv、配列として――シェル文字列ではありません。 |
checks.<name>.exit_code, duration_ms, started_at | そのままの意味です。 |
checks.<name>.verified_against | この結果がバインドされているgit head コミットと diff_sha256 フィンガープリント――これは status が現在のフィンガープリントと比較して PASS/FAIL か STALE かを決定するために使用するものです。 |
checks.<name>.signature | このマシンのローカルキー(上記の「改ざん防止レシート」を参照)の下で、そのチェックの他のすべてのフィールドのHMAC-SHA256。 |
ディスク上 vs. 信頼されたビュー — ファイル自体を解析する場合、これが重要な部分です: 署名が検証されないチェックは、"status": "tampered" のような値で書き直されることはなく、ファイルからも削除されません――ProofRunでは何も receipt.json に書き戻しません。ただし、実際の run/run-all を除く。編集されたエントリは、誰もそのチェックを再実行しない限り、ディスク上に "status": "pass" と表示されたままになります。実際には、Receipt.Load 関数(status/report が両方とも呼び出す関数)はファイルを解析し、各エントリの署名をチェックし、検証されないものはすべて返されるメモリ内結果から破棄します――そのチェックは NOT RUN として読み取られます(または、.proofrun.yml に宣言されていない場合は status 出力から完全に消えます;上記参照)。そのフィルタリングはディスク上のファイルには一切触れません。
具体的には、生のファイルを自分で json.parse して checks.test.status == "pass" を額面通りに信頼した場合、このプロジェクトが存在する理由である偽PASSへの露出に全く同じようにさらされることになります――署名チェックがそのステータスを信頼できるものにするものであり、それをスキップすることはショートカットではなく、メカニズム全体をオプトアウトすることになります。自分で署名を検証したい場合(proofrun にシェルアウトするのではなく):それは、チェックのオブジェクトのJSONエンコーディングに対するHMAC-SHA256です。signature 自体は "" に空白化され、このマシンの .proofrun/secret でキー付けされます――独立して実装する場合は、署名される正確なバイトについては internal/receipt/sign.go を参照してください。
GitHub Action
on: pull_request
permissions:
contents: read
jobs:
verify:
runs-on: ubuntu-latest
steps:
- uses: yebiguo/proofrun@v1
これは、PRの正確なヘッドコミットを独自にチェックアウトします――呼び出し元のワークフローがすでにチェックアウトしたものを決して信頼しないため、pull_request トリガーはGitHubの合成マージプレビューコミットをサイレントに渡すことができません。次に、PRブランチで提供された receipt.json をすべてクリアし、チェックサム検証済みの proofrun バイナリをダウンロードし、実際に proofrun run-all を実行してから proofrun status --strict でゲートします。PRブランチにチェックインされたレシートのいかなるものも決して信頼されません――ゲートが見るすべての結果は、この実行によって生成されたものです。
既知の制限: これは、コードを変更する同じPR内で .proofrun.yml 自体が弱められるのを防ぐものではありません――PRはチェックのコマンドを緩めたり削除したりする可能性があり、Actionはそれを忠実に再実行します。PRのベースブランチと異なる .proofrun.yml が存在する場合(ビルド注釈を通じて)警告しますが、それに基づいてブロックすることはありません。その差分は、他の変更部分と同じようにレビューしてください。
ロードマップ
- v0.4 — 一般的なテストランナー(pytest, Jest, JUnit)の構造化出力サポート
- 同じPR内でコードを変更する際に
.proofrun.yml自体が弱められるのを防ぐ(現在は警告のみ、ブロックなし — 上記「既知の制限」参照) - ローカル改ざん防止よりも強力なもの(リモートアテステーション、公開鍵署名)はまだ設計されていません — v0.3が何を行い、意図的に保証しないかについては、上記の「改ざん防止レシート」を参照してください。
貢献
IssueとPRを歓迎します。これは若く、1.0未満のプロジェクトであり、狭く意図的なスコープを持っています――STALE検出やレシートスキーマに触れる可能性のある提案をする前にAGENTS.md を参照してください。これらはこのプロジェクトが最も間違いを許容できない部分です。
ライセンス
MIT