## Avvio rapido```bash
cd examples/docker-compose
docker compose up

Ogni richiesta produce una voce di audit JSON strutturata:```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. Crea una rete Docker

iron-proxy necessita di un IP fisso affinché i container possano puntare il loro DNS ad esso:```bash
docker network create --subnet=172.20.0.0/24 iron-proxy

Il contenuto del blocco da tradurre è vuoto. Non è stato fornito alcun testo di input per questo chunk 15 di 70. Invia il contenuto da tradurre per procedere.```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

For stronger enforcement, layer nftables rules to block non-proxy egress, or use
TPROXY for kernel-level interception. Vedi [Instradare il traffico al
proxy](#routing-traffic-to-the-proxy) per i dettagli su ciascun approccio.

## Perché iron-proxy?

|                          | iron-proxy                     | Squid                       | mitmproxy                 | Envoy                              |
| ------------------------ | ------------------------------ | --------------------------- | ------------------------- | ---------------------------------- |
| Egress con negazione predefinita | Integrato              | Richiede configurazione ACL complessa | Richiede scripting personalizzato | Richiede configurazione RBAC/filtro |
| Iniezione di segreti     | Integrato                       | No                          | No                        | No                                 |
| Log di controllo strutturati | Integrato, tracce per trasformazione | Log di accesso di base      | Basato su plugin          | Log di accesso configurabili       |
| Complessità di configurazione | Singolo binario + YAML      | Linguaggio di configurazione esteso | Scripting Python          | YAML complesso o control plane     |

iron-proxy è progettato appositamente per un unico compito: controllare e
verificare l'egress dai workload non affidabili. Squid può fare default-deny ma
richiede una configurazione ACL significativa e non ha alcun concetto di
iniezione di segreti. mitmproxy è un ottimo strumento di debug ma non è
progettato per l'applicazione in produzione. Envoy è un proxy generico che può
essere configurato per fare parte di questo, ma rappresenta molta più
complessità di quanto il problema richieda.```
Container → DNS lookup → iron-proxy IP → TLS termination → transforms → upstream

### DNS

Per impostazione predefinita, tutto viene risolto in `proxy_ip`, che è ciò che instrada il traffico attraverso il proxy. Eccezioni:

- **`passthrough`:** modelli glob inoltrati al resolver del sistema operativo (ad es.,
  `*.internal.corp`). Il traffico verso questi host bypassa completamente il proxy.
- **`records`:** record A o CNAME statici. Priorità più alta.

### Handler di retry delle risposte

Imposta `IRON_RESPONSE_RETRY_HANDLER_URL`,
`IRON_RESPONSE_RETRY_COMPLETE_URL`, `IRON_RESPONSE_RETRY_HANDLER_TOKEN`,
`IRON_RESPONSE_RETRY_HANDLER_SANDBOX_ID` e un elenco
`IRON_RESPONSE_RETRY_STATUSES` separato da virgole per abilitare i retry delle risposte autorizzati
esternamente.

L'handler di autorizzazione riceve lo schema upstream esatto, l'authority, il metodo,
il path/query, la riproducibilità, lo stato e le intestazioni della risposta, il contesto di trace e
l'identità della sandbox. Può restituire le intestazioni della richiesta più un ID del tentativo per un
singolo replay esatto. L'handler di completamento riceve quindi lo stato del replay e
le intestazioni della risposta selezionate da `IRON_RESPONSE_RETRY_COMPLETION_HEADERS`, che
per impostazione predefinita è `Payment-Receipt`.

I body delle risposte non vengono mai inviati a nessuno dei due handler, le destinazioni non possono cambiare,
e le intestazioni di connessione/framing vengono rifiutate. Le richieste che superano
`proxy.max_request_body_bytes` procedono normalmente ma vengono contrassegnate come non riproducibili;
se contestate, viene restituita la loro risposta originale. Anche i fallimenti degli handler
preservano la risposta originale. Gli URL degli handler devono usare HTTPS a meno che loopback o
`IRON_RESPONSE_RETRY_HANDLER_ALLOW_HTTP=true` sia esplicitamente configurato per una
rete interna affidabile. I reindirizzamenti vengono rifiutati e il token di retry delle risposte
deve essere configurato indipendentemente dal token del piano di controllo. Le richieste WebSocket,
gRPC e streaming a lunghezza sconosciuta bypassano la gestione del retry delle risposte.

