Configuration

iron-proxy is configured via a single YAML file, passed at startup with the -config flag:

iron-proxy -config /etc/iron-proxy/proxy.yaml

Below is a complete reference for every configuration option.

Full Example

dns:
  listen: ":53"
  proxy_ip: "172.20.0.2"
  upstream_resolver: "8.8.8.8:53"
  passthrough:
    - "*.internal.corp"
  records:
    - name: "custom.local"
      type: A
      value: "10.0.0.5"
 
proxy:
  http_listen: ":80"
  https_listen: ":443"
  tunnel_listen: ":1080"
  max_request_body_bytes: 1048576
  max_response_body_bytes: 0
  upstream_response_header_timeout: "30s"
  upstream_deny_cidrs:
    - "169.254.169.254/32"
    - "fd00:ec2::254/128"
    - "127.0.0.0/8"
    - "::1/128"
 
tls:
  mode: "mitm"
  ca_cert: "/certs/ca.crt"
  ca_key: "/certs/ca.key"
  cert_cache_size: 1000
  leaf_cert_expiry_hours: 72
 
transforms:
  - name: allowlist
    config:
      domains:
        - "registry.npmjs.org"
      cidrs:
        - "10.0.0.0/8"
      rules:
        - host: "api.openai.com"
          methods: ["POST"]
          paths: ["/v1/*"]
        - host: "*.anthropic.com"
          methods: ["POST"]
          paths: ["/v1/messages", "/v1/complete"]
 
  - name: secrets
    config:
      secrets:
        - source:
            type: env
            var: OPENAI_API_KEY
          inject:
            header: "Authorization"
            formatter: "Bearer {{ .Value }}"
          rules:
            - host: "api.openai.com"
              methods: ["POST"]
              paths: ["/v1/*"]
        - source:
            type: aws_sm
            secret_id: "arn:aws:secretsmanager:us-west-1:123456789:secret:anthropic-key"
            region: "us-west-1"
            ttl: 5m
          replace:
            proxy_value: "pk-proxy-anthropic-xyz"
            match_headers: ["x-api-key"]
            require: true
          rules:
            - host: "api.anthropic.com"
        - source:
            type: aws_ssm
            name: "/myapp/openai-key"
            region: "us-east-1"
            ttl: 15m
          replace:
            proxy_value: "pk-proxy-openai-param"
            match_headers: ["Authorization"]
          rules:
            - host: "api.openai.com"
 
  - name: annotate
    config:
      annotations:
        - rules:
            - host: "api.openai.com"
              methods: ["POST"]
              paths: ["/v1/*"]
          headers: ["x-request-id"]
 
  - name: grpc
    config:
      name: "policy-engine"
      target: "localhost:9500"
      send_request_body: true
      send_response_body: true
      rules:
        - host: "api.openai.com"
          methods: ["POST"]
          paths: ["/v1/*"]
      tls:
        enabled: true
        ca_cert: "/etc/iron-proxy/grpc-ca.pem"
        cert: "/etc/iron-proxy/grpc-client.pem"
        key: "/etc/iron-proxy/grpc-client-key.pem"
 
  - name: judge
    config:
      name: "github-write-guard"
      fallback: "deny"
      timeout: "8s"
      rules:
        - host: "api.github.com"
          methods: ["POST", "PATCH", "DELETE", "PUT"]
      provider:
        type: "anthropic"
        model: "claude-haiku-4-5-20251001"
        api_key_env: "ANTHROPIC_API_KEY"
      prompt: |
        Allow writes to the repository under review. Deny writes to user
        settings, billing, or any other repository.
 
  - name: header_allowlist
    config:
      headers:
        - "Authorization"
        - "Content-Type"
        - "User-Agent"
        - "Accept"
        - "/^X-Trace-.*$/"
      rules:
        - host: "api.openai.com"
 
mcp:
  error:
    code: -32001
    message: "blocked by iron-proxy policy"
  servers:
    - name: github
      rules:
        - host: "mcp.github.com"
          paths: ["/mcp", "/mcp/*"]
      tools:
        - name: "search_repositories"
        - name: "create_issue"
          when:
            - path: "owner"
              equals: "ironsh"
            - path: "repo"
              in: ["iron-proxy"]
 
management:
  listen: "127.0.0.1:9092"
  api_key_env: "IRON_MANAGEMENT_API_KEY"
 
metrics:
  listen: ":9090"
 
