## クイックスタート```bash
cd examples/docker-compose
docker compose up

すべてのリクエストは構造化されたJSON監査エントリを生成します：```json
{
  "host": "httpbin.org",
  "method": "GET",
  "path": "/headers",
  "action": "allow",
  "status_code": 200,
  "duration_ms": 142,
  "request_transforms": [
    { "name": "allowlist", "action": "continue" },
    {
      "name": "secrets",
      "action": "continue",
      "annotations": { "swapped": [{ "secret": "OPENAI_API_KEY", "locations": ["header:Authorization"] }] }
    }
  ]
}

### 2. Dockerネットワークを作成する

iron-proxyは固定IPを必要とするため、コンテナがDNSをそのIPに向けられるようにします：```bash
docker network create --subnet=172.20.0.0/24 iron-proxy

[No input provided]```bash
docker run -d --name iron-proxy \
  --network iron-proxy --ip 172.20.0.2 \
  -v $(pwd)/proxy.yaml:/etc/iron-proxy/proxy.yaml:ro \
  -v $(pwd)/certs/ca.crt:/etc/iron-proxy/ca.crt:ro \
  -v $(pwd)/certs/ca.key:/etc/iron-proxy/ca.key:ro \
  --env-file .env \
  ironsh/iron-proxy:latest -config /etc/iron-proxy/proxy.yaml

より強力な適用を行うには、nftables ルールを重ねてプロキシを経由しない外部送信をブロックするか、または
カーネルレベルでの傍受には TPROXY を使用します。各アプローチの詳細は [プロキシへのトラフィックの
ルーティング](#routing-traffic-to-the-proxy) を参照してください。

## なぜ iron-proxy なのか？

|                          | iron-proxy                     | Squid                       | mitmproxy                 | Envoy                              |
| ------------------------ | ------------------------------ | --------------------------- | ------------------------- | ---------------------------------- |
| デフォルト拒否の外部送信 | 組み込み                       | 複雑なACL設定が必要         | カスタムスクリプトが必要   | RBAC/フィルター設定が必要           |
| シークレット注入         | 組み込み                       | なし                        | なし                      | なし                               |
| 構造化監査ログ           | 組み込み、変換ごとのトレース   | 基本的なアクセスログ        | プラグインベース          | 設定可能なアクセスログ             |
| セットアップの複雑さ     | 単一バイナリ + YAML            | 広範な設定言語              | Pythonスクリプト          | 複雑なYAMLまたはコントロールプレーン |

iron-proxy は、信頼できないワークロードからの外部送信を制御・監査するという単一の目的のために設計されています。Squid はデフォルト拒否を実行できますが、かなりの ACL 設定が必要であり、シークレット注入の概念はありません。mitmproxy は優れたデバッグツールですが、本番環境での強制適用を目的としていません。Envoy は汎用プロキシであり、この機能の一部を実行するように設定できますが、問題が必要とするよりもはるかに複雑です。

## 仕組み

iron-proxy は DNS サーバーと HTTP/HTTPS プロキシを実行します。コンテナの DNS を iron-proxy に向けると、すべてのホスト名のルックアップがプロキシ IP に解決され、トラフィックが自動的にプロキシを経由します。プロキシは TLS を終端し（提供する CA からリーフ証明書をその場で生成）、リクエストを順序付けられた変換パイプラインに通し、アップストリームに転送し、レスポンスを再度パイプラインに通します。```
Container → DNS lookup → iron-proxy IP → TLS termination → transforms → upstream

### DNS

デフォルトではすべてが `proxy_ip` に解決されます。これによりトラフィックがプロキシ経由でルーティングされます。例外は以下のとおりです。

- **`passthrough`:** OSリゾルバに転送されるグロブパターン（例: `*.internal.corp`）。これらのホストへのトラフィックはプロキシを完全にバイパスします。
- **`records`:** 静的AレコードまたはCNAMEレコード。最も優先度が高くなります。