Quando un handler attendibile risolve all'interno di `proxy.upstream_deny_cidrs`, imposta
`IRON_RESPONSE_RETRY_HANDLER_ALLOW_CIDRS` su un elenco separato da virgole dei
CIDR privati ristretti che può utilizzare. Questa eccezione si applica solo agli endpoint
authorize e complete esattamente configurati; il traffico proxy ordinario rimane
soggetto all'intera lista deny upstream. Gli intervalli pubblici, loopback, link-local e di metadata cloud
non possono essere aggiunti tramite questa impostazione.

### Allowlist

Negazione predefinita. Le richieste devono corrispondere ad almeno un glob di dominio o CIDR per procedere.
Le richieste non corrispondenti ricevono un `403 Forbidden`.

I pattern di dominio usano il glob matching: `*.example.com` corrisponde a qualsiasi sottodominio e
allo stesso `example.com`.

**Modalità Warn:** imposta `warn: true` per osservare cosa bloccherebbe l'allowlist senza
applicarla effettivamente. Le richieste che verrebbero rifiutate vengono lasciate passare ma
annotate con `"action": "warn"` nel trace di transform. Questo è utile per
distribuire nuove regole allowlist o per svolgere l'audit del traffico esistente prima
di passare all'applicazione.

### Annotate

Cattura le intestazioni delle richieste HTTP nelle annotazioni del log di audit in base a
regole host/metodo/path. È utile per arricchire i log di audit con
contesto specifico della richiesta, come gli ID di richiesta, senza modificare il core del proxy.

Ogni gruppo di annotazioni specifica le regole di corrispondenza e le intestazioni da catturare. Quando una
richiesta corrisponde a qualsiasi regola in un gruppo, i valori delle intestazioni specificati vengono scritti come
voci `header:<Name>` nelle annotazioni del trace di transform. Le richieste che non
corrispondono vengono lasciate passare invariate. Questa trasformazione non rifiuta mai le richieste.

> **Avvertenza:** I valori delle intestazioni vengono emessi in testo semplice nel log di audit.
> Solo registra le intestazioni che sono sicure da esporre, come gli ID di richiesta o le intestazioni contenenti
> token segreti del proxy. Non registrare intestazioni che contengono segreti non elaborati.```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"]

### Cattura del corpo

Registra il corpo della richiesta decodificata delle richieste corrispondenti e lo espone nel
record del log di audit in un gruppo `body_capture` contenente `request_body` e
`request_body_truncated`. Utile per verificare i payload che attraversano il
proxy, come i prompt che una sandbox invia a un provider LLM, senza
modificare il traffico a monte.

Host, metodi e percorsi vengono confrontati con la stessa sintassi `rules` di
`allowlist` e `secrets`. `max_request_body_bytes` limita quanto di ogni corpo
viene catturato; i corpi più grandi del limite vengono troncati al prefisso e
`request_body_truncated` viene impostato a `true`. Il limite predefinito è 16 KiB ed è
indipendente dal limite globale `proxy.max_request_body_bytes`. Questa trasformazione
è solo osservativa: non rifiuta mai una richiesta e gli errori di lettura del corpo sono
annotati sulla traccia invece di far fallire la richiesta.

In caso di cattura riuscita, la voce della trasformazione in `request_transforms` viene
annotata con `captured_bytes` e `truncated` così la traccia registra che un
corpo è stato catturato senza duplicare il corpo stesso.

I corpi delle risposte non vengono catturati. Le risposte in streaming (SSE) dovrebbero essere
bufferizzate end-to-end prima dell'inoltro, il che bloccherebbe il client.

> **Avvertenza:** I corpi catturati vengono scritti nel log di audit in testo semplice. Quando
> `secrets` viene eseguito con `match_body: true`, posiziona `body_capture` *prima* di `secrets`
> così il log di audit registra i token proxy della sandbox anziché le credenziali reali
> che `secrets` sostituisce nel corpo.```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"]

Invarianti:

- Il giudice può solo rifiutare. Non approva mai una richiesta che la allowlist statica
  avrebbe negato. La negazione statica vince sempre.
