agent-guardrail

Guardrail

📄 ホワイトペーパーを読む

AI エージェントと、取り消せないあらゆる操作の間にポリシーファイアウォールを設置します。

エージェントがシェルコマンドの実行、メールの送信、送金をしようとしています。 Guardrail は、その実行前にリクエストをユーザーが作成したルールと照合し、 許可するか、人間の確認を求めるか、ブロックします。そのたびに、 平易な言葉で理由を説明します。

60 秒で始めるクイックスタート

git clone <this repo> && cd agent-guardrail
pip install -r requirements.txt

python3 cli.py check --agent trading-agent-001 --tool wallet.transfer \
  --args '{"amount": 9999, "to": "0xabc"}'

または、pip install guardrail-mcp を実行すると、guardrail コマンドを直接使えます。出力は同じで、リポジトリをチェックアウトする必要もありません（--policy に独自のファイルを指定しない場合は、パッケージに同梱されたポリシーを使用します）。

guardrail check --agent trading-agent-001 --tool wallet.transfer \
  --args '{"amount": 9999, "to": "0xabc"}'

{
  "decision": "BLOCK",
  "matched_rules": [
    {"rule": "numeric_cap_exceeded", "severity": "BLOCK",
     "message": "amount=9999.0 exceeds cap 5 for 'wallet.transfer' (unknown agent)"}
  ]
}

これで完了です。サーバーもアカウントも API キーも必要ありません。判定に使われたファイルは policies/default.yaml です。 ファイルを開いて、独自のルールに合わせて数値を変更してください。

---

ほかの「AI リスクスコアリング」ツールではなく、これを選ぶ理由

多くの「AI エージェントセキュリティ」プロジェクト（私の以前のプロジェクトも含みます）は、ビルド時に誰も実際に検証できないデータから算出した統計的なリスクスコアに頼っています。ウォレットの経過期間、「評判」、コントラクトの「リスク」などです。こうしたデータを使うには、まだ用意できていない有料データフィードが必要になるか、いつの間にか実データのふりをしたモックデータになってしまいます。プロトタイピングには問題ありませんが、製品としてリリースするには不誠実です。

Guardrail が示すのは、根拠を示せることだけです。すべてのチェックは、ブロックリストの項目、正規表現の一致、数値上限、レート制限などの決定的なルールです。ユーザーが作成し、自分で監査できるポリシーファイルに照らして評価され、実際に永続化される監査ログ（SQLite）に記録されるため、あとからクエリで確認できます。ここでは、知らないことを知っているかのように装うものはありません。

また、ブロックチェーン専用ではありません。シェルの実行、メール、HTTP リクエスト、ファイルの削除、データベースへの書き込み、暗号資産の取引など、すべて同じエンジン、同じポリシーファイル、同じルールを使います。

---

使い方は 4 通り

1. CLI — ポリシーを手動でテストする

上記を参照してください。セットアップ不要で、ルールを書きながらすぐに結果を確認できます。

2. MCP サーバー（mcp_server.py）— 手軽に始められる助言型

guardrail_check、guardrail_record_outcome、guardrail_agent_history を、 MCP 対応エージェント（Claude Desktop、Claude Code、カスタム MCP クライアント）から呼び出せる MCP ツールとして公開します。

{
  "mcpServers": {
    "guardrail": {
      "command": "python3",
      "args": ["/absolute/path/to/agent-guardrail/mcp_server.py"],
      "env": { "GUARDRAIL_POLICY": "/absolute/path/to/agent-guardrail/policies/default.yaml" }
    }
  }
}

その後、エージェントのシステムプロンプトで、金銭の支払い、データの削除、外部へのメッセージ送信、コードの実行の前に、必ず guardrail_check を呼び出すよう指示してください。

限界を正しく理解してください。 他の MCP ツールと同様、呼び出し元のモデルがツールを呼び出さないことを止める手段はありません。エージェントに最初に必ずチェックするよう指示した場合にのみ役立ちます。スキップできない保証が必要な場合は、#3 をご覧ください。

3. guardrail.decorator.enforce — 確実な保証

