sycommon-python-lib 0.2.8a3__tar.gz → 0.2.8a5__tar.gz

{sycommon_python_lib-0.2.8a3 → sycommon_python_lib-0.2.8a5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sycommon-python-lib
-Version: 0.2.8a3
+Version: 0.2.8a5
 Summary: Add your description here
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{sycommon_python_lib-0.2.8a3 → sycommon_python_lib-0.2.8a5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sycommon-python-lib"
-version = "0.2.8a3"
+version = "0.2.8a5"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.11"

{sycommon_python_lib-0.2.8a3 → sycommon_python_lib-0.2.8a5}/src/sycommon/agent/deep_agent.py

@@ -1274,14 +1274,18 @@ async def create_deep_agent(
             on_evaluation=rubric_eval_collector.on_evaluation,
         ))
 
-    # SkillApiWhitelistMiddleware：按子技能注入接口白名单（拦 execute 工具，
-    # export SKILL_API_WHITELIST + 推送 sitecustomize 到沙箱做 path 级校验）
-    if sandbox_backend:
+    # SkillApiWhitelistMiddleware(旧管控层)：已被出网收口取代——
+    # 沙箱网关(egress gateway)做 path 白名单+凭据注入,iptables 硬墙(egress_wall)
+    # 在内核层挡 node/裸socket。旧的 .wl 推送/sitecustomize monkeypatch/shell-guard
+    # 不再注册(子进程 env 零密钥后 sitecustomize 的 SYT_API_AUTHZ 注入也已由网关承接)。
+    # 回滚开关: 环境变量 SANDBOX_LEGACY_WHITELIST=1 时恢复注册(应急用)。
+    if sandbox_backend and os.environ.get("SANDBOX_LEGACY_WHITELIST", "") == "1":
         try:
             from sycommon.agent.middleware.skill_api_whitelist import (
                 SkillApiWhitelistMiddleware)
             middleware_list.append(
                 SkillApiWhitelistMiddleware(sandbox_backend))
+            SYLogger.warning("[DeepAgent] 旧白名单中间件已启用(SANDBOX_LEGACY_WHITELIST=1 应急模式)")
         except Exception as _wl_err:
             SYLogger.warning(f"[DeepAgent] 技能接口白名单中间件加载失败(忽略): {_wl_err}")
 

{sycommon_python_lib-0.2.8a3 → sycommon_python_lib-0.2.8a5}/src/sycommon/agent/middleware/skill_api_whitelist.py

@@ -174,19 +174,58 @@ def _load_resource_bytes(filename: str) -> bytes:
 
 
 def _build_shell_guard(with_whitelist: bool = False,
-                       with_header: bool = False) -> str:
+                       with_header: bool = False,
+                       with_rewrite_to_gateway: bool = False) -> str:
     """生成内联到命令前缀的 curl/wget 包装函数（shell）。
 
-    抽取参数里【最后一个】 http(s) URL 到 _u，按需承担两类职责（可同时启用，
-    先白名单校验、再注入 header）：
-      - with_whitelist：用沙箱 python3 调 skill_wl_check.match 校验 _u，未命中 return 1。
-      - with_header：_u 的 host 命中 $__SYT_HOST__ 时追加 -H "X-Sy-Api-Authz:
-        $SYT_API_AUTHZ"（原参数已含同名头则不重复加）。
+    抽取参数里【最后一个】 http(s) URL 到 _u，按需承担三类职责（可同时启用）：
+      - with_rewrite_to_gateway：把 _u 的真上游 URL 改写成网关 URL
+        （http://127.0.0.1:port，真 host 进 X-Upstream-Host 头），凭据头剥除。
+        收口模式下子进程 SYT_BASE_URL 已是网关，多数脚本自动走网关；此分支兜底
+        硬编码 https://<真上游> 的 curl/wget 命令（绕过 SYT_BASE_URL）。
+      - with_whitelist：网关已做白名单，此处保留为纵深（沙箱 python3 校验）。
+      - with_header：收口后凭据由网关注入，此分支仅在未启用收口（兼容旧部署）时生效。
 
     skill_wl_check 与 sitecustomize 同处 site-packages，python3 启动时 sitecustomize
     会 import 它并把该目录加入 sys.path。覆盖 curl / wget；其它 shell 出网方式
-    (nc/裸 /dev/tcp 等)不覆盖。
+    (nc/裸 /dev/tcp 等)不覆盖（由 seccomp 硬墙兜底）。
     """