- Le richieste non corrispondenti vengono ignorate: nessuna chiamata LLM, nessuna annotazione di audit.
- In caso di errore LLM, timeout, circuit-breaker aperto o output del modello malformato, si
  applica il `fallback` configurato. `deny` blocca la richiesta (il default
  consigliato per la produzione). `skip` rimanda al resto della pipeline; poiché
  iron-proxy è default-deny, le richieste non corrispondenti vengono comunque bloccate.

Ordinamento della pipeline con il secrets transform:

- **Consigliato:** posizionare il giudice **prima** del secrets transform. Il provider
  LLM vede i token del proxy, mai le credenziali reali a cui il workload ha
  accesso.
- In alternativa, posizionare il giudice dopo il secrets transform gli consente di valutare l'esatta
  forma sul wire che verrà trasmessa in uscita, al costo di inviare credenziali reali al
  provider LLM. Scegli questa opzione solo se il tuo modello di minaccia accetta questo compromesso.

Provider supportati:

- **`anthropic`** (API Messages). Usa `api_key_env`, `model`, e opzionalmente
  `base_url` e `max_tokens`.
- **`openai`** (API Chat Completions). Stessi campi di cui sopra; imposta
  `type: openai`, punta `api_key_env` alla variabile d'ambiente che contiene la tua chiave
  OpenAI e scegli un modello come `gpt-5.4-nano`.

Output di audit: ogni richiesta corrispondente aggiunge campi strutturati nella trace del
transform, tra cui `judge.instance`, `judge.decision`, `judge.reason`,
`judge.duration_ms`, `judge.input_tokens`, `judge.output_tokens`,
`judge.fallback_applied` (quando un fallback scatta) e
`judge.circuit_breaker_tripped` (quando il breaker è aperto).

Crediti: grazie a Brex per il loro progetto CrabTrap (con licenza MIT), che
ha informato questo design.

## Policy MCP

iron-proxy può parlare il [trasporto HTTP Streamable di MCP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports). Quando una richiesta corrisponde a un server MCP configurato, il proxy analizza il corpo JSON-RPC, applica una allowlist di strumenti default-deny e filtra le risposte `tools/list` così che gli strumenti negati non raggiungano mai l'agente. Le risposte SSE vengono filtrate per evento, in modo che i flussi MCP di lunga durata restino attivi.

Questa è una capacità proxy di prima classe piuttosto che un transform: le risposte MCP possono essere stream SSE aperti che trasportano messaggi arbitrari avviati dal server, il che non si adatta al contratto request/response dei transform.```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).

Credentials use the same secret sources as the `secrets` transform. They are required by default. Set `require: false` on a credential to skip it when unavailable. Audit logs record the route, upstream URL, and credential injection locations, but never the injected credential values.

Limitations in v1:

- Only Streamable HTTP transport is supported. The legacy HTTP+SSE transport (separate `/messages` and `/sse` endpoints) is not.
- A JSON-RPC batch with any denied entry is rejected as a whole batch; partial-batch forwarding is not supported.
- Resources and prompts are not enforced. Agents can still call `resources/list`, `resources/read`, etc. without policy filtering.

### Body limits

Transforms that inspect or forward request/response bodies (secrets body
matching, gRPC transforms) operate on buffered bodies. Two global settings
control the maximum buffer sizes:

- **`max_request_body_bytes`** (predefinito: `1048576` / 1 MiB): limita la quantità
  del corpo della richiesta bufferizzata per le transform. I dati oltre questo limite vengono
  troncati dal punto di vista della transform ma vengono comunque inoltrati all'upstream.
- **`max_response_body_bytes`** (predefinito: `0` / senza limite): limita la quantità
  del corpo della risposta bufferizzata. Imposta a `0` per bufferizzare l'intera risposta, che
  è l'impostazione predefinita corretta per la maggior parte dei workload (ad es. pacchetti npm, pesi dei modelli).

I corpi vengono bufferizzati incrementalmente man mano che le transform li leggono, e automaticamente
riavvolti tra le fasi della pipeline. Se una transform non legge il corpo, non avviene
alcun buffering e il corpo scorre intatto.

### Tunnel listener (HTTP/CONNECT/SOCKS5)

The tunnel listener accepts absolute-form HTTP proxy requests, HTTP CONNECT,
and SOCKS5 connections on a dedicated port. This is useful for tools that
natively support proxy configuration via `HTTP_PROXY`/`HTTPS_PROXY`/`ALL_PROXY`
environment variables or SOCKS5 settings, rather than relying on DNS-based
routing.

To enable it, set `tunnel_listen` under `proxy`:```yaml
proxy:
  tunnel_listen: ":8080"

