MCP Permit Ledger v1.1

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への組み込みは含みません。