ツールの副作用を実行する実際の Python 関数をラップします。チェックはその関数が実行される前にコード内で行われるため、モデルが実際の関数を直接呼び出す機会はありません。

from guardrail.decorator import enforce, BlockedActionError

@enforce(engine, tool_name="send_email")
def send_email(agent_id: str, to: str, subject: str, body: str):
    ...  # only runs if the decision is ALLOW, or WARN-and-confirmed

独自のエージェントループ（LangChain、CrewAI、カスタム MCP ホスト、ツールにアクセスできる Slack ボットなど）を構築する場合に使ってください。python3 examples/example_agent_usage.py を実行すると、実際の関数呼び出しがブロックされる様子を確認できます。

4. guardrail.mcp_enforced_server.EnforcedGuardrailMCPServer — MCP を介した、確実な保証

上記 #2 の MCP サーバーは、助言のみであることを正直に示しています。モデルには guardrail_check ツールが提供されますが、先にチェックせずに実際のツール（別の MCP サーバーが公開しているもの、またはモデル自身が直接アクセスできるもの）を呼び出したり、ある内容をチェックして別の処理を実行したりするのを防ぐことはできません。モデルがインフラと通信する経路が MCP のみである場合（Python デコレーターを利用できない場合）は、このケースにおける #3 と同じ保証が適用されます。オペレーターは、実際のアクション実行関数（実際の認証情報を保持し、実際の副作用を実行するコード）を登録します。モデルがそのアクションを呼び出す方法は、それだけです。

from guardrail.mcp_enforced_server import EnforcedGuardrailMCPServer

def do_transfer(request):
    wallet = get_wallet_for(request.agent_id)  # real credentials, held here - never exposed to the model
    tx_hash = wallet.transfer(to=request.arguments["to"], amount=request.arguments["amount"])
    return {"tx_hash": tx_hash}

server = EnforcedGuardrailMCPServer(policy_path="policies/default.yaml")
server.register_action(
    "wallet.transfer", "Transfer funds from the agent's wallet.",
    input_schema={"type": "object", "properties": {"to": {"type": "string"}, "amount": {"type": "number"}}, "required": ["to", "amount"]},
    executor=do_transfer,
)
server.serve_stdio()

モデルに提供される MCP ツールは wallet.transfer の 1 つだけです。このサーバーを介して資金を移動する、別のガードレールのない方法はありません。BLOCK 判定の場合、do_transfer は実行されません。これも enforce() も、「チェックし、必要に応じて WARN を人間に回し、ブロックされていない場合のみ実行し、実際の結果を報告する」という処理を 1 つの実装（guardrail/enforcement.py）で共有しているため、同じ保証を個別に保守する 2 つの実装はありません。

---

WARN を人間に実際に確認してもらう

on_warn はフックです。Guardrail には、そのまま使える実装が 2 つ用意されています。

ローカル Web UI（guardrail/confirmation/web_ui.py）— 承認／拒否ボタンを備えた、小さな組み込みサーバーです（Flask は不要で、標準ライブラリのみを使用します）。ラップされた関数は、誰かがボタンをクリックするまで、またはタイムアウトするまでブロックします（フェイルクローズとなり、タイムアウトした場合は拒否します。「デフォルトで許可」にはなりません）。

from guardrail.confirmation.web_ui import ConfirmationServer

confirmation = ConfirmationServer(port=8787, timeout_seconds=300)
confirmation.start(open_browser=True)

@enforce(engine, tool_name="wallet.transfer", on_warn=confirmation.request_confirmation)
def transfer(...): ...

実際に試すには、python3 examples/example_web_confirmation.py を実行してから、http://localhost:8787 を開きます。

ターミナルプロンプト（guardrail/confirmation/cli_ui.py）— ブラウザーを使うほどではないスクリプトやローカルテスト向けです。

from guardrail.confirmation.cli_ui import cli_confirm

@enforce(engine, tool_name="wallet.transfer", on_warn=cli_confirm)
def transfer(...): ...

どちらも必須ではありません。on_warn は単なる関数 (decision) -> bool なので、Slack メッセージ、チケット、その他すでに利用しているものを使えます。

