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
 
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"
 
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.

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.

secrets.secrets[]

Secret Sources

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.

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. Query parameters are always scanned for proxy tokens.

The proxy_value, match_headers, match_body, 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.

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

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.