log:
  level: "info"

dns

Configures the built-in DNS server. The DNS server returns proxy_ip for all lookups so that outbound traffic routes through the proxy.

dns.records[]

proxy

Configures the HTTP/HTTPS proxy listeners.

upstream_deny_cidrs Defaults

When upstream_deny_cidrs is unset, iron-proxy blocks cloud instance metadata and loopback by default:

• 169.254.169.254/32 (AWS / GCP / Azure IPv4 IMDS)
• fd00:ec2::254/128 (AWS IPv6 IMDS)
• 127.0.0.0/8 (IPv4 loopback)
• ::1/128 (IPv6 loopback)

The defaults intentionally omit RFC1918 ranges, since many iron-proxy deployments target private corporate networks.

Provide an explicit list to override the defaults entirely, or an empty list to opt out:

proxy:
  upstream_deny_cidrs:
    - "169.254.169.254/32"
    - "127.0.0.0/8"

If a workload legitimately needs to talk to IMDS or loopback through the proxy, override the list before upgrading or the proxy will refuse those connections.

tls

Configures how iron-proxy handles HTTPS traffic. Two modes are supported: mitm (the default), which terminates TLS using a CA you provide and mints leaf certificates on the fly, and sni-only, which passes TLS through without termination.

TLS Modes

mitm (default): iron-proxy terminates the client TLS connection, inspects the decrypted request, and opens a new TLS connection to the upstream server. Clients must trust iron-proxy's CA certificate. This is the only mode that lets transforms see request methods, paths, headers, and bodies.

sni-only: iron-proxy peeks at the TLS ClientHello SNI and TCP-passthroughs the connection to the upstream without terminating TLS. Clients do not need to trust a proxy CA. The transform pipeline still runs with a host-only synthetic request: method, path, headers, and body are empty, so host-based allowlist rules are the only things that can match. Body-inspecting transforms like secrets and grpc still run but have nothing to act on. The CONNECT/SOCKS5 tunnel's TLS branch also switches to passthrough in sni-only mode.

tls:
  mode: "sni-only"

Use sni-only when you need host-level egress control but cannot distribute a CA certificate to workloads. Use mitm when you need secret injection, body inspection, or method/path allowlists.

transforms

An ordered array of transforms that run on every request. All transforms must pass for the request to be forwarded upstream. Transforms execute in the order they appear in the configuration.

Each transform has a name and a config object. The available transforms are documented below.

allowlist

Controls which destinations are reachable through the proxy. Requests to destinations not in the allowlist receive an HTTP 403 response.

There are two ways to specify allowed destinations: flat lists (domains and cidrs) that allow all methods and paths, and rules that support method and path restrictions. Both can be used together in the same allowlist.

allowlist.rules[]

Each rule matches a single host or CIDR, with optional method and path filters. A request is allowed if it matches any rule (or any flat domains/cidrs entry).

secrets

Injects or replaces secret values at the egress boundary so that real credentials are never exposed to sandboxed workloads. Each secret declares its own source and either an inject or replace block.

See the Static Secrets reference for a full overview of inject and replace modes, secret sources, and credential rotation. The fields below are the canonical schema.

secrets.secrets[]

Secret Sources

Every source supports an optional json_key field. When set, the resolved value is parsed as JSON and the named field is extracted before use. This works with all source types (env, aws_sm, aws_ssm, 1password, 1password_connect) and is useful for pulling individual fields out of a single shared JSON secret.

env

Read the secret from an environment variable on the iron-proxy process.

source:
  type: env
  var: OPENAI_API_KEY

aws_sm

Read the secret from AWS Secrets Manager. The value is cached and refreshed in the background based on the configured TTL.

source:
  type: aws_sm
  secret_id: "arn:aws:secretsmanager:us-west-1:123456789:secret:my-key"
  region: "us-west-1"
  ttl: 10m

aws_ssm

Read the secret from AWS Systems Manager Parameter Store. Like aws_sm, values are cached and refreshed in the background based on the TTL.

source:
  type: aws_ssm
  name: "/myapp/api-key"
  region: "us-east-1"
  with_decryption: true
  ttl: 15m

iron-proxy uses the standard AWS credential chain (environment variables, instance profile, ECS task role, etc.) to authenticate with AWS.

1password

Read the secret from 1Password using a service account token. Like the AWS sources, values are cached and refreshed in the background based on the TTL. For most deployments, prefer 1password_connect: the hosted SDK service applies per-account rate limits that can stall request handling under load.