---

ポリシーの作成

ポリシーは通常の YAML です。実際に動作する出発点として、policies/default.yaml をご覧ください（確認が必要なツールが 11 個、破壊的なパターンのチェックが 10 個、数値上限、ドメインルール、レート制限が含まれ、すべてコメント付きです）。

ルールの種類	チェック内容
blocked_tools	決して許可されないツール名
confirmation_required_tools	常に WARN を返すツール名
argument_patterns	JSON にシリアライズされた呼び出し引数に対する正規表現。破壊的なシェルコマンド、SQL、漏えいした認証情報、パストラバーサル、SSRF、強制プッシュを、どのツールが含んでいても検出します
numeric_caps	ツールごとの数値フィールド上限。履歴のないエージェントには、より厳しい上限を適用します
aggregate_caps	複数のツールで共有する上限。エージェントごとに合計値を追跡します。詳しくは以下をご覧ください
domain_rules	ツールごとに、URL またはメール受信者フィールドに対する許可リスト／拒否リスト
rate_limits	SQLite による、（エージェント、ツール）ごとのスライディングウィンドウ呼び出し回数制限

numeric_caps は各ツールを個別に制限します。たとえば、wallet.transfer と wallet.approve の上限をそれぞれ 1 日あたり 1000 に設定しても、両方を使うエージェントは合計で 1 日あたり 2000 を動かせます。これを防ぐのが aggregate_caps です。同じグループに含まれるすべてのツールは、共有の合計値から消費します。例：

aggregate_caps:
  daily_money_movement:
    tools:
      wallet.transfer: amount
      wallet.approve: amount
    window_seconds: 86400
    max_unknown_agent: 5
    max_known_agent: 1000

合計に加算されるのは、確認済みの支出のみです。BLOCK されたリクエストは加算されません。また、独自のチェックを通過したため暫定的に記録されたリクエストも、実際のアクションが成功しなかったと判明した場合は取り消されます。実行側で例外が発生した場合、または人間が WARN を拒否して BlockedActionError になった場合、enforce() と強制適用 MCP サーバーの両方が engine.record_outcome(request_id, "error") を自動的に呼び出します（どちらもこの処理を guardrail/enforcement.py で共有しています）。ただし、record_outcome の呼び出しに依存するほかの機能と同様、これを実際に適用する場合にも留意点があります。enforce() と強制適用 MCP サーバーでは完全に機能します（以下を参照）。一方、アドバイザリー専用の MCP サーバー（上記 #2）では、アクションが実際に行われたかどうかを報告する仕組みがないため、暫定記録された金額はそのまま記録され続けます。詳しくは guardrail/storage/aggregate_spend.py のモジュール docstring をご覧ください。

これらを調整するためのコード変更は不要です。YAML を編集して、プロセス（または MCP サーバー）を再起動してください。

---

テストの実行

pip install -r requirements.txt
PYTHONPATH=. python3 -m unittest discover -s tests -v

134 件のテストでは、ルール評価、エンジンの完全なパイプライン（SQLite を実際に使ったレート制限、合計支出の追跡、監査データの永続化）、enforce デコレーターと強制適用 MCP サーバー（どちらも BLOCK によって実際のアクションの実行が確実に防がれることを検証し、その保証の実装を共有しています）、アドバイザリー MCP サーバーの JSON-RPC 処理、稼働中のサーバーに対する実際の HTTP リクエストを使った確認用 Web UI をテストします。また、テスト用の合成ポリシーだけでなく、同梱されている policies/default.yaml が、謳っている内容を実際に検出できることを確認する専用のテストスイートもあります。

---

正直なところ、まだ不足しているもの

