MITM

MITM 配置用于启用 HTTP MITM 模块，并通过 mitm 路由动作选择对应模块。

已支持的 MITM 流量遵循 fail-closed 合同。默认观测输出会进行安全脱敏。sing-box 不会导出解密后的消息体内容，并且会从结构化 MITM 元数据中移除 Authorization、Cookie、各类 token 头和 API key 等敏感头。

结构

{
  "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
        }
      }
    ]
  }
}

字段

enabled

全局启用 MITM。

只有在 mitm.enabled 为真时，路由规则才允许引用 MITM 模块。

ca

用于下游叶子证书签发的 CA 材料。

证书和私钥都必须且只能提供一种来源。可以使用 certificate / private_key 内联 PEM，也可以使用 certificate_path / private_key_path 文件路径。

叶子证书只会为一个精确 DNS 名称或一个精确 IP 字面量签发。通配符会被拒绝。

external_worker

外部 MITM 模块的监督配置。

当任意模块启用了 modules[].external 时，此配置为必填。

external_worker.command

启动 worker 进程的可执行文件。

external_worker.args

传递给 worker 命令的参数。

external_worker.uds_path

worker 字节流使用的 Unix 域套接字路径。

该路径仅适用于 Linux，并且必须满足 Unix socket 路径长度限制。

external_worker.hard_timeout

worker 启动、流打开和消息接收操作的超时上限。

一旦超时，sing-box 会把 worker 会话视为失败，并关闭已支持的 MITM 流量，而不是静默绕过策略。

external_worker.max_memory

请求的 worker 内存限制，单位为字节。

external_worker.max_cpu

请求的 worker CPU 限制。

external_worker.max_pids

请求的 worker 进程数限制。

external_worker.max_concurrency

单个 worker 会话允许的活跃逻辑流上限。

external_worker.queue_depth

所有 worker 槽位都忙时允许排队的请求上限。

超出后会被确定性拒绝。

external_worker.max_frame_size

worker 协议允许的最大分帧负载大小。

external_worker.max_body_size

sing-box 为 worker 交换而缓冲的请求体或响应体最大大小。

external_worker.restart_backoff

worker 重启尝试的基础回退时间。

external_worker.linux_only_enforcement

Linux 侧限制是否必须强制生效。

启用后，如果请求的 Linux 限制（max_memory、max_cpu 或 max_pids）无法通过 cgroup v2 或 prlimit 生效，则启动会失败。

关闭后，这些限制在 Linux 上按尽力而为方式处理。

modules

MITM 模块列表。

路由规则通过 tag 引用这些模块。

modules[].tag

唯一模块名。

modules[].internal

内置请求重写规则。

可用规则类型：

host_replace
path_regex
query_regex
header

内置重写只会修改 MITM 本地 HTTP 元数据。权威路由元数据会保持冻结状态。

modules[].external

模块的外部 worker 模式。

必须且只能设置一个模式标志：

intercept
direct_service

capture_request_body、capture_response_body 和 support_trailers 用于声明 sing-box 需要与 worker 交换哪些 HTTP 表面。

关于分帧协议、能力协商、失败语义和示例收发流程，请参阅 MITM 独立 worker 协议指南。

示例

{
  "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"
      }
    ]
  }
}