source:
  type: 1password
  secret_ref: "op://Engineering/OpenAI/credential"
  token_env: OP_SERVICE_ACCOUNT_TOKEN
  ttl: 15m

1password_connect

Read the secret from a 1Password Connect server running in your own infrastructure. This is the recommended 1Password integration: Connect runs locally and avoids the per-account rate limits that the hosted SDK enforces. Values are cached and refreshed in the background based on the TTL.

source:
  type: 1password_connect
  secret_ref: "op://Engineering/OpenAI/credential"
  host_env: OP_CONNECT_HOST
  token_env: OP_CONNECT_TOKEN
  ttl: 15m

Inject Mode

In inject mode, the proxy unconditionally sets a header or query parameter on every request that matches the secret's rules. The workload never sees or sends any credential. This is useful when sandboxed workloads should have no knowledge of credentials at all.

The formatter field supports Go templates. Use {{ .Value }} to insert the raw secret. The base64 helper concatenates and base64-encodes its arguments:

# Set Authorization: Bearer <secret>
inject:
  header: "Authorization"
  formatter: "Bearer {{ .Value }}"
 
# Set a query parameter (no formatter needed)
inject:
  query_param: "key"

Replace Mode

In replace mode, the workload sends a proxy token that the proxy swaps for the real value before forwarding upstream.

The proxy_value, match_headers, match_body, match_path, match_query, and require fields may also be set at the top level of a secret entry for backwards compatibility. New configurations should use the replace block.

gcp_auth

Mints short-lived GCP OAuth2 access tokens from a service account keyfile and injects them as Authorization: Bearer on matching requests. Token minting, caching, and refresh are handled automatically. Requires MITM mode.

iron-proxy also stubs Google's OAuth2 token endpoints (oauth2.googleapis.com/token and the GCE/GKE metadata server's service-account token endpoints) so client SDKs that complete their own token dance reach the proxy with a placeholder token. The real token is minted separately and swapped onto the upstream API call.

See the GCP Service Accounts reference for a full overview, including keyfile sourcing, domain-wide delegation, and metadata server stubbing.

Exactly one of keyfile_path, keyfile, or credentials_provider must be set.

credentials_provider accepts {type: workload_identity}. The proxy holds the rotating credentials minted by the cloud SDK; the workload runs against the stubbed metadata server as usual.

- name: gcp_auth
  config:
    keyfile:
      type: aws_sm
      secret_id: "arn:aws:secretsmanager:us-east-1:123456789:secret:gcp-sa-key"
    subject: "user@workspace.example.com"
    scopes:
      - "https://www.googleapis.com/auth/cloud-platform"
    rules:
      - host: "*.googleapis.com"

oauth_token

Mints short-lived OAuth2 access tokens and injects them as Authorization: Bearer on matching requests. Each entry under tokens declares a grant type, its credential fields, and the hosts it applies to. Token exchange, caching, refresh, and single-flight deduplication are handled automatically. Requires MITM mode. If token minting fails the request is rejected with HTTP 502.

Each configured token_endpoint is also stubbed, so sandboxed client SDKs can complete their own OAuth2 handshake against the proxy with a placeholder token while the proxy injects the real one upstream.

See the OAuth2 Token Injection reference for a full overview, including per-vendor recipes (DocuSign, Salesforce, Box, Zoom, Gmail, AlphaSense) and credential rotation behavior.

oauth_token.tokens[]

Required credential fields depend on the grant:

Each credential field is a discrete secret source. private_key for jwt_bearer must resolve to a PEM-encoded RSA private key; private_key_id, when set, is emitted as the JWT kid header.

For Google service-account auth, use the gcp_auth transform instead: it wraps the same JWT-bearer flow with Google's keyfile format.