• デフォルトでは単一プロセスの SQLite です。 エージェントプロセスが1つなら問題ありません。複数のレプリカでレート制限や監査履歴を共有する場合は、すべてのプロセスを共有ストレージ上の同じファイルに接続するか、実際のデータベースに切り替えてください（ストレージクラスは小規模で、簡単に接続先を変更できます）。
• 監査ログでは、シークレット／PII のマスキングがデフォルトで有効です。 AuditLog は、キー名が機密情報を示すもの（password、 api_key、authorization など）や、確度の高いいくつかの値の形式（PEM 秘密鍵ブロック、JWT 形式の文字列）を、キー名に関係なくマスキングし、ネストされた dict／list も再帰的に処理します。検出対象と対象外の内容、および一般用途のエントロピー判定を意図的に除外した理由（通常の UUID やハッシュを誤検出しすぎるため）については、 guardrail/storage/redaction.py を参照してください。送信されたままの引数を保存するには AuditLog(redact=False) を、ツール固有の追加フィールド名をマスキングするには extra_sensitive_keys={...} を渡してください。
• デフォルトポリシーは妥当な出発点ですが、完全な脅威モデルではありません。 よく知られた破壊的なシェル／SQL パターンや、明らかな認証情報の形式を検出します。エージェントが実際に扱う内容に応じて argument_patterns を拡張してください。
• 確認用 Web UI には認証機能がありません。 設計上、127.0.0.1 にバインドされており（ネットワークには公開されません）が、そのポートにローカルアクセスできる人なら誰でも承認／拒否できます。開発者が1人で使うマシンなら問題ありませんが、複数人でホストを共有する場合は独自の認証機能の背後に配置してください。

これらはいずれもモックや偽物ではありません。まだ実装されていないだけで、これを採用する場合に次に取り組むべき正直な課題です。

---

これを公開し、実際に使ってもらうには

具体的なチェックリストについては PUBLISHING.md を参照してください。登録先の MCP ディレクトリ、掲載に必要なもの、そして「完了」の状態を確認できます。

---

関連プロジェクト

同じ作者が、同じ原則を別の分野に適用しています。

• agentic-wallet-guardian-v3 - オンチェーン取引を行う AI エージェント向けのセキュリティ判断レイヤーです。MIT、 テスト 112 件。
• x402-attest - エージェント間の支払いポリシー判断に対する、暗号署名（Ed25519）付きで独立して検証可能な 証明です。初期段階の概念実証です。
• open-agent-attestation - エージェントのポリシー判断に署名するための、ベンダー中立なオープン仕様（JWT+EdDSA）です。 誰でも検証できます。上記の x402-attest は独自形式を使用していますが、こちらは汎用化したバージョンです。ドラフト v0.1 です。

---

プロジェクト構成

guardrail/
    __main__.py            CLI implementation — also the `guardrail` console command
    mcp_server.py            MCP stdio server — also the `guardrail-mcp-server` console command
    core/
        models.py               ActionRequest, RuleMatch, GuardrailDecision (stdlib only)
        policy.py                 Policy loader (the one place PyYAML is used)
    rules.py                    Deterministic rule evaluators
    storage/
        rate_limiter.py           SQLite-backed sliding-window rate limiter
        audit.py                    SQLite-backed persistent audit log
    engine.py                    GuardrailEngine — orchestrates rules + rate limit + audit
    decorator.py                 enforce() — the unbypassable integration point
    confirmation/
        web_ui.py                    Local web UI for human approve/reject (stdlib http.server)
        cli_ui.py                      Terminal-prompt confirmation
    policies/default.yaml           Copy of the default policy bundled into the installed package
policies/default.yaml       Canonical, editable default policy (git-clone workflow)
cli.py                      Thin shim -> guardrail/__main__.py (for `python3 cli.py`)
mcp_server.py                Thin shim -> guardrail/mcp_server.py (for `python3 mcp_server.py`)
pyproject.toml               Package metadata — `pip install .` gives you `guardrail` + `guardrail-mcp-server`
.github/workflows/ci.yml      Runs the test suite + policy validation + package build on every push
examples/
    example_agent_usage.py       Decorator basics
    example_web_confirmation.py    Real browser-based approve/reject, live
tests/                       46 unit tests, all runnable with just PyYAML installed
CONTRIBUTING.md              How to add a rule type, ground rules
CHANGELOG.md                  Version history
PUBLISHING.md                 How to actually get this in front of people
landing/index.html             Static one-page site (open directly or host on GitHub Pages)