agentwit 0.1.0__tar.gz

agentwit-0.1.0/.claude/settings.local.json

@@ -0,0 +1,14 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python:*)",
+      "Bash(pip install:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(gh auth:*)",
+      "Bash(sudo apt:*)",
+      "Bash(curl:*)",
+      "Bash(pip index:*)"
+    ]
+  }
+}

agentwit-0.1.0/.gitignore

@@ -0,0 +1,73 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+dist/
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Testing
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+htmlcov/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pytype/
+.pyre/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# agentwit — witness log output
+witness_logs/
+*.jsonl
+/tmp/agentwit_*/
+
+# Secrets
+.env
+.env.*
+*.pem
+*.key
+secrets.json

agentwit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 agentwit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentwit-0.1.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: agentwit
+Version: 0.1.0
+Summary: Transparent proxy witness for AI agent ↔ MCP server communications
+Project-URL: Homepage, https://github.com/tokotokokame/agentwit
+Project-URL: Repository, https://github.com/tokotokokame/agentwit
+Project-URL: Issues, https://github.com/tokotokokame/agentwit/issues
+Project-URL: Changelog, https://github.com/tokotokokame/agentwit/releases
+Author: tokotokokame
+License: MIT
+License-File: LICENSE
+Keywords: ai-agent,audit,llm,mcp,proxy,security,witness
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.10
+Requires-Dist: anyio>=4.3.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: fastapi>=0.111.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: uvicorn[standard]>=0.29.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentwit
+
+> Transparent witness for AI agent ↔ MCP server communications
+
+[日本語版 / Japanese](README.ja.md)
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-48%20passing-brightgreen.svg)](#)
+
+## What is agentwit?
+
+agentwit is a transparent proxy that sits between AI agents and MCP servers,
+recording every communication as a tamper-proof witness log.
+
+Unlike existing tools that act as **"guards"** (blocking suspicious traffic),
+agentwit acts as a **"witness"** — it never blocks, never interferes, but
+records everything with cryptographic chain integrity.
+
+## Guard vs. Witness
+
+| Tool         | Approach          | Blocks traffic | Tamper-proof log |
+|--------------|-------------------|:--------------:|:----------------:|
+| mcp-scan     | Proxy + Guard     | ✅             | ❌               |
+| Proximity    | Static scanner    | —              | ❌               |
+| Intercept    | Policy proxy      | ✅             | ❌               |
+| **agentwit** | **Witness proxy** | **❌**         | **✅**           |
+
+## How it works
+
+```
+AI Agent
+   │
+   ▼
+agentwit proxy  ◄── records every message with chain hash
+   │                 never blocks, fully transparent
+   ▼
+MCP Server       ◄── zero modification required
+```
+
+Each recorded event is chained to the previous one via SHA-256:
+
+```
+genesis_hash = sha256("genesis:" + session_id)
+      │
+      ▼
+event_1:  session_chain = sha256(genesis_hash  +  hash(event_1))
+      │
+      ▼
+event_2:  session_chain = sha256(event_1_chain +  hash(event_2))
+      │
+      ▼
+     ...
+```
+
+Any single-byte modification to any event breaks the entire chain from
+that point forward — making tampering immediately detectable.
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install agentwit
+```
+
+### 1. Start the witness proxy
+
+```bash
+agentwit proxy --target http://localhost:3000 --port 8765
+# Starting agentwit proxy → http://localhost:3000
+# Listening on 127.0.0.1:8765
+# Session: ./witness_logs/session_20260314_120000
+```
+
+### 2. Point your agent to the proxy
+
+```bash
+# Before: http://localhost:3000
+# After:  http://localhost:8765
+# That's it. No other changes needed.
+```
+
+### 3. Generate an audit report
+
+```bash
+agentwit report --session ./witness_logs/session_20260314_120000 \
+                --format html --output report.html
+```
+
+### 4. Verify chain integrity
+
+```bash
+agentwit replay --session ./witness_logs/session_20260314_120000
+# Session: session_20260314_120000  (6 events)
+# Chain integrity: VALID
+```
+
+## Commands
+
+```
+agentwit proxy   --target URL [--port 8765] [--log-dir ./witness_logs] [--actor NAME]
+agentwit report  --session DIR [--format json|markdown|html] [--output FILE]
+agentwit replay  --session DIR [--verify/--no-verify]
+agentwit diff    --session-a DIR --session-b DIR
+```
+
+| Command   | Description                                    |
+|-----------|------------------------------------------------|
+| `proxy`   | Start the transparent witness proxy            |
+| `report`  | Generate audit report (json / markdown / html) |
+| `replay`  | Replay and verify chain integrity of a session |
+| `diff`    | Compare two sessions side by side              |
+
+## Witness Log Format
+
+Each intercepted event is stored as one JSON line in `witness.jsonl`:
+
+```json
+{
+  "witness_id":      "sha256 of the entire signed event",
+  "session_chain":   "sha256(prev_chain_hash + event_hash)",
+  "timestamp":       "2026-03-14T12:18:53.708937+00:00",
+  "actor":           "demo-agent",
+  "action":          "tools/call",
+  "tool":            "bash",
+  "input_hash":      "sha256 of the input payload",
+  "output_hash":     "sha256 of the output payload",
+  "full_payload":    { "params": {}, "result": {} },
+  "risk_indicators": [
+    { "pattern": "shell_exec", "severity": "high", "matched": "bash" }
+  ]
+}
+```
+
+Events are appended to a JSONL file as they arrive — the proxy never
+buffers or delays the upstream response.
+
+## Tamper Detection
+
+Modify any field in the log and agentwit detects it immediately:
+
+```bash
+# Simulate tampering: change "actor" in event[0]
+python3 -c "
+import json; lines=open('witness.jsonl').readlines()
+e=json.loads(lines[0]); e['actor']='ATTACKER'
+lines[0]=json.dumps(e)+'\n'; open('witness.jsonl','w').writelines(lines)
+"
+
+agentwit replay --session ./witness_logs/session_20260314_120000
+# Session: session_20260314_120000  (6 events)
+# Chain integrity: TAMPERED
+#   [event 0] FAIL - session_chain mismatch:
+#     expected '0fd4d24bcb3dab7d171e…'
+#     got      'a79a9e4cdb19795a521e…'
+```
+
+## Use Cases
+
+- **Security engineers** auditing AI agent behavior in production
+- **Enterprise teams** requiring AI activity compliance logs
+- **AI researchers** reproducibly comparing agent sessions
+- **Penetration testers** documenting MCP tool usage as evidence
+
+## Python API
+
+```python
+from agentwit import WitnessLogger, ChainManager
+
+# Direct logging (no proxy needed)
+logger = WitnessLogger(session_dir="./logs", actor="my-agent")
+event = logger.log_event(
+    action="tools/call",
+    tool="bash",
+    full_payload={"params": {"command": "ls"}, "result": {"stdout": "..."}}
+)
+logger.close()
+
+# Verify a recorded session
+chain = ChainManager(session_id="session_20260314_120000")
+results = chain.verify_chain(events)
+all_valid = all(r["valid"] for r in results)
+```
+
+## Requirements
+
+- Python 3.10+
+- FastAPI, uvicorn, httpx, click (installed automatically)
+
+## License
+
+[MIT](LICENSE) © agentwit contributors

agentwit-0.1.0/README.ja.md

@@ -0,0 +1,193 @@
+# agentwit
+
+> AIエージェントとMCPサーバー間の通信を記録する透過型Witnessプロキシ
+
+[English](README.md)
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-48%20passing-brightgreen.svg)](#)
+
+## agentwit とは？
+
+agentwit は、AIエージェントとMCPサーバーの間に置く透過型プロキシです。
+すべての通信を改ざん検知可能なWitness Log（改ざん検知ログ）として記録します。
+
+不審なトラフィックをブロックする **「ガード」** 型の既存ツールとは異なり、
+agentwit は **「証人（Witness）」** として動作します。
+通信をブロックせず、改変もせず、ただ暗号化されたChain Integrity（チェーン整合性）付きですべてを記録します。
+
+## Guard（ガード）vs. Witness（証人）
+
+| ツール       | アプローチ        | 通信のブロック | 改ざん検知ログ |
+|--------------|-------------------|:--------------:|:--------------:|
+| mcp-scan     | プロキシ + ガード | ✅             | ❌             |
+| Proximity    | 静的スキャナー    | —              | ❌             |
+| Intercept    | ポリシープロキシ  | ✅             | ❌             |
+| **agentwit** | **Witnessプロキシ** | **❌**       | **✅**         |
+
+## 仕組み
+
+```
+AIエージェント
+   │
+   ▼
+agentwit proxy  ◄── 全メッセージをChainハッシュ付きで記録
+   │                 ブロックなし・完全透過
+   ▼
+MCPサーバー      ◄── 変更不要・そのまま動作
+```
+
+記録された各イベントは SHA-256 でチェーン状に連結されます：
+
+```
+genesis_hash = sha256("genesis:" + session_id)
+      │
+      ▼
+event_1:  session_chain = sha256(genesis_hash  +  hash(event_1))
+      │
+      ▼
+event_2:  session_chain = sha256(event_1_chain +  hash(event_2))
+      │
+      ▼
+     ...
+```
+
+どのイベントに対しても1バイトの変更を加えると、その時点からチェーン全体が壊れます。
+これにより改ざんを即座に検出できます。
+
+## クイックスタート
+
+### インストール
+
+```bash
+pip install agentwit
+```
+
+### 1. Witnessプロキシを起動
+
+```bash
+agentwit proxy --target http://localhost:3000 --port 8765
+# Starting agentwit proxy → http://localhost:3000
+# Listening on 127.0.0.1:8765
+# Session: ./witness_logs/session_20260314_120000
+```
+
+### 2. エージェントの向き先をプロキシに変更
+
+```bash
+# 変更前: http://localhost:3000
+# 変更後: http://localhost:8765
+# 以上です。他に変更は不要です。
+```
+
+### 3. 監査レポートを生成
+
+```bash
+agentwit report --session ./witness_logs/session_20260314_120000 \
+                --format html --output report.html
+```
+
+### 4. Chain Integrityを検証
+
+```bash
+agentwit replay --session ./witness_logs/session_20260314_120000
+# Session: session_20260314_120000  (6 events)
+# Chain integrity: VALID
+```
+
+## コマンド一覧
+
+```
+agentwit proxy   --target URL [--port 8765] [--log-dir ./witness_logs] [--actor NAME]
+agentwit report  --session DIR [--format json|markdown|html] [--output FILE]
+agentwit replay  --session DIR [--verify/--no-verify]
+agentwit diff    --session-a DIR --session-b DIR
+```
+
+| コマンド  | 説明                                                     |
+|-----------|----------------------------------------------------------|
+| `proxy`   | 透過Witnessプロキシを起動                                 |
+| `report`  | 監査レポートを生成（json / markdown / html）              |
+| `replay`  | セッションを再生しChain Integrityを検証                   |
+| `diff`    | 2つのセッションを並べて比較                               |
+
+## Witness Logのフォーマット
+
+傍受された各イベントは `witness.jsonl` に1行のJSONとして記録されます：
+
+```json
+{
+  "witness_id":      "イベント全体のsha256",
+  "session_chain":   "sha256(直前のchain_hash + event_hash)",
+  "timestamp":       "2026-03-14T12:18:53.708937+00:00",
+  "actor":           "demo-agent",
+  "action":          "tools/call",
+  "tool":            "bash",
+  "input_hash":      "入力ペイロードのsha256",
+  "output_hash":     "出力ペイロードのsha256",
+  "full_payload":    { "params": {}, "result": {} },
+  "risk_indicators": [
+    { "pattern": "shell_exec", "severity": "high", "matched": "bash" }
+  ]
+}
+```
+
+イベントは到着と同時にJSONLファイルへ追記されます。
+プロキシは上流のレスポンスをバッファリングせず、遅延も発生しません。
+
+## 改ざん検知
+
+ログのどのフィールドを変更しても、agentwit は即座に検出します：
+
+```bash
+# 改ざんのシミュレーション: event[0] の "actor" フィールドを変更
+python3 -c "
+import json; lines=open('witness.jsonl').readlines()
+e=json.loads(lines[0]); e['actor']='ATTACKER'
+lines[0]=json.dumps(e)+'\n'; open('witness.jsonl','w').writelines(lines)
+"
+
+agentwit replay --session ./witness_logs/session_20260314_120000
+# Session: session_20260314_120000  (6 events)
+# Chain integrity: TAMPERED
+#   [event 0] FAIL - session_chain mismatch:
+#     expected '0fd4d24bcb3dab7d171e…'
+#     got      'a79a9e4cdb19795a521e…'
+```
+
+## ユースケース
+
+- **セキュリティエンジニア** — 本番環境でのAIエージェントの挙動を監査
+- **エンタープライズチーム** — AI活動のコンプライアンスログとして保存
+- **AI研究者** — エージェントセッションを再現可能な形式で比較・検証
+- **ペネトレーションテスター** — MCPツール使用状況を証跡として文書化
+
+## Python API
+
+```python
+from agentwit import WitnessLogger, ChainManager
+
+# プロキシなしで直接ログを記録
+logger = WitnessLogger(session_dir="./logs", actor="my-agent")
+event = logger.log_event(
+    action="tools/call",
+    tool="bash",
+    full_payload={"params": {"command": "ls"}, "result": {"stdout": "..."}}
+)
+logger.close()
+
+# 記録済みセッションのChain Integrityを検証
+chain = ChainManager(session_id="session_20260314_120000")
+results = chain.verify_chain(events)
+all_valid = all(r["valid"] for r in results)
+```
+
+## 動作要件
+
+- Python 3.10+
+- FastAPI, uvicorn, httpx, click（インストール時に自動導入）
+
+## ライセンス
+
+[MIT](LICENSE) © agentwit contributors