- name: oauth_token
  config:
    tokens:
      - grant: refresh_token
        refresh_token:
          type: aws_sm
          secret_id: "arn:aws:secretsmanager:us-east-1:123456789:secret:gsuite-oauth"
          json_key: "refresh_token"
        client_id:
          type: aws_sm
          secret_id: "arn:aws:secretsmanager:us-east-1:123456789:secret:gsuite-oauth"
          json_key: "client_id"
        client_secret:
          type: aws_sm
          secret_id: "arn:aws:secretsmanager:us-east-1:123456789:secret:gsuite-oauth"
          json_key: "client_secret"
        token_endpoint: "https://oauth2.googleapis.com/token"
        scopes:
          - "https://www.googleapis.com/auth/gmail.readonly"
        rules:
          - host: "gmail.googleapis.com"
 
      - grant: jwt_bearer
        issuer:  {type: env, var: DOCUSIGN_INTEGRATION_KEY}
        subject: {type: env, var: DOCUSIGN_USER_GUID}
        private_key:
          type: aws_sm
          secret_id: "arn:aws:secretsmanager:us-east-1:123456789:secret:docusign-private-key"
        audience: "account.docusign.com"
        token_endpoint: "https://account.docusign.com/oauth/token"
        scopes: ["signature", "impersonation"]
        rules:
          - host: "*.docusign.net"

aws_auth

Re-signs inbound AWS SigV4 requests with real credentials. The workload's AWS SDK signs with placeholders; iron-proxy reads the region and service from the inbound credential scope and re-signs with real credentials drawn from any secret source. One config entry covers every AWS service the client speaks to. Requires MITM mode.

See the AWS Request Signing reference for a full overview, including scope gating, body handling modes, and worked examples.

- name: aws_auth
  config:
    access_key_id:     {type: env, var: AWS_ACCESS_KEY_ID}
    secret_access_key: {type: env, var: AWS_SECRET_ACCESS_KEY}
    allowed_regions:   ["us-east-1", "eu-west-1"]
    allowed_services:  ["bedrock", "s3", "dynamodb"]
    rules:
      - host: "*.amazonaws.com"

hmac_sign

Signs outbound requests with HMAC before forwarding them upstream. Computes a signature over a Go-template message derived from the request and injects the signature plus any auxiliary credentials into a configurable set of headers. The four signature enums (algorithm, key_encoding, output_encoding, timestamp.format) plus the message template cover most signing schemes. Requires MITM mode.

See the HMAC Request Signing reference for a full overview, including template variable details, body integrity rules, and worked examples.

Because a truncated body would produce an invalid signature, the transform enforces body integrity:

• Bodies whose buffered length falls short of Content-Length (truncated by proxy.max_request_body_bytes) are rejected with HTTP 413.
• Chunked bodies are rejected with HTTP 400 unless allow_chunked_body: true.

- name: hmac_sign
  config:
    timestamp:
      format: unix_seconds
    signature:
      algorithm: sha256
      key_encoding: base64
      output_encoding: base64
      message: "{{.Timestamp}}{{.Method}}{{.PathWithQuery}}{{.Body}}"
    credentials:
      key:        {type: env, var: FALCONX_API_KEY}
      secret:     {type: env, var: FALCONX_SECRET}
      passphrase: {type: env, var: FALCONX_PASSPHRASE}
    headers:
      - {name: "FX-ACCESS-KEY",        value: "{{.Credentials.key}}"}
      - {name: "FX-ACCESS-SIGN",       value: "{{.Signature}}"}
      - {name: "FX-ACCESS-TIMESTAMP",  value: "{{.Timestamp}}"}
      - {name: "FX-ACCESS-PASSPHRASE", value: "{{.Credentials.passphrase}}"}
    rules:
      - host: "api.falconx.io"

body_capture

Records decoded request bodies of matching requests onto the audit log under body_capture.request_body (and body_capture.request_body_truncated when the body exceeds the cap). Observation-only: it never rejects a request, and read errors are annotated on the trace rather than failing the request. Response bodies are not captured.

- name: body_capture
  config:
    max_request_body_bytes: 16384
    rules:
      - host: "api.anthropic.com"
        methods: ["POST"]
        paths: ["/v1/messages"]

When secrets runs with match_body: true, place body_capture before secrets so the audit log records the workload's proxy tokens rather than the real credentials swapped in.

annotate

Captures HTTP request header values into audit log annotations based on host, method, and path rules. This is useful for enriching audit logs with request-specific context like request IDs or authorization tokens. This transform never rejects requests.

annotate.annotations[]

- name: annotate
  config:
    annotations:
      - rules:
          - host: "api.openai.com"
            methods: ["POST"]
            paths: ["/v1/*"]
        headers: ["x-request-id", "authorization"]

Example audit log annotation output:

{
  "header:X-Request-Id": "req-abc123",
  "header:Authorization": "Bearer sk-ant-..."
}

grpc

