Files
2026-11-02 22:54:14 +08:00

358 lines
14 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""
app/core/http_security.py - 控制面 HTTP 安全边界(审查条目 S1 / S13 / H1)
集中放置与部署安全相关的纯逻辑,便于单元测试:
- ``is_loopback_host``:判断客户端/监听地址是否为回环;
- ``origin_is_allowed``:跨源请求(CSRF / 跨站读取)来源判定;
- ``startup_security_errors``:公开监听但未启用认证、认证开关写成非布尔值
等不安全配置在启动期直接报错,而不是静默回退为「关闭认证」;
- ``is_secret_env_key`` / ``redact_env_for_backup``:备份导出时剔除秘密。
"""
from __future__ import annotations
import ipaddress
import os
import re
from typing import Any, Dict, Iterable, List, Mapping, Optional, Tuple
from urllib.parse import urlsplit
TRUE_VALUES = ("true", "1", "yes", "on")
FALSE_VALUES = ("false", "0", "no", "off")
# 显式放行「公开监听 + 无认证」的逃生开关(仅限完全可信的隔离网络)。
INSECURE_OVERRIDE_ENV = "ALLOW_INSECURE_PUBLIC_BIND"
_LOOPBACK_NAMES = {"localhost", "localhost.localdomain", "ip6-localhost", "ip6-loopback"}
def is_loopback_host(host: Optional[str]) -> bool:
"""回环地址判定(127.0.0.0/8、::1、IPv4 映射的 ::ffff:127.x、localhost)。"""
raw = str(host or "").strip().lower()
if not raw:
return False
if raw.startswith("[") and "]" in raw:
raw = raw[1:raw.index("]")]
if raw in _LOOPBACK_NAMES:
return True
try:
addr = ipaddress.ip_address(raw)
except ValueError:
return False
mapped = getattr(addr, "ipv4_mapped", None)
if mapped is not None:
addr = mapped
return bool(addr.is_loopback)
def is_public_bind_host(host: Optional[str]) -> bool:
"""监听地址是否会暴露到回环以外(0.0.0.0 / :: / 具体网卡地址 / 主机名)。"""
raw = str(host or "").strip()
if not raw:
# AppConfig.get_host() 默认 127.0.0.1;空串交给 uvicorn 时等价于默认回环。
return False
return not is_loopback_host(raw)
def _normalize_origin(value: str) -> Optional[Tuple[str, str]]:
"""返回 (scheme, host[:port]) 小写形式;默认端口剥离,无法解析返回 None。"""
try:
parts = urlsplit(str(value or "").strip())
except ValueError:
return None
scheme = (parts.scheme or "").lower()
if scheme not in ("http", "https") or not parts.hostname:
return None
host = parts.hostname.lower()
if ":" in host:
host = f"[{host}]"
try:
port = parts.port
except ValueError:
return None
if port and not ((scheme == "http" and port == 80) or (scheme == "https" and port == 443)):
host = f"{host}:{port}"
return scheme, host
def _normalize_host_header(value: str, scheme: str) -> Optional[str]:
raw = str(value or "").strip().lower()
if not raw:
return None
normalized = _normalize_origin(f"{scheme}://{raw}")
return normalized[1] if normalized else None
def origin_is_allowed(
origin: Optional[str],
host_header: Optional[str],
allowed_origins: Iterable[str] = (),
forwarded_host: Optional[str] = None,
) -> bool:
"""判断带 ``Origin`` 头的请求是否可被接受。
- 无 ``Origin`` 头:非浏览器客户端或同源导航,放行(交给认证层);
- 与请求 Host(或可信反代给出的 X-Forwarded-Host)同源:放行;
- 命中显式配置的 ``CORS_ORIGINS``(含用户显式配置的 ``*``):放行;
- 其它(含 ``Origin: null``):拒绝。
"""
if origin is None:
return True
raw_origin = str(origin).strip()
if raw_origin == "":
return True
allowed = [str(item or "").strip() for item in (allowed_origins or []) if str(item or "").strip()]
if "*" in allowed:
return True
parsed = _normalize_origin(raw_origin)
if parsed is None:
# "null"(沙箱 iframe / file://)或畸形值
return False
scheme, origin_host = parsed
for candidate in (host_header, forwarded_host):
if not candidate:
continue
# X-Forwarded-Host 可能是逗号分隔的链,取第一个(最靠近客户端)
first = str(candidate).split(",")[0].strip()
if _normalize_host_header(first, scheme) == origin_host:
return True
for item in allowed:
normalized = _normalize_origin(item)
if normalized is not None and normalized == parsed:
return True
return False
def parse_cors_origins(raw: Optional[str]) -> List[str]:
"""``CORS_ORIGINS`` 解析:空 = 不允许任何跨源(同源控制面板不需要 CORS)。"""
value = str(raw or "").strip()
if not value:
return []
if value == "*":
return ["*"]
return [item.strip().rstrip("/") for item in value.split(",") if item.strip()]
def _bool_value_error(name: str, env: Mapping[str, str]) -> Optional[str]:
raw = env.get(name)
if raw is None or str(raw).strip() == "":
return None
lowered = str(raw).strip().lower()
if lowered == "your-secret-here":
# 兼容 3.0.0 模板:视为未设置(由 startup_security_warnings 产生告警提示,不作致命错误)
return None
if lowered in TRUE_VALUES or lowered in FALSE_VALUES:
return None
return (
f"{name}={raw!r} 不是合法布尔值(应为 true/false)。"
f"此前该值会被静默当作 false 从而关闭认证,现拒绝启动。"
)
def startup_security_warnings(
host: Optional[str] = None,
env: Optional[Mapping[str, str]] = None,
) -> List[str]:
"""返回非致命但建议修改的安全告警(例如旧模板兼容项)。"""
env = os.environ if env is None else env
warnings: List[str] = []
for name in ("AUTH_ENABLED", "DASHBOARD_AUTH_ENABLED"):
raw = env.get(name)
if raw is not None and str(raw).strip().lower() == "your-secret-here":
warnings.append(
f"{name}='your-secret-here' 为 3.0.0 模板旧占位符,已兼容视为未设置(未启用认证)。"
"请尽快在控制面板或 .env 中显式设置为 false,或设置有效令牌后设为 true。"
)
return warnings
def _env_true(env: Mapping[str, str], name: str) -> bool:
return str(env.get(name) or "").strip().lower() in TRUE_VALUES
def startup_security_errors(
host: Optional[str] = None,
env: Optional[Mapping[str, str]] = None,
) -> List[str]:
"""返回会导致拒绝启动的安全配置错误列表(空列表 = 通过)。"""
env = os.environ if env is None else env
errors: List[str] = []
for name in ("AUTH_ENABLED", "DASHBOARD_AUTH_ENABLED"):
message = _bool_value_error(name, env)
if message:
errors.append(message)
bind_host = host if host is not None else env.get("APP_HOST", "127.0.0.1")
if not is_public_bind_host(bind_host):
return errors
if _env_true(env, INSECURE_OVERRIDE_ENV):
return errors
service_enabled = _env_true(env, "AUTH_ENABLED")
service_token = str(env.get("AUTH_TOKEN") or "").strip()
raw_dash = env.get("DASHBOARD_AUTH_ENABLED")
if raw_dash is None or str(raw_dash).strip() == "":
dash_enabled = service_enabled
else:
dash_enabled = _env_true(env, "DASHBOARD_AUTH_ENABLED")
dash_token = str(env.get("DASHBOARD_AUTH_TOKEN") or "").strip() or service_token
if not (dash_enabled and dash_token):
errors.append(
f"APP_HOST={bind_host} 会把控制面板暴露到本机以外,但控制面板认证未启用或未设置令牌。"
"请设置 DASHBOARD_AUTH_ENABLED=true 与 DASHBOARD_AUTH_TOKEN(或 AUTH_ENABLED=true 与 AUTH_TOKEN),"
f"或改回 APP_HOST=127.0.0.1。确认处于完全可信的隔离网络时可设 {INSECURE_OVERRIDE_ENV}=true 跳过此检查。"
)
if not (service_enabled and service_token):
errors.append(
f"APP_HOST={bind_host} 会把 /v1 API 暴露到本机以外,但 API 认证未启用或未设置令牌。"
"请设置 AUTH_ENABLED=true 与 AUTH_TOKEN,"
f"或改回 APP_HOST=127.0.0.1(可信隔离网络可设 {INSECURE_OVERRIDE_ENV}=true)。"
)
# S2:把「在服务进程内执行任意代码」的能力与对外绑定组合起来,
# 等于把远程代码执行直接暴露到网络上。
for flag, description in (
(
"CMD_ALLOW_UNSAFE_PYTHON_COMMANDS",
"命令引擎的 Python 脚本会以非沙箱模式执行(可访问完整 builtins 与浏览器对象)",
),
(
"PARSER_INSTALL_ENABLED",
"运行时解析器安装会把任意源码写入 app/core/parsers/ 并立即 import",
),
):
if _env_true(env, flag):
errors.append(
f"{flag}=true 与对外绑定(APP_HOST={bind_host})同时开启:"
f"{description},等于把远程代码执行暴露到网络上。"
f"请把 APP_HOST 改回 127.0.0.1,或关闭 {flag}。"
)
return errors
# ---------------------------------------------------------------------------
# 备份脱敏(S13)
# ---------------------------------------------------------------------------
_SECRET_KEY_PATTERN = re.compile(
r"(TOKEN|SECRET|PASSWORD|PASSWD|PASSPHRASE|API_?KEY|ACCESS_?KEY|PRIVATE_?KEY|"
r"COOKIE|CREDENTIAL|AUTH_USER|SESSION)",
re.IGNORECASE,
)
_URL_USERINFO_PATTERN = re.compile(r"^[a-z][a-z0-9+.\-]*://[^/@\s]+@", re.IGNORECASE)
def is_secret_env_key(key: str) -> bool:
return bool(_SECRET_KEY_PATTERN.search(str(key or "")))
def value_contains_credentials(value: Any) -> bool:
"""形如 scheme://user:pass@host 的值(代理地址等)视为含凭据。"""
if not isinstance(value, str):
return False
return any(_URL_USERINFO_PATTERN.match(part.strip()) for part in value.split(",") if part.strip())
def redact_env_for_backup(env: Mapping[str, Any]) -> Tuple[Dict[str, Any], List[str]]:
"""剔除秘密键/含凭据的值,返回 (安全子集, 被剔除的键名列表)。
剔除而不是替换为占位符:导入时缺失的键会原样保留目标机器 ``.env`` 里的现值,
避免把占位符写回去覆盖真实令牌。
"""
safe: Dict[str, Any] = {}
removed: List[str] = []
for key, value in (env or {}).items():
if is_secret_env_key(key) or value_contains_credentials(value):
# 空值不算泄露,但为了语义一致也一并剔除(导入时保持目标现值)
removed.append(str(key))
continue
safe[key] = value
return safe, sorted(removed)
# ---------------------------------------------------------------------------
# 「本机请求」判定(S13 回退路径 / S4)
# ---------------------------------------------------------------------------
# 反向代理 / 隧道(ngrok、cloudflared、nginx 等)常见的转发头。回环连接上出现这些头,
# 说明真实客户端在别处,不能再把「连接来自 127.0.0.1」当作授权依据。
FORWARDING_HEADERS = (
"forwarded",
"x-forwarded-for",
"x-forwarded-host",
"x-real-ip",
"cf-connecting-ip",
"true-client-ip",
"x-client-ip",
)
# start.py 的定时重启 handoff 代理会用这两个头把真实客户端地址传给子进程;
# 共享密钥每次启动随机生成并通过环境变量传递,外部请求无法伪造。
PROXY_CLIENT_HEADER = "x-uwa-client-addr"
PROXY_SECRET_HEADER = "x-uwa-proxy-secret"
PROXY_SECRET_ENV = "UWAPI_PROXY_SECRET"
def _header(headers: Any, name: str) -> Optional[str]:
if headers is None:
return None
try:
value = headers.get(name)
except Exception:
value = None
if value is None and isinstance(headers, Mapping):
for key, item in headers.items():
if str(key).lower() == name:
value = item
break
return None if value is None else str(value)
def effective_client_host(
client_host: Optional[str],
headers: Any = None,
env: Optional[Mapping[str, str]] = None,
) -> Optional[str]:
"""返回真实客户端地址:只有来自受信 handoff 代理(回环 + 密钥匹配)时才采信转发头。"""
env = os.environ if env is None else env
secret = str(env.get(PROXY_SECRET_ENV) or "").strip()
if secret and is_loopback_host(client_host):
supplied = _header(headers, PROXY_SECRET_HEADER)
if supplied is not None:
import hmac
if hmac.compare_digest(supplied.strip().encode("utf-8"), secret.encode("utf-8")):
forwarded = (_header(headers, PROXY_CLIENT_HEADER) or "").strip()
return forwarded or None
return None # 伪造/错误密钥:不采信也不当作本机
return client_host
def is_trusted_local_request(
client_host: Optional[str],
headers: Any = None,
env: Optional[Mapping[str, str]] = None,
) -> bool:
"""连接来自本机回环,且没有任何迹象表明它是被代理/隧道转发进来的。"""
env = os.environ if env is None else env
real = effective_client_host(client_host, headers, env)
if not is_loopback_host(real):
return False
# handoff 代理(S4/S5)会原样保留外部转发头、只剥离并重写 X-UWA-*:
# 若 handoff 代理前面还有 nginx / 隧道,真实地址在转发头里,不能因为
# 「代理报告的对端是 127.0.0.1」就当作本机。所以无论是否经 handoff 代理,
# 出现任何转发头都视为经反代/隧道进入。
for name in FORWARDING_HEADERS:
if _header(headers, name):
return False
return True