### レスポンス再試行ハンドラ

`IRON_RESPONSE_RETRY_HANDLER_URL`、`IRON_RESPONSE_RETRY_COMPLETE_URL`、`IRON_RESPONSE_RETRY_HANDLER_TOKEN`、`IRON_RESPONSE_RETRY_HANDLER_SANDBOX_ID`、およびカンマ区切りの `IRON_RESPONSE_RETRY_STATUSES` リストを設定すると、外部認証によるレスポンス再試行を有効にできます。認証ハンドラは、正確なアップストリームのスキーム、オーソリティ、メソッド、パス/クエリ、再試行可能性、レスポンスステータスとヘッダー、トレースコンテキスト、サンドボックスIDを受け取ります。ハンドラは、1回の正確な再試行のためのリクエストヘッダーと試行IDを返すことができます。完了ハンドラは、`IRON_RESPONSE_RETRY_COMPLETION_HEADERS` によって選択された再試行ステータスとレスポンスヘッダーを受け取ります。これはデフォルトで `Payment-Receipt` になります。

レスポンスボディはどちらのハンドラにも送信されず、宛先を変更することはできず、接続/フレーミングヘッダーは拒否されます。`proxy.max_request_body_bytes` を超えるリクエストは通常どおり処理されますが、再試行不可としてマークされます。チャレンジされた場合、元のレスポンスが返されます。ハンドラの障害でも元のレスポンスは保持されます。ハンドラURLは、ループバックまたは信頼された内部ネットワーク向けに `IRON_RESPONSE_RETRY_HANDLER_ALLOW_HTTP=true` が明示的に設定されている場合を除き、HTTPSを使用する必要があります。リダイレクトは拒否され、レスポンス再試行トークンはコントロールプレーントークンとは独立して設定する必要があります。WebSocket、gRPC、および長さ不明のストリーミングリクエストは、レスポンス再試行処理をバイパスします。

信頼されたハンドラが `proxy.upstream_deny_cidrs` 内で解決される場合、`IRON_RESPONSE_RETRY_HANDLER_ALLOW_CIDRS` に、ハンドラが使用できる狭いプライベートCIDRのカンマ区切りリストを設定します。この例外は、設定された正確な認証エンドポイントと完了エンドポイントにのみ適用されます。通常のプロキシトラフィックは、引き続き完全なアップストリーム拒否リストの対象となります。パブリック、ループバック、リンクローカル、およびクラウドメタデータのレンジは、この設定では追加できません。

### 許可リスト

デフォルトは拒否です。リクエストは、少なくとも1つのドメイングロブまたはCIDRに一致する必要があります。一致しないリクエストには `403 Forbidden` が返されます。

ドメインパターンはグロブマッチングを使用します。`*.example.com` は任意のサブドメインと `example.com` 自体に一致します。

**警告モード:** `warn: true` を設定すると、許可リストが実際に適用せずに何をブロックするかを確認できます。拒否されるはずのリクエストは通過できますが、変換トレースに `"action": "warn"` という注釈が付けられます。これは、新しい許可リストルールを段階的に導入したり、適用に切り替える前に既存のトラフィックを監査したりするのに役立ちます。

### 注釈 (Annotate)

ホスト/メソッド/パスルールに基づいて、HTTPリクエストヘッダーを監査ログの注釈に取り込みます。これは、プロキシコアを変更せずに、リクエストIDなどのリクエスト固有のコンテキストで監査ログを強化するのに役立ちます。

各注釈グループは、照合するルールと取得するヘッダーを指定します。リクエストがグループ内のいずれかのルールに一致すると、指定されたヘッダー値が変換トレースの注釈に `header:<Name>` エントリとして書き込まれます。一致しないリクエストは変更されずに通過します。この変換がリクエストを拒否することはありません。

