MITM

MITM config enables HTTP MITM modules that are selected by the mitm route action.

The rollout contract is fail-closed for supported MITM flows. Normal observability output keeps request metadata redaction-safe by default. sing-box does not export decrypted body content, and it strips secret-style headers such as Authorization, Cookie, token headers, and API keys from structured MITM metadata.

Structure

{
  "mitm": {
    "enabled": true,
    "ca": {
      "certificate": [],
      "certificate_path": [],
      "private_key": [],
      "private_key_path": []
    },
    "external_worker": {
      "command": "",
      "args": [],
      "uds_path": "",
      "hard_timeout": "",
      "max_memory": 0,
      "max_cpu": 0,
      "max_pids": 0,
      "max_concurrency": 0,
      "queue_depth": 0,
      "max_frame_size": 0,
      "max_body_size": 0,
      "restart_backoff": "",
      "linux_only_enforcement": false
    },
    "modules": [
      {
        "tag": "capture",
        "internal": {
          "rules": []
        },
        "external": {
          "script_id": "worker-id",
          "intercept": true,
          "direct_service": false,
          "capture_request_body": false,
          "capture_response_body": false,
          "support_trailers": false
        }
      }
    ]
  }
}

Fields

enabled

Enable MITM globally.

Route rules may not reference a MITM module unless mitm.enabled is true.

ca

Certificate authority material used for downstream leaf issuance.

For both certificate and private key, you must provide exactly one source. Use inline PEM with certificate / private_key, or use file paths with certificate_path / private_key_path.

Leaf certificates are issued only for one exact DNS name or one exact IP literal. Wildcards are rejected.

external_worker

Supervisor settings for external MITM modules.

This block is required when any module uses modules[].external.

external_worker.command

Executable used to start the worker process.

external_worker.args

Arguments passed to the worker command.

external_worker.uds_path

Unix domain socket path used for the worker byte stream.

This path is Linux-only and must fit the Unix socket pathname limit.

external_worker.hard_timeout

Bound for worker startup, stream open, and message receive operations.

When the timeout fires, sing-box treats the worker session as failed and closes supported MITM traffic instead of silently bypassing it.

external_worker.max_memory

Requested worker memory guardrail in bytes.

external_worker.max_cpu

Requested worker CPU guardrail.

external_worker.max_pids

Requested worker process-count guardrail.

external_worker.max_concurrency

Maximum number of active logical streams on one worker session.

external_worker.queue_depth

Maximum number of waiting requests while all worker slots are busy.

Overflow is rejected deterministically.

external_worker.max_frame_size

Maximum framed payload accepted on the worker protocol.

external_worker.max_body_size

Maximum captured request or response body size that sing-box will buffer for worker exchange.

external_worker.restart_backoff

Base delay before worker restart attempts.

external_worker.linux_only_enforcement

Whether Linux guardrail enforcement is mandatory.

If enabled, startup fails when a requested Linux guardrail (max_memory, max_cpu, or max_pids) cannot be enforced through cgroup v2 or prlimit.

If disabled, those limits are best-effort on Linux.

modules

List of named MITM modules.

Route rules refer to these modules by tag.

modules[].tag

Unique module name.

modules[].internal

Built-in request rewrite rules.

Available rule types are:

• host_replace
• path_regex
• query_regex
• header

Internal rewrites only mutate MITM-local HTTP metadata. Authoritative routing metadata remains frozen.

modules[].external

External worker mode for the module.

Exactly one mode flag must be set:

• intercept
• direct_service

capture_request_body, capture_response_body, and support_trailers declare which HTTP surfaces sing-box should exchange with the worker.

See the MITM standalone worker protocol guide for the framed protocol, capability negotiation, failure semantics, and example transcripts.

Example

{
  "mitm": {
    "enabled": true,
    "ca": {
      "certificate_path": ["./mitm-ca.pem"],
      "private_key_path": ["./mitm-ca.key"]
    },
    "modules": [
      {
        "tag": "capture",
        "internal": {
          "rules": [
            {
              "type": "host_replace",
              "from": "origin.example",
              "to": "rewritten.example"
            },
            {
              "type": "header",
              "action": "add",
              "name": "X-MITM",
              "value": "1"
            }
          ]
        }
      }
    ]
  },
  "route": {
    "rules": [
      {
        "protocol": "tls",
        "action": "mitm",
        "module": "capture"
      }
    ]
  }
}