**Esempio di proxy HTTP semplice:**```bash
curl -x http://172.20.0.2:8080 \
  http://httpbin.org/get

Puoi anche impostare le variabili d'ambiente standard così che tutti gli strumenti
vengano instradati automaticamente attraverso il tunnel:```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

Facile da configurare ma facile da bypassare: il workload può impostare IP hardcoded o usare il
proprio resolver DNS per saltare del tutto il proxy.

### DNS + firewall egress nftables (imposto)

Aggiungi un firewall nftables sopra il routing DNS. Il DNS continua a indirizzare il traffico
verso il proxy, ma nftables garantisce che il workload _non_ possa comunicare con nient'altro,
anche con IP hardcoded.

La directory [`examples/nftables`](https://github.com/paradigmxyz/iron-proxy/blob/HEAD/examples/nftables/) contiene una configurazione funzionante.
Il container client carica le regole del firewall all'avvio, prima di eseguire qualsiasi
traffico applicativo:

**nftables.conf** consente il traffico verso il proxy e blocca tutto il resto:```
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
  }
}

In una configurazione di produzione caricherai le regole in un wrapper di entrypoint e poi
`exec` il processo effettivo come utente non root senza `CAP_NET_ADMIN`.

### TPROXY (proxy trasparente)

Per ambienti in cui non puoi controllare affatto il DNS del workload, il TPROXY di nftables
può reindirizzare il traffico a livello di kernel senza alcuna cooperazione da parte del
workload. Questo intercetta i pacchetti nella catena PREROUTING e li consegna
direttamente a 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** inserisce `httpbin.org` e `icanhazip.com` nell'allowlist, scambia due segreti:```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"

## Formato del log di audit

Ogni richiesta inoltrata tramite proxy produce una voce di log JSON strutturata:```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": []
}

Tutta la configurazione usa le variabili d'ambiente OTEL standard:

| Variabile                     | Descrizione                                             | Predefinito      |
| ------------------------------ | ------------------------------------------------------- | ---------------- |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | URL del collector OTLP. L'export OTEL è disattivato se non impostato. | (disattivato)       |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | `http/protobuf` o `grpc`.                              | `http/protobuf`  |
| `OTEL_EXPORTER_OTLP_HEADERS`  | Coppie `key=value` separate da virgole per le header di autenticazione. | (nessuno)           |
| `OTEL_SERVICE_NAME`            | Nome del servizio associato a tutti i record di log.                | `iron-proxy`     |
| `OTEL_RESOURCE_ATTRIBUTES`    | Attributi di risorsa `key=value` separati da virgole.        | (nessuno)           |

Quando abilitato, ogni evento di audit viene emesso come record di log OTEL insieme ai
log JSON esistenti su stderr. Il record di log trasporta lo stesso schema della voce di
audit JSON: `host`, `method`, `path`, `action`, `status_code`, `duration_ms`,
e gli array completi `request_transforms`/`response_transforms` con annotazioni.

## API di gestione

iron-proxy può opzionalmente esporre un'API HTTP autenticata per attività
operative. Attualmente espone un singolo endpoint, `POST /v1/reload`, che rilegge
la configurazione YAML dal disco e sostituisce atomicamente la pipeline di
trasformazione con una appena costruita. La pipeline in esecuzione viene conservata
se la nuova configurazione non è valida.

Il server di gestione è disabilitato per impostazione predefinita. Per abilitarlo, aggiungi un blocco `management`
alla tua configurazione:```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

Hai bisogno di backend segreti Vault/KMS, di un operatore Kubernetes o di una gestione centralizzata delle policy? [iron.sh](https://iron.sh) si basa su iron-proxy con funzionalità enterprise per i team che lo eseguono su larga scala.

## Verifica delle firme di rilascio

Gli artefatti di rilascio includono un manifesto checksum firmato:

- `checksums.txt`
- `checksums.txt.asc` (firma distaccata in formato ASCII-armored)

Usa la chiave pubblica inclusa in [`public-key.asc`](https://github.com/paradigmxyz/iron-proxy/blob/HEAD/public-key.asc) per verificare:```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