Initial commit

This commit is contained in:
Alex committed 2026-11-02 22:54:14 +08:00
commit 57fc3525eb
7311 files changed
+1291398

No files matched your search

+357
View File
@@ -0,0 +1,357 @@
"""
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