POPL・プルーフコマンド

公開安全な監査証跡とバリデーションプラン管理

POPLとは？

POPL (Public Observable Proof Ledger) は、MCPセッションから公開安全な監査証跡を生成します。すべての機密情報（パス、シークレット、PII）は自動的にサニタイズされます。

主な特徴

🔒 自動サニタイズ: シークレット、パス、PIIを削除
📊 セッションメタデータ: セッション構造、タイミング、ステータスを保持
🔐 コンテンツハッシュ: RPCペイロードをSHA-256ハッシュに置換
📝 再現可能: 生成ログを含む
🌐 公開安全: バグレポートや公開共有に安全

用途

用途	説明
バグレポート	シークレットを露出せずに実行証拠を含める
監査	ツール使用と権限を追跡
ドキュメント	再現可能な例を生成
コンプライアンス	規制環境向けの監査証跡を作成
デバッグ	セキュリティリスクなしでセッション詳細を共有

`popl` - POPL管理

公開安全な監査証跡を作成・管理します。

サブコマンド

`popl init`

POPLディレクトリを初期化します。

cd /path/to/project
pfscan popl init

これにより以下が作成されます：

.popl/
├── README.md         # POPLドキュメント
└── entries/          # POPLエントリの保存場所

`popl session`

セッションからPOPLエントリを作成します。

# 基本的な使用
pfscan popl session --session <session-id>

# タイトル付き
pfscan popl session --session abc123 --title "Time Server Test"

# 説明付き
pfscan popl session --session abc123 \
  --title "Weather API Integration" \
  --description "Testing weather forecast tool"

出力例：

✓ POPL entry created: 20260104-abc123

Entry location:
  .popl/entries/20260104-abc123/

Files created:
  POPL.yml              # エントリメタデータ
  status.json           # セッションサマリー
  rpc.sanitized.jsonl   # サニタイズ済みRPCイベント
  validation-run.log    # 生成ログ

`popl list`

POPLエントリの一覧を表示します。

pfscan popl list
pfscan popl list --json

`popl show`

POPLエントリの詳細を表示します。

# エントリ詳細
pfscan popl show 20260104-abc123

# 特定のアーティファクト
pfscan popl show 20260104-abc123 status
pfscan popl show 20260104-abc123 popl
pfscan popl show 20260104-abc123 log

POPLエントリの構造

.popl/entries/20260104-abc123/
├── POPL.yml              # エントリメタデータと証拠サマリー
├── status.json           # セッションサマリー（公開安全）
├── rpc.sanitized.jsonl   # サニタイズ済みRPCイベント
└── validation-run.log    # 生成ログ

サニタイゼーション

POPLは機密データを保護するために自動サニタイゼーションを適用します。

削除される情報

シークレット: APIキー、トークン、パスワード
ファイルパス: 絶対パス、ホームディレクトリ、一時ディレクトリ
PII: 個人を特定できる情報
RPCペイロード: SHA-256ハッシュに置換

保持される情報

セッション構造（コネクタ、タイミング、ステータス）
RPC メソッド名とID
ツール名と呼び出し回数
エラーステータス（詳細メッセージはサニタイズ）
機能（tools、resources、prompts）

`plans` - バリデーションプラン

MCPサーバーのバリデーションプランを管理・実行します。

サブコマンド

`plans ls`

プランの一覧を表示します。

pfscan plans ls
pfscan plans list

出力例：

Name           Source   Description                Created
----------------------------------------------------------------
basic-mcp      manual   Basic MCP validation       2026-01-04
full-scan      import   Full server scan           2026-01-03

`plans show`

プランの詳細を表示します。

pfscan plans show basic-mcp
pfscan plans show basic-mcp --raw     # 生のYAML
pfscan plans show basic-mcp --json    # JSON形式

`plans add`

新しいプランを追加します。

# ファイルから追加
pfscan plans add myplan --file plan.yaml

# 標準入力から追加
cat plan.yaml | pfscan plans add myplan --stdin

プランYAML形式：

version: 1
name: basic-mcp-validation
description: Basic MCP server validation
steps:
  - mcp: initialize
  - mcp: tools/list
  - when: capabilities.resources
    mcp: resources/list
  - when: capabilities.prompts
    mcp: prompts/list

`plans run`

プランを実行します。

# コネクタに対して実行
pfscan plans run basic-mcp --connector time

# オプション付き
pfscan plans run basic-mcp --connector time --timeout 60
pfscan plans run basic-mcp --connector time --out ./results

# ドライラン（実行せずにステップを表示）
pfscan plans run basic-mcp --connector time --dry-run

出力例：

Running plan 'basic-mcp' against connector 'time'...

Run ID: 01KE4ABCD1234
Status: completed
Duration: 523ms

Steps:
  1. [OK] initialize (269ms)
  2. [OK] tools/list (12ms)
  3. [SKIP] resources/list (when: capabilities.resources)
  4. [SKIP] prompts/list (when: capabilities.prompts)

Inventory:
  Capabilities: tools
  Tools: 2

Artifacts: ~/.config/proofscan/artifacts/01KE4ABCD1234

`plans runs`

実行履歴を表示します。

pfscan plans runs
pfscan plans runs --plan basic-mcp    # プランでフィルタ
pfscan plans runs --limit 50

`plans run-show`

実行の詳細を表示します。

pfscan plans run-show 01KE4ABCD1234
pfscan plans run-show 01KE4 --json    # 部分IDも使用可能

`plans delete`

プランを削除します。

pfscan plans delete myplan
pfscan plans delete myplan --force    # 関連する実行も削除

`plans import`