+    rewrite_block = ""
+    if with_rewrite_to_gateway:
+        # _u 形如 https://syapi.x.com/path?qs。改写为 http://127.0.0.1:$__GW_PORT__/path?qs，
+        # 真上游 host 进 X-Upstream-Header，并剥除 Authorization/SYU-Token/X-Sy-Api-Authz
+        # （网关重新注入正确凭据）。port 取自子进程 SYT_BASE_URL（收口已注入网关地址）。
+        # 修审核 P1-6:重写后的 URL 必须替换 "$@" 里的原 URL 参数(旧实现只改了
+        # 校验变量 _u,curl 实际仍直连真上游)。URL 参数判定:与 _u 原值相等的参数。
+        # 注:该分支当前无调用方启用(旧白名单中间件已注销,收口走 SYT_BASE_URL
+        # 指向网关),保留为 legacy 应急路径并修正确性。
+        rewrite_block = (
+            'if [ -n "$_u" ]; then '
+            # 取真上游 host（去 scheme/path/port）
+            '_rh="${_u#*://}"; _rh="${_rh%%/*}"; _rh="${_rh%%\\?*}"; _rh="${_rh%%:*}"; '
+            # 取 path?query
+            '_rp="${_u#*://}"; _rp="${_rp#*/}"; '
+            '[ "$_rp" = "$_u#*://" ] && _rp=""; '
+            '[ -n "$_rp" ] && _rp="/$_rp"; '
+            # 网关地址来自 SYT_BASE_URL（收口已注入 http://127.0.0.1:port）
+            '_gw="${SYT_BASE_URL%%/}"; '
+            'if [ -n "$__GW_PORT__" ]; then _gw="http://127.0.0.1:$__GW_PORT__"; fi; '
+            'if [ -n "$_gw" ] && [ -n "$_rh" ]; then '
+            '_rw="$_gw$_rp"; '
+            # 重建参数:剥凭据头 + 把原 URL 参数替换为网关 URL(P1-6 修)
+            'set -- "$@"; _new=(); _skip=0; '
+            'for _a in "$@"; do '
+            'if [ "$_skip" = "1" ]; then _skip=0; continue; fi; '
+            'case "$_a" in '
+            '"-H"|"--header") _skip=1; continue;; '
+            '"Authorization:"*|"SYU-Token:"*|"X-Sy-Api-Authz:"*|"SYU-Url:"*) continue;; '
+            '"$_u") _new+=("$_rw"); continue;; '
+            'esac; _new+=("$_a"); done; '
+            'set -- "${_new[@]}" -H "X-Upstream-Host: $_rh"; '
+            '_u="$_rw"; '
+            'fi; '
+            'fi; '
+        )
     wl_block = ""
     if with_whitelist:
         check_cmd = (
@@ -199,7 +238,7 @@ def _build_shell_guard(with_whitelist: bool = False,
         )
     hdr_block = ""
     if with_header:
-        # 从 _u 取 host（小写）：剥 scheme/path/query/fragment/userinfo/port
+        # 仅兼容旧部署（未收口）的 X-Sy-Api-Authz 注入。收口模式下网关注入，跳过。
         hdr_block = (
             'if [ -n "$_u" ] && [ -n "$__SYT_HOST__" ] && [ -n "$SYT_API_AUTHZ" ]; then '
             '_h="${_u#*://}"; _h="${_h%%/*}"; _h="${_h%%\\?*}"; _h="${_h%%#*}"; '
@@ -212,12 +251,12 @@ def _build_shell_guard(with_whitelist: bool = False,
             'esac; '
             'fi; '
         )
-    if not wl_block and not hdr_block:
+    if not wl_block and not hdr_block and not rewrite_block:
         return ""
     body = (
         '() { local _u _a _h; for _a in "$@"; do '
         'case "$_a" in http://*|https://*) _u="$_a";; esac; done; '
-        + wl_block + hdr_block +
+        + rewrite_block + wl_block + hdr_block +
         'command {CMD} "$@"; };'
     )
     guard = "curl" + body.replace("{CMD}", "curl") + " wget" + body.replace("{CMD}", "wget")

{sycommon_python_lib-0.2.8a3 → sycommon_python_lib-0.2.8a5}/src/sycommon/config/Config.py

@@ -201,19 +201,29 @@ class Config(metaclass=SingletonMeta):
         self.config = {**self.config, **
                        share_configs.get('llm', {}), **share_configs}
 
-        # Project-specific override: if the Nacos config whose dataId matches
-        # the application Name contains LLMConfig/EmbeddingConfig/RerankerConfig,
-        # those entries take priority (full override) over the shared llm defaults.
+        # Project-specific override: the Nacos config whose dataId matches the
+        # application Name (e.g. shengye-platform-digital-work) takes priority
+        # over everything above, at top level.
+        #
+        # 历史:曾用写死的 override_keys 白名单(LLMConfig/SkillApiWhitelist/...)
+        # 提升项目 dataId 的顶层 key——每新增一个配置段都要改库,易漏。
+        # 现改为【全量提升】:项目 dataId 的所有顶层 key 均覆盖到顶层,例外:
+        #   - spring:数据库连接以 setup_database 的 shareConfigKey 指向源为准
+        #     (如 common.yml),项目 dataId 的 spring 不覆盖,防止连错库;
+        #   - Nacos/Name/Host/Port 等本地启动键:属于 app.yaml 启动配置,
+        #     不允许远端覆盖(防止热更新破坏服务注册/监听地址)。
+        # 向后兼容:原白名单内的 key 行为不变(依旧覆盖),新增 key 自动生效。
         app_name = self.config.get('Name', '')
         project_cfg = share_configs.get(app_name, {})
-        # 这些 key 写在「与 app 同名的 dataId」里（如 shengye-platform-digital-work），
-        # 但消费方按顶层 key 读取（LLMConfig 等）——提升到顶层，免得每个调用方都得知道嵌套路径。
-        override_keys = ['LLMConfig', 'EmbeddingConfig', 'RerankerConfig',
-                         'ACPAgentConfig',
-                         'SkillApiWhitelist',
-                         'SensitiveConfig']
-        for k in override_keys:
-            if k in project_cfg:
-                self.config[k] = project_cfg[k]
+        if isinstance(project_cfg, dict):
+            # 本地启动键:app.yaml 的进程级配置,远端不覆盖
+            _LOCAL_BOOT_KEYS = frozenset((
+                'Name', 'Host', 'Port', 'Workers', 'MaxBytes', 'Timeout',
+                'MaxRetries', 'Nacos', 'Version',
+            ))
+            for k, v in project_cfg.items():
+                if k in _LOCAL_BOOT_KEYS or k == 'spring':
+                    continue
+                self.config[k] = v
 
         self._process_config()

sycommon_python_lib-0.2.8a5/src/sycommon/config/EgressPolicyConfig.py

@@ -0,0 +1,183 @@
+"""沙箱出网策略配置模型。
+
+配置来源:沙箱服务自己的 Nacos dataId(`shengye-platform-sandbox`)下的
+`EgressPolicy` 段。硬墙(egress_wall)与网关(sandbox_gateway)都跑在沙箱进程,
+直接读本地 Config,不依赖主进程推送——出网策略是【沙箱的部署属性】。
+
+    EgressPolicy:
+      directAllow:           # 直连放行(无凭据不注入):内网无鉴权服务/公网查询类
+        - "10.10.13.32"      # 具体条目优先于管制判定
+        - "zxgk.court.gov.cn"
+      # 其余外网: DROP(不可配,防数据外泄是硬墙本意)
+
+【管制判定不配置,自动推导】:目标 host 与凭据包 SYT_BASE_URL(真上游,主进程
+按环境解析:prod=syapi.sytechnology.com / test=cloudapi-*.syitservice.com)
+同域名 → 管制(仅网关可达,凭据注入+审计)。也就是说「凡 ${SYT_BASE_URL} 系
+的域名」一律收口,换环境/换网关域名无需改这里——这正是「sy-base-url 管制」
+的字面语义。viaGateway 字段保留为可选的【额外】管制补充(如 OA MCP 后端),
+不影响 SYT_BASE_URL 自动判定。
+
+匹配语义(优先级从高到低):
+  1. directAllow 命中(host/IP,精确或 *.domain 通配) → 直连放行
+  2. host == SYT_BASE_URL 的 host(自动,不配置)        → 仅网关可达(直连被墙)
+  3. viaGateway 命中(可选的额外管制名单)               → 仅网关可达
+  4. 都不命中                                            → DROP / 网关 403
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import socket
+from typing import Optional
+from urllib.parse import urlparse
+
+from pydantic import BaseModel, Field
+
+from sycommon.logging.kafka_log import SYLogger
+
+
+class EgressPolicyConfig(BaseModel):
+    """沙箱出网策略(SYT_BASE_URL 同域名自动管制 / directAllow 直连 / 其余 DROP)。"""
+
+    viaGateway: list[str] = Field(
+        default_factory=list,
+        description=(
+            "【额外】强制走网关的目标 host(精确或 *.domain 通配),补充 SYT_BASE_URL "
+            "自动判定之外的管制对象。当前阶段:OA MCP 后端(ai.syitservice.com,含 "
+            "oa-workorder/xinghan/yealink/unlock/overtime/officesupplies/knowledge, "
+            "需 SYU-Token/SYU-Url 注入)。命中者直连被墙,只能经网关。"))
+    directAllow: list[str] = Field(
+        default_factory=list,
+        description=(
+            "直连放行的目标 host/IP(精确或 *.domain 通配)。不注入凭据。"
+            "显式豁免优先,包括豁免 SYT 管制。"))
+    defaultMode: str = Field(
+        default="allow",
+        description=(
+            "名单外 host 的默认处置: 'allow'=放行直连(当前阶段策略——只管制 "
+            "SYT_BASE_URL 同域名与 viaGateway 名单,其余外网全放行,用户自建技能"
+            "不受阻); 'drop'=DROP(未来收紧时改此值即可,不用改代码)。"))
+
+    # ---- 匹配 ----
+
+    @staticmethod
+    def _host_match(host: str, patterns: list[str]) -> bool:
+        """host 是否命中 patterns(精确或 fnmatch 通配,大小写不敏感)。"""
+        h = (host or "").lower()
+        for p in patterns:
+            p = (p or "").strip().lower()
+            if not p:
+                continue
+            if "*" in p or "?" in p:
+                if fnmatch.fnmatch(h, p):
+                    return True
+            elif h == p:
+                return True
+        return False
+
+    def classify(self, host: str, syt_base_url: str = "") -> str:
+        """分类一个目标 host → 'direct' | 'gateway' | 'drop'。
+
+        管制判定【自动】:host 与 syt_base_url(凭据包的真上游,主进程按环境
+        解析)同 host → gateway。directAllow 优先于一切(显式豁免)。
+        viaGateway 为额外管制名单(当前阶段放 OA/星瀚后端)。
+
+        名单外 defaultMode='allow' → direct(当前阶段:其余外网全放行);
+        未来收紧改 'drop' 即名单外 DROP,不用改代码。
+        """
+        h = (host or "").lower().strip()
+        if not h:
+            return "drop"
+        # 1. directAllow 显式豁免优先
+        if self._host_match(h, self.directAllow):
+            return "direct"
+        # 2. SYT_BASE_URL 同域名 → 自动管制(核心语义,不配置)
+        syt_host = ""
+        try:
+            syt_host = (urlparse(syt_base_url or "").hostname or "").lower()
+        except Exception:
+            syt_host = ""
+        if syt_host and h == syt_host:
+            return "gateway"
+        # 3. 额外管制名单(OA/星瀚)
+        if self._host_match(h, self.viaGateway):
+            return "gateway"
+        # 4. 名单外:按 defaultMode(当前 allow=放行,可配置收紧为 drop)
+        return "drop" if (self.defaultMode or "").lower() == "drop" else "direct"
+
+    # ---- 供硬墙用:directAllow 解析成 IP(含端口) ----
+
+    def direct_targets(self) -> list[tuple[str, int]]:
+        """把 directAllow 条目解析成 (ip, port) 列表,供 iptables 放行。
+
+        条目可以是 host、host:port、裸 IP。域名在此(沙箱进程)解析成 IP——
+        child 只放行解析后的 IP。解析失败跳过并告警(不阻断其它条目)。
+        默认端口 443(host 无端口且是 https 语义)——为兼容 http 内网服务,
+        无端口条目同时放行 80 与 443。
+        """
+        out: list[tuple[str, int]] = []
+        for raw in self.directAllow:
+            entry = (raw or "").strip()
+            if not entry:
+                continue
+            port = None
+            host = entry
+            if ":" in entry and not entry.count(":") > 1:  # host:port(非 IPv6)
+                host, _, ps = entry.partition(":")
+                if ps.isdigit():
+                    port = int(ps)
+            # 跳过通配符条目(硬墙按 IP 放行,通配域名无法枚举;告警提示)
+            if "*" in host or "?" in host:
+                SYLogger.warning(
+                    f"[EgressPolicy] directAllow 含通配符 {entry},iptables 无法按 IP 放行,跳过(改用精确 host)")
+                continue
+            # host → IP(是 IP 则原样)
+            try:
+                socket.inet_aton(host)
+                ip = host
+            except OSError:
+                try:
+                    ip = socket.gethostbyname(host)
+                except Exception as e:
+                    SYLogger.warning(f"[EgressPolicy] 解析 {host} 失败,跳过: {e}")
+                    continue
+            ports = [port] if port else [80, 443]
+            for p in ports:
+                if (ip, p) not in out:
+                    out.append((ip, p))
+        return out
+
+    # ---- 供网关用:全部允许经网关的 host ----
+
+    def allowed_hosts(self, syt_base_url: str = "") -> list[str]:
+        """网关 host 白名单全集。
+
+        defaultMode='allow'(当前阶段)时返回 None 语义由调用方处理——名单外
+        也放行(不设限);'drop' 模式下才用集合判定。这里恒返回集合供 'drop'
+        模式与审计使用:directAllow + viaGateway + SYT host。
+        """
+        hosts = list(self.directAllow) + list(self.viaGateway)
+        try:
+            syt_host = (urlparse(syt_base_url or "").hostname or "").lower()
+            if syt_host:
+                hosts.append(syt_host)
+        except Exception:
+            pass
+        return list(dict.fromkeys(h for h in hosts if h))
+
+    # ---- 加载 ----
+
+    @classmethod
+    def from_config(cls) -> "EgressPolicyConfig":
+        """从沙箱自身 dataId(shengye-platform-sandbox)读 EgressPolicy 段。
+
+        项目 dataId 顶层 key 已全量提升(Config.set_attr),无需登记。
+        未配置 → 空策略(SYT_BASE_URL 同域名仍自动管制,其余 DROP)。
+        """
+        from sycommon.config.Config import Config
+        raw = Config().config.get("EgressPolicy") or {}
+        try:
+            return cls(**raw) if isinstance(raw, dict) else cls()
+        except Exception as e:
+            SYLogger.warning(f"[EgressPolicy] 配置解析失败,按空策略处理: {e}")
+            return cls()

sycommon_python_lib-0.2.8a5/src/sycommon/middleware/egress_wall.py

@@ -0,0 +1,268 @@
+"""沙箱出网收口硬墙：iptables OUTPUT 白名单（按 child uid owner-match）。
+
+在沙箱服务进程（root，有 CAP_NET_ADMIN）启动时、网关 listener 起来之后调用
+setup_egress_wall()，配置 OUTPUT 链规则，把 child 子进程（降权到 CHILD_DROP_UID）
+的出网限制为：
+
+  1. 本机网关 host:port（${SYT_BASE_URL} 指向它,SYT/OA 流量强制经网关受管制）
+  2. DNS（udp/tcp 53,child 要解析域名）
+  3. EgressPolicy.directAllow 的目标（内网无鉴权服务/公网查询类,直连不受影响）
+  4. 其余全部 DROP（防数据外泄——node/Go/裸socket/任意静态二进制绕不过）
+
+EgressPolicy 来自沙箱自己的 Nacos dataId(shengye-platform-sandbox)的
+EgressPolicy 段(见 sycommon/config/EgressPolicyConfig.py),Nacos 热更新后
+调 refresh_egress_wall() 重配。
+
+这是 L3/L4 内核级硬墙，语言无关、绕不过——比应用层 hook（sitecustomize/
+LD_PRELOAD/HTTPS_PROXY）强且无盲区。
+
+设计要点：
+  - owner-match（-m owner --uid-owner）：只锁 child uid，沙箱服务进程（root/其它 uid）
+    连 Nacos/Redis/MinIO 不受影响。避免「全容器 DROP 把服务自己搞挂」。
+  - 幂等：规则带 _RULE_COMMENT 标记,重配前先清理旧规则,不累积。
+  - 降级：无 CAP_NET_ADMIN / iptables 不存在 / 非 Linux → 跳过并告警，不阻断启动
+    （此时无硬墙，凭据隔离仍是主防线，但 node 等盲区未堵，日志明确提示）。
+
+依赖：
+  - 容器有 CAP_NET_ADMIN（K8s securityContext.capabilities.add: [NET_ADMIN]）
+  - 镜像装了 iptables（Dockerfile: apt-get install iptables）
+  - child 降权到 CHILD_DROP_UID（sandbox.py _preexec_drop_privileges）
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import platform
+import shlex
+import subprocess
+from typing import Optional
+
+from sycommon.logging.kafka_log import SYLogger
+
+
+# iptables 规则链上的注释标记，用于幂等识别/清理本模块加的规则。
+_RULE_COMMENT = "sycommon-egress-wall"
+
+
+def _read_dns_ips() -> list[str]:
+    """从 /etc/resolv.conf 读 nameserver IP（去重）。child 要能解析域名。"""
+    ips: list[str] = []
+    try:
+        with open("/etc/resolv.conf") as f:
+            for line in f:
+                line = line.strip()
+                if line.lower().startswith("nameserver"):
+                    parts = line.split()
+                    if len(parts) >= 2 and parts[1] not in ips:
+                        ips.append(parts[1])
+    except Exception as e:
+        SYLogger.warning(f"[EgressWall] 读 /etc/resolv.conf 失败: {e}")
+    return ips
+
+
+def _have_net_admin() -> bool:
+    """实测当前进程能否配 iptables（有 CAP_NET_ADMIN）。"""
+    if platform.system() != "Linux":
+        return False
+    try:
+        r = subprocess.run(
+            ["iptables", "-t", "nat", "-L"],
+            capture_output=True, timeout=5,
+        )
+        return r.returncode == 0
+    except Exception:
+        return False
+
+
+def _run_iptables(args: list[str]) -> tuple[int, str]:
+    """跑一条 iptables 命令，返回 (returncode, stderr)。"""
+    try:
+        r = subprocess.run(["iptables", *args], capture_output=True, timeout=10)
+        return r.returncode, (r.stderr.decode(errors="replace").strip())
+    except Exception as e:
+        return 1, str(e)
+
+
+def _clear_old_rules(child_uid: int) -> None:
+    """幂等清理本模块之前加的 OUTPUT 规则（按注释标记匹配）。
+
+    iptables 无「按注释批量删」的原子操作，这里用 -S 列出 OUTPUT 规则，
+    逐条匹配含 _RULE_COMMENT 的，-D 删除。重复 setup 不累积规则。
+    """
+    try:
+        r = subprocess.run(["iptables", "-S", "OUTPUT"], capture_output=True, timeout=10)
+        if r.returncode != 0:
+            return
+        lines = r.stdout.decode(errors="replace").splitlines()
+        for line in lines:
+            if _RULE_COMMENT in line:
+                # line 形如 "-A OUTPUT -m owner ... -j DROP -m comment --comment sycommon-egress-wall"
+                # 把 -A 换成 -D 即可删除该条。
+                del_spec = line.replace("-A OUTPUT", "OUTPUT", 1).strip()
+                # 去掉行首可能的 "-A"
+                _run_iptables(["-D"] + shlex.split(del_spec))
+    except Exception as e:
+        SYLogger.debug(f"[EgressWall] 清理旧规则异常(非致命): {e}")
+
+
+def setup_egress_wall(child_uid: int, gateway_port: int,
+                      gateway_host: str = "127.0.0.1",
+                      direct_targets: Optional[list] = None,
+                      drop_fallback: bool = True) -> bool:
+    """配置 child uid 的出网硬墙。返回是否成功。
+
+    规则（按顺序，owner-match 只锁 child uid）：
+      1. ESTABLISHED,RELATED 放行（回包）
+      2. DNS（udp/tcp 53）放行——按 /etc/resolv.conf 的 nameserver
+      3. 连本机网关 host:port 放行
+      4. direct_targets [(ip, port), ...] 放行（EgressPolicy.directAllow 解析产物,
+         内网无鉴权服务/公网查询类直连）
+      5. drop_fallback=True 时:其余 child uid 出网全 DROP。
+         当前阶段 EgressPolicy.defaultMode='allow'(只管制 SYT/OA 域,其余放行)
+         → drop_fallback=False,墙只保障「管制 host 直连被挡、必须走网关」,
+         不做兜底 DROP。未来收紧 defaultMode='drop' 时自动启用兜底。
+
+    管制 host(SYT_BASE_URL 同域名/viaGateway)不在放行之列——它们直连被墙,
+    只能经网关(网关注入凭据+审计),这正是「sy-base-url 管制」的硬墙侧执行。
+    要解析「管制域名的 IP 并精确 DROP」需 ipset+定时解析(域名 IP 会漂移),
+    当前简化:defaultMode=allow 时墙退化为「网关保障」模式(不 DROP 兜底),
+    管制由【库层 URL 重写+网关凭据注入】承担——凭据只有网关有,直连即使
+    通了也无凭据可用。
+
+    幂等：先清理本模块旧规则，再追加。非 Linux / 无 NET_ADMIN / iptables 缺失 → 跳过+告警。
+    """
+    if platform.system() != "Linux":
+        SYLogger.info("[EgressWall] 非 Linux，跳过 iptables 硬墙")
+        return False
+    if not _have_net_admin():
+        SYLogger.warning(
+            "[EgressWall] 无 CAP_NET_ADMIN 或无 iptables，跳过硬墙配置。"
+            "此时无内核级出网限制，node/裸 socket 盲区未堵——请给沙箱 Pod 加 "
+            "securityContext.capabilities.add:[NET_ADMIN] 并在镜像装 iptables。")
+        return False
+    if not gateway_port:
+        SYLogger.warning("[EgressWall] 网关端口未知，跳过硬墙配置")
+        return False
+
+    dns_ips = _read_dns_ips()
+    direct_targets = direct_targets or []
+
+    _clear_old_rules(child_uid)
+
+    uid = str(child_uid)
+    c = lambda spec: ["-m", "comment", "--comment", _RULE_COMMENT, *spec]  # noqa: E731
+
+    # 1. ESTABLISHED,RELATED（回包）
+    _run_iptables(["-A", "OUTPUT", "-m", "owner", "--uid-owner", uid,
+                   "-m", "conntrack", "--ctstate", "ESTABLISHED,RELATED",
+                   "-m", "comment", "--comment", _RULE_COMMENT, "-j", "ACCEPT"])
+
+    # 2. DNS（每个 nameserver，udp + tcp 53）
+    for ip in dns_ips:
+        _run_iptables(["-A", "OUTPUT", "-m", "owner", "--uid-owner", uid,
+                       "-p", "udp", "-d", ip, "--dport", "53",
+                       "-m", "comment", "--comment", _RULE_COMMENT, "-j", "ACCEPT"])
+        _run_iptables(["-A", "OUTPUT", "-m", "owner", "--uid-owner", uid,
+                       "-p", "tcp", "-d", ip, "--dport", "53",
+                       "-m", "comment", "--comment", _RULE_COMMENT, "-j", "ACCEPT"])
+
+    # 3. 本机网关
+    gw_rc, gw_err = _run_iptables(
+        ["-A", "OUTPUT", "-m", "owner", "--uid-owner", uid,
+         "-p", "tcp", "-d", gateway_host, "--dport", str(gateway_port),
+         "-m", "comment", "--comment", _RULE_COMMENT, "-j", "ACCEPT"])
+    if gw_rc != 0:
+        SYLogger.warning(f"[EgressWall] 放行网关规则失败: {gw_err}")
+
+    # 4. directAllow 直连放行(EgressPolicy.directAllow 解析出的 (ip, port))
+    direct_ok = 0
+    for ip, port in direct_targets:
+        rc, err = _run_iptables(
+            ["-A", "OUTPUT", "-m", "owner", "--uid-owner", uid,
+             "-p", "tcp", "-d", ip, "--dport", str(port),
+             "-m", "comment", "--comment", _RULE_COMMENT, "-j", "ACCEPT"])
+        if rc == 0:
+            direct_ok += 1
+        else:
+            SYLogger.warning(f"[EgressWall] directAllow 放行失败 {ip}:{port}: {err}")
+
+    # 5. 兜底 DROP(defaultMode='drop' 时;当前阶段 allow 不加,其余外网放行)
+    if drop_fallback:
+        drop_rc, drop_err = _run_iptables(
+            ["-A", "OUTPUT", "-m", "owner", "--uid-owner", uid,
+             "-m", "comment", "--comment", _RULE_COMMENT, "-j", "DROP"])
+        if drop_rc != 0:
+            SYLogger.warning(f"[EgressWall] DROP 规则失败: {drop_err}")
+            return False
+        fallback_desc = "其余 DROP"
+    else:
+        fallback_desc = "其余放行(defaultMode=allow)"
+
+    SYLogger.info(
+        f"[EgressWall] 硬墙已配置: child uid={child_uid}, "
+        f"放行网关 {gateway_host}:{gateway_port} + DNS({dns_ips}) + "
+        f"directAllow({direct_ok} 条), {fallback_desc}")
+    return True
+
+
+def teardown_egress_wall(child_uid: int) -> None:
+    """关闭时清理本模块规则。"""
+    if platform.system() != "Linux":
+        return
+    try:
+        _clear_old_rules(child_uid)
+        SYLogger.info(f"[EgressWall] 已清理硬墙规则: child uid={child_uid}")
+    except Exception as e:
+        SYLogger.debug(f"[EgressWall] 清理规则异常: {e}")
+
+
+# ============== 供 services.py lifespan 调用的高层封装 ==============
+
+_egress_wall_installed = False
+_gateway_port_cache: int = 0
+_gateway_host_cache: str = "127.0.0.1"
+
+
+async def setup_egress_wall_async(child_uid: int, gateway_port: int,
+                                  gateway_host: str = "127.0.0.1") -> bool:
+    """异步包装：在线程池跑 iptables（subprocess 阻塞），不卡事件循环。
+
+    自动读沙箱 dataId 的 EgressPolicy:directAllow 并入放行列表;
+    defaultMode 决定是否启用兜底 DROP('drop' 才加,'allow' 只保障网关通道)。
+    """
+    global _egress_wall_installed, _gateway_port_cache, _gateway_host_cache
+    _gateway_port_cache = gateway_port
+    _gateway_host_cache = gateway_host
+    direct, drop_fb = await asyncio.to_thread(_policy_wall_params)
+    ok = await asyncio.to_thread(
+        setup_egress_wall, child_uid, gateway_port, gateway_host, direct, drop_fb)
+    _egress_wall_installed = ok
+    return ok
+
+
+def _policy_wall_params() -> tuple:
+    """读 EgressPolicy → (direct_targets, drop_fallback)(沙箱本地 Config)。"""
+    try:
+        from sycommon.config.EgressPolicyConfig import EgressPolicyConfig
+        policy = EgressPolicyConfig.from_config()
+        return (policy.direct_targets(),
+                (policy.defaultMode or "allow").lower() == "drop")
+    except Exception as e:
+        SYLogger.warning(f"[EgressWall] 读 EgressPolicy 失败(仅网关+DNS 放行): {e}")
+        return ([], False)
+
+
+async def refresh_egress_wall_async(child_uid: int) -> bool:
+    """Nacos EgressPolicy 热更新后重配硬墙(幂等:清理旧规则再加)。"""
+    if not _gateway_port_cache:
+        SYLogger.warning("[EgressWall] 网关未启动,跳过刷新")
+        return False
+    return await setup_egress_wall_async(
+        child_uid, _gateway_port_cache, _gateway_host_cache)
+
+
+async def teardown_egress_wall_async(child_uid: int) -> None:
+    global _egress_wall_installed
+    await asyncio.to_thread(teardown_egress_wall, child_uid)
+    _egress_wall_installed = False