Delegates request and response processing to an external gRPC server implementing the TransformService API. You can define multiple grpc transforms to pipeline through several servers.

grpc.tls

judge

Calls a large language model to produce an allow or deny decision for outbound requests that match the instance's rules. Each judge entry is an independent instance with its own natural-language policy, LLM backend, semaphore, and circuit breaker. See the LLM Judge reference for a full overview, including writing policies, pipeline ordering, and envelope limits.

The judge can only reject. It never approves a request that the static allowlist would have denied.

judge.circuit_breaker

Judge Providers

The provider block selects and configures the LLM backend. The type field discriminates the shape of the block. Two providers are supported: anthropic and openai.

anthropic

Calls the Anthropic Messages API.

provider:
  type: "anthropic"
  model: "claude-haiku-4-5-20251001"
  api_key_env: "ANTHROPIC_API_KEY"
  max_tokens: 256

openai

Calls the OpenAI Chat Completions API.

provider:
  type: "openai"
  model: "gpt-5.4-nano"
  api_key_env: "OPENAI_API_KEY"
  max_tokens: 256

Full Judge Example

- name: judge
  config:
    name: "github-write-guard"
    fallback: "deny"
    timeout: "8s"
    max_concurrent: 100
    circuit_breaker:
      consecutive_failures: 5
      cooldown: "10s"
    rules:
      - host: "api.github.com"
        methods: ["POST", "PATCH", "DELETE", "PUT"]
    provider:
      type: "anthropic"
      model: "claude-haiku-4-5-20251001"
      api_key_env: "ANTHROPIC_API_KEY"
      max_tokens: 256
    prompt: |
      This agent performs code review on the repository under review.
      Allow writes to the comments and reviews endpoints of the specific
      repository under review. Deny writes to user settings, organization
      management, billing, or any repository the agent is not reviewing.

Place the judge transform before the secrets transform so the LLM provider sees proxy tokens rather than real credentials. See pipeline ordering for details.

header_allowlist

Strips any request header not present in a configured allowlist before forwarding the request upstream. The allowlist uses a default-deny model: every header must match either a literal name or a regex pattern to pass through. Stripped header names are recorded in the trace annotation stripped_headers.

Place this transform after any transforms that inject headers (such as secrets) so injected headers survive the allowlist.

- name: header_allowlist
  config:
    headers:
      - "Authorization"
      - "Content-Type"
      - "User-Agent"
      - "Accept"
      - "/^X-Trace-.*$/"
    rules:
      - host: "api.openai.com"

mcp

Top-level block that enforces a default-deny tool allowlist on Streamable HTTP MCP servers. The interceptor runs after the transform pipeline, so allowlist still gates which hosts can be reached and secrets has already swapped proxy tokens before the interceptor evaluates the body.

See the MCP Interception reference for a full overview, including matchers, audit log behavior, and current limitations.

mcp.error

mcp.servers[]

mcp.servers[].tools[]

mcp.servers[].tools[].when[]

mcp:
  error:
    code: -32001
    message: "blocked by iron-proxy policy"
  servers:
    - name: github
      rules:
        - host: "mcp.github.com"
          paths: ["/mcp", "/mcp/*"]
      tools:
        - name: "search_repositories"
        - name: "create_issue"
          when:
            - path: "owner"
              equals: "ironsh"
            - path: "repo"
              in: ["iron-proxy", "tunis-v2"]

management

Configures an opt-in, bearer-authenticated HTTP management API. When set, iron-proxy listens on the configured address and exposes endpoints that operate on the running process. The API is disabled when the management block is omitted.

The first available endpoint is POST /v1/reload, which re-reads the YAML config from disk and atomically swaps in a freshly built transform pipeline with no restart and no dropped connections. Parse or build errors return HTTP 422 and leave the running pipeline untouched.

management:
  listen: "127.0.0.1:9092"
  api_key_env: "IRON_MANAGEMENT_API_KEY"

Reload a running proxy:

curl -X POST http://127.0.0.1:9092/v1/reload \
  -H "Authorization: Bearer $IRON_MANAGEMENT_API_KEY"

metrics

Configures the OpenTelemetry/Prometheus metrics endpoint.

log

Configures logging output.

OpenTelemetry Environment Variables

OTEL log export is configured through environment variables, not the YAML config file. Set OTEL_EXPORTER_OTLP_ENDPOINT to enable it. See the OTEL export guide for usage examples.