プランをインポートします。

# ファイルからインポート（複数ドキュメントYAML対応）
pfscan plans import --file plans.yaml

`plans export`

プランをエクスポートします。

# ファイルにエクスポート
pfscan plans export myplan --file myplan.yaml

# 標準出力にエクスポート
pfscan plans export myplan --stdout

実行アーティファクト

各プラン実行は ~/.config/proofscan/artifacts/<run-id>/ にアーティファクトを作成します：

meta.json          # 実行メタデータ
plan.yaml          # 正規化されたプラン定義
plan.original.yaml # 元のYAML
run.log            # 人間が読める実行ログ
results.json       # ステップごとの結果
inventory.json     # 発見された機能/ツール/リソース/プロンプト

`archive` - データ保持管理

データ保持とクリーンアップを管理します。

サブコマンド

`archive status`

アーカイブステータスを表示します。

pfscan archive status

`archive plan`

アーカイブ/削除される内容を表示します（実際には実行しません）。

pfscan archive plan

`archive run`

アーカイブを実行します。

# ドライラン（何が起こるか表示）
pfscan archive run

# 実際に実行
pfscan archive run --yes

# 実行してディスク領域を回収
pfscan archive run --yes --vacuum

よくあるワークフロー

POPL生成ワークフロー

# 1. POPLディレクトリを初期化
cd /path/to/project
pfscan popl init

# 2. スキャンを実行
pfscan scan start --id time

# 3. セッションIDを取得
pfscan tree

# 4. POPLエントリを作成
pfscan popl session --session abc123 \
  --title "Time Server Validation" \
  --description "Testing time server tools"

# 5. エントリを確認
pfscan popl list
pfscan popl show 20260104-abc123

バリデーションプランワークフロー

# 1. プランを作成
cat > validation.yaml << 'EOF'
version: 1
name: mcp-validation
description: MCP server validation
steps:
  - mcp: initialize
  - mcp: tools/list
  - mcp: tools/call
    tool: get_current_time
    args: {}
EOF

# 2. プランを追加
pfscan plans add mcp-validation --file validation.yaml

# 3. プランを実行
pfscan plans run mcp-validation --connector time

# 4. 結果を確認
pfscan plans runs
pfscan plans run-show <run-id>

# 5. POPLエントリを作成
pfscan popl session --session <session-id> \
  --title "MCP Validation Run"

メンテナンスワークフロー

# 1. ステータス確認
pfscan status
pfscan archive status

# 2. アーカイブプランを表示
pfscan archive plan

# 3. 古いデータをクリーンアップ
pfscan archive run --yes --vacuum

# 4. ステータス再確認
pfscan status

ベストプラクティス

POPL使用時

わかりやすいタイトル: エントリに説明的なタイトルを付ける
バグレポートに含める: POPLエントリをバグレポートに添付
定期的なレビュー: POPLエントリを定期的にレビューして古いものを削除
バージョン管理: 重要なPOPLエントリをGitで管理

バリデーションプラン

段階的なテスト: 基本的なステップから始めて徐々に拡張
条件付きステップ: when を使って機能に応じた実行
再利用可能なプラン: 汎用的なプランを作成して複数のコネクタで使用
CI/CD統合: プランを自動テストパイプラインに組み込む

データ管理

定期的なアーカイブ: 週次または月次でアーカイブを実行
保持ポリシー: 適切な保持設定を config.json で設定
ディスク容量監視: データベースサイズを定期的に確認
重要なセッションをPOPL化: 削除前に重要なセッションをPOPLエントリとして保存

よくある質問

Q. POPLエントリは本当に公開安全ですか？

A. はい。POPLは以下をすべて削除/ハッシュ化します：

APIキー、トークン、パスワード
ファイルパス（絶対パス、ホームディレクトリ）
個人を特定できる情報（PII）
RPCペイロードの内容（SHA-256ハッシュに置換）

ただし、念のため公開前にエントリを確認することをお勧めします。

Q. バリデーションプランの実行が失敗する

A. 以下を確認してください：

コネクタが有効で動作しているか
プランのYAML形式が正しいか
タイムアウト設定が十分か
実行ログ（run.log）を確認

Q. アーカイブでデータが失われないか心配

A. まずドライランで確認してください：

# 何が削除されるか確認
pfscan archive plan

# 重要なセッションをPOPL化
pfscan popl session --session <important-session-id>

# 安全に実行
pfscan archive run --yes

POPL・プルーフコマンド

POPLとは？

主な特徴

用途

popl - POPL管理

サブコマンド

popl init

popl session

popl list

popl show

POPLエントリの構造

サニタイゼーション

削除される情報

保持される情報

plans - バリデーションプラン

サブコマンド

plans ls

plans show

plans add

plans run

plans runs

plans run-show

plans delete

plans import

plans export

実行アーティファクト

archive - データ保持管理

サブコマンド

archive status

archive plan

archive run

よくあるワークフロー

POPL生成ワークフロー

バリデーションプランワークフロー

メンテナンスワークフロー

ベストプラクティス

POPL使用時

バリデーションプラン

データ管理

よくある質問

Q. POPLエントリは本当に公開安全ですか？

Q. バリデーションプランの実行が失敗する

Q. アーカイブでデータが失われないか心配

関連情報

`popl` - POPL管理

`popl init`

`popl session`

`popl list`

`popl show`

`plans` - バリデーションプラン

`plans ls`

`plans show`

`plans add`

`plans run`

`plans runs`

`plans run-show`

`plans delete`

`plans import`

`plans export`

`archive` - データ保持管理

`archive status`

`archive plan`

`archive run`