> **警告:** ヘッダー値は監査ログに平文で出力されます。リクエストIDやプロキシのシークレットトークンを含むヘッダーなど、公開しても安全なヘッダーのみをログに記録してください。生のシークレットを含むヘッダーはログに記録しないでください。```yaml
transforms:
  - name: annotate
    config:
      annotations:
        - rules:
            - host: "api.openai.com"
              methods: ["POST"]
              paths: ["/v1/*"]
          headers: ["x-request-id"]
        - rules:
            - host: "*.anthropic.com"
          headers: ["x-request-id"]

### ボディキャプチャ

一致するリクエストのデコード済みリクエストボディを記録し、監査ログレコードの `body_capture` グループに `request_body` と `request_body_truncated` として表示します。プロキシを通過するペイロード（サンドボックスがLLMプロバイダーに送信するプロンプトなど）を、上流のトラフィックを変更せずに監査するのに役立ちます。

ホスト、メソッド、パスは、`allowlist` や `secrets` と同じ `rules` 構文で照合されます。`max_request_body_bytes` は、各ボディのうちどれだけをキャプチャするかを制限します。上限を超えるボディはプレフィックスに切り詰められ、`request_body_truncated` が `true` に設定されます。上限のデフォルトは16 KiBで、グローバルな `proxy.max_request_body_bytes` 制限とは独立しています。このトランスフォームは観察専用であり、リクエストを拒否することはありません。また、ボディの読み取りエラーはリクエストを失敗させるのではなく、トレースに注釈として記録されます。

キャプチャが成功すると、`request_transforms` 内のこのトランスフォームのエントリに `captured_bytes` と `truncated` が注釈として付与され、ボディ自体を複製することなく、ボディがキャプチャされたことがトレースに記録されます。

レスポンスボディはキャプチャされません。ストリーミングレスポンス（SSE）は、転送前にエンドツーエンドでバッファリングする必要があり、クライアントを停滞させることになります。

> **警告:** キャプチャされたボディは監査ログに平文で書き込まれます。`secrets` を `match_body: true` で実行する場合は、`body_capture` を `secrets` の *前* に配置して、監査ログが `secrets` がボディに置き換える実際の認証情報ではなく、サンドボックスのプロキシトークンを記録するようにしてください。```yaml
transforms:
  - name: body_capture
    config:
      max_request_body_bytes: 16384
      rules:
        - host: "api.anthropic.com"
          methods: ["POST"]
          paths: ["/v1/messages"]
        - host: "api.openai.com"
          methods: ["POST"]
          paths: ["/v1/chat/completions"]

不変条件:

- 判定は拒否のみを行います。静的許可リストが拒否するリクエストを承認することはありません。
  静的拒否が常に優先されます。
- 一致しないリクエストは無視されます。LLM呼び出しも監査注釈も行われません。
- LLMエラー、タイムアウト、サーキットブレーカー解放、または不正なモデル出力の場合、
  設定された`fallback`が適用されます。`deny`はリクエストをブロックします
  (本番環境での推奨デフォルト)。`skip`はパイプラインの残りに委ねます。iron-proxyは
  デフォルト拒否のため、一致しないリクエストも引き続きブロックされます。

シークレット変換とのパイプライン順序:

- **推奨:** 判定をシークレット変換の**前**に配置します。LLMプロバイダーには
  プロキシトークンのみが表示され、ワークロードがアクセスできる実際の認証情報が
  表示されることはありません。
- あるいは、判定をシークレット変換の後に配置すると、実際に外部へ送信されるワイヤー形式
  そのものを評価できますが、実際の認証情報をLLMプロバイダーに送信するという
  コストがかかります。このトレードオフを脅威モデルが許容できる場合にのみ選択してください。

対応プロバイダー:

- **`anthropic`** (Messages API)。`api_key_env`、`model`、オプションの
  `base_url`と`max_tokens`を使用します。
- **`openai`** (Chat Completions API)。上記と同じフィールドです。
  `type: openai`を設定し、`api_key_env`をOpenAIキーを保持する環境変数
  に向け、`gpt-5.4-nano`のようなモデルを選択してください。

