# MCP Permit Ledger 1.1.0 AIエージェントやMCPツールの「操作予定・操作結果イベント」をJSONLで受け取り、ローカルで権限判定と監査レシートを生成するWindows向けCLIです。実際のMCP通信を中継・実行する製品ではありません。Python 3.11以上、標準ライブラリのみで動きます。 ## できること - `read / write / execute / network / delete / other` の判定 - `allow / deny / require_approval` と先勝ちルール - 承認者・理由・時刻の記録（`deny`は承認で上書き不可） - dry-run記録。どのモードでも本CLI自体は操作を実行しません - SHA-256ハッシュチェーンによる改変検知支援 - HTML / JSON / CSVレポート - 許可済み観測から最小権限ポリシー候補を生成 - Codex/MCP風ツールイベントを正規JSONLへ変換 - Windowsパス正規化、重複ID拒否、追記前チェーン検証 - 単一プロセスロックと原子的台帳更新 - オプションのHMAC-SHA256承認検証 - inboxへJSONLを置くだけのフォルダ一括取り込み ## 3分デモ（Windows） 1. Python 3.11以上をインストールします。 2. `run_demo.bat` をダブルクリックします。 3. `sample/report.html` をブラウザで開きます。 既存の `sample/ledger.jsonl` がある状態で再実行すると追記されます。新品デモに戻す場合は、`sample`内の生成物を別の場所へ移してから実行してください。 ## CLI ```powershell python mcp_permit_ledger.py ingest --events examples/events.jsonl --policy examples/policy.json --ledger my-ledger.jsonl --dry-run python mcp_permit_ledger.py verify --ledger my-ledger.jsonl python mcp_permit_ledger.py report --ledger my-ledger.jsonl --output report.html --format html python mcp_permit_ledger.py report --ledger my-ledger.jsonl --output report.csv --format csv python mcp_permit_ledger.py suggest --ledger my-ledger.jsonl --output suggested-policy.json python mcp_permit_ledger.py convert --input examples/codex-mcp-generic.jsonl --output converted.jsonl python mcp_permit_ledger.py ingest-folder --folder inbox --processed processed --policy examples/policy.json --ledger my-ledger.jsonl --dry-run ``` イベントは1行1 JSONオブジェクトです。`id, actor, action, resource` が必須です。承認付きイベントは次の形式です。 ```json {"id":"evt-1","actor":"codex","action":"write","resource":"C:/project/out.txt","approval":{"approver":"山田太郎","reason":"成果物レビュー済み","approved_at":"2026-07-17T01:00:00+09:00"}} ``` ポリシーはJSONが正式対応です。ルールは上から最初に一致したものを採用します。広い許可より先に秘密領域の拒否など具体的ルールを置いてください。 ## Codex / MCP風JSONLアダプター `convert`は汎用的なツール呼び出しログを正規イベントへ変換します。入力は1行1 JSONオブジェクトです。実例は`examples/codex-mcp-generic.jsonl`にあります。 | 正規フィールド | 入力候補（左から優先） | |---|---| | `id` | `id`, `event_id`, `call_id`, `tool_call_id`。なければ内容から安定ID | | `actor` | `actor`, `agent`, `agent_id`, `source` | | `action` | 有効な`action`、またはツール名からread/write/execute/network/deleteを推定 | | `resource` | `resource`, `target`, `path`, `url`、次に`arguments`内のpath/file/target/resource/url/command/cwd | | `timestamp` | `timestamp`, `time`、なければ変換時刻 | | `details` | アダプター名、ツール名、元のarguments | ツール名は`tool`, `tool_name`, `name`, `operation`から取得し、`arguments`, `args`, `input`を引数として扱います。推定は完全ではないため、変換結果を確認してからingestしてください。本製品はCodexやMCPの内部ログ形式を保証するものではなく、公開された汎用JSONLの受け口です。 ## Windowsリソース正規化 ポリシー照合前にドライブ文字・パスの大小文字をcase-foldし、`\\`を`/`へ統一し、`.`と`..`を解決します。`C:\\Allowed\\..\\Secrets\\A.txt`は`c:/secrets/a.txt`として判定されます。元値が変化した場合は`resource_original`へ残します。URLはscheme/hostの大小文字とパスのdot segmentを正規化します。ルールprefixはディレクトリ境界で照合するため、`c:/safe`が`c:/safety`へ一致することはありません。 ## 署名付き承認（オプション） HMAC鍵は環境変数だけから読みます。CLI引数、設定ファイル、ログに秘密値を書かないでください。 ```powershell $env:MPL_APPROVAL_KEY = "十分に長いランダムな秘密値" python mcp_permit_ledger.py sign-approval --event approved-event.json --output signed-event.json --key-env MPL_APPROVAL_KEY python mcp_permit_ledger.py ingest --events signed-events.jsonl --policy examples/policy-hmac.json --ledger ledger.jsonl --dry-run ``` `sign-approval`の入力は単一JSONオブジェクトで、出力はそのままingestできる1行JSONLです。署名対象はevent id、actor、action、正規化resource、approver、reason、approved_atです。署名後にこれらを変更すると検証に失敗します。ポリシーの`approval.require_hmac: true`または`--require-signed-approvals`で未署名承認を保留にできます。HMACは共有鍵の所持を示すだけで、個人の本人性や否認防止を保証しません。 ## inbox運用 `ingest-folder`は`--folder`直下の`*.jsonl`を名前順に取り込み、成功したファイルだけ`--processed`へ移します。失敗したファイルはinboxに残ります。台帳は毎回ロックされ、既存チェーン検証、重複event ID検査、原子的置換を行います。複数ホストからの共有フォルダ同時書き込みは対象外です。 ## 重要な限界 ハッシュチェーンは「改変があった可能性を検知しやすくする」tamper-evident機能です。改変そのものを防ぐ、作成者を証明する、法的証拠能力を保証する、という機能ではありません。攻撃者がログ全体を再生成できる環境では検知できないため、定期的に最終ハッシュを別管理してください。ファイルロックは同一PC上の協調プロセス向けで、悪意あるプロセスやネットワーク共有を排他するものではありません。詳しくは `SECURITY.md` と `THREAT_MODEL.md` を参照してください。 ## テスト ```powershell python -m unittest discover -s tests -v ``` ## 商用利用 同梱 `LICENSE` を参照してください。購入組織内での利用を想定しています。再配布・再販売・SaaSへの組み込みは含みません。