監査出力: 一致したすべてのリクエストは、変換トレースの下に構造化フィールドを追加します。
これには`judge.instance`、`judge.decision`、`judge.reason`、
`judge.duration_ms`、`judge.input_tokens`、`judge.output_tokens`、
`judge.fallback_applied`(フォールバックが発動した場合)、および
`judge.circuit_breaker_tripped`(ブレーカーが開いている場合)が含まれます。

クレジット: この設計に影響を与えたBrexのCrabTrapプロジェクト(MITライセンス)に
感謝します。

## MCPポリシー

iron-proxyは[MCPのStreamable HTTPトランスポート](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports)に対応しています。リクエストが設定済みのMCPサーバーに一致すると、プロキシはJSON-RPCボディを解析し、デフォルト拒否のツール許可リストを適用し、`tools/list`レスポンスをフィルタリングして、拒否されたツールがエージェントに届かないようにします。SSEレスポンスはイベントごとにフィルタリングされるため、長期間存続するMCPストリームもライブのまま維持されます。

これはトランスフォームではなく、第一級のプロキシ機能です。MCPレスポンスは、サーバーが任意に開始するメッセージを運ぶオープンエンドのSSEストリームになり得るため、リクエスト/レスポンスのトランスフォーム契約には適合しません。```yaml
mcp:
  # JSON-RPC error envelope returned to the agent on policy denial.
  # Defaults: code -32001, message "blocked by iron-proxy policy".
  error:
    code: -32001
    message: "blocked by iron-proxy policy"
  servers:
    - name: github                         # appears in audit as mcp.server
      rules:                               # standard host/method/path rules
        - host: "mcp.github.com"
          paths: ["/mcp", "/mcp/*"]
      tools:
        - name: "search_repositories"      # always allowed
        - name: "create_issue"
          when:                            # all clauses must hold; otherwise deny
            - path: "owner"                # dotted path against arguments
              equals: "ironsh"
            - path: "repo"
              in: ["iron-proxy", "tunis-v2"]
        # Anything not listed is denied (default-deny).

資格情報は、`secrets` 変換と同じシークレットソースを使用します。これらはデフォルトで必須です。資格情報に `require: false` を設定すると、利用できない場合にスキップできます。監査ログには、ルート、アップストリームURL、資格情報の挿入場所が記録されますが、挿入された資格情報の値は決して記録されません。

v1での制限事項:

- Streamable HTTP トランスポートのみがサポートされます。レガシーの HTTP+SSE トランスポート(個別の `/messages` エンドポイントと `/sse` エンドポイント)はサポートされません。
- 拒否されたエントリを含む JSON-RPC バッチは、バッチ全体として拒否されます。部分的なバッチ転送はサポートされません。
- リソースとプロンプトは適用されません。エージェントは、ポリシーフィルタリングなしで `resources/list`、`resources/read` などを引き続き呼び出すことができます。

### ボディ制限

リクエスト/レスポンスボディを検査または転送する変換(シークレットのボディマッチング、gRPC 変換)は、バッファリングされたボディに対して動作します。最大バッファサイズを制御する2つのグローバル設定があります:

- **`max_request_body_bytes`** (デフォルト: `1048576` / 1 MiB): 変換用にバッファリングされるリクエストボディの量を制限します。この制限を超えるデータは、変換の観点からは切り捨てられますが、それでもアップストリームに転送されます。
- **`max_response_body_bytes`** (デフォルト: `0` / 無制限): バッファリングされるレスポンスボディの量を制限します。`0` に設定するとレスポンス全体がバッファリングされます。これはほとんどのワークロード(例: npm パッケージ、モデルウェイト)の適切なデフォルトです。

ボディは、変換が読み取る際に増分的にバッファリングされ、パイプラインステージ間で自動的に巻き戻されます。変換がボディを読み取らない場合、バッファリングは発生せず、ボディは変更されずにストリーミングされます。

### トンネルリスナー (HTTP/CONNECT/SOCKS5)

トンネルリスナーは、専用ポートで絶対形式の HTTP プロキシリクエスト、HTTP CONNECT、SOCKS5 接続を受け入れます。これは、DNS ベースのルーティングに依存するのではなく、`HTTP_PROXY`/`HTTPS_PROXY`/`ALL_PROXY` 環境変数または SOCKS5 設定を介したプロキシ設定をネイティブにサポートするツールに役立ちます。

これを有効にするには、`proxy` の下に `tunnel_listen` を設定します:```yaml
proxy:
  tunnel_listen: ":8080"

**プレーンHTTPプロキシの例:**```bash
curl -x http://172.20.0.2:8080 \
  http://httpbin.org/get

また、標準環境変数を設定すると、すべてのツールが自動的にトンネル
経由でルーティングされます：```bash
export HTTP_PROXY=http://172.20.0.2:8080
export HTTPS_PROXY=http://172.20.0.2:8080
export ALL_PROXY=socks5h://172.20.0.2:8080

セットアップは簡単ですが、迂回も簡単です。ワークロードはIPをハードコードするか、独自のDNSリゾルバを使用してプロキシを完全に迂回できます。

### DNS + nftables エグレスファイアウォール (強制)

DNSルーティングの上にnftablesファイアウォールを重ねます。DNSは依然としてトラフィックをプロキシへ誘導しますが、nftablesは、IPをハードコードしていても、ワークロードが他の何とも通信_できない_ことを保証します。

[`examples/nftables`](https://github.com/paradigmxyz/iron-proxy/blob/HEAD/examples/nftables/) ディレクトリには、動作するセットアップがあります。クライアントコンテナは、アプリケーショントラフィックを実行する前に、起動時にファイアウォールルールをロードします。

**nftables.conf** はプロキシへのトラフィックを許可し、その他すべてをドロップします:```
table ip iron {
  chain output {
    type filter hook output priority 0; policy drop;

    # allow loopback
    oif lo accept

    # allow traffic to the proxy itself (DNS + HTTP/HTTPS)
    ip daddr 172.20.0.2 tcp dport { 80, 443 } accept
    ip daddr 172.20.0.2 udp dport 53 accept

    # allow established/related (return traffic)
    ct state established,related accept

    # log and drop everything else
    log prefix "iron-proxy-drop: " drop
  }
}

本番環境では、エントリーポイントのラッパーでルールをロードし、その後
`CAP_NET_ADMIN` を持たない非 root ユーザーとして実際のプロセスを `exec` します。

### TPROXY (透過プロキシ)

ワークロードのDNSをまったく制御できない環境では、nftables
TPROXY がカーネルレベルでトラフィックをリダイレクトでき、ワークロード側の協力を
一切必要としません。これは PREROUTING チェーンでパケットを傍受し、それらを
直接 iron-proxy に渡します:```
table ip iron {
  chain prerouting {
    type filter hook prerouting priority mangle; policy accept;

    # redirect HTTP/HTTPS to iron-proxy via TPROXY
    tcp dport 80 tproxy to 172.20.0.2:80 meta mark set 1 accept
    tcp dport 443 tproxy to 172.20.0.2:443 meta mark set 1 accept
  }

  chain output {
    type route hook output priority mangle; policy accept;

    # mark locally-originated packets for policy routing
    tcp dport { 80, 443 } meta mark set 1
  }
}

**proxy.yaml** は `httpbin.org` と `icanhazip.com` を許可リストに登録し、2つの
シークレットを交換します:```yaml
transforms:
  - name: allowlist
    config:
      domains:
        - "httpbin.org"
        - "icanhazip.com"
      cidrs:
        - "172.20.0.0/24"

  - name: secrets
    config:
      secrets:
        - source:
            type: env
            var: OPENAI_API_KEY
          replace:
            proxy_value: "proxy-openai-abc123"
            match_headers: ["Authorization"]
            match_query: true # scan the query string
          rules:
            - host: "httpbin.org"

        - source:
            type: env
            var: INTERNAL_TOKEN
          proxy_value: "proxy-internal-tok"
          match_headers: [] # scan all headers
          rules:
            - host: "httpbin.org"

## 監査ログ形式

プロキシされたすべてのリクエストは、構造化されたJSONログエントリを生成します:```json
{
  "host": "httpbin.org",
  "method": "GET",
  "path": "/headers",
  "action": "allow",
  "status_code": 200,
  "duration_ms": 142,
  "request_transforms": [
    {
      "name": "allowlist",
      "action": "continue"
    },
    {
      "name": "secrets",
      "action": "continue",
      "annotations": {
        "swapped": [{ "secret": "OPENAI_API_KEY", "locations": ["header:Authorization"] }]
      }
    }
  ],
  "response_transforms": []
}

すべての設定は、標準のOTEL環境変数を使用します:

| 変数                           | 説明                                                       | デフォルト          |
| ------------------------------ | ---------------------------------------------------------- | ------------------ |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLPコレクタのURL。未設定の場合はOTELエクスポートが無効になります。 | (無効)             |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | `http/protobuf` または `grpc`。                             | `http/protobuf`    |
| `OTEL_EXPORTER_OTLP_HEADERS`  | 認証ヘッダー用のカンマ区切り `key=value` ペア。             | (なし)             |
| `OTEL_SERVICE_NAME`            | すべてのログレコードに付加されるサービス名。                 | `iron-proxy`       |
| `OTEL_RESOURCE_ATTRIBUTES`    | カンマ区切りの `key=value` リソース属性。                   | (なし)             |

有効にすると、既存のJSON stderrログに加えて、すべての監査イベントがOTELログレコードとして出力されます。ログレコードはJSON監査エントリと同じスキーマを保持します: `host`、`method`、`path`、`action`、`status_code`、`duration_ms`、および注釈付きの完全な `request_transforms`/`response_transforms` 配列です。

## 管理API

iron-proxyは、運用タスク用の認証付きHTTP APIをオプションで公開できます。現在は単一のエンドポイント `POST /v1/reload` を提供しており、ディスクからYAML設定を再読み込みし、新しく構築された変換パイプラインを原子的に交換します。新しい設定が無効な場合、実行中のパイプラインは維持されます。

管理サーバーはデフォルトでは無効です。有効にするには、設定に `management` ブロックを追加します:```yaml
management:
  # Bind on loopback unless you front this with a private network or auth proxy:
  # /v1/reload can rebuild the entire transform pipeline.
  listen: "127.0.0.1:9092"
  # Env var that holds the bearer token. Defaults to IRON_MANAGEMENT_API_KEY.
  api_key_env: "IRON_MANAGEMENT_API_KEY"

## iron.sh

Need Vault/KMS シークレットバックエンド、Kubernetes オペレーター、または集中化されたポリシー管理が必要ですか？ [iron.sh](https://iron.sh) は iron-proxy をベースに、これを大規模に運用するチーム向けのエンタープライズ機能を提供します。

## リリース署名の検証

リリースアーティファクトには、署名付きチェックサムマニフェストが含まれています：

- `checksums.txt`
- `checksums.txt.asc`（ASCIIアーマー形式の分離署名）

同梱の公開鍵 [`public-key.asc`](https://github.com/paradigmxyz/iron-proxy/blob/HEAD/public-key.asc) を使用して検証してください：```bash
# 1) Download release artifacts for a tag
TAG=vX.Y.Z
gh release download "$TAG" --pattern "checksums.txt" --pattern "checksums.txt.asc"

# 2) Import the project signing key
gpg --import public-key.asc

# 3) Verify the signature over checksums.txt
gpg --verify checksums.txt.asc checksums.txt